Daraja API文档抓取器和MCP服务器

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/) ![Python](https://python.org/) ](https://docker.com/) ![MCP](https://modelcontextprotocol.io/)

通过web抓取和模型上下文协议（MCP）集成访问Safaricom的Daraja API文档的综合工具包。该项目提供了一个强大的刮刀来保持文档的最新状态，以及一个用于AI助手集成的专业MCP服务器。

⚠️ 重要法律声明和免责声明

数据来源和使用权

文档来源：本项目从Safaricom的Daraja API门户网站抓取文档
需要认证：scraper需要登录凭据才能访问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等
离线就绪：包括可立即使用的完整文档数据集
自动发现：智能路径检测，实现无缝设置

快速开始

选项1:Docker部署（推荐）

# Clone the repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Build and start Docker container
cd mpesa-daraja-mcp
pnpm run docker:build
pnpm run docker:start

# Configure your editor (see Editor Integration section)

选项2：本机安装

# Clone the repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Setup MCP server
cd mpesa-daraja-mcp
pnpm install
pnpm run build

# Configure your editor (see Editor Integration section)

选项3：新废料+MCP设置

# Clone and setup scraper
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Setup Python environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run scraper (requires Daraja portal login)
python scraper.py

# Setup MCP server
cd mpesa-daraja-mcp
pnpm install
pnpm run build

安装

先决条件

码头工人 （推荐）或
Python 3.8+ （用于刮板）+ Node.js 18+ （适用于MCP服务器）
Git （用于克隆）

平台特定设置

视窗

# Option 1: Docker (Recommended)
# Install Docker Desktop from https://docker.com
# Clone repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp\mpesa-daraja-mcp
pnpm run docker:build

# Option 2: Native Installation
# Install Python and Node.js from official websites
# Clone repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python setup (for scraper)
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

# Node.js setup (for MCP server)
cd mpesa-daraja-mcp
pnpm install
pnpm run build

macOS

# Option 1: Docker (Recommended)
# Install Docker Desktop from https://docker.com
brew install git
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp/mpesa-daraja-mcp
pnpm run docker:build

# Option 2: Native Installation
# Install dependencies via Homebrew
brew install python node git pnpm

# Clone repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python setup (for scraper)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Node.js setup (for MCP server)
cd mpesa-daraja-mcp
pnpm install
pnpm run build

Linux（Ubuntu/Debian）

# Option 1: Docker (Recommended)
# Install Docker
sudo apt update
sudo apt install docker.io docker-compose git
sudo usermod -aG docker $USER
# Log out and back in, then:
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp/mpesa-daraja-mcp
pnpm run docker:build

# Option 2: Native Installation
# Install dependencies
sudo apt update
sudo apt install python3 python3-venv nodejs npm git
npm install -g pnpm

# Clone repository
git clone https://github.com/JacksCodeVault/mpesa-daraja-mcp.git
cd mpesa-daraja-mcp

# Python setup (for scraper)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Node.js setup (for MCP server)
cd mpesa-daraja-mcp
pnpm install
pnpm run build

Docker部署

Docker在所有平台上提供了最可靠和一致的部署方法。

快速Docker设置

cd mpesa-daraja-mcp

# Build the Docker image
pnpm run docker:build

# Start the container
pnpm run docker:start

# Check status
pnpm run docker:status

# View logs
pnpm run docker:logs

Docker管理命令

# Build and deployment
pnpm run docker:build     # Build the Docker image
pnpm run docker:start     # Start the container
pnpm run docker:stop      # Stop the container
pnpm run docker:restart   # Restart the container

# Monitoring and debugging
pnpm run docker:status    # Check container status
pnpm run docker:logs      # View container logs
pnpm run docker:shell     # Open shell in container

# Cleanup
pnpm run docker:clean     # Remove container and image

Docker配置

Docker设置包括：

多阶段构建 用于优化图像大小
非root用户 出于安全考虑
数据载体安装 用于文档访问
健康检查 可靠性
资源限制 用于生产用途

Docker编写配置

# 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的政策

scraper会自动下载所有22个Daraja API的文档和图像。

首次设置

激活Python环境:

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

运行刮板:

   python scraper.py

登录进程:

- 浏览器窗口自动打开 - 出现提示时手动登录Daraja门户 - 登录成功后，在终端中按ENTER键 - Scraper保存会话以备将来使用

更新文档

获取最新的API文档：

# Activate environment
source venv/bin/activate

# Run scraper (uses saved session)
python scraper.py

# If session expired, login again when browser opens

输出结构

daraja_docs_v3/
├── data_index.json          # API metadata and index
├── docs/                    # Markdown documentation
│   ├── Authorization.md
│   ├── MpesaExpressSimulate.md
│   └── ... (22 API files)
└── images/                  # Downloaded images
    ├── Authorization_img_0.svg
    └── ... (200+ images)

MCP服务器设置

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

本地构建和测试

cd mpesa-daraja-mcp

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Test server can find documentation
pnpm test

# Run server (for testing)
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容器）
通过环境变量自定义路径

编辑器集成

开发 IDE

创建MCP配置文件:

   # Create .kiro/settings/mcp.json in your workspace
   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"]
       }
     }
   }

光标IDE

打开光标设置

添加MCP服务器配置:

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

帆板运动

访问Windsurf MCP设置

添加服务器配置:

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

克劳德桌面版

编辑Claude配置文件:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %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": "/absolute/path/to/mpesa-daraja-mcp",
      "env": {}
    }
  }
}

API文档

可用API

该项目包括22个Daraja API的综合文档，分为6类：

核心支付API

授权 -OAuth令牌生成和管理
MpesaExpress模拟 -STK推送支付启动
MpesaExpressQuery -STK推送交易状态查询

支付处理

客户业务 -C2B支付处理
从企业到客户 -B2C支付支出
客户商业注册URL -C2B URL注册

事务管理

交易状态 -交易状态验证
账户余额 -账户余额查询
逆转 -交易撤销操作
Pull交易 -交易明细检索

业务运营

商业付款单 -账单支付处理
企业购买商品 -货物采购付款
B2B快递结账 -企业对企业交易
商业ToPochi -企业到Pochi钱包转账

高级功能

动态QR码 -动态二维码生成
账单管理器 -票据管理和处理
税款汇款 -纳税处理
时间表 -计划付款管理

专业服务

B2C账户充值 -账户充值服务
交换 -货币互换操作
IMSI -SIM卡管理服务
IoTSIM管理 -物联网SIM卡管理

使用MCP工具

高级API搜索

使用具有强大过滤功能的search_daraja_apis工具：

查询：“支付”+类别：“核心”→ 核心支付API
查询：“余额”→ AccountBalance和相关API
类别：“商业”→ 所有业务操作API
无参数→ 所有22个API及其分类

完整的文档访问权限

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

api_name：“授权”→ 完整的OAuth实施指南
api_name:“MpesaExpressSimulate”→ 完整的STK推送文档
包括代码示例、参数和响应格式

增强的API摘要

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

api_name：“业务客户”→ 关键端点摘要
include_端点：true→ 包括端点URL
非常适合快速参考和比较

API比较

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

api_names:\[“授权”，“MpesaExpressSimulate”\]→ 比较身份验证与支付
比较方面：\[“端点”，“身份验证”\]→ 关注具体方面
同时支持2-4个API

使用统计

使用get_server_stats工具进行监控：

API总数和类别
访问最多的API
请求统计
服务器运行状况信息

基于类别的浏览

使用list_apis_by_category工具进行有序访问：

类别：“付款”→ 所有与支付相关的API
无类别→ 列出所有有计数的类别
非常适合发现相关API

故障排除

Docker问题

容器无法启动

# Check Docker is running
docker --version
docker-compose --version

# View detailed logs
pnpm run docker:logs

# Rebuild if needed
pnpm run docker:clean
pnpm run docker:build

在容器中找不到文档

# Check volume mounting
docker inspect daraja-mcp-server

# Verify documentation exists
ls -la ../daraja_docs_v3/data_index.json

# Test container access
pnpm run docker:shell
ls -la /app/daraja_docs_v3/

Docker的MCP连接问题

# Ensure container is running
pnpm run docker:status

# Test MCP tools directly
docker exec -i daraja-mcp-server node dist/index.js

# Check container logs for errors
pnpm run docker:logs

本地安装问题

MCP服务器问题

服务器无法启动:

# Check Node.js version
node --version  # Should be 18+

# Rebuild server
cd mpesa-daraja-mcp
pnpm run clean
pnpm install
pnpm run build

未找到文档:

# Test documentation detection
pnpm test

# Check paths manually
ls -la ../daraja_docs_v3/data_index.json

TypeScript错误:

# Update dependencies
pnpm update
pnpm run build

# Check for syntax errors
pnpm run dev

刮刀问题

浏览器无法打开:

# Install browser dependencies
playwright install chromium

# Check Python version
python --version  # Should be 3.8+

登录会话已过期:

# Delete auth file and re-login
rm auth.json
python scraper.py

权限错误:

# Check file permissions
chmod +x scraper.py
# Or run with python explicitly
python scraper.py

编辑器集成问题

MCP服务器未连接

验证Docker容器是否正在运行:

   pnpm run docker:status

检查MCP配置语法:

- 确保JSON有效 - 验证命令和参数是否正确 - 使用绝对路径进行本机安装

手动测试服务器:

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

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

重新启动编辑器 配置更改后

工具未出现

检查服务器日志 在编辑的MCP面板中
验证自动批准列表 包括所需工具
确保服务器构建成功: pnpm run build
以最小配置进行测试 第一

平台特定问题

Windows平台问题

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

macOS平台问题

安装Xcode命令行工具: xcode-select --install
使用自制咖啡 对于依赖关系管理： brew install docker
检查Docker桌面 正在运行和配置
验证文件权限: 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性能

# Limit container resources
docker update --memory=512m --cpus="0.5" daraja-mcp-server

# Use multi-stage builds for smaller images
# (Already implemented in Dockerfile)

# Clean up unused Docker resources
docker system prune -a

MCP服务器性能

# Monitor server stats
# Use get_server_stats tool to track usage

# Optimize documentation loading
# Server caches documentation on startup

# Use appropriate log levels
NODE_ENV=production pnpm run docker:start

获取帮助

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

贡献

⚠️ 贡献者数据处理指南:

PR中没有报废数据：在pull请求中不包括抓取的文档
尊重知识产权：确保贡献不侵犯Safaricom的知识产权
仅限代码：改进scraper和MCP服务器代码，而不是数据
文档：更新README和代码注释，而不是抓取API文档

开发设置

克隆该仓库

创建特征分支: git checkout -b feature/amazing-feature

设置开发环境:

   # Docker development (recommended)
   cd mpesa-daraja-mcp
   pnpm run docker:build
   pnpm run docker:start

   # Native development
   # Python development
   pip install -r requirements-dev.txt  # If exists

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

添加新API

更新抓取器URL:

   URLS = [
       "https://developer.safaricom.co.ke/apis/NewAPI",
       # ... existing URLs
   ]

测试刮擦:

   python scraper.py

更新API分类:

   // In mpesa-daraja-mcp/src/config.ts
   API_CATEGORIES: {
     new_category: ["NewAPI"],
     // ... existing categories
   }

验证MCP服务器:

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

代码的风格

python：遵循PEP 8，使用 black 格式化程序
TypeScript：使用Prettier格式、ESLint规则
码头工人：遵循多阶段构建的最佳实践
提交：使用常规提交格式

测试

# Test scraper
python scraper.py --test-mode

# Test MCP server (native)
cd mpesa-daraja-mcp
pnpm test
pnpm run build

# Test MCP server (Docker)
pnpm run docker:build
pnpm run docker:start
pnpm run docker:logs

文档

更新README以获取新功能
添加内联代码注释
更新API文档
包括Docker特定说明

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

⚠️ 重要许可证澄清:

软件许可证：MIT许可证仅适用于scraper和MCP服务器代码
文件权利：抓取的Daraja API文件仍归Safaricom PLC所有
单独条款：使用Safaricom的文档须遵守其服务条款
无转移：本许可证不授予Safaricom知识产权的权利

这意味着什么

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

归因

如果您使用此项目，请考虑：

⭐ 对存储库进行标记 在GitHub上
📝 提及该项目 在您的文档中
🔗 链接返回 到原始存储库

致谢

萨法利通信 用于提供Daraja API平台
模型上下文协议团队 对于MCP标准
编剧团队 优秀的自动化框架
Docker社区 集装箱化最佳实践
开源贡献者 是谁让这样的项目成为可能

存储库信息

仓库:
问题: 报告错误或请求功能
讨论: 社区讨论
发布: 最新版本

支持

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

⭐ 对存储库进行标记
🐛 报告问题 你遇到
💡 提出改进建议
🤝 贡献到项目
📢 共享与其他可能受益的人

______________________________________________________________________

准备好将Daraja API文档与您的人工智能助手集成吗？

Docker快速入门: cd mpesa-daraja-mcp && pnpm run docker:build && pnpm run docker:start

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

需要帮助？ 检查故障排除节或打开一个问题

从快速开始引导您的AI助手在几分钟内访问Daraja文档！

Daraja API MCP Server

快速接入

详细介绍