cloudflare-daraja-mcp

# Daraja MCP 服务器 [](https://dl.circleci.com/status-badge/redirect/gh/pmutua/cloudflare-daraja-mcp/tree/main) [](https://codecov.io/github/pmutua/cloudflare-daraja-mcp) 一个用于 Safaricom M-Pesa (Daraja) API 的自主托管 MCP 服务器，部署在 Cloudflare Workers 上。您可以克隆它，添加自己的 Daraja 凭证，部署到您自己的 Cloudflare 账户，并将您的 AI 工具连接到它。 如果您是 LLM 用户：请先阅读 [llm.txt](llm.txt) 并将其视为主要集成合同。 ## 目标人群 本服务器设计为**自主托管**。没有共享的托管实例 - 每个用户都部署自己的实例。 | 受众 | 您获得的内容 | |----------|-------------| | **构建 AI 驱动的应用的开发者** | 将此部署到您的 Cloudflare 账户，连接到您的 AI 助手（VS Code Copilot、Claude、Cursor），您的代理可以启动 M-Pesa 支付、检查状态和调试错误，而无需您编写粘合代码。 | | **提供 M-Pesa 集成的团队** | 将此用作 AI 代理的支付后端 - 客户支持机器人、结账助手或需要触发和验证支付的自动化工作流。 | | **单独探索 MCP 的开发者** | 复刻，部署到沙箱环境中使用测试凭证，并使用安全环境中的真实支付 API 实验 AI 工具如何交互。 | ### 部署模型 ``` 您（开发者） ├── 克隆此仓库 ├── 添加您的 Daraja 凭证（消费者密钥、密钥、通行密钥） ├── 部署到您自己的 Cloudflare 账户（免费层有效） └── 将您的 AI 工具连接到您的 Worker URL ``` 每个部署都是隔离的。您的凭证、KV 数据、速率限制和交易日志完全属于您。没有人可以访问您的实例。 ## 从这里开始（适合初学者） 如果您是 MCP 新手，请先阅读： - [docs/BEGINNER_GUIDE.md](docs/BEGINNER_GUIDE.md) - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - [docs/MCP_CONSUMERS.md](docs/MCP_CONSUMERS.md) 简单来说，这个项目允许 AI 助手通过结构化工具安全地执行常见的 M-Pesa 支付任务。 ## 什么是 MCP 服务器？ MCP（模型上下文协议）是一种标准方法，允许 AI 助手调用工具。 MCP 服务器是一种服务，它： 1. 用清晰的输入/输出规则定义工具 2. 从 AI 客户端接收工具调用 3. 执行实际的业务操作 4. 返回结构化响应 在这个项目中，工具是支付焦点操作，如启动 STK 推送和检查交易状态。 ## 为什么这个服务器有用？ 没有这个服务器，团队通常在聊天机器人提示或应用程序粘合代码中硬编码支付逻辑。 这个服务器为您提供： 1. 可重用的支付工具，任何 MCP 兼容的客户端都可以调用 2. 通过 API 密钥身份验证和速率限制实现更安全的运营 3. KV 日志中可靠的交易可追溯性 4. AI 行为和支付基础设施之间的清晰分离 ## 典型用例 1. AI 客户支持可以在用户确认后触发 STK 推送。 2. AI 结账助手可以验证支付是否完成。 3. 运维助手可以快速解释 Daraja 错误代码。 4. 开发者可以在沙箱环境中模拟支付流程而无需实际收费。 ## 工作原理（高级别） 1. 您的 AI 客户端向 `/mcp` 发送工具调用。 2. 服务器验证身份验证和用法限制。 3. 选定的工具运行 Daraja API 逻辑。 4. 结果作为结构化 JSON 返回给 AI 客户端。 5. 回调更新和交易元数据存储在 KV 中。 ## 架构图 ```mermaid flowchart LR A[AI 客户端] -->|MCP 调用| B[Daraja MCP 服务器] B --> C[身份验证和速率限制] B --> D[工具处理程序] D --> E[Daraja API] D --> F[Cloudflare KV] E --> G["/回调端点"] G --> F ``` 有关完整的架构、时序图和示例，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 有关 MCP 消费者（VS Code、stdio-first 主机和自定义客户端）的详细设置，请参阅 [docs/MCP_CONSUMERS.md](docs/MCP_CONSUMERS.md)。 ## 使用示例 列出工具： ```bash curl -H "x-api-key: <您的_API_密钥>" https://<您的域名>/mcp/tools ``` 健康检查： ```bash curl https://<您的域名>/health ``` 在 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 中查看端到端说明和工具输入/输出示例。 ## 5 分钟快速入门 1. 安装依赖项：`npm install` 2. 创建本地变量模板：`npm run setup:local` 3. 在 `.dev.vars` 中填写真实值 4. 验证配置：`npm run doctor` 5. 启动本地服务器：`npm run dev` 6. 检查健康状况：`GET /health` 如果您希望在缺少必填值时进行严格的配置检查，请运行：`npm run doctor -- --strict` ## 初学者学习链接 图例：初学者 = 无需先前的 MCP 知识。 中级 = 需要一些先前的上下文。 MCP 基础知识： - MCP 介绍（初学者，~10 分钟）：https://modelcontextprotocol.io/introduction - MCP 架构概念（初学者，~15 分钟）：https://modelcontextprotocol.io/docs/learn/architecture - MCP 规范（中级，~20-30 分钟浏览）：https://spec.modelcontextprotocol.io/ 本项目的 Cloudflare 基础知识： - Cloudflare Workers 概述（初学者，~10 分钟）：https://developers.cloudflare.com/workers/ - Wrangler CLI 文档（初学者，~15 分钟）：https://developers.cloudflare.com/workers/wrangler/ - Workers KV 入门（初学者，~15 分钟）：https://developers.cloudflare.com/kv/get-started/ - Workers 绑定概述（中级，~15 分钟）：https://developers.cloudflare.com/workers/runtime-apis/bindings/ Daraja 和 M-Pesa 文档： - Safaricom 开发者门户（初学者，~5 分钟）：https://developer.safaricom.co.ke/ - Daraja API 目录（初学者，~10 分钟）：https://developer.safaricom.co.ke/apis - Daraja 入门（初学者，~15 分钟）：https://developer.safaricom.co.ke/apis/GettingStarted - Daraja 授权 OAuth（中级，~10 分钟）：https://developer.safaricom.co.ke/apis/Authorization MCP 客户端和工具： - 在 VS Code 中使用 MCP 服务器（初学者，~15 分钟）：https://code.visualstudio.com/docs/copilot/chat/mcp-servers - VS Code 中的 MCP 配置（中级，~15 分钟）：https://code.visualstudio.com/docs/copilot/reference/mcp-configuration 图表和视觉效果： - Mermaid 介绍（初学者，~10 分钟）：https://mermaid.js.org/intro/ - Mermaid 在线编辑器（初学者，动手）：https://mermaid.live/edit ## 当前状态 已实现：**提交 1 - 项目引导**，**提交 2 - MCP 服务器设置**，**提交 3 - API 密钥身份验证**，**提交 4 - 速率限制（KV）**，**提交 5 - OAuth 令牌（Daraja）**，**提交 6 - STK 推送**，**提交 7 - 交易状态**，**提交 8 - 支付验证层**，**提交 9 - 回调处理程序**，**提交 10 - 模拟工具**，**提交 11 - 错误智能**，**提交 12 - Workers AI 集成**，**提交 13 - 日志记录 + 可观察性**，**提交 14 - 代理集成（未来）** - Cloudflare Worker 项目脚手架 - 基本 `fetch` 处理程序 - 健康端点：`GET /health` - MCP SDK 集成（`@modelcontextprotocol/sdk`） - MCP 服务器配置为 `daraja-mcp-server` v`1.1.0` - 基本工具注册，初始 `get_usage_status` 工具 - MCP 传输端点：`/mcp` - 工具发现端点：`GET /mcp/tools` - 受保护路由的 API 密钥身份验证中间件，通过 `x-api-key` - KV 支持的每日速率限制中间件（`USAGE` 命名空间） - 请求限制：每天 `50` 个请求 - Daraja OAuth 令牌工具：`get_access_token` - KV 中的令牌缓存（`TOKENS` 命名空间） - STK 推送工具：`stk_push` - Daraja STK 密码生成：`Base64(shortCode + passkey + timestamp)` - KV 中的 STK 请求/响应日志（`TRANSACTIONS` 命名空间） - 交易状态工具：`check_transaction_status` - 规范化响应字段：`status`，`resultCode`，`responseCode`，`isComplete` - 支付验证工具：`verify_payment_intent` - 验证检查：金额匹配和可选电话匹配 - 回调端点：`POST /callback` - 回调有效负载存储在 KV（`CALLBACKS` 命名空间）中 - 开发模拟工具：`simulate_payment`（无外部 API 调用） - Daraja 错误解释工具：`explain_error_code` - 交易日志摘要工具：`summarize_transaction_logs` - 用于自然语言摘要的 Workers AI 增强（可选） - 结构化请求和错误日志记录实用程序 - `DEBUG_MODE=true` 发出请求/错误日志 - 业务流程规划工具：`orchestrate_payment_workflow` - 为未来的 Cloudflare 代理运行时提供代理到代理的支付工作流程计划 ## 身份验证 - 受保护的路由需要头部：`x-api-key: <您的_API_密钥>` - 公共路由：`GET /health` 在部署前设置 API 密钥秘密： ```bash wrangler secret put API_KEY ``` ## 速率限制（KV） 在 `wrangler.toml` 中创建一个 KV 命名空间，并将其绑定为 `USAGE`： ```toml [[kv_namespaces]] binding = "USAGE" id = "<您的-usage-kv-namespace-id>" preview_id = "<您的-usage-kv-preview-id>" ``` 如果每日配额耗尽，受保护的端点将返回 `429`。 ## Daraja OAuth 所需的秘密： ```bash wrangler secret put DARAJA_CONSUMER_KEY wrangler secret put DARAJA_CONSUMER_SECRET ``` 可选的秘密/变量： - `DARAJA_ENV` = `sandbox`（默认）或 `production` - `DARAJA_BASE_URL` = 自定义 Daraja 基本 URL 的覆盖 在 `wrangler.toml` 中添加令牌缓存 KV 绑定： ```toml [[kv_namespaces]] binding = "TOKENS" id = "<您的-tokens-kv-namespace-id>" preview_id = "<您的-tokens-kv-preview-id>" ``` ## STK 推送 所需配置： ```bash wrangler secret put DARAJA_SHORTCODE wrangler secret put DARAJA_PASSKEY wrangler secret put DARAJA_CALLBACK_URL ``` 重要注意事项： - 需要回调端点以实现端到端的 STK 流程，因为 Daraja 会异步发送最终支付结果。 - 此服务器已经在 POST /callback 处实现了回调路由。 - 将 DARAJA_CALLBACK_URL 设置为真实的公共 HTTPS URL，例如 https://<您的-worker-domain>/callback。 - 对于沙箱环境，使用短代码 174379 的 Lipa Na M-Pesa Online 通行密钥。不要将 Security Credential 用于 STK 密码生成。 - STK 密码公式为 Base64（shortCode + passkey + timestamp），其中 timestamp 格式为 YYYYMMDDHHmmss。 可选： - `DARAJA_TRANSACTION_TYPE` = `CustomerPayBillOnline`（默认）或 `CustomerBuyGoodsOnline` 在 `wrangler.toml` 中添加交易日志 KV 绑定： ```toml [[kv_namespaces]] binding = "TRANSACTIONS" id = "<您的-transactions-kv-namespace-id>" preview_id = "<您的-transactions-kv-preview-id>" ``` `stk_push` 输入字段： - `amount` - `phoneNumber` - `accountReference` - `transactionDesc` - `callbackUrl`（可选覆盖） - `transactionType`（可选覆盖） 将您的 Daraja 回调设置为此端点： - `https://<您的-worker-domain>/callback` 回调端点出于设计考虑，保持无身份验证，以便 Safaricom 可以提供支付更新。 在 `wrangler.toml` 中添加回调存储 KV 绑定： ```toml [[kv_namespaces]] binding = "CALLBACKS" id = "<您的-callbacks-kv-namespace-id>" preview_id = "<您的-callbacks-kv-preview-id>" ``` ## 本地运行 快速本地设置： ```bash npm run setup:local npm install npm run doctor ``` 医生命令在启动 Worker 之前检查所需的 Daraja 和 API 密钥变量。 ```bash npm install npm run dev ``` ## 测试（TDD） ```bash npm test ``` ## 测试覆盖率报告 安装覆盖率工具（如果从最小设置开始）： ```bash npm install --save-dev vitest @vitest/coverage-v8 ``` 生成覆盖率输出： ```bash npx vitest run --coverage ``` 在 README 中生成和刷新覆盖率报告： ```bash npm run coverage:update ``` <!-- coverage-report:start --> 上次更新：2026-03-22T00:35:43.569Z | 指标 | 覆盖率 | 覆盖 | 总数 | | --- | ---: | ---: | ---: | | 语句 | 80.69% | 347 | 430 | | 分支 | 61.98% | 225 | 363 | | 函数 | 84.50% | 60 | 71 | | 行 | 80.42% | 337 | 419 | 刷新：`npm run coverage:update` <!-- coverage-report:end --> ## Codecov CLI 上传（手动，本地操作系统） Codecov 上传故意在 CircleCI 之外进行此存储库。 最佳方法：手动本地上传，在生成覆盖率后，避免在管道作业中处理令牌。 如果您稍后选择基于 CI 的上传，请使用相同的验证 CLI 流程，并在您的 CI 运行器中使用，并将 `CODECOV_TOKEN` 仅保留在 CI 机密中。 推荐流程： 1. 生成覆盖率：`npx vitest run --coverage` 2. 验证并安装 Codecov CLI 适用于您的操作系统 3. 上传令牌： ```bash ./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest ``` Windows（PowerShell）： ```powershell $ProgressPreference = 'SilentlyContinue' Invoke-WebRequest -Uri https://keybase.io/codecovsecurity/pgp_keys.asc -OutFile codecov.asc gpg.exe --import codecov.asc Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe -OutFile codecov.exe Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe.SHA256SUM -OutFile codecov.exe.SHA256SUM Invoke-WebRequest -Uri https://cli.codecov.io/latest/windows/codecov.exe.SHA256SUM.sig -OutFile codecov.exe.SHA256SUM.sig gpg.exe --verify codecov.exe.SHA256SUM.sig codecov.exe.SHA256SUM if ((Compare-Object -ReferenceObject ((($(certUtil -hashfile codecov.exe SHA256)[1]), 'codecov.exe') -join ' ') -DifferenceObject (Get-Content codecov.exe.SHA256SUM)).Length -eq 0) { Write-Output 'SHASUM verified' } else { exit 1 } .\codecov.exe upload-process -t "$env:CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest ``` Linux： ```bash curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import curl -Os https://cli.codecov.io/latest/linux/codecov curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM curl -Os https://cli.codecov.io/latest/linux/codecov.SHA256SUM.sig gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM shasum -a 256 -c codecov.SHA256SUM sudo chmod +x codecov ./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest ``` macOS： ```bash curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import curl -Os https://cli.codecov.io/latest/macos/codecov curl -Os https://cli.codecov.io/latest/macos/codecov.SHA256SUM curl -Os https://cli.codecov.io/latest/macos/codecov.SHA256SUM.sig gpg --verify codecov.SHA256SUM.sig codecov.SHA256SUM shasum -a 256 -c codecov.SHA256SUM sudo chmod +x codecov ./codecov upload-process -t "$CODECOV_TOKEN" -f coverage/coverage-final.json -F vitest ``` ## CircleCI 持续集成/持续部署 此存储库现在包含 `.circleci/config.yml` 中的 CircleCI 管道配置。 管道行为： - 分支和标签上的 CI： - `npm run check` - `npm test` - `npm run test:e2e` - `npm run test:coverage` - 将覆盖率工件存储在 CircleCI 中 - 通过 CircleCI Codecov orb 上传 Codecov（`codecov/codecov@5`） - 主分支上的 CD 到沙箱。 - 生产部署在 CircleCI 中故意禁用。 - 工作流中目前禁用了冒烟测试。 所需的 CircleCI 环境变量： - `CLOUDFLARE_API_TOKEN` - `CLOUDFLARE_ACCOUNT_ID` 沙箱部署所需的运行时机密变量（自动同步到 Worker 机密）： - `SANDBOX_API_KEY` -> `API_KEY` - `SANDBOX_DARAJA_CONSUMER_KEY` -> `DARAJA_CONSUMER_KEY` - `SANDBOX_DARAJA_CONSUMER_SECRET` -> `DARAJA_CONSUMER_SECRET` - `SANDBOX_DARAJA_SHORTCODE` -> `DARAJA_SHORTCODE` - `SANDBOX_DARAJA_PASSKEY` -> `DARAJA_PASSKEY` - `SANDBOX_DARAJA_CALLBACK_URL` -> `DARAJA_CALLBACK_URL` 沙箱部署配置生成所需的 KV 命名空间变量： - `SANDBOX_USAGE_KV_ID` - `SANDBOX_USAGE_KV_PREVIEW_ID` - `SANDBOX_TOKENS_KV_ID` - `SANDBOX_TOKENS_KV_PREVIEW_ID` - `SANDBOX_TRANSACTIONS_KV_ID` - `SANDBOX_TRANSACTIONS_KV_PREVIEW_ID` - `SANDBOX_CALLBACKS_KV_ID` - `SANDBOX_CALLBACKS_KV_PREVIEW_ID` 可选的沙箱运行时变量： - `SANDBOX_DARAJA_ENV` -> `DARAJA_ENV` - `SANDBOX_DARAJA_BASE_URL` -> `DARAJA_BASE_URL` - `SANDBOX_DARAJA_TRANSACTION_TYPE` -> `DARAJA_TRANSACTION_TYPE` 使用上述“Codecov CLI 上传（手动，本地操作系统）”部分。 所需的 Codecov 变量： - `CODECOV_TOKEN` ## 预提交钩子 此存储库使用 Husky 预提交钩子。 - 钩子文件：`.husky/pre-commit` - 在每次提交前运行： - `npm run check` - `npm test` ## 部署 出于安全考虑，`wrangler.toml` 不存储实际的 KV 命名空间 ID。 使用环境变量生成临时部署配置，并使用生成的配置文件进行部署。 示例（PowerShell）： ```powershell $env:SANDBOX_USAGE_KV_ID="<kv-id>" $env:SANDBOX_USAGE_KV_PREVIEW_ID="<kv-preview-id>" $env:SANDBOX_TOKENS_KV_ID="<kv-id>" $env:SANDBOX_TOKENS_KV_PREVIEW_ID="<kv-preview-id>" $env:SANDBOX_TRANSACTIONS_KV_ID="<kv-id>" $env:SANDBOX_TRANSACTIONS_KV_PREVIEW_ID="<kv-preview-id>" $env:SANDBOX_CALLBACKS_KV_ID="<kv-id>" $env:SANDBOX_CALLBACKS_KV_PREVIEW_ID="<kv-preview-id>" node scripts/generate-wrangler-sandbox-config.mjs npx wrangler deploy --name daraja-mcp-server-sandbox -c .wrangler.sandbox.toml ``` ```bash npm run deploy ``` ## 发布运行手册 使用 [docs/RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) 中的生产检查清单： - 预发布验证（`npm run check`，测试，Terraform 验证） - Cloudflare 机密和绑定验证 - 部署顺序（`terraform apply` 和 `npm run deploy`） - 部署后烟雾测试 `/health`，`/mcp/tools` 和回调路由 发布治理文档： - [CHANGELOG.md](CHANGELOG.md) - [docs/VERSIONING.md](docs/VERSIONING.md) ## 健康检查响应 `GET /health` ```json { "ok": true, "service": "daraja-mcp-server", "status": "healthy", "timestamp": "2026-03-22T00:00:00.000Z" } ``` ## 与您的 AI 工具集成 在部署到您自己的 Cloudflare 账户后，将您的 AI 编程助手或生产代理连接到您的 Worker URL。 **对于开发者：** 将您的 IDE 的 MCP 客户端指向您部署的服务器，以便您的 AI 助手可以测试 M-Pesa 流、调试错误代码和验证交易 — 无需切换到 Postman 或编写一次性脚本。 **对于生产 AI 代理：** 连接您的聊天机器人、客户支持代理或自动化工作流，以便它可以代表真实用户发起支付、检查状态和处理 M-Pesa 操作。 复制粘贴配置模板位于 [`examples/`](examples/)： | 平台 | 配置文件 | 设置 | |----------|------------|-------| | VS Code (Copilot Chat) | [`examples/vscode-mcp.json`](examples/vscode-mcp.json) | 复制到 `.vscode/mcp.json` | | Claude Code | [`examples/claude-code-mcp.json`](examples/claude-code-mcp.json) | 复制到 `.mcp.json` 或 `claude mcp add` | | Claude Desktop | [`examples/claude-desktop-config.json`](examples/claude-desktop-config.json) | 合并到 `claude_desktop_config.json` | | Cursor | [`examples/cursor-mcp.json`](examples/cursor-mcp.json) | 复制到 `.cursor/mcp.json` | | Windsurf | [`examples/windsurf-mcp.json`](examples/windsurf-mcp.json) | 通过 Windsurf MCP 设置添加 | | OpenAI Codex | [`examples/codex-consumer-config.toml`](examples/codex-consumer-config.toml) | 添加到 `.codex/config.toml` | 所有模板都使用 `https://<your-domain>/mcp` — 用您部署的 Worker URL 替换。 有关每个平台的详细设置说明，请参阅 [docs/MCP_CONSUMERS.md](docs/MCP_CONSUMERS.md)。 ## 与 OpenAI Codex 结合使用 该项目已针对 OpenAI Codex（CLI、IDE 扩展和 Codex 应用）进行了全面配置。 ### 快速入门 ```bash npm install -g @openai/codex cd daraja_mcp_server codex ``` Codex 自动读取 `AGENTS.md` 并从 `.codex/config.toml` 加载项目范围的配置。 ### 包含的内容 | 组件 | 位置 | 目的 | |-----------|----------|---------| | `AGENTS.md` | 根目录 | 项目上下文、约定、命令 | | `.codex/config.toml` | 项目 | MCP 服务器、代理配置、技能 | | `.codex/agents/` | 项目 | 自定义代理定义（6 个代理） | | `.agents/skills/` | 项目 | 可重用的工作流技能（6 个技能） | | `.codex/PLANS.md` | 项目 | 复杂任务的规划模板 | | `.codex/code_review.md` | 项目 | 代码审查标准参考 | | `docs/CODEX_GUIDE.md` | 文档 | Codex 使用指南 | ### 多代理工作流 ``` # 完整的代码库分析 分析此代码库。并行启动 codebase_analyst、reviewer 和 pr_explorer。 # PR 审查 使用安全、正确性和测试覆盖率代理审查此分支与 main 分支。 # TDD 实现 $tdd-workflow — 使用完整的 TDD 修复 [描述问题]。 ``` 有关完整的工作流文档，请参阅 [docs/CODEX_GUIDE.md](docs/CODEX_GUIDE.md)。