FluidMCP CLI

Uma ferramenta de linha de comando para executar servidores MCP a partir de um único arquivo, com suporte para resolução automática de dependências, configuração de ambiente e instalação de pacotes de fontes locais ou S3.

GitHub
8
Experimente este MCPPatrocinado

Documentação

🌀 FluidMCP CLI

Orquestre múltiplos servidores MCP com um único arquivo de configuração

⚡ Início Rápido - Execute Múltiplos Servidores MCP

O principal poder do FluidMCP é executar múltiplos servidores MCP a partir de um único arquivo de configuração em um endpoint FastAPI unificado.

1. Crie um Arquivo de Configuração

Crie um arquivo config.json com seus servidores MCP:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@google-maps/mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    }
  }
}

2. Inicie Todos os Servidores

fluidmcp run config.json --file --start-server

Isso irá:

  • Instalar e configurar todos os servidores MCP listados na sua configuração
  • Iniciá-los através de um gateway FastAPI unificado
  • Disponibilizá-los em http://localhost:8099
  • Fornecer documentação automática da API em http://localhost:8099/docs

fluidmcp_file_

🚀 Recursos

  • 📁 Orquestração Multi-Servidor

    • Defina múltiplos servidores MCP em um único arquivo de configuração JSON
    • Inicie todos os servidores com um único comando: fluidmcp run --file <config.json>
    • Gateway FastAPI unificado servindo todas as suas ferramentas MCP

  • 📦 Gerenciamento de Pacotes

    • Instale pacotes MCP com fluidmcp install author/package@version
    • Resolução automática de dependências e configuração do ambiente
    • Suporte para servidores MCP npm, Python e personalizados

  • 🚀 Gateway FastAPI

    • Endpoints HTTP unificados para todas as ferramentas MCP
    • Suporte a streaming Server-Sent Events (SSE)
    • Documentação Swagger em /docs

  • 🔐 Segurança e Autenticação

    • Autenticação por token Bearer
    • Modo seguro com comunicações criptografadas
    • Criptografia de variáveis de ambiente para chaves de API

📥 Instalação

pip install fluidmcp

🔧 Padrões Alternativos de Uso

Instalar Pacotes Individuais

fluidmcp install author/package@version

Listar Pacotes Instalados

fluidmcp list

Executar Pacote Individual

fluidmcp run author/package@version --start-server

🔐 Uso Avançado

Modo Seguro com Autenticação

Execute com autenticação por token bearer:

fluidmcp run config.json --file --secure --token your_token --start-server

fluidmcp_secure_1

após autorização

fluidmcp_secure_2

☁️ Executar a partir de URL S3

Execute a configuração diretamente do S3:

fluidmcp run "https://bucket.s3.amazonaws.com/config.json" --s3

Opções Comuns:

  • --start-server – Inicia o servidor FastAPI
  • --master – Usa configuração orientada por S3
  • --file – Executa a partir de config.json local
  • --s3 – Executa a partir de URL S3
  • --secure – Ativa o modo de token seguro
  • --token <token> – Token bearer personalizado
  • --verbose – Ativa log detalhado (nível DEBUG)

Executar Todos os Pacotes Instalados

fluidmcp run all --start-server

📂 Modos de Execução

🧠 Modo Mestre (S3 Centralizado)

fluidmcp install author/package@version --master
fluidmcp run all --master

🧩 Variáveis de Ambiente

# S3 Credentials (used in --master mode)
export S3_BUCKET_NAME="..."
export S3_ACCESS_KEY="..."
export S3_SECRET_KEY="..."
export S3_REGION="..."


# Registry access
export MCP_FETCH_URL="https://registry.fluidmcp.com/fetch-mcp-package"
export MCP_TOKEN="..."

Editar Ambiente

fluidmcp edit-env <author/package@version>

Mostrar Versão

fluidmcp --version

Exibe a versão do FluidMCP, a versão do Python e o caminho de instalação.

Validar Configuração

# Validate a local configuration file
fluidmcp validate config.json --file

# Validate an installed package
fluidmcp validate author/package@version

O comando validate verifica:

  • Estrutura e resolução do arquivo de configuração
  • Disponibilidade de comandos no PATH do sistema
  • Variáveis de ambiente obrigatórias (marcadas com required: true)
  • Variáveis de ambiente e tokens opcionais
  • Existência de Metadata.json para pacotes instalados

Observação: A busca por variáveis de ambiente não diferencia maiúsculas de minúsculas. Por exemplo, se sua configuração especificar github_token, o validador verificará tanto github_token quanto GITHUB_TOKEN no seu ambiente.

O comando distingue entre erros (problemas fatais) e avisos (problemas não fatais):

Erros (código de saída 1):

  • Comandos ausentes no PATH
  • Variáveis de ambiente obrigatórias ausentes
  • Falhas na resolução da configuração

Avisos (código de saída 0):

  • Variáveis de ambiente opcionais ausentes
  • Variáveis TOKEN ausentes não marcadas explicitamente como obrigatórias

Exemplos de saída:

Sucesso:

✔ Configuration is valid with no issues found.

Somente com avisos:

⚠️  Configuration is valid with warnings:
  - Optional env var 'DEBUG_MODE' is not set (server: test-server)
  - Token env var 'GITHUB_TOKEN' is not set (server: github-server)

✔ No fatal errors found. You may proceed, but consider addressing the warnings above.

Com erros:

❌ Configuration validation failed with errors:
  - Command 'nonexistent-command' not found in PATH (server: test-server)
  - Missing required env var 'API_KEY' (server: test-server)

⚠️  Warnings:
  - Optional env var 'DEBUG_MODE' is not set (server: test-server)

📁 Estrutura de Diretórios

.fmcp-packages/
└── Author/
    └── Package/
        └── Version/
            ├── metadata.json
            └── [tool files]

📑 Exemplo de metadata.json

{
  "mcpServers": {
    "maps": {
      "command": "npx",
      "args": ["-y", "@package/server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

🧪 Experimente um Servidor MCP

fluidmcp install Google_Maps/google-maps@0.6.2
fluidmcp run all

Em seguida, chame-o usando:

import requests, json


url = "http://localhost:8099/google-maps/mcp"
payload = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "maps_search_places",
    "arguments": {
      "query": "coffee shops in San Francisco"
    }
  }
}
response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))

📡 Streaming com SSE

curl -N -X POST http://localhost:8099/package/sse \
  -H "Content-Type: application/json" \
  -d @payload.json
  • sse/start
  • sse/stream
  • sse/message
  • sse/tools_call

Útil para LLMs, web scraping ou fluxos de trabalho de IA que transmitem dados.

📸 Demonstração

Instalando um pacote individual

fluidmcp_install

Executando um pacote individual

fluidmcp_run_individual (2)

Editar ambiente de um pacote

fluidmcp_edit-env (2)

🤝 Contribua

O FluidMCP está aberto para colaboração. Recebemos contribuições da comunidade!

  • Guia de Contribuição: Veja CONTRIBUTING.md para configuração de desenvolvimento e diretrizes
  • Relatar Problemas: Abra uma issue no GitHub
  • Enviar PRs: Siga nossas diretrizes de contribuição para enviar pull requests

📌 Licença

GNU General Public License v3.0