karma-mcp-server

Karma 通用 Agent MCP Server —— 薄接入层。把已有后端能力接到 MCP，不重写任何业务。

• 设计：docs/mcp/karma-mcp-architecture.md
• 工具契约：docs/mcp/karma-mcp-tools.md
• 安全：docs/mcp/karma-mcp-security.md

安全红线

• 本进程只注入 KARMA_RUNTIME_KEY；禁止私钥、助记词。启动时会检查并拒绝启动。
• 远程 HTTP 传输默认关闭（需 KARMA_MCP_ENABLE_HTTP=1 + KARMA_MCP_HTTP_TOKEN；缺一拒绝启动）。
• Tier-2/3（动钱）默认不注册（KARMA_MCP_ENABLE_TIER2/3=1 才开）。

环境变量

安装

# 在仓库根目录：
pip install ./packages/karma-mcp-server

# 没 clone 过仓库（公开仓库，一行装）：
pip install "karma-mcp-server @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-mcp-server"

PyPI 上还没有这个包（pip install karma-mcp-server 会 404）。装 / 接线 / 自检 / 发包的完整口径：docs/mcp/karma-mcp-integration.md。

运行

pip install -e ".[dev]"
karma-mcp-server                                    # stdio（本地 Agent，默认）

KARMA_MCP_ENABLE_HTTP=1 KARMA_MCP_HTTP_TOKEN=... \
  karma-mcp-server --transport streamable-http --host 0.0.0.0 --port 8765

远程启动有三道红线：进程里出现私钥 / 未设 KARMA_MCP_ENABLE_HTTP=1 / 没配 KARMA_MCP_HTTP_TOKEN —— 任一条不满足都拒绝启动。

测试

python -m pytest -q -c pyproject.toml

当前状态（第二阶段 S2–S5 已落地）

已实现并有测试（packages/karma-mcp-server/tests，56 例全绿）：

• S2 薄层：配置 / 凭据（只读）/ Agent Ed25519 逐请求签名（与服务端逐字对齐）/ 后端客户端（错误分类 + client_nonce）/ 凭据 0600 落盘 / stdio 入口。
• S3 配对与身份：karma_connect → karma_connect_status → karma_connect_claim （配对码只落本机文件，凭据只回指纹）；身份核验、授权状态、策略、交易 / 结算 / 信誉查询。
• S3 授权读写：karma_request_authorization（预览，不写后端）→ karma_submit_authorization（主人钱包签名后铸造）→ karma_update_authorization （铸新 + 撤旧）→ karma_revoke_authorization（一键停用）。
• S4 远程入口：--transport streamable-http + 静态 bearer token（常量时间比较）。
• S5 交易工具：Tier-2/3 已实现，默认不注册，按 Tier 白名单 fail-closed。

未做（S6 及以后）：跨平台适配器（Telegram / 微信等）、完整 OAuth 2.1 授权服务器接入。