内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/ibm-x402-mcp</h1>
<p align="center"><strong>按使用付费的 IBM Granite AI — 聊天、代码、嵌入、分析、预测，在 Solana 上使用 USDC 支付。无需 IBM 账户。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/ibm-x402-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/ibm-x402-mcp?logo=npm&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@three-ws/ibm-x402-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/ibm-x402-mcp?color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/ibm-x402-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/ibm-x402-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas%2Fibm--x402--mcp-6e56cf"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
<p align="center">
<a href="#安装">安装</a> ·
<a href="#快速开始">快速开始</a> ·
<a href="#工具">工具</a> ·
<a href="#支付流程">支付流程</a> ·
<a href="#需求">需求</a> ·
<a href="https://three.ws">three.ws</a>
</p>
---
> 一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，通过 [x402](https://x402.org) 支付协议，以按使用付费的方式提供 IBM Granite 基础模型作为工具。终端用户按调用次数支付 **Solana 上的 USDC** — 无需拥有 IBM Cloud 账户。服务器运营商提供 IBM 凭证 (`WATSONX_*`) 和接收 Solana 钱包 (`MCP_SVM_PAYMENT_ADDRESS`)；调用者仅需提供 USDC。有一个免费工具 (`ibm_granite_getting_started`) 可以解释价格和支付流程，免费用户无需支付。
>
> 由 [three.ws](https://three.ws) 构建。社区驱动，不隶属于 IBM。
## 工作原理
1. MCP 客户端（Claude Desktop、Claude Code、Cursor 或代理）连接到此服务器。
2. 客户端调用一个工具 — 例如 `ibm_granite_chat`。
3. 如果没有 x402 支付载荷，服务器返回一个 `402 PaymentRequired` 信封，引用 USDC 价格和 Solana 接收地址。
4. 客户端签署 Solana USDC 转账交易并重试，交易附在 `_meta["x402/payment"]` 中。
5. 服务器通过促进者验证并结算支付，调用 IBM watsonx.ai，并返回结果和结算收据，附在 `_meta["x402/payment-response"]` 中。
支持 x402 的 MCP 客户端会自动处理此循环。
## 安装
```bash
npm install @three-ws/ibm-x402-mcp
```
直接使用 `npx` 运行（无需安装）：
```bash
MCP_SVM_PAYMENT_ADDRESS=<您的Solana钱包地址> \
WATSONX_API_KEY=<IBM API密钥> \
WATSONX_PROJECT_ID=<watsonx项目ID> \
npx @three-ws/ibm-x402-mcp
```
或全局安装 `ibm-x402-mcp` 二进制文件：
```bash
npm install -g @three-ws/ibm-x402-mcp
```
## 快速开始
使用 Claude Code，只需一个命令（作为终端用户，按调用次数付费，无需环境变量）：
```bash
claude mcp add ibm-granite-x402 -- npx -y @three-ws/ibm-x402-mcp
```
服务器操作员添加 `-e MCP_SVM_PAYMENT_ADDRESS=... -e WATSONX_API_KEY=... -e WATSONX_PROJECT_ID=...` 在 `--` 之前。
或将服务器连接到您的 MCP 客户端配置（`claude_desktop_config.json`，Cursor 的 `mcp.json`）：
```json
{
"mcpServers": {
"ibm-x402": {
"command": "npx",
"args": ["-y", "@three-ws/ibm-x402-mcp"],
"env": {
"MCP_SVM_PAYMENT_ADDRESS": "您的Solana钱包地址",
"WATSONX_API_KEY": "您的IBM Cloud API密钥",
"WATSONX_PROJECT_ID": "您的watsonx项目ID"
}
}
}
}
```
使用 MCP Inspector 检查工具表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/ibm-x402-mcp
```
## 工具
| 工具 | 功能 | 价格 |
| ----------------------------- | ----------------------------------------------------------------------------------- | ----------- |
| `ibm_granite_getting_started` | 概览、价格和 x402 支付流程。无需支付或 IBM 账户。 | 免费 |
| `ibm_granite_chat` | 通过 IBM Granite 进行对话式 AI（默认 `ibm/granite-3-8b-instruct`）。 | $0.02 USDC |
| `ibm_granite_code` | 代码生成、审查、重构、解释、测试、文档。 | $0.025 USDC |
| `ibm_granite_embed` | 批量文本嵌入，用于 RAG、搜索和聚类（1–64 个文本）。 | $0.005 USDC |
| `ibm_granite_analyze` | 结构化文档分析：实体、情感、风险标志、摘要、后续步骤。 | $0.04 USDC |
| `ibm_granite_forecast` | 通过 IBM Granite TTM（Tiny Time Mixer）进行零镜头时间序列预测。 | $0.05 USDC |
每个工具都是只读模型推理调用 — 您的机器或任何账户都不会被修改 — 并且声明 MCP 工具注释（`readOnlyHint`、`openWorldHint`、`idempotentHint`），以便客户端在支付前推理副作用。
### 输入参数
**`ibm_granite_chat`** — `messages`（必填：1–50 `{ role, content }` 对）、`model`、`max_new_tokens`（1–4096，默认 1024）、`temperature`（0–2，默认 0.7）。
**`ibm_granite_code`** — `task`（必填：`generate`/`review`/`refactor`/`explain`/`test`/`document`）、`prompt`（必填）、`language`、`context`。
**`ibm_granite_embed`** — `inputs`（必填：1–64 个文本，每个文本 ≤8000 字符）、`model`。
**`ibm_granite_analyze`** — `document`（必填）、`analysis_type`（`general`/`contract`/`financial`/`technical`/`medical`/`sentiment`，默认 `general`）、`language`。
**`ibm_granite_forecast`** — `timestamps`（必填：64–1024 个 ISO-8601 日期，均匀间隔，最旧的在前）、`values`（必填：64–1024 个数字，长度相同）、`freq`（必填：pandas 频率，例如 `1h`、`1D`）、`prediction_length`（1–96）、`label`。
### 示例调用
```jsonc
// ibm_granite_chat
{
"messages": [
{ "role": "system", "content": "您是一位专家数据工程师。" },
{ "role": "user", "content": "为 IoT 传感器遥测设计一个湖仓架构。" }
],
"max_new_tokens": 1024,
"temperature": 0.7
}
// ibm_granite_code
{ "task": "review", "prompt": "def calculate_roi(revenue, cost): return revenue / cost", "language": "Python" }
// ibm_granite_embed
{ "inputs": ["企业数据治理", "云原生 AI 流水线", "实时分析"] }
// ibm_granite_analyze
{ "document": "本软件许可协议由...", "analysis_type": "contract" }
// ibm_granite_forecast （timestamps/values 必须为 64–1024 个点；此处缩写）
{ "timestamps": ["2025-01-01T00:00:00Z", "...", "2025-03-05T00:00:00Z"], "values": [12500, "...", 13200], "freq": "1D", "prediction_length": 14, "label": "daily_revenue_usd" }
```
## 支付流程
此服务器使用 [x402 协议](https://x402.org) 进行微支付：
1. 客户端调用工具，无支付 → `402 PaymentRequired`，包含 USDC 金额和 Solana 地址。
2. 客户端构建并签署 Solana USDC 转账交易。
3. 客户端重试，已签署的交易在 `_meta["x402/payment"]` 中。
4. 服务器通过配置的促进者（默认 PayAI）验证并结算。
5. 服务器调用 IBM watsonx.ai 并返回结果，附带 `_meta["x402/payment-response"]`（结算收据）。
```
MCP 客户端（Claude Desktop / Cursor / 代理）
│ 工具调用（_meta 中带有 x402 支付）
▼
ibm-x402-mcp（stdio MCP 服务器）
│ 验证 + 结算 Solana 上的 USDC
├──► x402 促进者（默认 https://facilitator.payai.network）
│
│ 使用 IAM Bearer 令牌进行推理调用
└──► IBM watsonx.ai（us-south.ml.cloud.ibm.com）
└── IBM Granite 3 8B Instruct / Embedding / TTM
```
## 需求
- **Node.js >= 20.**
- 一个 Solana 钱包地址来接收 USDC（`MCP_SVM_PAYMENT_ADDRESS`）。
- IBM Cloud 凭证：API 密钥（[创建](https://cloud.ibm.com/iam/apikeys)）和 watsonx.ai 项目 ID（项目 → 管理 → 常规 → 项目 ID），或部署空间 ID。
### 环境变量
| 变量 | 必需 | 默认 |
| ------------------------- | ----------------------------------- | ----------------------------------------- |
| `MCP_SVM_PAYMENT_ADDRESS` | 是 | — |
| `WATSONX_API_KEY` | 是 | — |
| `WATSONX_PROJECT_ID` | 是（或 `WATSONX_SPACE_ID`） | — |
| `WATSONX_SPACE_ID` | `WATSONX_PROJECT_ID` 的替代品 | — |
| `WATSONX_URL` | 否 | `https://us-south.ml.cloud.ibm.com` |
| `WATSONX_MODEL_ID` | 否 | `ibm/granite-3-8b-instruct` |
| `WATSONX_EMBED_MODEL_ID` | 否 | `ibm/granite-embedding-278m-multilingual` |
| `X402_FEE_PAYER_SOLANA` | 否 | three.ws 费用支付者 |
| `X402_FACILITATOR_URL` | 否 | `https://facilitator.payai.network` |
区域主机：`us-south`、`eu-de`、`eu-gb`、`jp-tok`、`au-syd`、`ca-tor` — 例如 `https://eu-de.ml.cloud.ibm.com`。
## 相关
- [`@three-ws/ibm-watsonx-mcp`](https://www.npmjs.com/package/@three-ws/ibm-watsonx-mcp) — 相同的 IBM Granite 工具，由您自己的 IBM Cloud 凭证驱动（无 x402，按调用付费）。
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 见 [LICENSE](./LICENSE)。 未获得版权所有者的明确书面许可，不得授予任何权利。
