ACP-MCP-Server

ACP-MCP-Server

Um servidor de ponte que conecta agentes do Agent Communication Protocol (ACP) com clientes do Model Context Protocol (MCP), permitindo integração perfeita entre agentes de IA baseados em ACP e ferramentas compatíveis com MCP, como o Claude Desktop.

✨ Recursos

• 🔄 Ponte de Protocolo: Conecta agentes ACP com clientes MCP de forma transparente
• 🚀 Múltiplos Transportes: Suporta STDIO, SSE e HTTP Streamable
• 🤖 Descoberta de Agentes: Descoberta e registro automáticos de agentes ACP
• 🧠 Roteamento Inteligente: Roteamento inteligente de solicitações para os agentes apropriados
• 🔄 Suporte Assíncrono: Suporte completo para operações síncronas e assíncronas
• 💬 Sessões Interativas: Suporte para interações de múltiplas etapas com agentes
• 🌐 Multimodal: Lida com texto, imagens e outros tipos de conteúdo

🚀 Início Rápido

Instalação

# Install from PyPI
pip install acp-mcp-server

# Or use uvx for isolated execution
uvx acp-mcp-server

Uso Básico

# Run with STDIO (default, for Claude Desktop)
acp-mcp-server

# Run with SSE transport
acp-mcp-server --transport sse --port 8000

# Run with HTTP transport
acp-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000

# Connect to different ACP server
acp-mcp-server --acp-url http://localhost:8001

Usando com o Claude Desktop

Adicione à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "acp-bridge": {
      "command": "uvx",
      "args": ["acp-mcp-server"]
    }
  }
}

📋 Requisitos

• Python 3.11+
• Servidor ACP em execução com agentes
• FastMCP para implementação do protocolo

🔧 Configuração

Variáveis de Ambiente

• ACP_BASE_URL: URL do servidor ACP (padrão: http://localhost:8000)

Opções de Linha de Comando

usage: acp-mcp-server [-h] [--transport {stdio,sse,streamable-http}] [--host HOST] [--port PORT] [--path PATH] [--acp-url ACP_URL] [--version]

options:
  -h, --help            show this help message and exit
  --transport {stdio,sse,streamable-http}
                        Transport protocol (default: stdio)
  --host HOST           Host address for HTTP transports (default: 127.0.0.1)
  --port PORT           Port number for HTTP transports (default: 8000)
  --path PATH           URL path for HTTP transports (default: /mcp)
  --acp-url ACP_URL     ACP server URL (default: http://localhost:8000)
  --version             show program's version number and exit

🛠️ Ferramentas Disponíveis

O servidor de ponte fornece várias ferramentas MCP:

Gerenciamento de Agentes

• discover_acp_agents: Descubra agentes ACP disponíveis
• get_agent_info: Obtenha informações detalhadas sobre agentes específicos

Execução de Agentes

• run_acp_agent: Execute agentes em modos síncrono/assíncrono
• get_async_run_result: Recupere resultados de execuções assíncronas
• list_active_runs: Liste todas as execuções de agentes ativas

Roteamento Inteligente

• smart_route_request: Roteie solicitações de forma inteligente para os melhores agentes
• test_routing: Teste a lógica de roteamento sem execução
• add_routing_rule: Adicione regras de roteamento personalizadas
• list_routing_strategies: Visualize todas as estratégias de roteamento

Sessões Interativas

• start_interactive_agent: Inicie sessões interativas com agentes
• provide_user_input: Forneça entrada para agentes em espera
• list_pending_interactions: Visualize interações pendentes

Processamento de Mensagens

• convert_acp_message: Converta entre formatos ACP e MCP
• analyze_message_content: Analise a estrutura e o conteúdo das mensagens

🏗️ Arquitetura

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  ACP-MCP Bridge │    │   ACP Agents    │
│ (Claude Desktop)│◄──►│     Server      │◄──►│ (echo, chat,    │
│                 │    │                 │    │  translate...)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
       │                         │                       │
   MCP Protocol            Protocol Bridge         ACP Protocol
  (STDIO/SSE/HTTP)        (FastMCP + aiohttp)    (HTTP/WebSocket)

🔌 Modos de Transporte

STDIO (Padrão)

Perfeito para integração com o Claude Desktop:

acp-mcp-server

SSE (Server-Sent Events)

Para aplicações web e streaming:

acp-mcp-server --transport sse --port 8000

HTTP Streamable

Para integração com API REST:

acp-mcp-server --transport streamable-http --port 9000

🐳 Docker

Início Rápido com Docker

# Build the image
docker build -t acp-mcp-server .

# Run with Streamable HTTP transport
docker run -p 9000:9000 acp-mcp-server

# Run with SSE transport
docker run -p 8000:8000 acp-mcp-server \
  --transport sse --host 0.0.0.0 --port 8000

# Connect to custom ACP server
docker run -p 9000:9000 -e ACP_BASE_URL=http://my-acp-server:8001 acp-mcp-server

Usando Docker Compose

# Run HTTP transport service
docker-compose up acp-mcp-http

# Run SSE transport service
docker-compose up acp-mcp-sse

# Run both services
docker-compose up

# Run development mode with live code reload
docker-compose --profile dev up acp-mcp-dev

Imagem Docker de Produção

Para implantações em produção, use o Dockerfile de múltiplas etapas:

# Build production image
docker build -f Dockerfile.prod -t acp-mcp-server:prod .

# Run production container
docker run -d \
  --name acp-mcp-server \
  --restart unless-stopped \
  -p 9000:9000 \
  -e ACP_BASE_URL=http://your-acp-server:8000 \
  acp-mcp-server:prod

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🔗 Projetos Relacionados

• FastMCP - Framework de servidor MCP rápido e Pythonico
• ACP SDK - SDK do Protocolo de Comunicação de Agentes
• Claude Desktop - Assistente de IA com suporte a MCP

📞 Suporte

• 🐛 Reportar Problemas
• 💬 Discussões
• 📖 Documentação