使用说明

项目简介

本项目 'aipolabs-mcp' 提供了两种 Model Context Protocol (MCP) 服务器，旨在帮助开发者更轻松地将 ACI.dev 平台上的功能（工具）集成到 LLM 应用中。它允许 LLM 客户端（如 Claude Desktop, Cursor）通过标准 MCP 协议调用 ACI.dev 托管的工具。

主要功能点

1. 两种服务器类型：

   • Apps Server: 直接暴露指定应用的工具，工具列表清晰可见，适用于需要明确控制工具范围的场景。
   • Unified Server: 提供两个元工具 ('ACI_SEARCH_FUNCTIONS_WITH_INTENT' 和 'ACI_EXECUTE_FUNCTION')，允许 LLM 客户端根据意图动态发现和执行 ACI.dev 平台上的所有工具，无需预先加载大量工具，更灵活高效。

2. 工具访问: 通过 MCP 协议，以标准化的方式向 LLM 客户端提供 ACI.dev 平台上的工具。

3. 会话管理与能力声明: MCP 服务器负责处理客户端连接，声明自身提供的工具能力。

4. 多种传输协议支持: 支持 Stdio 和 SSE 传输协议，满足不同应用场景的需求。

安装步骤

1. 安装 'uvx': 如果您还没有安装 'uvx'，请先安装它。

   curl -sSf https://install.pypa.io/get-pip.py | python3 -
   pip install uv
   

2. 配置 ACI.dev API 密钥: 在您的环境中设置 'AIPOLABS_ACI_API_KEY' 环境变量，该密钥是您在 ACI.dev 平台创建项目的 API 密钥。
3. 配置应用和授权: 在 ACI.dev 平台配置您的应用，并在项目设置中为您的代理配置 'allowed_apps'。
4. 链接账户: 在 ACI.dev 平台链接您的应用账户，并记录 '--linked-account-owner-id'，后续启动服务器时需要使用。

服务器配置

1. Apps Server 配置 (针对 Claude Desktop 或 Cursor 等 MCP 客户端)

Apps Server 允许您指定要暴露的应用工具。以下是针对 Claude Desktop 和 Cursor 的配置示例：

Claude Desktop 配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "aipolabs-mcp-apps": {
      "command": "uvx",
      "args": ["aipolabs-mcp", "apps-server", "--apps", "BRAVE_SEARCH,GMAIL", "--linked-account-owner-id", "<替换为您的 linked_account_owner_id>"]
    }
  }
}

参数说明:

• 'command': 启动 MCP 服务器的命令，这里使用 'uvx' 运行 'aipolabs-mcp' 包。
• 'args': 传递给 'aipolabs-mcp apps-server' 命令的参数列表。
  • '--apps': 指定要使用的应用列表，多个应用名用逗号分隔，例如 "BRAVE_SEARCH,GMAIL"。请替换为您需要使用的应用名称。
  • '--linked-account-owner-id': 您的 linked account owner ID，用于授权工具调用，请替换为您的实际 ID。

Cursor 配置 (mcp.json):

{
    "mcpServers": {
      "aipolabs-mcp-apps": {
        "command": "uvx",
        "args": ["aipolabs-mcp", "apps-server", "--apps", "BRAVE_SEARCH,GMAIL", "--linked-account-owner-id", "<替换为您的 linked_account_owner_id>"],
        "env": {
            "AIPOLABS_ACI_API_KEY": "<替换为您的 AIPOLABS_ACI_API_KEY 环境变量值>"
        }
      }
    }
  }

参数说明:

• 'command': 同 Claude Desktop 配置。
• 'args': 同 Claude Desktop 配置。
• 'env': 环境变量设置。
  • 'AIPOLABS_ACI_API_KEY': 您的 ACI.dev API 密钥，请替换为您的实际密钥。

2. Unified Server 配置 (针对 Claude Desktop 或 Cursor 等 MCP 客户端)

Unified Server 提供动态工具发现能力。以下是针对 Claude Desktop 和 Cursor 的配置示例：

Claude Desktop 配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "aipolabs-mcp-unified": {
      "command": "uvx",
      "args": ["aipolabs-mcp", "unified-server", "--linked-account-owner-id", "<替换为您的 linked_account_owner_id>"]
    }
  }
}

Cursor 配置 (mcp.json):

{
    "mcpServers": {
      "aipolabs-mcp-unified": {
        "command": "uvx",
        "args": ["aipolabs-mcp", "unified-server", "--linked-account-owner-id", "<替换为您的 linked_account_owner_id>"],
        "env": {
            "AIPOLABS_ACI_API_KEY": "<替换为您的 AIPOLABS_ACI_API_KEY 环境变量值>"
        }
      }
    }
  }

参数说明:

• 'command': 启动 MCP 服务器的命令。
• 'args': 传递给 'aipolabs-mcp unified-server' 命令的参数列表。
  • '--linked-account-owner-id': 您的 linked account owner ID，请替换为您的实际 ID。
• 'env': 环境变量设置 (仅 Cursor 配置需要)。
  • 'AIPOLABS_ACI_API_KEY': 您的 ACI.dev API 密钥，请替换为您的实际密钥。

基本使用方法

1. 启动 MCP 服务器: 根据您选择的服务器类型 (Apps Server 或 Unified Server) 和配置，在终端中运行相应的 'uvx' 命令。例如，启动 Unified Server (stdio 传输):

   uvx aipolabs-mcp unified-server --linked-account-owner-id <您的 LINKED_ACCOUNT_OWNER_ID>
   

2. 配置 MCP 客户端: 将上述生成的 JSON 配置添加到您的 MCP 客户端 (如 Claude Desktop, Cursor) 的配置文件中。
3. 在 LLM 应用中使用工具: 在您的 LLM 应用中，客户端会自动连接到 MCP 服务器，并根据服务器提供的工具列表或动态发现能力来调用 ACI.dev 平台上的工具。

注意: 请确保您已正确配置 ACI.dev 平台的相关设置，包括 API 密钥、应用配置和账户链接，否则 MCP 服务器可能无法正常工作。