Daraja API文档抓取器和MCP服务器
通过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等
- 离线就绪:包括可立即使用的完整文档数据集
- 自动发现:智能路径检测,实现无缝设置
目录
- 重要法律声明和免责声明
- 快速开始
- 安装
- Docker部署
- 刮板使用
- MCP服务器设置
- 编辑器集成
- API文档
- 故障排除
- 贡献
- 许可证
- 贡献
快速开始
选项1:Docker部署(推荐)```bash
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:本机安装```bash
# 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设置```bash
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** (用于克隆)
### 平台特定设置
#### 视窗```powershell
# 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```bash
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)```bash
# 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设置```bash
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管理命令```bash
# 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编写配置```yaml
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配置:```json
{
"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环境:```bash
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
1. **运行刮板**:```bash
python scraper.py
- 登录进程:
- 浏览器窗口自动打开
- 出现提示时手动登录Daraja门户
- 登录成功后,在终端中按ENTER键
- Scraper保存会话以备将来使用
更新文档
获取最新的API文档:```bash
Activate environment
source venv/bin/activate
Run scraper (uses saved session)
python scraper.py
If session expired, login again when browser opens
### 输出结构```text
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文档的权限。
本地构建和测试```bash
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个综合工具:
1. **`search_daraja_apis`** -具有类别过滤功能的高级搜索
1. **`get_daraja_api_doc`** -完成API文档检索
1. **`list_apis_by_category`** -按类别组织API列表
1. **`get_api_summary`** -带有端点的增强摘要
1. **`get_server_stats`** -使用统计和监控
1. **`compare_apis`** -API并列比较
### 服务器配置
服务器会自动检测以下位置的文档:
- `../daraja_docs_v3` (相对于服务器)
- `./daraja_docs_v3` (当前目录)
- `/app/daraja_docs_v3` (Docker容器)
- 通过环境变量自定义路径
## 编辑器集成
### 开发 IDE
1. **创建MCP配置文件**:```bash
# Create .kiro/settings/mcp.json in your workspace
mkdir -p .kiro/settings
- Docker配置 (推荐):```json
{
"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"
]
}
}
}
1. **本机配置**:```json
{
"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中配置:```json
{
"mcp.servers": {
"daraja-docs": {
"command": "docker",
"args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
}
}
}
### 光标IDE
1. **打开光标设置**
1. **添加MCP服务器配置**:```json
{
"mcp": {
"servers": {
"daraja-docs": {
"command": "docker",
"args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
}
}
}
}
帆板运动
-
访问Windsurf MCP设置
-
添加服务器配置:```json
{
"mcpServers": {
"daraja-docs": {
"command": "docker",
"args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
}
}
}
### 克劳德桌面版
1. **编辑Claude配置文件**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
1. **添加服务器配置**:```json
{
"mcpServers": {
"daraja-docs": {
"command": "docker",
"args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"]
}
}
}
通用MCP客户端
对于任何使用Docker的MCP兼容客户端:```json
{
"servers": {
"daraja-docs": {
"command": "docker",
"args": ["exec", "-i", "daraja-mcp-server", "node", "dist/index.js"],
"env": {}
}
}
}
对于本机安装:```json
{
"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问题
容器无法启动```bash
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
#### 在容器中找不到文档```bash
# 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连接问题```bash
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服务器问题
**服务器无法启动**:```bash
# Check Node.js version
node --version # Should be 18+
# Rebuild server
cd mpesa-daraja-mcp
pnpm run clean
pnpm install
pnpm run build
未找到文档:```bash
Test documentation detection
pnpm test
Check paths manually
ls -la ../daraja_docs_v3/data_index.json
**TypeScript错误**:```bash
# Update dependencies
pnpm update
pnpm run build
# Check for syntax errors
pnpm run dev
刮刀问题
浏览器无法打开:```bash
Install browser dependencies
playwright install chromium
Check Python version
python --version # Should be 3.8+
**登录会话已过期**:```bash
# Delete auth file and re-login
rm auth.json
python scraper.py
权限错误:```bash
Check file permissions
chmod +x scraper.py
Or run with python explicitly
python scraper.py
### 编辑器集成问题
#### MCP服务器未连接
1. **验证Docker容器是否正在运行**:```bash
pnpm run docker:status
- 检查MCP配置语法:
- 确保JSON有效
- 验证命令和参数是否正确
- 使用绝对路径进行本机安装
- 手动测试服务器:```bash
Docker
docker exec -i daraja-mcp-server node dist/index.js
Native
cd mpesa-daraja-mcp
node dist/index.js
1. **重新启动编辑器** 配置更改后
#### 工具未出现
1. **检查服务器日志** 在编辑的MCP面板中
1. **验证自动批准列表** 包括所需工具
1. **确保服务器构建成功**: `pnpm run build`
1. **以最小配置进行测试** 第一
### 平台特定问题
#### 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性能```bash
# 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服务器性能```bash
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
### 获取帮助
1. **先检查日志**:Docker和本机安装都提供详细的错误消息
1. **单独测试组件**:使用 `pnpm test` 验证MCP服务器设置
1. **验证路径和权限**:确保所有文件路径正确且可访问
1. **更新依赖关系**:保持Docker、Node.js和Python包的最新版本
1. **使用Docker实现一致性**:Docker消除了大多数特定于平台的问题
## 贡献
**⚠️ 贡献者数据处理指南**:
- **PR中没有报废数据**:在pull请求中不包括抓取的文档
- **尊重知识产权**:确保贡献不侵犯Safaricom的知识产权
- **仅限代码**:改进scraper和MCP服务器代码,而不是数据
- **文档**:更新README和代码注释,而不是抓取API文档
### 开发设置
1. **克隆该仓库**
1. **创建特征分支**: `git checkout -b feature/amazing-feature`
1. **设置开发环境**:```bash
# 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:```python
URLS = [
"https://developer.safaricom.co.ke/apis/NewAPI",
... existing URLs
]
1. **测试刮擦**:```bash
python scraper.py
- 更新API分类:```typescript
// In mpesa-daraja-mcp/src/config.ts
API_CATEGORIES: {
new_category: ["NewAPI"],
// ... existing categories
}
1. **验证MCP服务器**:```bash
cd mpesa-daraja-mcp
pnpm test
pnpm run docker:build
代码的风格
- python:遵循PEP 8,使用
black格式化程序 - TypeScript:使用Prettier格式、ESLint规则
- 码头工人:遵循多阶段构建的最佳实践
- 提交:使用常规提交格式
测试```bash
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社区 集装箱化最佳实践
- 开源贡献者 是谁让这样的项目成为可能
存储库信息
- 仓库: https://github.com/JacksCodeVault/mpesa-daraja-mcp
- 问题: 报告错误或请求功能
- 讨论: 社区讨论
- 发布: 最新版本
支持
如果你觉得这个项目有帮助,请考虑:
- ⭐ 对存储库进行标记
- 🐛 报告问题 你遇到
- 💡 提出改进建议
- 🤝 贡献 到项目
- 📢 共享 与其他可能受益的人
准备好将Daraja API文档与您的人工智能助手集成吗?
Docker快速入门: cd mpesa-daraja-mcp && pnpm run docker:build && pnpm run docker:start
浏览文档:使用MCP工具探索22个全面的Daraja API
需要帮助? 检查 故障排除 节或打开一个问题
从 快速开始 引导您的AI助手在几分钟内访问Daraja文档!
