ming-metaphysics-mcp

将五种中国玄学引擎作为 MCP 工具，适用于 Claude Desktop 及任何兼容 MCP 的客户端。

与 Cantian 的 bazi-mcp 对比

工具

引擎要求

此包是一个 MCP 封装器。它不包含玄学计算逻辑 — 它通过 HTTP 将工具调用转发给 Ming 引擎端点。要使用它，请将 MING_API_URL 指向正在运行的引擎。

获取引擎的两种方式：

1. 托管端点（推荐，如有）。公共 Ming 端点即将发布；一旦可用，配置 MING_API_URL 指向它即可。

2. 自托管。Ming 引擎本身目前是闭源参考实现。如果您有权访问 Ming 代码库，请运行 uvicorn api.main:app --port 8000 并将此 MCP 指向 localhost:8000。

如果没有可访问的引擎，MCP 服务器会启动并列出工具，但工具调用会返回 HTTP 错误。

安装

第 1 步 — 确保引擎可访问

请参阅上方的“引擎要求”。

第 2 步 — 安装 MCP 服务器

npm install -g ming-metaphysics-mcp

第 3 步 — 添加到 claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ming": {
      "command": "ming-metaphysics-mcp",
      "args": [],
      "env": {
        "MING_API_URL": "http://localhost:8000"
      }
    }
  }
}

重启 Claude Desktop。Ming 工具将出现在工具列表中。

验证

在 Claude Desktop 中：

Using the ming_bazi_analyze tool, analyze the chart for someone born 1990-03-15, male, in Singapore.

您应该会得到一份完整的八字解读。如果工具报错，请检查 Python 引擎是否在 8000 端口运行。

端点差距

以下功能在完全按规范运行前需要扩展 FastAPI。每一项都在工具响应中标记了说明 — 不会静默失败。

要实现特定年份的飞星或 forecast_year 支持，请在 api/main.py 的 /consult 中添加这些参数，并在此处更新相应的工具处理程序。

开发

git clone <this-repo>
cd ming-metaphysics-mcp
npm install
npm run build          # compile TypeScript → dist/
npm test               # smoke tests (no engine required)

# With engine running at localhost:8000:
npx ts-node scripts/benchmark.ts --tool all --iterations 5

环境变量

延迟目标

如果任何工具持续超过 5 秒，请检查引擎瓶颈，并考虑在 MCP 配置中添加 timeout: 10000。

认证

封装层级无认证 — 此服务器是开源且免费的（MIT 许可证）。如有任何认证，均由 MING_API_URL 指向的端点强制执行。

获取完整的五引擎解读

通过 Ming 的 Telegram 机器人可获得由陈大师综合的五引擎咨询（八字 + 紫微 + 奇门 + 风水 + 易经）。链接将在机器人进入公开测试阶段后发布。

隐私

此 MCP 封装器本身不收集数据。它会将您的工具参数（出生日期、时间、性别、问题文本）转发给您配置的 MING_API_URL。如果您指向托管端点，该端点将接收数据 — 请阅读其隐私政策。如果您自托管，数据不会离开您的网络。

出生数据是敏感信息。如果您为最终用户配置此项，请明确告知哪个端点会接收他们的输入。

项目状态

此包版本为 1.0.0。MCP 协议表面（6 个工具、JSON 模式、响应形状）是稳定的。底层的 Ming 引擎演进较快 — 工具响应中的微小数值变化属于正常现象。

欢迎贡献 — 请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE。