内容
# upi-mcp
印度 **UPI 模型上下文协议（MCP）服务器**。它为 AI 助手（Claude Desktop、Cursor、Cline、MCP Inspector 等）提供了 **生成和解析 UPI 支付链接和二维码** 的能力 — 完全 **离线**，无需 **API 密钥** 和 **网络调用**。
> 许多基于 Web 的 UPI 二维码生成器存在。本项目提供 **代理可调用** 的形式：LLM 可以在对话中生成 `upi://pay` 链接或可扫描的二维码，然后验证或解析该链接。它与支付-API MCP 服务器自然配对。
## ✨ 功能
- 🔗 从付款人详细信息生成验证的 `upi://pay` 深度链接
- 🔳 生成可扫描的 **PNG 二维码** — 本地构建，无需外部服务
- 🔍 将 UPI 链接解析回结构化字段
- 🛡️ 输入验证（VPA 格式、金额限制）
- 🔒 零身份验证，零网络 — 纯粹的确定性逻辑
- ⌨️ 使用 TypeScript 编写，启用 `strict` 模式
## 🛠️ 工具
| 工具 | 描述 |
|------|-------------|
| `create_upi_link` | 从付款人详细信息构建验证的 `upi://pay` 深度链接。返回链接文本。 |
| `create_upi_qr` | 构建 UPI 链接并将其返回为可扫描的 **PNG 二维码**（以及原始链接）。 |
| `parse_upi_link` | 将 `upi://pay` 链接解析回结构化字段。 |
### 输入
**`create_upi_link` / `create_upi_qr`**
| 字段 | 类型 | 必需 | 备注 |
|-------|------|----------|-------|
| `payee_vpa` | 字符串 | ✅ | UPI ID / VPA，例如 `name@okhdfc` |
| `payee_name` | 字符串 | ✅ | UPI 应用中显示的名称 |
| `amount` | 数字 | ❌ | 固定金额（印度卢比），必须大于 0 且小于或等于 1,00,000 |
| `note` | 字符串 | ❌ | 短交易备注 |
| `transaction_ref` | 字符串 | ❌ | 引用 ID |
**`parse_upi_link`**
| 字段 | 类型 | 必需 |
|-------|------|----------|
| `link` | 字符串 | ✅ |
## 📋 要求
- **Node.js 18+** （在 Node 22 上开发）
## 🚀 安装和构建
```bash
git clone https://github.com/<your-username>/upi-mcp.git
cd upi-mcp
npm install
npm run build # 编译 TypeScript -> dist/
```
## ▶️ 运行
```bash
npm start # 在标准输入/输出上启动服务器
```
您应该会看到 `upi-mcp running on stdio` — 然后等待 MCP 客户端连接。
## 🧪 测试（MCP Inspector）
尝试工具的最快方式，无需客户端设置：
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
这将打开一个本地 Web 界面 → **连接** → **工具** 选项卡 → **列出工具** → 选择一个工具，填写输入内容，然后 **运行**。二维码图像直接渲染在那里。
## 🖥️ 与 Claude Desktop 一起使用
打开 **设置 → 开发者 → 编辑配置** 并添加以下内容（合并到现有配置中）：
```json
{
"mcpServers": {
"upi": {
"command": "node",
"args": ["/absolute/path/to/upi-mcp/dist/index.js"]
}
}
}
```
将路径替换为您的项目完整路径 + `/dist/index.js`。然后 **完全退出** Claude Desktop（`Cmd + Q`）并重新打开。
尝试：*"生成一个 UPI 支付链接，支付给 `nirav@okhdfc` ₹250，备注为 test。"*
> ⚠️ **关于 Claude Desktop 中的二维码图像：** 桌面客户端当前对渲染 MCP 工具返回的图像支持有限/不一致（以及 ~1 MB 的内容上限）。文本链接始终有效，在移动设备上可点击。要 **可靠地** 查看二维码图像，请使用 **MCP Inspector**（上面），它正确渲染图像。
## 📦 UPI 链接格式
```
upi://pay?pa=<vpa>&pn=<name>&cu=INR&am=<amount>&tn=<note>&tr=<ref>
```
**示例输出**
输入： `{ "payee_vpa": "nirav@okhdfc", "payee_name": "Nirav", "amount": 250, "note": "test" }`
```
upi://pay?pa=nirav%40okhdfc&pn=Nirav&cu=INR&am=250.00&tn=test
```
`parse_upi_link` 将其反向解析为 `{ payeeVpa, payeeName, amount, note, transactionRef }`.
## 🧑💻 开发
```bash
npx tsc --watch # 自动重新构建
```
**项目结构**
```
src/
upi.ts # 纯逻辑：构建和解析链接（无 MCP，可完全测试）
index.ts # MCP 服务器：在标准输入/输出上将逻辑包装为 3 个工具
```
## 🌍 发布到 npm
```bash
npm run build
npm publish --access public
```
确保 `package.json` 包含 `"files": ["dist"]` 以便编译后的代码被发布。发布后，任何人都可以运行它而无需克隆：
```json
{ "command": "npx", "args": ["-y", "upi-mcp"] }
```
## ⚠️ 免责声明
- UPI 通过此链接格式仅支持 **印度卢比（INR）** 和一次性支付。
- 本项目 **不隶属于** NPCI 或任何银行。它仅构建公共 UPI 深度链接 URI 格式及其二维码图像。
- 支付前请始终在 UPI 应用中验证付款人姓名。
## 📄 许可证
MIT
