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 助手。

📞 支持

• 🐛 報告問題
• 💬 討論
• 📖 文檔