saroday-mcp-server

@saroday/mcp-server

Saroday 的 MCP（Model Context Protocol）服务，用于计算韩国四柱（사주）并查询命理学（命理學）术语表。

此 MCP 服务通过调用 Saroday 的公共 API，让 Claude Desktop、Cline、Cursor 及其他兼容 MCP 的 AI 客户端能够准确计算韩国四柱（命运四柱）。

---

功能

连接后，AI 客户端即可使用以下四种工具：

工具	描述
calculate_saju	根据出生日期／时间／性别，计算完整的四柱分析（8 个字符、十星、神煞、合冲、12 运星、用神、大运）。
lookup_glossary	查询 80 多个命理学术语（도화살、천을귀인、식신、육합等），并获取完整的韩语解释。
get_daily_fortune	查询 12 个西方星座或 12 个中国生肖之一的今日运势。结果缓存在服务端，响应迅速。
discover_saroday_api	列出 Saroday API 可用的端点和元数据。

这很重要：直接询问时，ChatGPT、Claude 和其他大模型经常会算错四柱，因为查阅万岁历（萬歲曆）和处理节气（절기，jeolgi）边界需要精确数据。此 MCP 将计算工作交给经过验证的服务，同时让 AI 专注于解读。

---

安装

选项 A — npx（无需安装）

npx @saroday/mcp-server

选项 B — 全局安装

npm install -g @saroday/mcp-server
saroday-mcp

选项 C — 克隆并运行

git clone https://github.com/saroday/mcp-server.git
cd mcp-server
npm install
node index.js

需要 Node.js 18 或更高版本。

---

配置 Claude Desktop

编辑 Claude Desktop 配置文件：

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

添加（或合并）以下内容：

{
  "mcpServers": {
    "saroday": {
      "command": "npx",
      "args": ["-y", "@saroday/mcp-server"]
    }
  }
}

重启 Claude Desktop。你应该会在 MCP 服务面板中看到“saroday”（输入区域中的插头图标）。

本地开发（从克隆的仓库运行）

{
  "mcpServers": {
    "saroday": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"]
    }
  }
}

---

配置 Cline / Cursor / 其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用。将其指向 saroday-mcp 二进制文件或 node index.js。具体配置格式请参阅客户端文档。

---

试用

连接后，可以向 Claude 提出以下问题：

• “我的生日是 1992 年 3 月 15 日上午 10 点。请计算我的韩国四柱。”
• “도화살（dohwa-sal）在韩国算命中是什么意思？”
• “帮我看看我的四柱。1990년 5월 20일 음력 14시 여성.”
• “제왕（jeokwang）12-unseong 是什么？”

Claude 会自动调用 calculate_saju 或 lookup_glossary，并根据返回的结构化数据提供润色后的解读。

---

环境变量

变量	默认值	用途
SARODAY_API_BASE	https://saroday.com	覆盖 API 基础 URL（例如用于可自托管或预发布环境）。

---

速率限制

Saroday 公共 API 面向免费用户的限额为每个 IP 每小时 100 次请求。使用量较大的用户——面向众多终端用户发布应用的团队、处理许多并发用户的 AI Agent——应申请 API 密钥（即将推出），以获得更高配额。

联系方式：[email protected]

---

工作原理

[User in Claude Desktop]
        ↓ types "내 사주 봐줘"
[Claude Desktop]
        ↓ calls calculate_saju via MCP stdio
[saroday-mcp (this package, runs locally)]
        ↓ HTTPS POST /api/v1/saju
[saroday.com server]
        ↓ runs verified manse-ryeok algorithm
[result JSON]
        ↑ flows back through the chain
[Claude] writes a beautiful Korean interpretation

此 MCP 软件包只是一个轻量级适配器——所有计算都在 Saroday 的服务器上完成，因此算法或术语表的更新会自动上线，无需升级软件包。

---

特色

• 精准的万岁历计算 — 处理大模型经常弄错的节气（절기，太阳节气）边界（已通过 @fullstackfamily/manseryeok 库验证）
• 80 多个术语条目（约 400 个解读字段） — 每个神煞、合冲、十星和 12 运星术语都包含以通俗易懂的韩语撰写的概要／含义／正面解读／负面解读／实用建议
• 韩国命理学传统 — 参考《滴天髓》（적천수）、《子平真詮》（자평진전）、《窮通寶鑑》（궁통보감）
• 三种接入渠道 — 同一算法可通过 Web 服务（saroday.com）、公共 REST API（saroday.com/api/v1）和 MCP 服务（本软件包）使用。选择适合你集成需求的渠道。

---

许可证

MIT

---

Support

• Web: https://saroday.com
• API docs: https://saroday.com/api/docs
• LLM-friendly index: https://saroday.com/llms.txt
• Email: [email protected]