Mpesa Daraja MCP

🚀 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 的文档及其相关图片。

首次设置

1. 激活 Python 环境：

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

2. 运行抓取器：

   python scraper.py
   

3. 登录流程：
   • 浏览器窗口会自动打开。
   • 当提示时，手动登录 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 个全面的工具：

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

服务器配置

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

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

💻 编辑器集成

Kiro IDE

1. 创建 MCP 配置文件：

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

2. 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"
         ]
       }
     }
   }
   

3. 原生配置：

   {
     "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

1. 安装 MCP 扩展（如果可用）
2. 在 settings.json 中进行配置：

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

Cursor IDE

1. 打开 Cursor 设置
2. 添加 MCP 服务器配置：

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

Windsurf

1. 访问 Windsurf MCP 设置
2. 添加服务器配置：

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

Claude Desktop

1. 编辑 Claude 配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加服务器配置：

   {
     "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 服务器无法连接

1. 验证 Docker 容器是否正在运行：

   pnpm run docker:status
   

2. 检查 MCP 配置语法：
   • 确保 JSON 格式有效。
   • 验证命令和参数是否正确。
   • 原生安装时使用绝对路径。
3. 手动测试服务器：

   # Docker
   docker exec -i daraja-mcp-server node dist/index.js
   
   # 原生
   cd mpesa-daraja-mcp
   node dist/index.js
   

4. 配置更改后重启编辑器

工具未显示

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

特定平台问题

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

获取帮助

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

🤝 贡献指南

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

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

开发设置

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 设置开发环境：

   # 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

1. 更新抓取器 URL：

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

2. 测试抓取：

   python scraper.py
   

3. 更新 API 分类：

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

4. 验证 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 文档！