ACP-MCP-Server

ACP-MCP-Server

桥接服务，可将 Agent Communication Protocol (ACP) Agent 与 Model Context Protocol (MCP) 客户端连接起来，实现基于 ACP 的 AI Agent 与 Claude Desktop 等兼容 MCP 的工具之间的无缝集成。

✨ 功能

• 🔄 协议桥接：无缝连接 ACP Agent 与 MCP 客户端
• 🚀 多种传输方式：支持 STDIO、SSE 和 Streamable HTTP
• 🤖 Agent 发现：自动发现并注册 ACP Agent
• 🧠 智能路由：将请求智能路由至合适的 Agent
• 🔄 异步支持：全面支持同步和异步操作
• 💬 交互式会话：支持多轮 Agent 交互
• 🌐 多模态：处理文本、图像和其他内容类型

🚀 快速开始

安装

# Install from PyPI
pip install acp-mcp-server

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

基本用法

# 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

在 Claude Desktop 中使用

添加到 Claude Desktop 配置中：

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

📋 要求

• Python 3.11+
• 正在运行且包含 Agent 的 ACP 服务
• 用于协议实现的 FastMCP

🔧 配置

环境变量

• ACP_BASE_URL：ACP 服务 URL（默认值：http://localhost:8000）

命令行选项

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

🛠️ 可用工具

该桥接服务提供多个 MCP 工具：

Agent 管理

• discover_acp_agents：发现可用的 ACP Agent
• get_agent_info：获取特定 Agent 的详细信息

Agent 执行

• run_acp_agent：以同步/异步模式执行 Agent
• get_async_run_result：获取异步执行的结果
• list_active_runs：列出所有正在运行的 Agent

智能路由

• smart_route_request：将请求智能路由至最合适的 Agent
• test_routing：在不执行的情况下测试路由逻辑
• add_routing_rule：添加自定义路由规则
• list_routing_strategies：查看所有路由策略

交互式会话

• start_interactive_agent：启动交互式 Agent 会话
• provide_user_input：向正在等待的 Agent 提供输入
• list_pending_interactions：查看待处理的交互

消息处理

• convert_acp_message：在 ACP 和 MCP 格式之间进行转换
• analyze_message_content：分析消息结构和内容

🏗️ 架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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)

🔌 传输模式

STDIO（默认）

非常适合与 Claude Desktop 集成：

acp-mcp-server

SSE（服务器发送事件）

适用于 Web 应用和流式传输：

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

Streamable HTTP

适用于 REST API 集成：

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

🐳 Docker

使用 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

使用 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

生产环境 Docker 镜像

生产环境部署请使用多阶段 Dockerfile：

# 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

🤝 参与贡献

欢迎贡献！欢迎提交 Pull Request。

📄 许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。

🔗 相关项目

• FastMCP - 快速、符合 Python 风格的 MCP 服务框架
• ACP SDK - Agent Communication Protocol SDK
• Claude Desktop - 支持 MCP 的 AI 助手

📞 支持

• 🐛 报告问题
• 💬 讨论
• 📖 文档