AI导哈

AI代理工具服务器

Clara MCP服务器是一个通过标准化工具接口将Clara后端API暴露给AI代理的服务，用于集成内容验证和分析功能。

  • by crazi-co
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 crazi-co/clara-mcp-server

使用说明

Clara MCP服务器

1.概述

这是一个 MCP（模型上下文协议）服务器 它将Clara后端API作为AI代理的工具公开。

Clara提供快速、可靠的工具，用于检查在线内容、验证声明、分析帖子和视频，以及了解互联网上的真假——所有这些都在一个地方。

MCP服务器使AI代理能够通过标准化的工具界面与Clara的API进行交互，从而可以轻松地将Clara的功能集成到代理工作流程中。

2.快速入门

2.1安装

  1. 克隆存储库：

    git clone https://github.com/crazi-co/clara-mcp-server.git
cd clara-mcp-server

  2. 安装依赖项：

    pip install -r requirements.txt

  3. 设置环境变量：

    • 复制 .env.example 到 .env
    • 填写您的凭据：
      USER_ID=your_user_id
API_KEY_TOKEN=your_api_key_token
PORT=8000

    注： 您可以设置 USER_ID 和 API_KEY_TOKEN 在 .env 文件，或通过标头从您的AI代理传递它们：

    • Authorization: Bearer <api_key_token>
    • User-Id: <user_id>

  4. 运行MCP服务器：

    python run.py

服务器将在您的 .env 文件（默认值：8000）。

3.堆叠和核心组件

3.1技术栈

  • 语言： python
  • MCP框架： FastMCP
  • Web框架： Starlette（用于SSE端点）
  • HTTP客户端： 请求（具有会话管理和重试策略）
  • 服务器： Uvicorn

3.2架构

  1. MCP服务器（FastMCP）

    • 展示Clara API端点作为MCP工具
    • 为代理通信提供SSE（服务器发送事件）流
    • 处理工具注册和执行

  2. 工具层

    • 按模块组织： user, transaction, task, agent, stripe, misc
    • 每个工具都映射到一个Clara API端点
    • 工具处理请求格式化和响应解析

  3. 请求实用程序

    • 具有会话管理的集中式HTTP客户端
    • 瞬态错误的自动重试策略
    • 意外异常的错误日志记录

  4. 身份验证中间件

    • 验证来自的承载令牌 Authorization 头球
    • 提取物 User-Id 从标题
    • 返回401缺少或无效的凭据

4.身份验证和授权

4.1 API密钥认证

  • 头球 Authorization: Bearer <api-key-token>
  • 用户ID标题： User-Id: <user-id>

经过身份验证的请求都需要这两个标头。

4.2请求流

  1. 客户端发送请求 Authorization 和 User-Id 标头
  2. 中间件验证：
    • 授权标头必须以“Bearer”开头
    • 两者 user_id 和 api_key_token 必须出席
  3. 如果验证失败→ 回报 401 Unauthorized
  4. 如果有效→ 请求继续到MCP服务器

5.可用工具

MCP服务器将以下Clara API端点作为工具公开：

5.1用户工具(user.*)

  • user.view
    • 查看用户帐户详细信息
    • 返回：用户信息，包括信用、电子邮件、偏好等。

5.2交易工具(transaction.*)

  • transaction.view_all

    • 使用分页查看所有用户事务
    • 参数： limit （int）， offset （int）
    • 返回：事务对象数组

  • transaction.view

    • 查看特定交易
    • 参数： transaction_id （字符串）
    • 退货：交易明细

5.3任务工具(task.*)

  • task.view_all

    • 使用分页查看所有用户任务
    • 参数： limit （字符串）， offset （字符串）
    • 返回：任务对象数组

  • task.view

    • 查看特定任务
    • 参数： task_id （字符串）
    • 返回：任务详细信息，包括状态和结果

5.4代理工具(agent.*)

  • agent.analyze_transaction
    • 使用Analytiq的代理在Base上分析交易
    • 最低学分要求：10
    • 参数： transaction_hash （字符串）
    • 返回：任务对象（分析异步运行）

5.5条纹工具(stripe.*)

  • stripe.rate

    • 获取当前信贷利率和定价
    • 返回：包含限额和每美元信用额度的费率信息

  • stripe.portal

    • 创建Stripe客户门户会话以进行计费管理
    • 返回：门户URL

  • stripe.buy

    • 通过Stripe结账购买积分
    • 参数： amount （int）， return_path （字符串）
    • 返回：签出会话URL

5.6其他工具(misc.*)

  • misc.health

    • 检查API运行状况
    • 返回：服务状态信息

  • misc.version

    • 获取API版本
    • 返回：当前API版本

6.配置

6.1环境变量

  • USER_ID：默认用户ID（可由以下内容覆盖 User-Id 头球
  • API_KEY_TOKEN：默认API密钥令牌（可由重写 Authorization 头球
  • PORT：服务器端口（默认值：8000）
  • BASE_URL：Clara API基本URL（默认值： http://localhost:5001/api/v1)

7.API响应处理

7.1响应格式

所有工具都以以下格式返回JSON响应：

{
  "data": {...},
  "message": "Success message",
  "status": "success"
}

7.2错误处理

  • API错误（4xx，5xx）：按响应中的原样返回（不作为例外处理）
  • 网络/连接错误：记录并作为异常重新提出
  • 身份验证错误：中间件返回401 HTTP响应

7.3重试策略

请求实用程序包括以下内容的自动重试：

  • 状态代码：429、502、503、504
  • 最大重试次数：3
  • 退避系数：1

注：500个错误 不 重试，因为它们表示有效的API响应。

8.MCP协议

8.1终点

  • GET /sse：用于代理通信的服务器发送事件流
  • POST /messages：MCP消息端点

8.2工具命名约定

工具使用点符号命名： <module>.<action>

示例：

  • user.view
  • transaction.view_all
  • stripe.buy

9.发展

9.1项目结构

.
├── app/
│   ├── data/           # Global data and configuration
│   ├── tools/          # MCP tool implementations
│   │   ├── user.py
│   │   ├── transaction.py
│   │   ├── task.py
│   │   ├── agent.py
│   │   ├── stripe.py
│   │   └── misc.py
│   └── utils/          # Utility functions
│       └── request.py   # HTTP request helper
├── run.py              # Server entry point
└── requirements.txt    # Python dependencies

9.2添加新工具

  1. 在中创建或更新相应的工具文件 app/tools/
  2. 定义一个静态方法 @app.data.mcp.tool(name = "module.action") 装饰器
  3. 使用 make_request() 从 app.utils.request 用于HTTP调用
  4. 包含正确的类型提示和文档字符串

例子：

@staticmethod
@app.data.mcp.tool(name = "module.action")
def action(param: str) -> Dict[str, Any]:
    """Tool description."""
    return make_request(
        method = "GET",
        url = f"{app.data.base_url}/endpoint",
        headers = app.data.headers
    )

10.总结

此MCP服务器为AI代理提供了一个标准化的接口，用于与Clara的API进行交互。它

  • 将Clara端点作为MCP工具公开
  • 处理身份验证和授权
  • 提供强大的错误处理和重试逻辑
  • 维护会话管理以实现高效的HTTP请求
  • 支持SSE进行实时代理通信

服务器设计为：

  • 无状态：每个请求都是自包含的
  • 可扩展：通过实现Clara API端点，轻松添加新工具
  • 可靠的：自动重试和全面的错误处理

相关 MCP