项目简介

此项目是SolvaPay SDK中的一个功能示例，演示了如何构建一个Model Context Protocol (MCP) 服务器，并无缝集成SolvaPay支付墙功能来保护其提供的工具。它实现了一个简单的CRUD（创建、读取、删除任务）任务管理系统，并为每个操作设置了免费使用限制和按使用量计费的支付要求。该服务器通过标准JSON-RPC协议与大型语言模型（LLM）客户端通信，允许LLM客户端发现并调用任务管理工具。

主要功能点

MCP工具托管: 提供了一系列开箱即用的MCP工具，包括 'create_task'（创建任务）、'get_task'（获取任务）、'list_tasks'（列出任务）、'delete_task'（删除任务）。
支付墙保护: 对所有任务管理工具应用支付墙逻辑，为每个用户提供每日免费使用次数限制。超出限制后，服务器将返回支付要求信息，引导LLM客户端通知用户进行付费以继续使用。
标准MCP协议支持: 完全支持MCP协议的工具发现（'listTools'）和工具调用（'callTool'）请求，确保与兼容的LLM客户端进行标准化交互。
用户会话管理: 通过 'x-customer-ref'（或工具参数中的'auth.customer_ref'）HTTP头或参数识别用户身份，并据此管理每个用户的免费使用额度和付费状态。
简明易懂: 作为SDK的示例，代码结构清晰，注释详尽，非常适合开发者理解如何将SolvaPay集成到自己的MCP服务器中。

安装步骤

在本地机器上运行此MCP服务器，请遵循以下步骤：

克隆SolvaPay SDK仓库: 打开终端或命令提示符，执行以下命令克隆项目：

git clone https://github.com/solvapay/solvapay-sdk
cd solvapay-sdk

安装依赖并构建项目: 在 'solvapay-sdk' 目录下运行：
```
pnpm install
pnpm build
```
这将安装所有必要的依赖并构建SDK的各个模块。
启动MCP服务器示例: 导航到MCP服务器示例的目录，并启动它：
```
cd examples/mcp-basic
pnpm dev
```
服务器将以演示模式启动，提供3次免费操作额度（可在 'stub-api-client.ts' 中配置），并将启动信息、可用工具和支付墙详情输出到控制台。

服务器配置

此MCP服务器通过标准输入/输出（Stdio）协议与MCP客户端通信。MCP客户端需要配置服务器的启动命令，以便建立连接。以下是一个JSON格式的配置模板，您可以根据实际情况填充并提供给MCP客户端：

{
  "name": "SolvaPay CRUD MCP Server",
  "description": "一个带支付墙的任务管理MCP服务器，提供任务的创建、读取、列表和删除功能。",
  "command": "tsx",
  "args": [
    "src/index.ts"
  ],
  "cwd": "examples/mcp-basic",
  "environment": {
    "STUB_DEBUG": "true",
    "SOLVAPAY_DEBUG": "true",
    "USE_REAL_BACKEND": "false"
  },
  "auth": {
    "type": "custom",
    "key": "customer_ref",
    "description": "用于标识用户身份的客户参考ID。LLM客户端需要在每次调用工具时，通过工具参数中的 'auth.customer_ref' 字段提供此ID（例如：{\"auth\": {\"customer_ref\": \"user_alice\"}}），服务器将据此管理用户的免费额度或付费情况。"
  },
  "capabilities": {
    "tools": {
      "create_task": {
        "description": "创建一个新任务。**受支付墙保护**",
        "parameters": {
          "type": "object",
          "properties": {
            "title": { "type": "string", "description": "任务标题，必填。" },
            "description": { "type": "string", "description": "任务的详细描述，可选。" },
            "auth": {
              "type": "object",
              "properties": {
                "customer_ref": { "type": "string", "description": "用户的唯一标识符，用于支付墙鉴权。" }
              },
              "required": ["customer_ref"]
            }
          },
          "required": ["title", "auth"]
        }
      },
      "get_task": {
        "description": "根据ID获取单个任务。**受支付墙保护**",
        "parameters": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "description": "要获取的任务的唯一ID。" },
            "auth": {
              "type": "object",
              "properties": {
                "customer_ref": { "type": "string", "description": "用户的唯一标识符，用于支付墙鉴权。" }
              },
              "required": ["customer_ref"]
            }
          },
          "required": ["id", "auth"]
        }
      },
      "list_tasks": {
        "description": "获取所有任务的列表。**受支付墙保护**",
        "parameters": {
          "type": "object",
          "properties": {
            "limit": { "type": "number", "description": "返回任务的最大数量（默认值：10）。" },
            "offset": { "type": "number", "description": "跳过任务的起始位置（默认值：0）。" },
            "auth": {
              "type": "object",
              "properties": {
                "customer_ref": { "type": "string", "description": "用户的唯一标识符，用于支付墙鉴权。" }
              },
              "required": ["customer_ref"]
            }
          },
          "required": ["auth"]
        }
      },
      "delete_task": {
        "description": "根据ID删除任务。**受支付墙保护**",
        "parameters": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "description": "要删除的任务的唯一ID。" },
            "auth": {
              "type": "object",
              "properties": {
                "customer_ref": { "type": "string", "description": "用户的唯一标识符，用于支付墙鉴权。" }
              },
              "required": ["customer_ref"]
            }
          },
          "required": ["id", "auth"]
        }
      }
    }
  }
}

配置说明:

'command': 启动MCP服务器的命令。此处为 'tsx'，因为它直接运行TypeScript文件。请确保您的系统已安装 'tsx'（通常通过 'pnpm add -g tsx' 或 'npm install -g tsx' 安装）。
'args': 传递给 'command' 的参数。此处为 'src/index.ts'，指向MCP服务器的入口文件。
'cwd': 当前工作目录。务必设置为 'solvapay-sdk/examples/mcp-basic' 目录的绝对或相对路径，以便服务器能够找到其源文件和依赖。
'environment': 环境变量配置。'STUB_DEBUG' 和 'SOLVAPAY_DEBUG' 用于控制调试日志输出，'USE_REAL_BACKEND' 设置为 'false' 确保使用示例自带的模拟支付客户端。
'auth': 认证配置。定义了LLM客户端如何提供用户身份信息（'customer_ref'），这对支付墙功能至关重要。
'capabilities.tools': 声明了服务器提供的所有MCP工具及其描述、参数和预期响应格式。

基本使用方法

LLM客户端连接并配置好此MCP服务器后，即可开始交互：

工具发现: LLM客户端可以发送一个 'listTools' 的MCP请求来获取服务器提供的所有工具（如 'create_task', 'get_task' 等）的详细定义。

调用工具: LLM客户端可以通过发送 'callTool' 请求来调用这些工具。例如，要创建一个任务，LLM客户端应构建一个如下的请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "callTool",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "撰写关于MCP服务器的报告",
      "description": "包含核心功能和集成支付墙的说明",
      "auth": {
        "customer_ref": "user_john_doe"
      }
    }
  }
}

关键点: 在 'arguments' 中包含 'auth' 对象，并提供一个唯一的 'customer_ref'（如 'user_john_doe'）来标识用户。服务器将使用此ID来跟踪用户的免费额度。在前3次调用后（在演示模式下），服务器将返回一个包含 'payment_required' 信息的结构化响应，指示LLM客户端通知用户需要付费以继续操作。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息