JinDaGe - mpesa-daraja-mcp MCP Details

article

README

🚀 Daraja API 文档抓取器与 MCP 服务器

这是一个综合工具包，可通过网页抓取和模型上下文协议（MCP）集成来访问 Safaricom 的 Daraja API 文档。该项目既提供了强大的抓取器以保持文档更新，也提供了专业的 MCP 服务器用于 AI 助手集成。

⚠️ 重要法律声明与免责条款

数据来源与使用权限

文档来源：本项目从 Safaricom 的 Daraja API 门户抓取文档。
认证要求：抓取器需要登录凭证才能访问 Safaricom 的开发者门户。
服务条款：使用抓取器时，用户必须遵守 Safaricom 的服务条款。
数据所有权：所有抓取的文档仍为 Safaricom PLC 的知识产权。

法律合规性

个人使用：本工具仅用于个人开发和学习目的。
商业使用：对于商业应用，请确保你已获得 Safaricom 的适当许可。
速率限制：抓取器包含延迟设置以尊重 Safaricom 的服务器，请不要修改这些设置。
账户责任：用户需对自己的 Safaricom 开发者账户凭证负责。

免责声明

无保证：本软件“按原样”提供，不附带任何形式的保证。
数据准确性：抓取的文档可能会过时，请始终与官方来源进行核实。
服务可用性：Safaricom 可能会更改其门户结构，从而导致抓取器无法正常工作。
法律责任：用户需对使用本工具承担所有法律责任。

道德使用准则

尊重速率限制：不要向 Safaricom 的服务器发送过多请求。
有效凭证：仅使用你自己合法的 Safaricom 开发者账户。
数据共享：在共享抓取的数据时要谨慎，尊重 Safaricom 的知识产权。
更新：保持抓取的文档为最新状态，不要重新分发过时的信息。

使用本软件即表示你已阅读、理解并同意遵守这些条款以及 Safaricom 的服务条款。

✨ 主要特性

完整的文档抓取器：自动抓取所有 22 个 Daraja API 及其相关图片。
专业的 MCP 服务器：符合标准的服务器，用于 AI 助手集成。
Docker 支持：支持容器化部署，确保环境一致性。
多平台支持：可在 Windows、macOS 和 Linux 上运行。
编辑器集成：与 Kiro、VSCode、Cursor、Windsurf、Claude Desktop 等编辑器兼容。
离线可用：包含完整的文档数据集，可立即使用。
自动发现：智能检测路径，实现无缝设置。

🚀 快速开始

方案一：Docker 部署（推荐）

# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# 构建并启动 Docker 容器
cd mpesa-daraja-mcp
pnpm run docker:build
pnpm run docker:start

# 配置你的编辑器（请参阅“编辑器集成”部分）

方案二：原生安装

# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# 设置 MCP 服务器
cd mpesa-daraja-mcp
pnpm install
pnpm run build

# 配置你的编辑器（请参阅“编辑器集成”部分）

方案三：全新抓取 + MCP 设置

# 克隆并设置抓取器
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# 设置 Python 环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上使用：venv\Scripts\activate
pip install -r requirements.txt

# 运行抓取器（需要 Daraja 门户登录）
python scraper.py

# 设置 MCP 服务器
cd mpesa-daraja-mcp
pnpm install
pnpm run build

📦 安装指南

先决条件

Docker（推荐）或
Python 3.8+（用于抓取器）+ Node.js 18+（用于 MCP 服务器）
Git（用于克隆仓库）

特定平台设置

Windows

# 方案一：Docker（推荐）
# 从 https://docker.com 安装 Docker Desktop
# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp\mpesa-daraja-mcp
pnpm run docker:build

# 方案二：原生安装
# 从官方网站安装 Python 和 Node.js
# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python 环境设置（用于抓取器）
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

# Node.js 环境设置（用于 MCP 服务器）
cd mpesa-daraja-mcp
pnpm install
pnpm run build

macOS

# 方案一：Docker（推荐）
# 从 https://docker.com 安装 Docker Desktop
brew install git
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp/mpesa-daraja-mcp
pnpm run docker:build

# 方案二：原生安装
# 通过 Homebrew 安装依赖项
brew install python node git pnpm

# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python 环境设置（用于抓取器）
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Node.js 环境设置（用于 MCP 服务器）
cd mpesa-daraja-mcp
pnpm install
pnpm run build

Linux（Ubuntu/Debian）

# 方案一：Docker（推荐）
# 安装 Docker
sudo apt update
sudo apt install docker.io docker-compose git
sudo usermod -aG docker $USER
# 注销并重新登录，然后执行以下操作：
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp/mpesa-daraja-mcp
pnpm run docker:build

# 方案二：原生安装
# 安装依赖项
sudo apt update
sudo apt install python3 python3-venv nodejs npm git
npm install -g pnpm

# 克隆仓库
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python 环境设置（用于抓取器）
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Node.js 环境设置（用于 MCP 服务器）
cd mpesa-daraja-mcp
pnpm install
pnpm run build

🐳 Docker 部署

Docker 提供了跨所有平台最可靠、一致的部署方法。

快速 Docker 设置

cd mpesa-daraja-mcp

# 构建 Docker 镜像
pnpm run docker:build

# 启动容器
pnpm run docker:start

# 检查状态
pnpm run docker:status

# 查看日志
pnpm run docker:logs

Docker 管理命令

# 构建和部署
pnpm run docker:build     # 构建 Docker 镜像
pnpm run docker:start     # 启动容器
pnpm run docker:stop      # 停止容器
pnpm run docker:restart   # 重启容器

# 监控和调试
pnpm run docker:status    # 检查容器状态
pnpm run docker:logs      # 查看容器日志
pnpm run docker:shell     # 在容器中打开 shell

# 清理
pnpm run docker:clean     # 删除容器和镜像

Docker 配置

Docker 设置包括：

多阶段构建：优化镜像大小。
非根用户：提高安全性。
卷挂载：方便访问文档。
健康检查：确保可靠性。
资源限制：适用于生产环境。

Docker Compose 配置

# docker-compose.yml
services:
  daraja-mcp:
    build: .
    container_name: daraja-mcp-server
    restart: unless-stopped
    volumes:
      - ../daraja_docs_v3:/app/daraja_docs_v3:ro
    environment:
      - NODE_ENV=production
    stdin_open: true
    tty: true

Docker 环境下的 MCP 配置

使用 Docker 时，更新编辑器的 MCP 配置：

{
  "mcpServers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"],
      "disabled": false,
      "autoApprove": [
        "search_daraja_apis",
        "get_daraja_api_doc",
        "list_apis_by_category",
        "get_api_summary",
        "get_server_stats",
        "compare_apis"
      ]
    }
  }
}

💻 抓取器使用方法

⚠️ 重要提示：在使用抓取器之前，请确保你具备以下条件：

拥有有效的 Safaricom 开发者账户。
已接受 Safaricom 的服务条款。
获得以编程方式访问文档的权限。
了解你需要遵守 Safaricom 的政策。

抓取器会自动下载所有 22 个 Daraja API 的文档及其相关图片。

首次设置

激活 Python 环境：

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

运行抓取器：
```
python scraper.py
```
登录流程：
- 浏览器窗口会自动打开。
- 当提示时，手动登录 Daraja 门户。
- 登录成功后，在终端中按 ENTER 键。
- 抓取器会保存会话，以便后续使用。

更新文档

要获取最新的 API 文档，请执行以下操作：

# 激活环境
source venv/bin/activate

# 运行抓取器（使用保存的会话）
python scraper.py

# 如果会话过期，当浏览器打开时重新登录

输出结构

daraja_docs_v3/
├── data_index.json          # API 元数据和索引
├── docs/                    # Markdown 文档
│   ├── Authorization.md
│   ├── MpesaExpressSimulate.md
│   └── ... (22 个 API 文件)
└── images/                  # 下载的图片
    ├── Authorization_img_0.svg
    └── ... (200 多张图片)

💻 MCP 服务器设置

MCP 服务器通过 6 个强大的工具为 AI 助手提供对 Daraja 文档的访问。

原生构建与测试

cd mpesa-daraja-mcp

# 安装依赖项
pnpm install

# 构建 TypeScript
pnpm run build

# 测试服务器是否能找到文档
pnpm test

# 运行服务器（用于测试）
pnpm run dev

可用的 MCP 工具

MCP 服务器提供 6 个全面的工具：

search_daraja_apis - 支持类别过滤的高级搜索。
get_daraja_api_doc - 完整的 API 文档检索。
list_apis_by_category - 按类别组织的 API 列表。
get_api_summary - 包含端点的增强摘要。
get_server_stats - 使用统计信息和监控。
compare_apis - 并排的 API 比较。

服务器配置

服务器会自动检测以下位置的文档：

../daraja_docs_v3（相对于服务器）
./daraja_docs_v3（当前目录）
/app/daraja_docs_v3（Docker 容器内）
通过环境变量设置的自定义路径

💻 编辑器集成

Kiro IDE

创建 MCP 配置文件：

# 在工作区中创建 .kiro/settings/mcp.json
mkdir -p .kiro/settings

Docker 配置（推荐）：

{
  "mcpServers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"],
      "disabled": false,
      "autoApprove": [
        "search_daraja_apis",
        "get_daraja_api_doc",
        "list_apis_by_category",
        "get_api_summary",
        "get_server_stats",
        "compare_apis"
      ]
    }
  }
}

原生配置：

{
  "mcpServers": {
    "daraja-docs": {
      "command": "node",
      "args": ["mpesa-daraja-mcp/dist/index.js"],
      "disabled": false,
      "autoApprove": [
        "search_daraja_apis",
        "get_daraja_api_doc",
        "list_apis_by_category",
        "get_api_summary",
        "get_server_stats",
        "compare_apis"
      ]
    }
  }
}

带有 MCP 扩展的 VSCode

安装 MCP 扩展（如果可用）

在 settings.json 中进行配置：

{
  "mcp.servers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
    }
  }
}

Cursor IDE

打开 Cursor 设置

添加 MCP 服务器配置：

{
  "mcp": {
    "servers": {
      "daraja-docs": {
        "command": "docker",
        "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
      }
    }
  }
}

Windsurf

访问 Windsurf MCP 设置

添加服务器配置：

{
  "mcpServers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
    }
  }
}

Claude Desktop

编辑 Claude 配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json

添加服务器配置：

{
  "mcpServers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
    }
  }
}

通用 MCP 客户端

对于任何使用 Docker 的 MCP 兼容客户端：

{
  "servers": {
    "daraja-docs": {
      "command": "docker",
      "args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"],
      "env": {}
    }
  }
}

对于原生安装：

{
  "servers": {
    "daraja-docs": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/绝对路径/to/mpesa-daraja-mcp",
      "env": {}
    }
  }
}

📚 API 文档

可用的 API

该项目包含 22 个 Daraja API 的详细文档，这些 API 分为 6 个类别：

核心支付 API

Authorization - OAuth 令牌生成和管理
MpesaExpressSimulate - STK Push 支付发起
MpesaExpressQuery - STK Push 交易状态查询

支付处理

CustomerToBusiness - C2B 支付处理
BusinessToCustomer - B2C 支付分发
CustomerToBusinessRegisterURL - C2B URL 注册

交易管理

TransactionStatus - 交易状态验证
AccountBalance - 账户余额查询
Reversal - 交易撤销操作
PullTransaction - 交易详情检索

业务操作

BusinessPayBill - 账单支付处理
BusinessBuyGoods - 商品购买支付
B2BExpressCheckout - 企业对企业交易
BusinessToPochi - 企业到 Pochi 钱包转账

高级功能

DynamicQRCode - 动态 QR 码生成
BillManager - 账单管理和处理
TaxRemittance - 税务支付处理
MpesaRatiba - 定期支付管理

专业服务

B2CAccountTopUp - 账户充值服务
Swap - 货币兑换操作
IMSI - SIM 卡管理服务
IotSimManagement - IoT SIM 卡管理

使用 MCP 工具

高级 API 搜索

使用 search_daraja_apis 工具进行强大的过滤搜索：

查询："payment" + 类别："core" → 核心支付 API
查询："balance" → 账户余额及相关 API
类别："business" → 所有业务操作 API
无参数 → 所有 22 个带类别的 API

完整文档访问

使用 get_daraja_api_doc 工具获取完整文档：

api_name: "Authorization" → 完整的 OAuth 实现指南
api_name: "MpesaExpressSimulate" → 完整的 STK Push 文档
包含代码示例、参数和响应格式

增强的 API 摘要

使用 get_api_summary 工具进行快速概述：

api_name: "BusinessToCustomer" → 包含关键端点的摘要
include_endpoints: true → 包含端点 URL
非常适合快速参考和比较

API 比较

使用 compare_apis 工具进行并排分析：

api_names: ["Authorization", "MpesaExpressSimulate"] → 比较认证和支付 API
comparison_aspects: ["endpoints", "authentication"] → 关注特定方面
支持同时比较 2 - 4 个 API

使用统计信息

使用 get_server_stats 工具进行监控：

API 总数和类别
访问最多的 API
请求统计信息
服务器健康信息

按类别浏览

使用 list_apis_by_category 工具进行有组织的访问：

category: "payments" → 所有与支付相关的 API
无类别 → 列出所有类别及其数量
非常适合发现相关 API

🛠️ 故障排除

Docker 问题

容器无法启动

# 检查 Docker 是否正在运行
docker --version
docker-compose --version

# 查看详细日志
pnpm run docker:logs

# 如果需要，重新构建
pnpm run docker:clean
pnpm run docker:build

容器中找不到文档

# 检查卷挂载
docker inspect daraja-mcp-server

# 验证文档是否存在
ls -la ../daraja_docs_v3/data_index.json

# 测试容器访问
pnpm run docker:shell
ls -la /app/daraja_docs_v3/

Docker 环境下 MCP 连接问题

# 确保容器正在运行
pnpm run docker:status

# 直接测试 MCP 工具
docker exec -i daraja-mcp-server node dist/index.js

# 检查容器日志中的错误信息
pnpm run docker:logs

原生安装问题

MCP 服务器问题

服务器无法启动：

# 检查 Node.js 版本
node --version  # 应大于等于 18

# 重新构建服务器
cd mpesa-daraja-mcp
pnpm run clean
pnpm install
pnpm run build

找不到文档：

# 测试文档检测
pnpm test

# 手动检查路径
ls -la ../daraja_docs_v3/data_index.json

TypeScript 错误：

# 更新依赖项
pnpm update
pnpm run build

# 检查语法错误
pnpm run dev

抓取器问题

浏览器无法打开：

# 安装浏览器依赖项
playwright install chromium

# 检查 Python 版本
python --version  # 应大于等于 3.8

登录会话过期：

# 删除认证文件并重新登录
rm auth.json
python scraper.py

权限错误：

# 检查文件权限
chmod +x scraper.py
# 或者显式使用 Python 运行
python scraper.py

编辑器集成问题

MCP 服务器无法连接

验证 Docker 容器是否正在运行：
```
pnpm run docker:status
```
检查 MCP 配置语法：
- 确保 JSON 格式有效。
- 验证命令和参数是否正确。
- 原生安装时使用绝对路径。

手动测试服务器：

# Docker
docker exec -i daraja-mcp-server node dist/index.js

# 原生
cd mpesa-daraja-mcp
node dist/index.js

配置更改后重启编辑器

工具未显示

检查编辑器 MCP 面板中的服务器日志
验证 autoApprove 列表是否包含所需工具
确保服务器构建成功：pnpm run build
首先使用最小配置进行测试

特定平台问题

Windows 平台问题

在 Docker 路径中使用正斜杠：C:/path/to/project
如果存在 Docker 权限问题，以管理员身份运行 PowerShell
检查 Windows Defender 是否阻止了 Docker 或 Node.js
使用 WSL2 以获得更好的 Docker 性能

macOS 平台问题

安装 Xcode 命令行工具：xcode-select --install
使用 Homebrew 进行依赖管理：brew install docker
检查 Docker Desktop 是否正在运行并已配置
验证文件权限：chmod +x docker-scripts.sh

Linux 平台问题

将用户添加到 docker 组：sudo usermod -aG docker $USER
安装构建必备工具：sudo apt install build-essential
检查 Docker 服务：sudo systemctl status docker
验证 Node.js 安装：which node

性能优化

Docker 性能

# 限制容器资源
docker update --memory=512m --cpus="0.5" daraja-mcp-server

# 使用多阶段构建以获得更小的镜像
# （Dockerfile 中已实现）

# 清理未使用的 Docker 资源
docker system prune -a

MCP 服务器性能

# 监控服务器统计信息
# 使用 get_server_stats 工具跟踪使用情况

# 优化文档加载
# 服务器在启动时缓存文档

# 使用适当的日志级别
NODE_ENV=production pnpm run docker:start

获取帮助

首先检查日志：Docker 和原生安装都会提供详细的错误信息。
单独测试组件：使用 pnpm test 验证 MCP 服务器设置。
验证路径和权限：确保所有文件路径正确且可访问。
更新依赖项：保持 Docker、Node.js 和 Python 包为最新版本。
使用 Docker 确保一致性：Docker 可以消除大多数特定平台问题。

🤝 贡献指南

⚠️ 贡献者的数据处理指南：

PR 中不包含抓取的数据：不要在拉取请求中包含抓取的文档。
尊重知识产权：确保贡献内容不侵犯 Safaricom 的知识产权。
仅贡献代码：对抓取器和 MCP 服务器代码进行改进，而不是数据。
更新文档：更新 README 和代码注释，而不是抓取的 API 文档。

开发设置

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature

设置开发环境：

# Docker 开发（推荐）
cd mpesa-daraja-mcp
pnpm run docker:build
pnpm run docker:start

# 原生开发
# Python 开发
pip install -r requirements-dev.txt  # 如果存在

# Node.js 开发
cd mpesa-daraja-mcp
pnpm install
pnpm run dev

添加新 API

更新抓取器 URL：

URLS = [
    "https://developer.safaricom.co.ke/apis/NewAPI",
    # ... 现有 URL
]

测试抓取：
```
python scraper.py
```

更新 API 分类：

// 在 mpesa-daraja-mcp/src/config.ts 中
API_CATEGORIES: {
  new_category: ["NewAPI"],
  // ... 现有类别
}

验证 MCP 服务器：

cd mpesa-daraja-mcp
pnpm test
pnpm run docker:build

代码风格

Python：遵循 PEP 8 规范，使用 black 格式化工具。
TypeScript：使用 Prettier 格式化，遵循 ESLint 规则。
Docker：遵循多阶段构建的最佳实践。
提交：使用常规提交格式。

测试

# 测试抓取器
python scraper.py --test-mode

# 测试 MCP 服务器（原生）
cd mpesa-daraja-mcp
pnpm test
pnpm run build

# 测试 MCP 服务器（Docker）
pnpm run docker:build
pnpm run docker:start
pnpm run docker:logs

文档更新

为新功能更新 README。
添加代码内联注释。
更新 API 文档。
包含特定于 Docker 的说明。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

⚠️ 重要许可证说明：

软件许可证：MIT 许可证仅适用于抓取器和 MCP 服务器代码。
文档权利：抓取的 Daraja API 文档仍为 Safaricom PLC 的财产。
单独条款：使用 Safaricom 的文档需遵守其服务条款。
无转让：本许可证不授予对 Safaricom 知识产权的权利。

这意味着

✅ 商业使用 - 可在商业应用中使用本项目。
✅ 修改 - 可修改源代码以满足需求。
✅ 分发 - 可分发软件副本。
✅ 私人使用 - 可将软件用于私人目的。
❌ 责任 - 作者对任何损害不承担责任。
❌ 保证 - 软件“按原样”提供，无任何保证。

致谢

如果你使用本项目，请考虑：

⭐ 在 GitHub 上给仓库加星
📝 在你的文档中提及本项目
🔗 链接回原始仓库

👏 致谢

Safaricom：提供 Daraja API 平台。
Model Context Protocol 团队：制定 MCP 标准。
Playwright 团队：提供出色的自动化框架。
Docker 社区：分享容器化最佳实践。
开源贡献者：使这样的项目成为可能。

仓库信息

仓库地址：https://github.com/JacksCodeVault/mpesa-daraja-mcp
问题反馈：报告错误或请求功能
讨论区：社区讨论
版本发布：最新版本

支持我们

如果你觉得这个项目有帮助，请考虑：

⭐ 给仓库加星
🐛 报告你遇到的问题
💡 提出改进建议
🤝 为项目做出贡献
📢 与可能受益的人分享

准备好将 Daraja API 文档与你的 AI 助手集成了吗？

使用 Docker 快速开始：cd mpesa-daraja-mcp && pnpm run docker:build && pnpm run docker:start

浏览文档：使用 MCP 工具探索 22 个全面的 Daraja API。

需要帮助？ 查看故障排除部分或提交问题。

从快速开始指南开始，让你的 AI 助手在几分钟内访问 Daraja 文档！