使用说明

项目简介

Subtotal AI Toolkit 是一个工具库，旨在帮助开发者将流行的 Agent 框架（如 LangChain、CrewAI、Vercel's AI SDK）和 Model Context Protocol (MCP) 与 Subtotal API 集成。本仓库的 'modelcontextprotocol' 模块提供了一个基于 MCP 标准的服务器实现，允许 LLM 客户端通过 MCP 协议调用 Subtotal API 提供的功能，例如获取商家信息、创建连接、查询购买记录等。

主要功能点

MCP 服务器实现: 基于 Model Context Protocol 标准协议构建，可以作为 MCP 服务器运行，为 LLM 应用提供上下文服务。
Subtotal API 集成: 内置了对 Subtotal 财务数据 API 的支持，通过工具的形式暴露 API 功能。
工具化能力: 提供了一系列预定义的工具 (Tools)，如 'getMerchants'（获取商家列表）、'createConnection'（创建连接）、'getPurchases'（获取购买记录）等，方便 LLM 调用。
可配置工具: 允许用户配置允许 LLM 调用的工具列表，实现权限控制和功能定制。
Stdio 传输协议: 默认使用 Stdio 作为 MCP 服务器的传输协议，易于部署和集成。

安装步骤

安装 npm 包: 如果你的 MCP 客户端环境支持 npm，可以直接安装 '@subtotal-inc/mcp' 包。
```
npm install @subtotal-inc/mcp
```
配置 Subtotal API 密钥: 你需要拥有 Subtotal 账户的 API 密钥。请访问 Subtotal Dashboard 获取。

服务器配置

MCP 客户端需要配置连接 MCP 服务器的命令和参数。以下是针对 'ai-toolkit' MCP 服务器的配置信息：

{
  "serverName": "SubtotalMCP",
  "command": "npx",
  "args": [
    "-y",
    "@subtotal-inc/mcp",
    "--tools=all",
    "--subtotal-secret-key=<YOUR_SUBTOTAL_SECRET_KEY>"
  ],
  "description": "Subtotal MCP Server",
  "transport": "stdio"
}

参数说明:

'serverName': 自定义服务器名称，例如 "SubtotalMCP"。
'command': 运行 MCP 服务器的命令，这里使用 'npx' 来执行 npm 包。
'args': 传递给 'npx @subtotal-inc/mcp' 命令的参数列表：
- '-y': 'npx' 参数，自动确认安装包。
- '@subtotal-inc/mcp': 要执行的 npm 包名，即 Subtotal MCP 服务器。
- '--tools=all': 指定启用的工具，'all' 表示启用所有可用工具。你也可以替换为具体的工具列表，例如 '--tools=get-merchants,get-purchases'。可用的工具包括：'get-purchases', 'get-purchase-details', 'create-connection', 'create-merchant-link-url', 'get-merchants'。
- '--subtotal-secret-key=<YOUR_SUBTOTAL_SECRET_KEY>': 请务必替换 '<YOUR_SUBTOTAL_SECRET_KEY>' 为你实际的 Subtotal API 密钥。 或者，你也可以将 Subtotal API 密钥设置为环境变量 'SUBTOTAL_SECRET_KEY'，此时可以省略此参数。
'description': 服务器描述信息，方便识别。
'transport': 传输协议，这里使用 'stdio'。

注意: 请确保你的 MCP 客户端能够正确解析和执行上述 JSON 配置。

基本使用方法

启动 MCP 服务器: 根据上述服务器配置，在 MCP 客户端中配置并启动 Subtotal MCP 服务器。
LLM 客户端请求: LLM 客户端可以通过 MCP 协议向 Subtotal MCP 服务器发送请求，例如调用 'get-merchants' 工具获取商家列表，或调用 'get-purchases' 工具查询用户的购买记录。
数据访问: MCP 服务器会调用 Subtotal API 获取数据，并将结果以 MCP 协议规定的格式返回给 LLM 客户端。
工具调用: LLM 客户端可以根据业务需求，选择合适的工具并传递参数，实现对 Subtotal 财务数据的访问和利用。

示例: 假设你的 LLM 应用需要获取用户在某个商家下的购买记录，可以引导 LLM 调用 'get-purchases' 工具，并提供必要的 'connection_id' 参数。MCP 服务器会处理该请求，并返回购买记录数据。

关键词