接入文档

一、概述

财税AI SkillHub 是一个面向 AI Agent 的财税能力开放平台。通过 MCP (Model Context Protocol) 协议，您可以让您的 AI 助手（Cursor、Claude Desktop 等）获得以下专业财税能力：

• 发票AI解析 — 智能识别发票信息，自动提取关键字段
• 商品赋码 — 根据商品名称自动匹配税收分类编码
• 财税AI问答 — 智能财税咨询，税法解读、会计处理

二、认证方式

SkillHub 采用 JWT Token 认证体系，所有 API 调用均需携带有效的 Access Token。

2.1 获取 Token

登录 SkillHub 门户后，在控制台生成 JWT 凭证（Access Token + Refresh Token）：

# 登录后访问控制台，点击"生成凭证"即可获取 Token 对
GET /api/credentials/generate

返回的 Access Token 有效期为 1 小时，Refresh Token 有效期为 30 天。

2.2 使用 Token 调用 API

在请求头中携带 Bearer Token：

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://skillhub.a-i-tools.top/v1/tools/call

2.3 MCP 模式接入

适用于 AI Agent 通过 MCP 协议接入。在 MCP 配置中设置 Authorization 头：

{
  "mcpServers": {
    "caishui-ai": {
      "url": "https://skillhub.a-i-tools.top/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

三、API 端点

3.1 工具调用端点

方法	路径	说明	认证
GET	/v1/tools/list	获取可用工具列表	JWT
POST	/v1/tools/call	调用指定工具	JWT
POST	/mcp	MCP JSON-RPC 端点	JWT
GET	/health	健康检查	无

3.2 技能管理端点

方法	路径	说明	认证
GET	/v1/skills/list	获取技能列表	JWT
GET	/v1/skills/{skill_key}	获取技能详情	JWT
GET	/v1/skills/{skill_key}/download	下载技能包（zip）	JWT
GET	/v1/skills/{skill_key}/tools	获取技能关联工具	JWT

API 版本化：所有 REST API 端点支持 /v1/ 和 /latest/ 两种路径。

四、MCP 协议说明

网关实现了完整的 MCP JSON-RPC 2.0 协议，支持以下方法：

• initialize — 初始化握手
• tools/list — 动态能力发现（仅返回有权限的工具）
• tools/call — 工具调用

五、Token 管理

通用 Token 端点

• POST /auth/refresh — 用 Refresh Token 换取新 Token 对
• POST /auth/revoke — 撤销当前 Token

注意：API Key 认证方式已废弃。所有外部调用统一使用 JWT Token 认证。

六、限流说明

网关对 API 调用实施双重限流：

• 用户级：默认 10 QPS
• Skill 级：默认 5 QPS

超出限流时会返回 HTTP 429 状态码。

七、定价模式

模式	说明	获取方式
免费	所有登录用户自动可用	微信扫码登录即自动获取
试用	有期限和次数限制	微信扫码登录后点击开通
付费	按次计费	微信扫码登录后支付开通