ACP MCP Server

🚀 ACP-MCP-Server

ACP-MCP-Server 是一座桥梁服务器，它将 Agent Communication Protocol (ACP) 代理与 Model Context Protocol (MCP) 客户端连接起来，实现了基于 ACP 的 AI 代理与支持 MCP 的工具（如 Claude Desktop）之间的无缝集成。

🚀 快速开始

安装

# 从 PyPI 安装
pip install acp-mcp-server

# 或者使用 uvx 进行隔离执行
uvx acp-mcp-server

基础用法

# 使用 STDIO 运行（默认，适用于 Claude Desktop）
acp-mcp-server

# 使用 SSE 传输运行
acp-mcp-server --transport sse --port 8000

# 使用 HTTP 传输运行
acp-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000

# 连接到不同的 ACP 服务器
acp-mcp-server --acp-url http://localhost:8001

与 Claude Desktop 配合使用

添加到你的 Claude Desktop 配置中：

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

✨ 主要特性

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

📦 安装指南

# 从 PyPI 安装
pip install acp-mcp-server

# 或者使用 uvx 进行隔离执行
uvx acp-mcp-server

💻 使用示例

基础用法

# 使用 STDIO 运行（默认，适用于 Claude Desktop）
acp-mcp-server

# 使用 SSE 传输运行
acp-mcp-server --transport sse --port 8000

# 使用 HTTP 传输运行
acp-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000

# 连接到不同的 ACP 服务器
acp-mcp-server --acp-url http://localhost:8001

高级用法

# 与 Claude Desktop 配合使用，添加到配置中
{
  "mcpServers": {
    "acp-bridge": {
      "command": "uvx",
      "args": ["acp-mcp-server"]
    }
  }
}

📚 详细文档

要求

• Python 3.11 及以上版本。
• 运行带有代理的 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            显示此帮助信息并退出
  --transport {stdio,sse,streamable-http}
                        传输协议（默认：stdio）
  --host HOST           HTTP 传输的主机地址（默认：127.0.0.1）
  --port PORT           HTTP 传输的端口号（默认：8000）
  --path PATH           HTTP 传输的 URL 路径（默认：/mcp）
  --acp-url ACP_URL     ACP 服务器 URL（默认：http://localhost:8000）
  --version             显示程序的版本号并退出

可用工具

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

代理管理

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

代理执行

• run_acp_agent：以同步/异步模式执行代理。
• get_async_run_result：从异步执行中检索结果。
• list_active_runs：列出所有活跃的代理运行。

智能路由

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

交互式会话

• start_interactive_agent：启动交互式代理会话。
• provide_user_input：向等待的代理提供输入。
• 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

可流式传输的 HTTP

适用于 REST API 集成：

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

Docker

使用 Docker 快速开始

# 构建镜像
docker build -t acp-mcp-server .

# 使用可流式传输的 HTTP 传输运行
docker run -p 9000:9000 acp-mcp-server

# 使用 SSE 传输运行
docker run -p 8000:8000 acp-mcp-server \
  --transport sse --host 0.0.0.0 --port 8000

# 连接到自定义 ACP 服务器
docker run -p 9000:9000 -e ACP_BASE_URL=http://my-acp-server:8001 acp-mcp-server

使用 Docker Compose

# 运行 HTTP 传输服务
docker-compose up acp-mcp-http

# 运行 SSE 传输服务
docker-compose up acp-mcp-sse

# 同时运行两个服务
docker-compose up

# 以开发模式运行，支持实时代码重新加载
docker-compose --profile dev up acp-mcp-dev

生产 Docker 镜像

对于生产部署，请使用多阶段 Dockerfile：

# 构建生产镜像
docker build -f Dockerfile.prod -t acp-mcp-server:prod .

# 运行生产容器
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

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🔗 相关项目

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

📞 支持

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