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

1. 安装依赖项：

   pip install -r requirements.txt

1. 设置环境变量：

- 复制 .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 - User-Id:

1. 运行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（服务器发送事件）流 - 处理工具注册和执行

1. 工具层

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

1. 请求实用程序

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

1. 身份验证中间件

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

______________________________________________________________________

4.身份验证和授权

4.1 API密钥认证

• 头球 Authorization: Bearer
• 用户ID标题： User-Id:

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

4.2请求流

1. 客户端发送请求 Authorization 和 User-Id 标头
2. 中间件验证：

- 授权标头必须以“Bearer”开头 - 两者 user_id 和 api_key_token 必须出席

1. 如果验证失败→ 回报 401 Unauthorized
2. 如果有效→ 请求继续到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工具命名约定

工具使用点符号命名： .

示例：

• 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端点，轻松添加新工具
• 可靠的：自动重试和全面的错误处理