convez.ai
MCP ServerDevOps & InfraestruturaAvançado
sudebaker

MCP Orchestrator

sudebaker/mcp-go

Servidor MCP em Go para orquestração de ferramentas em redes restritas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP baseado em Go que orquestra ferramentas externas (principalmente Python) para análise de dados, OCR, geração de relatórios e gestão de base de conhecimento. Otimizado para ambientes isolados e redes restritas, com suporte a PostgreSQL, pgvector e armazenamento S3-compatível.

Instalação

$npx convez-ai sudebaker/mcp-go

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
5

Casos de uso

  • Análise de dados e geração de relatórios em ambientes air-gapped
  • Gestão de base de conhecimento com busca vetorial (pgvector)
  • Processamento de documentos e OCR em redes isoladas
  • Transcrição de áudio e renderização JS sem acesso externo

Veredito

Solução robusta para ambientes corporativos isolados, com orquestração clara de ferramentas e integração completa de stack (PostgreSQL, S3, Ollama). Requer conhecimento em Go, Docker e DevOps; pronto para produção em deployments restritos.

README

A tradução para o português deste README ainda está na fila.

MCP Orchestrator

A Go-based MCP (Model Context Protocol) server that orchestrates external tools — primarily Python — for data analysis, OCR, report generation, knowledge base management, and more. Built for air-gapped and restricted-network deployments.

Go Docker MCP

Features

  • Go-based MCP server with primary endpoint POST /mcp
  • Legacy SSE transport for backward compatibility (/sse and /message)
  • Configurable tool catalog via configs/config.yaml
  • PostgreSQL + pgvector knowledge base integration
  • RustFS/S3-compatible file storage integration
  • Designed for air-gapped and restricted-network deployments

Requirements

  • Go 1.23+
  • Docker and Docker Compose
  • Optional: Ollama on the same Docker network

Quick Start

cd deployments
docker compose up -d

docker compose ps

Services defined in deployments/docker-compose.yml:

ServiceURLPurpose
mcp-serverhttp://localhost:8080MCP server
postgreslocalhost:5432KB storage (pgvector)
rustfshttp://localhost:9000S3-compatible storage
searxnghttp://localhost:8080 (internal)Private web search
browserlesshttp://localhost:3000Headless browser (JS rendering)
whisperhttp://localhost:8000Audio transcription

Resource Limits

Each service in docker-compose.yml has CPU and memory limits to prevent any single container from consuming all host resources:

ServiceCPU LimitMemory LimitCPU ReservationMemory Reservation
mcp-server2 CPUs2 GB0.5 CPUs1 GB
postgres1 CPU1 GB0.5 CPUs512 MB
whisper2 CPUs2 GB0.5 CPUs512 MB
browserless1 CPU1 GB0.25 CPUs512 MB
searxng1 CPU512 MB0.25 CPUs128 MB
rustfs1 CPU512 MB0.25 CPUs128 MB

Limits cap the maximum resources a container can use; reservations guarantee a minimum to the Docker scheduler (effective in Swarm mode). These values balance headroom for the Go MCP server and CPU-intensive Whisper with tighter bounds on lighter services like SearXNG and RustFS.

MCP Endpoints

EndpointProtocolDescription
/mcpStreamable HTTPPrimary endpoint (recommended)
/sseSSELegacy client compatibility
/messageSSE MessageMessage sender for SSE transport
/healthHTTPServer healthcheck

Supported MCP methods: initialize, ping, tools/list, tools/call.

Included Tools

Defined in configs/config.yaml:

Note: The default configuration has tool descriptions in Spanish. To switch to English descriptions, rename the included alternate config:

mv configs/config-en.yaml configs/config.yaml
docker compose restart mcp-server
CategoryTools
Coreecho
Analysis & Generationanalyze_data, analyze_image, generate_report
Knowledge Basekb_ingest, kb_search
Document Processingbatch_summarize, regulation_diff, config_auditor, document_classifier
Utilitiesweather_forecast, web_scraper, rss_reader, canvas_diagram, rustfs_storage, transcribe, searxng_search, browser_scraper

Vision Tool: Provider Override

The analyze_image tool supports optional provider and model parameters to route vision requests to specific LLM backends. This enables private vision analysis without sending images to third-party APIs.

Supported Providers

ProviderRoutes toDefault ModelAPI Key Required
ollama / localLLM_API_URL env var (default http://localhost:11434)LLM_MODEL or llavaNo
remote-ollamaREMOTE_OLLAMA_URL env varqwen3.5:9b (multimodal)No
openrouterhttps://openrouter.ai/api/v1google/gemini-2.0-flash-001OPENROUTER_API_KEY
openaihttps://api.openai.com/v1gpt-4o-miniOPENAI_API_KEY
Custom URLUsed directly as-isLLM_MODEL or llavaVaries

Configuration

Set the REMOTE_OLLAMA_URL environment variable in your .env file (gitignored) to point to a remote Ollama instance (VPN, Tailscale, LAN, etc.):

# Example: Ollama running on a remote machine via VPN/Tailscale
REMOTE_OLLAMA_URL=http://<your-remote-ollama-host>:11434

Usage Examples

// Route to remote Ollama (private, no third-party)
analyze_image(image_path="/data/tmp/photo.jpg", task="describe", provider="remote-ollama")

// Specify model explicitly
analyze_image(image_path="/data/tmp/photo.jpg", task="ocr", provider="remote-ollama", model="gemma4:34b")

// Use OpenRouter (cloud-based)
analyze_image(image_path="/data/tmp/photo.jpg", task="answer", provider="openrouter", model="google/gemini-2.0-flash-001")

Testing

# Go unit + integration tests
go test ./...

# Quick environment tests
./tests/test_quick.sh

# Integration test suite
./tests/test_excel_analysis.sh

Docker Sandbox

The Docker sandbox image (mcp-python-sandbox:latest) is used by data_analysis to run LLM-generated Pandas code in isolation.

# Build from the repository root
docker build -f tools/data_analysis/sandbox.Dockerfile -t mcp-python-sandbox:latest .

Toolset Filtering

The server can expose different subsets of tools without code changes, using toolsets defined in configs/toolsets.yaml.

Available Toolsets

ToolsetToolsUse Case
default14 general-purpose tools (echo, weather, kb, web, etc.)End users, general assistance
development10 dev tools + core (opencode_context, codebase_scan, etc.)Developers, coding agents
ocu-investigacion17 tools (6 forenses + kb, web scraping, OCR, transcription, reports, storage)Criminal investigation

Usage

Set the MCP_TOOLSET environment variable in your .env file:

# .env — only expose general-purpose tools
MCP_TOOLSET=default

# .env — expose development tools
MCP_TOOLSET=development

# .env — combine multiple toolsets
MCP_TOOLSET=default,development

# .env — forensic investigation toolset
MCP_TOOLSET=ocu-investigacion

# .env — all tools + forensics
MCP_TOOLSET=default,development,ocu-investigacion

# .env — omit to expose all tools (default behavior)
# (no MCP_TOOLSET set)

Or with Docker directly:

# General toolset
docker run -e MCP_TOOLSET=default -p 8080:8080 sudebaker/mcp-go

# Development toolset
docker run -e MCP_TOOLSET=development -p 8080:8080 sudebaker/mcp-go

# All tools (backward compatible)
docker run -p 8080:8080 sudebaker/mcp-go

How It Works

  1. The server discovers all available tools from tools/<name>/tool.yaml.
  2. If MCP_TOOLSET is set, it loads configs/toolsets.yaml and filters tools by the active toolset(s).
  3. Multiple toolsets can be combined: MCP_TOOLSET=default,development produces the union of both.
  4. The client (Hermes, Claude Desktop, etc.) receives only the filtered tools via tools/list.

The client does not need to know about toolsets. The filtering happens entirely on the server side.

Adding Custom Toolsets

Add a new entry to configs/toolsets.yaml:

  my-team:
    description: "Custom toolset for my team"
    tools:
      - echo
      - datetime
      - kb_search

Then run with:

MCP_TOOLSET=my-team docker compose up -d mcp-server

Documentation

DocumentDescription
QUICKSTART.mdQuick start and verification guide
USAGE.mdFunctional usage per tool
DOCUMENTATION_INDEX.mdDocumentation map
docs/DEVELOPMENT.mdTechnical architecture and development guide
docs/API.mdAPI reference
AGENTS.mdBuild/test commands and conventions

Project Structure

mcp-go/
├── cmd/server/         # Entry point
├── internal/           # Go core (config, executor, transport, etc.)
├── tools/              # Python tools
├── templates/          # HTML/CSS report templates
├── configs/            # YAML configuration
├── deployments/        # Dockerfile + compose
└── tests/              # Go, Python, and shell tests

Tool Management

Tools are defined in configs/config.yaml under the tools: key. Each tool entry specifies the command, arguments, timeout, and input schema.

Toolsets

Toolset definitions in configs/toolsets.yaml are curated lists of tools for specific use cases. See Available Toolsets above.

Adding a Tool

  1. Create tools/my_tool/main.py implementing the JSON stdin/stdout protocol.
  2. Register the tool in configs/config.yaml under the tools: section.
  3. Restart:
docker compose restart mcp-server

Manifest Discovery

Tools are auto-discovered from tools/<tool-name>/. Each subdirectory must contain a tool.yaml manifest:

tools/
├── echo/
│   ├── main.py
│   └── tool.yaml
├── codebase_scan/
│   ├── main.py
│   └── tool.yaml
└── ...

Discovery is enabled by default via TOOLS_DISCOVERY=manifest.

VariableValueDescription
TOOLS_DISCOVERYmanifestEnables manifest-based discovery
TOOLS_DIR/app/toolsDirectory to scan for tool manifests
TOOLS_APPENDtrueKeep config tools and append discovered ones (false = discovered override config)

Adding a Custom Toolset

Add a new entry to configs/toolsets.yaml:

  my_stack:
    description: "My custom tool stack"
    tools:
      - echo
      - datetime
      - kb_search

Then run with MCP_TOOLSET=my_stack. Multiple toolsets can be combined: MCP_TOOLSET=my_stack,default.

For the OCu (criminal investigation) toolset, see the full deployment guide including the required database stack (Memgraph, OpenSearch):

Disabling a Tool

Remove its entry from tools/ or exclude it from the active toolset in configs/toolsets.yaml.

License

See LICENSE.

Ver o original no GitHub

Bom para

Relacionados