Daraja MCP

🚀 薩法利通信達拉拉賈MCP服務器

這是一個模型上下文協議（MCP）服務器，它將薩法利通信（Safaricom）的M-PESA達拉拉賈（Daraja）API與Claude集成，實現自然語言支付處理和即時交易通知功能。

🚀 快速開始

前提條件

• 系統中安裝 Python 3.10+。
• 擁有 達拉拉賈API賬戶，可在 developer.safaricom.co.ke 註冊。
• （可選）安裝 ngrok 用於測試回調，可從 ngrok.com 下載。
• （可選）安裝 Claude桌面版 用於MCP集成。

安裝步驟

1. 克隆倉庫

# 克隆倉庫
git clone https://github.com/mboya/daraja-mcp.git
cd daraja-mcp

# 若已克隆倉庫，直接進入目錄
cd daraja-mcp

2. 設置虛擬環境

# 創建虛擬環境
python3 -m venv venv

# 激活虛擬環境
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

激活後，終端提示符前應顯示 (venv)。

3. 安裝依賴

# 從requirements.txt安裝所有必需的包
pip install -r requirements.txt

這將安裝以下包：

• mcp - 模型上下文協議服務器
• requests - 用於API調用的HTTP庫
• flask - 用於回調服務器的Web框架
• python-dotenv - 環境變量管理工具
• gunicorn - WSGI HTTP服務器（用於生產部署）

4. 配置環境變量

在項目根目錄下創建 .env 文件，倉庫中包含 .env.example 文件作為模板。 快速設置：

# 複製示例文件
cp .env.example .env

# 使用你喜歡的文本編輯器（如nano、vim、code等）編輯.env文件
nano .env

然後將佔位符值替換為你實際的達拉拉賈API憑證（見下面的 獲取達拉拉賈憑證 部分）。

運行服務器

快速啟動

完成上述安裝和配置步驟後，按以下步驟運行服務器：

1. 驗證設置

# 確保你在項目目錄中
cd daraja-mcp

# 激活虛擬環境
source venv/bin/activate  # macOS/Linux
# 或者
venv\Scripts\activate     # Windows

# 驗證.env文件是否存在
ls -la .env  # macOS/Linux
# 或者
dir .env     # Windows

2. 運行服務器
   • 本地開發並使用Claude桌面版

# 激活虛擬環境（如果尚未激活）
source venv/bin/activate

# 運行服務器
python server.py

- **生產/雲部署**

# 激活虛擬環境
source venv/bin/activate

# 使用Python運行（用於測試）
python server_http.py

# 或者使用gunicorn運行（用於生產）
gunicorn server_http:app --bind 0.0.0.0:3000 --workers 2

3. 驗證服務器是否運行
   • 檢查輸出：應看到以下內容

🚀 達拉拉賈MCP服務器啟動中...
📡 回調服務器正在0.0.0.0:3000上運行
🌐 公共回調URL: http://localhost:3000/mpesa/callback
🔧 環境: 沙盒

- **測試健康端點**：在新終端中運行

curl http://localhost:3000/health

預期響應：

{
  "status": "healthy",
  "callback_url": "http://localhost:3000/mpesa/callback",
  "unread_payments": 0
}

4. 設置ngrok（用於本地測試真實回調） 如果在本地開發期間需要接收真實的M-PESA回調：

# 在新終端中啟動ngrok
ngrok http 3000

# 複製HTTPS URL（例如，https://abc123.ngrok.io）
# 更新.env文件：
PUBLIC_URL=https://abc123.ngrok.io

# 重啟服務器
python server.py

5. 與Claude桌面版集成
   1. 打開Claude桌面版設置。
   2. 添加MCP服務器配置（見 與Claude桌面版集成 部分）。
   3. 重啟Claude桌面版。
   4. 開始聊天並使用自然語言處理支付！

不同場景下的運行方式

場景1：本地開發（無需回調）

source venv/bin/activate
python server.py

• 用於在本地測試MCP工具。
• 回調功能將無法使用（本地主機無法從互聯網訪問）。
• 適合開發和調試。

場景2：本地開發（使用ngrok進行回調）

# 終端1：啟動ngrok
ngrok http 3000

# 終端2：使用ngrok URL更新.env文件，然後啟動服務器
source venv/bin/activate
python server.py

• 用於測試帶有真實回調的完整支付流程。
• ngrok提供公共HTTPS URL。
• 薩法利通信可以訪問你的回調端點。

場景3：生產部署（Railway/Heroku）

# 部署到Railway（從git push自動部署）
git push origin main

# 或者在本地使用生產設置運行
source venv/bin/activate
gunicorn server_http:app --bind 0.0.0.0:3000 --workers 2

• 生產環境使用 server_http.py。
• Railway自動提供HTTPS。
• 無需ngrok。

啟動問題排查

• “無法分配請求的地址”：在macOS上綁定 0.0.0.0 時經常出現此問題。在本地開發時使用 127.0.0.1：

# 在.env文件中設置：
CALLBACK_HOST=127.0.0.1

如果 .env 文件中 CALLBACK_HOST 已經設置為 0.0.0.0，將其更改為 127.0.0.1 或刪除該行以使用默認值。服務器仍然可以與ngrok一起工作（ngrok將轉發到本地主機）。

• 端口已被使用：

# 檢查哪個進程正在使用3000端口
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# 殺死該進程或更改.env文件中的CALLBACK_PORT

• 缺少依賴項：

# 重新安裝依賴項
pip install -r requirements.txt

• 環境變量未加載：

# 驗證.env文件是否存在且值正確
cat .env

# 測試加載
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('DARAJA_CONSUMER_KEY'))"

• 服務器啟動但健康檢查失敗：

# 檢查Flask回調服務器是否正在運行
curl http://localhost:3000/health

# 檢查服務器日誌中的錯誤
# 在運行server.py的終端中查找錯誤消息

✨ 主要特性

• STK推送支付：通過自然語言發起M-PESA支付請求。
• 即時回調：使用Flask服務器自動處理支付通知。
• 支付跟蹤：存儲和查詢支付歷史記錄，並顯示已讀/未讀狀態。
• 自然語言界面：通過Claude對話與M-PESA進行交互。
• 沙盒測試：全面支持達拉拉賈沙盒環境。
• 自動化測試：擁有全面的測試套件進行驗證。

📦 安裝指南

環境變量

倉庫中包含 .env.example 文件，其中包含所有必需的環境變量。設置環境的步驟如下：

1. 複製示例文件：

cp .env.example .env

2. 編輯 .env 文件，使用實際憑證：

# 使用nano
nano .env

# 或者使用你喜歡的編輯器
code .env  # VS Code
vim .env   # Vim

3. 替換佔位符值 為你實際的達拉拉賈API憑證：

• DARAJA_CONSUMER_KEY - 你從達拉拉賈門戶獲取的消費者密鑰。
• DARAJA_CONSUMER_SECRET - 你從達拉拉賈門戶獲取的消費者密鑰。
• DARAJA_SHORTCODE - 你的業務短代碼（沙盒環境為174379）。
• DARAJA_PASSKEY - 你從達拉拉賈門戶獲取的密碼。
• PUBLIC_URL - 你的公共回調URL（本地測試使用ngrok URL）。

示例 .env 文件結構：

# 達拉拉賈API憑證
DARAJA_CONSUMER_KEY=your_consumer_key_here
DARAJA_CONSUMER_SECRET=your_consumer_secret_here
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=your_passkey_here

# 環境（沙盒或生產）
DARAJA_ENV=sandbox

# 回調服務器配置
CALLBACK_PORT=3000
CALLBACK_HOST=127.0.0.1
PUBLIC_URL=http://localhost:3000

重要提示：

• 本地開發使用 CALLBACK_HOST=127.0.0.1 以避免在macOS上出現 “無法分配請求的地址” 問題。
• 切勿將 .env 文件提交到版本控制！（它已經在 .gitignore 中）
• .env.example 文件可以安全提交，作為模板使用。
• 對於生產部署，在託管平臺（如Railway、Heroku等）中設置環境變量。

項目文件

倉庫中已經包含所有必要的文件：

• server.py - 用於本地Claude桌面版集成的MCP服務器（stdio）。
• server_http.py - 用於雲/生產部署的MCP服務器（HTTP）。
• test_daraja.py - 全面的測試套件。
• quick_test.py - 快速驗證腳本。
• requirements.txt - Python依賴項（已配置）。
• .gitignore - Git忽略規則（已配置）。
• .env.example - 環境變量模板。
• Procfile - Railway部署配置。
• railway.json - Railway平臺設置。
• README.md - 本文件。

你只需要通過複製 .env.example 創建 .env 文件：

cp .env.example .env

然後使用你實際的達拉拉賈API憑證編輯 .env 文件（見上面的配置部分）。

💻 使用示例

啟動服務器

本地開發（Claude桌面版）

# 激活虛擬環境
source venv/bin/activate

# 運行用於Claude桌面版的stdio服務器
python server.py

預期輸出：

🚀 達拉拉賈MCP服務器啟動中...
📡 回調服務器正在0.0.0.0:3000上運行
🌐 公共回調URL: http://localhost:3000/mpesa/callback
🔧 環境: 沙盒

生產/雲部署

# 激活虛擬環境
source venv/bin/activate

# 運行HTTP服務器（用於Railway、Heroku等）
python server_http.py

# 或者使用gunicorn進行生產部署（如Procfile中配置）
gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

預期輸出：

🚀 達拉拉賈MCP服務器（HTTP模式）
📡 正在監聽3000端口
🌐 公共URL: http://localhost:3000
🔧 環境: 沙盒

服務器組件

MCP服務器同時運行兩個組件：

1. MCP協議服務器 - 通過stdio與Claude通信。
2. Flask回調服務器 - 在3000端口接收M-PESA支付通知。

選擇 server.py 還是 server_http.py

本項目包含兩個服務器實現，適用於不同的使用場景：

server.py - 用於本地Claude桌面版集成（stdio）

適用場景：

• 在本地機器上運行MCP服務器。
• 與Claude桌面版應用集成。
• 進行本地開發和測試。
• 使用stdio（標準輸入/輸出）進行MCP通信。

特性：

• 通過stdio協議與Claude桌面版通信。
• 在後臺線程中運行Flask回調服務器。
• 實現了完整的MCP工具，具備所有功能。
• 最適合本地開發和測試。

使用方法：

python server.py

server_http.py - 用於遠程部署（HTTP）

適用場景：

• 部署到雲平臺（如Railway、Heroku、AWS等）。
• 在生產環境中運行。
• 需要基於HTTP的MCP端點。
• 使用gunicorn或類似的WSGI服務器。

特性：

• 單個Flask應用，結合了MCP HTTP端點和回調。
• 暴露 /mcp/tools 和 /mcp/call_tool 端點。
• 與gunicorn配合用於生產部署。
• 與Railway的Procfile配置兼容。

使用方法：

# 使用gunicorn進行生產部署（如Procfile中配置）
gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

# 本地測試
python server_http.py

Railway部署： Procfile 配置為使用 server_http.py 和gunicorn：

web: gunicorn server_http:app --bind 0.0.0.0:$PORT --workers 2

總結：

• 本地開發並使用Claude桌面版 → 使用 server.py。
• 雲/生產部署 → 使用 server_http.py。

📚 詳細文檔

測試

快速測試（建議每日檢查）

# 終端1：啟動服務器
source venv/bin/activate
python server.py

# 終端2：運行快速測試
source venv/bin/activate
python quick_test.py

預期輸出：

🔐 測試達拉拉賈認證...
✅ 認證成功！（沙盒環境）

🌐 測試回調服務器...
✅ 回調服務器正在運行！

📨 測試回調端點...
✅ 回調端點正常工作！

測試通過: 3/3
🎉 所有測試通過！

全面測試套件

python test_daraja.py

此測試運行8個測試階段：

1. 環境變量驗證
2. Python依賴項檢查
3. 達拉拉賈API認證
4. MCP服務器啟動
5. 回調服務器健康檢查
6. 回調端點處理
7. ngrok可用性
8. STK推送格式驗證

手動測試

• 測試認證

curl -X GET "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials" \
  -H "Authorization: Basic $(echo -n 'KEY:SECRET' | base64)"

• 測試回調服務器

curl http://localhost:3000/health

• 測試回調端點

curl -X POST http://localhost:3000/mpesa/callback \
  -H "Content-Type: application/json" \
  -d '{
    "Body": {
      "stkCallback": {
        "ResultCode": 0,
        "ResultDesc": "Success"
      }
    }
  }'

與Claude桌面版集成

1. 定位配置文件

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加MCP服務器配置

{
  "mcpServers": {
    "daraja": {
      "command": "/absolute/path/to/daraja-mcp/venv/bin/python",
      "args": ["/absolute/path/to/daraja-mcp/server.py"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your_consumer_key",
        "DARAJA_CONSUMER_SECRET": "your_consumer_secret",
        "DARAJA_SHORTCODE": "174379",
        "DARAJA_PASSKEY": "your_passkey",
        "DARAJA_ENV": "sandbox",
        "CALLBACK_PORT": "3000",
        "PUBLIC_URL": "https://your-ngrok-url.ngrok.io"
      }
    }
  }
}

重要提示：

• 使用絕對路徑（而非相對路徑）。
• 使用虛擬環境的Python：venv/bin/python。
• 使用你的ngrok HTTPS URL更新 PUBLIC_URL。

3. 重啟Claude桌面版

完全退出並重新打開Claude桌面版以加載MCP服務器。

4. 驗證集成

在Claude桌面版中詢問：

"達拉拉賈回調服務器是否正常工作？"

Claude應回覆服務器狀態信息。

可用工具

配置完成後，Claude可以使用以下工具：

1. stk_push

發起STK推送支付請求。 示例：

"向0712345678發送500肯尼亞先令的支付請求，訂單號為#INV-001"

參數：

• phone_number - 客戶電話號碼（254XXXXXXXXX或07XXXXXXXX）
• amount - 金額（肯尼亞先令，最低1）
• account_reference - 參考信息，如發票/訂單號
• transaction_desc - 交易描述

2. stk_query

檢查支付請求的狀態。 示例：

"檢查結賬請求ws_CO_12345的狀態"

參數：

• checkout_request_id - STK推送返回的ID

3. get_recent_payments

查看最近的支付通知。 示例：

"顯示最近10筆支付"

參數：

• limit - 要檢索的支付數量（默認：10，最大：50）

4. get_payment_details

獲取特定支付的詳細信息。 示例：

"顯示收據QAR7I8K3LM的詳細信息"

參數：

• checkout_request_id - 或者 -
• mpesa_receipt - M-PESA收據號碼

5. mark_payment_read

將通知標記為已讀。 示例：

"將支付ws_CO_12345標記為已讀"

6. get_notification_summary

獲取所有通知的摘要。 示例：

"我有多少未讀支付？"

7. get_callback_status

檢查回調服務器是否正在運行。 示例：

"回調服務器是否正常工作？"

回調設置

為什麼需要ngrok（或類似的隧道服務）

問題：

• M-PESA達拉拉賈API需要 HTTPS回調（而非HTTP）。
• 薩法利通信的服務器需要從互聯網訪問你的回調端點。
• 你的本地開發服務器（localhost:3000）無法從互聯網訪問。
• 防火牆和NAT阻止外部訪問你的本地機器。

解決方案： ngrok創建一個安全隧道，具有以下優點：

• ✅ 通過HTTPS將你的本地服務器暴露到互聯網。
• ✅ 提供一個薩法利通信可以訪問的公共URL。
• ✅ 自動處理SSL/TLS加密。
• ✅ 允許在不部署到生產環境的情況下進行即時測試。
• ✅ 在Web界面中顯示所有傳入請求，便於調試。

工作原理：

薩法利通信服務器 → ngrok HTTPS URL → ngrok隧道 → 你的本地服務器（localhost:3000）

本地測試使用ngrok

1. 安裝ngrok

# macOS
brew install ngrok

# Linux（使用snap）
sudo snap install ngrok

# Windows
# 從https://ngrok.com/download下載
# 或者使用Chocolatey：choco install ngrok

# 或者直接從https://ngrok.com/download下載

免費註冊：訪問 ngrok.com 並創建一個賬戶以獲取你的認證令牌。

2. 認證ngrok（僅首次需要）

ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

3. 啟動ngrok隧道

# 將HTTPS流量轉發到本地端口3000
ngrok http 3000

輸出：

Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Latency                       45ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

重要提示：複製 Forwarding 的HTTPS URL（例如，https://abc123.ngrok.io）。

4. 更新配置

更新 .env 文件中的 PUBLIC_URL：

PUBLIC_URL=https://abc123.ngrok.io

或者在Claude桌面版配置中更新ngrok URL。

注意：免費的ngrok URL每次重啟ngrok時都會改變。若需要靜態URL，可以升級到付費計劃或使用ngrok的保留域名功能。

5. 重啟服務器

# 停止服務器（Ctrl+C）
# 使用新的PUBLIC_URL重啟
python server.py

6. 驗證ngrok是否正常工作

• 檢查ngrok Web界面：在瀏覽器中打開 http://localhost:4040，你將看到所有通過ngrok轉發的請求，這有助於調試回調問題。
• 測試隧道：

# 通過ngrok測試健康端點
curl https://abc123.ngrok.io/health

# 應返回：
# {"status":"healthy","callback_url":"https://abc123.ngrok.io/mpesa/callback",...}

7. 保持ngrok運行

重要提示：在測試期間保持ngrok終端窗口打開。如果關閉它，隧道將停止，薩法利通信將無法訪問你的回調端點。

專業提示：在單獨的終端中運行ngrok，或使用 tmux 或 screen 等進程管理器：

# 使用tmux
tmux new -s ngrok
ngrok http 3000
# 按Ctrl+B然後D分離（保持在後臺運行）

ngrok替代方案

如果你更喜歡其他隧道服務：

• Cloudflare Tunnel（cloudflared） - 免費，基本使用無需賬戶

cloudflared tunnel --url http://localhost:3000

• localtunnel - 基於npm的簡單隧道

npx localtunnel --port 3000

• serveo - 基於SSH的隧道（無需安裝）

ssh -R 80:localhost:3000 serveo.net

然而，建議使用ngrok，因為它：

• 最可靠和穩定。
• 有最佳的文檔和社區支持。
• 提供Web界面用於請求檢查。
• 易於使用和配置。

生產回調設置

對於生產環境，部署到具備以下條件的服務器：

1. 公共HTTPS端點（需要SSL證書）
2. 靜態IP或域名
3. 防火牆規則，允許傳入的HTTPS流量
4. 監控和日誌記錄

常見選項：

• 帶有彈性IP的AWS EC2
• DigitalOcean Droplet
• 帶有SSL的Heroku
• Google Cloud Run
• Railway（推薦 - 見下面的部署指南）

示例nginx配置：

server {
    listen 443 ssl;
    server_name api.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mpesa/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Railway部署（快速啟動）

Railway是部署此MCP服務器的絕佳選擇，因為它：

• ✅ 自動提供HTTPS端點。
• ✅ 處理SSL證書。
• ✅ 易於配置環境變量。
• ✅ 支持從Git自動部署。
• ✅ 提供免費測試層。

Railway部署步驟

1. 創建Railway賬戶：訪問 railway.app，使用GitHub/GitLab註冊。
2. 創建新項目：點擊 “New Project”，選擇 “Deploy from GitHub repo”（或上傳代碼）。
3. 配置環境變量：在Railway儀表板中添加以下環境變量：

DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=your_passkey
DARAJA_ENV=sandbox
CALLBACK_PORT=3000
PUBLIC_URL=https://your-app-name.railway.app

注意：在Railway上，應用由gunicorn提供服務，它會自動綁定到 0.0.0.0:$PORT，你無需設置 CALLBACK_HOST。 4. 部署：Railway將自動檢測 Procfile 和 railway.json，Procfile 使用 server_http.py 和gunicorn，Railway將自動構建和部署。 5. 獲取公共URL：Railway提供一個公共HTTPS URL（例如，https://your-app.railway.app），使用此URL更新 PUBLIC_URL 環境變量，Railway將自動重啟服務。 6. 驗證部署：

# 測試健康端點
curl https://your-app.railway.app/health

# 應返回：
# {"status":"healthy","callback_url":"https://your-app.railway.app/mpesa/callback",...}

重要注意事項：

• Railway自動提供HTTPS，因此生產環境無需ngrok。
• PUBLIC_URL 必須與你的Railway應用URL完全匹配。
• 對於Railway部署，使用 server_http.py（在 Procfile 中配置）。
• Railway通過 $PORT 環境變量自動處理端口綁定。

故障排除

常見問題

1. “無法獲取訪問令牌”

原因：

• 消費者密鑰或密鑰無效。
• 環境錯誤（沙盒與生產環境）。
• 網絡連接問題。

解決方案：

# 手動測試認證
python -c "
from dotenv import load_dotenv
import os, base64, requests
load_dotenv()
key = os.getenv('DARAJA_CONSUMER_KEY')
secret = os.getenv('DARAJA_CONSUMER_SECRET')
auth = base64.b64encode(f'{key}:{secret}'.encode()).decode()
r = requests.get('https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
                 headers={'Authorization': f'Basic {auth}'})
print(r.json())
"

2. “回調服務器無響應”

解決方案：

# 檢查3000端口是否可用
lsof -i :3000

# 殺死使用該端口的任何進程
kill -9 <PID>

# 重啟服務器
python server.py

3. “Claude中找不到MCP服務器”

解決方案：

• 驗證配置文件路徑是否正確。
• 在配置中使用絕對路徑。
• 確保虛擬環境Python路徑正確。
• 檢查Claude桌面版日誌：幫助 → 查看日誌。
• 完全重啟Claude桌面版。

4. “未收到回調”

解決方案：

• 驗證ngrok是否正在運行：curl https://your-url.ngrok.io/health。
• 檢查 PUBLIC_URL 環境變量。
• 確保ngrok URL是HTTPS（薩法利通信要求）。
• 查看ngrok請求日誌：http://localhost:4040。
• 檢查防火牆設置。

5. “無效的電話號碼”

解決方案：

• 使用格式：254XXXXXXXXX（不是 +254 或 07XX）。
• 沙盒環境：使用達拉拉賈門戶的測試號碼。
• 去除空格、破折號或特殊字符。

調試命令

# 檢查服務器進程
ps aux | grep server.py

# 測試回調健康
curl http://localhost:3000/health

# 測試ngrok轉發
curl https://your-ngrok-url.ngrok.io/health

# 查看Python錯誤
tail -f server.log

# 檢查Claude日誌
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs\

獲取幫助

1. 查看達拉拉賈API文檔：developer.safaricom.co.ke/Documentation。
2. 查看ngrok請求檢查器：http://localhost:4040。
3. 檢查Claude桌面版日誌。
4. 驗證所有環境變量是否正確設置。
5. 獨立測試每個組件。

安全最佳實踐

1. 憑證管理

• ✅ 切勿將憑證提交到版本控制。
• ✅ 使用 .env 文件並配置 .gitignore。
• ✅ 定期輪換憑證。
• ✅ 沙盒和生產環境使用不同的憑證。
• ✅ 將生產密鑰存儲在安全的保險庫中（如AWS Secrets Manager等）。

2. 網絡安全

• ✅ 所有回調使用HTTPS（薩法利通信要求）。
• ✅ 實現Webhook簽名驗證。
• ✅ 將回調端點限制為薩法利通信的IP地址。
• ✅ 使用防火牆規則限制訪問。
• ✅ 啟用速率限制。

3. 應用程序安全

• ✅ 驗證所有輸入數據。
• ✅ 清理電話號碼和金額。
• ✅ 實現請求日誌記錄。
• ✅ 為敏感操作添加身份驗證。
• ✅ 使用特定於環境的配置。

4. 數據隱私

• ✅ 不記錄敏感數據（PIN、完整卡號）。
• ✅ 在日誌中屏蔽電話號碼。
• ✅ 實施數據保留策略。
• ✅ 遵守數據保護法規。
• ✅ 加密數據在靜止和傳輸過程中。

5. 監控

• ✅ 設置錯誤警報。
• ✅ 監控回調成功率。
• ✅ 跟蹤失敗的交易。
• ✅ 記錄所有API調用。
• ✅ 實施健康檢查。

生產部署

預部署清單

• [ ] 在沙盒環境中進行全面測試。
• [ ] 從達拉拉賈獲取生產憑證。
• [ ] 設置帶有SSL/TLS的生產服務器。
• [ ] 配置防火牆和安全組。
• [ ] 實施適當的日誌記錄和監控。
• [ ] 設置錯誤警報。
• [ ] 記錄部署過程。
• [ ] 創建備份和恢復計劃。
• [ ] 先使用小額測試。
• [ ] 配置失敗時自動重啟。

部署步驟

1. 準備服務器

# 更新系統
sudo apt update && sudo apt upgrade -y

# 安裝Python
sudo apt install python3.10 python3.10-venv -y

# 安裝nginx（用於反向代理）
sudo apt install nginx -y

# 安裝supervisor（用於進程管理）
sudo apt install supervisor -y

2. 部署應用程序

# 創建應用程序目錄
sudo mkdir -p /opt/daraja-mcp
sudo chown $USER:$USER /opt/daraja-mcp
cd /opt/daraja-mcp

# 克隆或複製應用程序文件
# 設置虛擬環境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 創建生產.env文件
nano .env
# 添加生產憑證

3. 配置Supervisor

創建 /etc/supervisor/conf.d/daraja-mcp.conf：

[program:daraja-mcp]
command=/opt/daraja-mcp/venv/bin/python /opt/daraja-mcp/server.py
directory=/opt/daraja-mcp
user=www-data
autostart=true
autorestart=true
stderr_logfile=/var/log/daraja-mcp/error.log
stdout_logfile=/var/log/daraja-mcp/access.log
environment=PRODUCTION="true"

4. 配置nginx

創建 /etc/nginx/sites-available/daraja-mcp：

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

5. 啟動服務

# 重新加載supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start daraja-mcp

# 啟用並重啟nginx
sudo ln -s /etc/nginx/sites-available/daraja-mcp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 檢查狀態
sudo supervisorctl status daraja-mcp
curl https://api.yourdomain.com/health

監控和維護

# 查看日誌
sudo tail -f /var/log/daraja-mcp/error.log

# 重啟服務
sudo supervisorctl restart daraja-mcp

# 檢查資源使用情況
htop

# 監控nginx訪問日誌
sudo tail -f /var/log/nginx/access.log

🔧 技術細節

達拉拉賈API端點

認證

GET https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic <base64(consumer_key:consumer_secret)>

STK推送

POST https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "TransactionType": "CustomerPayBillOnline",
  "Amount": 100,
  "PartyA": "254712345678",
  "PartyB": "174379",
  "PhoneNumber": "254712345678",
  "CallBackURL": "https://your-domain.com/callback",
  "AccountReference": "Order123",
  "TransactionDesc": "Payment for Order123"
}

STK查詢

POST https://api.safaricom.co.ke/mpesa/stkpushquery/v1/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": "174379",
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20240108143022",
  "CheckoutRequestID": "ws_CO_08012024123456789"
}

MCP服務器端點

健康檢查

GET http://localhost:3000/health

Response:
{
  "status": "healthy",
  "callback_url": "http://localhost:3000/mpesa/callback",
  "unread_payments": 0
}

M-PESA回調

POST http://localhost:3000/mpesa/callback
Content-Type: application/json

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_08012024123456789",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {"Name": "Amount", "Value": 100},
          {"Name": "MpesaReceiptNumber", "Value": "QAR7I8K3LM"},
          {"Name": "TransactionDate", "Value": 20240108143022},
          {"Name": "PhoneNumber", "Value": 254712345678}
        ]
      }
    }
  }
}

項目結構

daraja-mcp/
├── venv/                       # 虛擬環境（不在git中）
├── server.py                   # 用於本地Claude桌面版的MCP服務器（stdio）
├── server_http.py              # 用於雲部署的MCP服務器（HTTP）
├── test_daraja.py             # 全面的測試套件
├── quick_test.py              # 快速驗證腳本
├── Procfile                   # Railway部署配置
├── railway.json               # Railway平臺配置
├── .env                       # 環境變量（不在git中）
├── .gitignore                 # Git忽略規則
├── requirements.txt           # Python依賴項
├── README.md                  # 本文件
└── docs/                      # 其他文檔
    ├── DEPLOYMENT.md          # 部署指南
    ├── API.md                 # API文檔
    └── TROUBLESHOOTING.md     # 擴展故障排除文檔

關鍵文件：

• server.py - 用於與Claude桌面版進行本地開發（stdio協議）。
• server_http.py - 用於像Railway這樣的雲部署（HTTP端點）。
• Procfile - 定義Railway如何運行應用程序（使用 server_http.py）。
• railway.json - Railway平臺配置（構建器、副本、重啟策略）。

📄 許可證

本項目採用MIT許可證 - 詳情請見 LICENSE 文件。

致謝

• 薩法利通信達拉拉賈API - M-PESA API平臺
• Anthropic MCP - 模型上下文協議
• Flask - 用於回調的Web框架
• ngrok - 用於本地開發的安全隧道

支持

• 文檔：developer.safaricom.co.ke/Documentation
• 達拉拉賈支持：support@safaricom.co.ke
• MCP文檔：modelcontextprotocol.io
• 問題反饋：GitHub Issues

變更日誌

v1.0.0 (2024-01-08)

• 初始版本發佈
• 實現STK推送功能
• 即時回調處理
• 支付通知存儲
• 自動化測試套件
• 與Claude桌面版集成
• 全面的文檔

---

為M-PESA生態系統精心打造 ❤️

如有問題或需要支持，請在GitHub上提交問題或聯繫維護者。