Gmcps

Gerencia servidores MCP (Model Context Protocol) do Docker MCP Gateway via Web Vue 3.

Visão Geral

O Docker MCP Gateway expõe servidores MCP via SSE em http://localhost:3099/sse. O gmcp gerencia o ciclo de vida desses servidores — instala, ativa/desativa, remove, compartilha entre agentes — sincronizando com o profile Docker subjacente.

┌─────────────────────────────────────────────────────┐
│                  gmcp                                │
│  ┌──────────┐  ┌────────────┐                       │
│  │ Web UI   │  │ API REST   │                       │
│  │ (Vue 3)  │  │(FastAPI)   │                       │
│  └────┬─────┘  └─────┬──────┘                       │
│       └──────┬───────┘                              │
│              ▼                                       │
│     ┌────────────────┐                              │
│     │ GatewayService │ (hexagonal)                  │
│     └───┬────┬────┬──┘                              │
│ ┌────────┐ ┌──┴──┐ ┌──┴──┐ ┌───────────┐ ┌──────┐  │
│ │ SQLite │ │File │ │Docker│ │Subprocess │ │ MCP  │  │
│ │Catalog │ │State│ │Profile││Gateway    │ │Relay │  │
│ └────┬───┘ └─────┘ └──┬───┘ └─────┬─────┘ └──┬───┘  │
│      ▼                ▼           ▼          ▼      │
│ mcp-toolkit.db   state.json   docker CLI   SSE :31xx│
└─────────────────────────────────────────────────────┘

Interfaces

Interface	Caminho	Tecnologia
Web	http://localhost:8173	Vue 3 + Vite + Tailwind
API	http://localhost:8000/api	FastAPI + Uvicorn

Funcionalidades

• Home: Estatísticas do gateway, recursos do sistema (RAM/CPU/storage/online), logs recentes, restart
• MCPs: Servidores instalados com filtro All/Active/Inactive, busca, toggle, remoção, compartilhamento (Share)
• Market: Catálogo de servidores disponíveis, seleção múltipla para instalação, modal de detalhes, busca, filtro por categorias, add custom MCP
• Integrações: Detecta agentes (OpenCode, Kilo Code, Claude Code, Codex CLI, OpenClaude) com dropdown expansível, adiciona/remove MCPs
• Settings: Configurações de tema, idioma, compartilhamento padrão
• Logs/Conexões: Tabela de conexões de containers MCP com filtros tag/date/stop, persistência SQLite, Clear em massa
• Modo Compartilhado (Shared): Ativa relay SSE dedicado para um MCP — 1 container, N agentes simultâneos
• i18n: pt-BR e en-US (detecção automática via navigator.language)
• Dark/Light: Tema alternável na navbar Web UI
• Paginação: Listagens com paginação (20 MCPs, 30 Market)
• Autostart: gmcps-web inicia o gateway automaticamente via PM2

Preview

Home	MCPs	Market

Integrações	Logs

Suporte a Plataformas

SO	Web	API	Observação
🐧 Linux	✅	✅	Alvo principal
🪟 Windows (WSL2)	✅	✅	Necessita Docker Desktop com integração WSL2
🍎 macOS	✅	✅	Testado
🪟 Windows nativo	✅	❌	Sem suporte a /proc/

O Docker MCP Gateway requer Docker Desktop com o plugin MCP instalado. No Windows, utilize WSL2.

Quick Start

Instalação via npm (recomendado)

npm install -g @figcodessolucoes/gmcps

gmcps-web       # Servidor web (inicia gateway + backend + frontend automaticamente)

Desenvolvimento (repositório clonado)

npm run dev:backend            # Apenas API (:8000)
npm run dev                    # Apenas frontend (:5173)
npm run dev:all                # Gateway + Backend + Frontend

Docker

docker compose up -d
# Acessar: http://localhost:8173

Modo Compartilhado (Shared)

Cada MCP pode rodar em modo compartilhado — um único container atende todos os agentes conectados:

Sem compartilhar (padrão):
  OpenCode ──► gateway:3099/sse?server=memory ──► container #1
  KiloCode ──► gateway:3099/sse?server=memory ──► container #2

Com compartilhamento ativo:
  OpenCode ──┐
  KiloCode ──┼──► relay:3100/sse ──► container mcp/memory (ÚNICO)
  OpenClaude─┘

Ativar:

• Web: Aba MCPs → botão Share → tag verde S:porta

Stack

Backend

• Python 3.14+ — runtime
• FastAPI + Uvicorn — REST API
• SQLite — catálogo MCP (mcp-toolkit.db), histórico de conexões (connections.db)
• Pytest — testes unitários (27 testes)

Frontend (Web)

• Vue 3.5 — framework SPA
• Vite 8 — bundler | TypeScript 6 — tipagem
• Pinia 3 — estado global | Vue Router 5 — navegação
• Tailwind CSS 4 — estilização | vue-i18n 10 — i18n
• Vitest 4 — testes | Playwright — e2e

DevOps

• Docker — runtime + deploy containerizado
• PM2 — gerenciamento de processo (produção)
• concurrently — dev server paralelo
• Oxlint + ESLint — linting | Prettier — formatação
• Fallow — codebase intelligence (health 92 A)
• Snyk — security scan (0 vulns)

Arquitetura

Hexagonal (Ports & Adapters) — todo o core está em backend/core/ com interfaces abstratas em ports.py, implementações concretas em adapters/, e o GatewayService orquestrando a lógica de negócio.

backend/
├── core/
│   ├── entities.py      # Dataclasses de domínio
│   ├── ports.py         # Interfaces abstratas
│   ├── services.py      # Lógica de negócio
│   ├── i18n.py          # Internacionalização
│   └── integrations.py  # Detecção de agentes
├── adapters/
│   ├── sqlite_catalog.py     # Leitura do catálogo Docker
│   ├── file_state.py         # Persistência em state.json
│   ├── docker_profile.py     # Sincronia profile + gateway
│   ├── docker_containers.py  # Leitura de containers MCP
│   ├── connection_db.py      # Histórico SQLite de conexões
│   └── mcp_relay.py          # Relay compartilhado (SSE proxy)
├── main.py              # FastAPI
└── tests/
    ├── test_core.py
    └── test_api.py

Estado

~/.config/gmcp/state.json gerencia servidores + modo compartilhado:

{
  "installed": ["exa", "memory", "playwright"],
  "enabled": ["memory", "playwright"],
  "shared_servers": { "memory": 3100 }
}

Comandos Úteis

# Iniciar
gmcps-web             # Web + gateway (PM2)
docker compose up -d  # Docker

# Gateway manual
./start-gateway.sh

# API
curl localhost:8000/api/stats
curl localhost:8000/api/resources

# Compartilhar
curl -X POST localhost:8000/api/servers/memory/share
curl -X POST localhost:8000/api/servers/memory/unshare

# PM2 (produção)
pm2 start gmcps-web --name gmcps-web
pm2 logs gmcps-web

# Testes
npx vitest run                      # Frontend
.venv/bin/python3 -m pytest backend/tests/  # Backend

# Qualidade
npm run fallow          # Full analysis
npm run snyk:test       # Security
npm run lint            # Lint

Portas

Serviço	Porta
Gateway MCP	3099
Backend API	8000
Frontend (Web)	8173
Shared relays	3100+

Variáveis Críticas

Variável	Padrão	Descrição
MCP_GATEWAY_AUTH_TOKEN	mcp-local-token	Token de autenticação do gateway

Licença

MIT