Subway Open Platform MCP Adapter
将 Subway 开放平台 API 通过 MCP (Model Context Protocol) 协议暴露为 AI 可调用的工具。
概述
这个 MCP Adapter 服务将 Java 开放平台客户端封装为 Python MCP 工具,使得 AI 助手可以直接调用开放平台接口。它自动处理:
- ✅ RSA 签名生成(完全兼容 Java 实现)
- ✅ 时间戳和随机数生成
- ✅ 请求头自动注入
- ✅ Token 鉴权支持
- ✅ 异步 HTTP 调用
快速开始
1. 安装 uv
# macOS
brew install uv
# Linux/Windows
curl -LsSf https://astral.sh/uv/install.sh | sh
2. 配置 AI IDE
在 Cursor/Claude Desktop 的 MCP 配置中添加:
{
"mcpServers": {
"subway-open-platform": {
"command": "uvx",
"args": ["subway-mcp-open-api-adapter"],
"env": {
"OPEN_PLATFORM_GATEWAY_URL": "https://your-gateway.com",
"OPEN_PLATFORM_APP_INSTANCE_ID": "your-instance-id",
"OPEN_PLATFORM_PARTNER_ID": "your-partner-id",
"OPEN_PLATFORM_APP_INSTANCE_VERSION": "1.0.0",
"OPEN_PLATFORM_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYOUR_KEY\n-----END PRIVATE KEY-----",
"OPEN_PLATFORM_ACCESS_TOKEN": "token-abc-123"
}
}
}
}
3. 开始使用
重启 AI IDE 后,可以直接在对话中使用:
查询会员 3742473176800792202 的信息
配置说明
环境变量清单
| 环境变量 | 必填 | 说明 | 示例 |
|---|---|---|---|
OPEN_PLATFORM_GATEWAY_URL |
✅ | 开放平台网关地址 | https://api.example.com |
OPEN_PLATFORM_APP_INSTANCE_ID |
✅ | 应用实例 ID | instance-001 |
OPEN_PLATFORM_PARTNER_ID |
✅ | 商户号 | P123456 |
OPEN_PLATFORM_APP_INSTANCE_VERSION |
❌ | 应用版本(默认 1.0.0) |
1.0.0 |
OPEN_PLATFORM_PRIVATE_KEY |
✅ | RSA 私钥(PEM 格式) | -----BEGIN PRIVATE KEY-----... |
OPEN_PLATFORM_ACCESS_TOKEN |
❌ | 访问令牌 | token-abc-123 |
重要说明
appInstanceId vs partnerId:
OPEN_PLATFORM_APP_INSTANCE_ID→ 用于appInstanceId请求头(网关签名)OPEN_PLATFORM_PARTNER_ID→ 用于auth_partnerId请求头(业务鉴权)和请求体中的partnerId字段- 这两个值可能相同,但它们是不同的配置项
可用的 MCP 工具
1. get_member_info - 查询会员信息
对应Java接口: SaasMemberClient.getMember()
API路径: POST /opencenter/customer/member/getMember
支持通过会员ID、手机号或动态码查询:
# 通过会员ID查询
get_member_info(ident_type="memberId", ident_id="3742473176800792202")
# 通过手机号查询
get_member_info(ident_type="mobile", ident_id="13800138000")
# 通过动态码查询
get_member_info(ident_type="dynamicCode", ident_id="56#123456#")
2. svc_refund - 会员储值卡退款
对应Java接口: SaasMemberSvcClient.svcRefund()
API路径: POST /opencenter/mam/member/svc/refund
svc_refund(
fpid="FP001",
out_order_no="OUT123456",
refund_trade_no="REFUND789",
refund_amount=10000, # 单位:分(10000分=100元)
refund_desc="客户申请退款"
)
签名机制
自动处理的请求头
每次请求都会自动生成以下请求头:
签名相关(SaaSFeignConfig)
apiVersion: v2
appInstanceId: {OPEN_PLATFORM_APP_INSTANCE_ID}
appVersion: {OPEN_PLATFORM_APP_INSTANCE_VERSION}
nonce: {自动生成10位随机字符串}
timestamp: {当前时间戳(毫秒)}
sign: {RSA签名}
签名算法:
- 签名字符串格式:
{timestamp};{nonce};{request_body}; - 签名算法:SHA256withRSA
- 使用紧凑JSON格式(无空格),与Java Feign/Jackson一致
业务鉴权(GlobalFeignConfig)
access_token: {OPEN_PLATFORM_ACCESS_TOKEN} # 如果配置了
auth_partnerId: {OPEN_PLATFORM_PARTNER_ID}
auth_appId: {OPEN_PLATFORM_APP_ID}
项目结构
mcp-python/
├── src/subway_mcp_adapter/ # 源代码
│ ├── __init__.py # 包初始化
│ ├── config.py # 配置管理
│ ├── client.py # HTTP客户端(含签名逻辑)
│ ├── server.py # MCP Server(工具定义)
│ └── utils/
│ ├── rsa.py # RSA签名工具
│ └── nonce.py # 随机数生成
├── README.md # 项目文档
├── HEADERS_MAPPING.md # 请求头详细说明
├── INTERFACE_REVISION.md # 接口修订说明
├── pyproject.toml # 项目配置
├── requirements.txt # Python依赖
└── Makefile # 构建脚本
技术栈
- Python: 3.10+
- MCP Framework: FastMCP
- HTTP Client: httpx (异步)
- 加密库: cryptography
- 配置管理: pydantic + pyyaml
常见问题
Q: 签名验证失败怎么办?
- 检查私钥格式是否正确(PEM格式)
- 确认所有必填环境变量已配置
- 设置 DEBUG 日志查看详细信息:
export MCP_LOG_LEVEL=DEBUG
Q: 如何添加新的 API 接口?
编辑 src/subway_mcp_adapter/server.py,在 _register_tools() 方法中添加:
@self.mcp.tool(name="new_tool", description="描述这个工具的功能")
async def new_tool(param1: str) -> str:
response = await self.client.post(
"/your-api-path",
body={"param1": param1}
)
return json.dumps(response, ensure_ascii=False, indent=2)
相关文档
- 请求头详细说明 - 完整的请求头映射和签名算法说明
许可证
Internal Use Only
Metadata
Release files for subway-mcp-open-api-adapter 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| subway_mcp_open_api_adapter-1.1.0.tar.gz | 16.2 kB | Without provenance | Details for subway_mcp_open_api_adapter-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| subway_mcp_open_api_adapter-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for subway_mcp_open_api_adapter-1.1.0-py3-none-any.whl |
Total release size: 31.3 kB
Release files / subway_mcp_open_api_adapter-1.1.0.tar.gz
| Download URL | subway_mcp_open_api_adapter-1.1.0.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54a3ece6c34b73b31654581ae5f2926ac7f3822cacd172acd741cf13d055a787
|
|
BLAKE2b-256 checksum How to use checksums |
db6103d51b0f1a6d00ffa4aa75e52cdcb9d935dbc2e265877eaf4242ae8527a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Release files / subway_mcp_open_api_adapter-1.1.0-py3-none-any.whl
| Download URL | subway_mcp_open_api_adapter-1.1.0-py3-none-any.whl |
|---|---|
| Size | 15.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
558706f43391813174506c19787798778b2bf0946c5fb6f498e5e68bdc8bf8f7
|
|
BLAKE2b-256 checksum How to use checksums |
36ebfc62151e0222b4693d8a769b4f17b2c28a0d101bff7a32935c7b2666f5ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.7
|
Security for subway-mcp-open-api-adapter 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.