gnomon

gnomon-mcp

日晷上的指针，将影子化为时间。

一个小型 MCP 服务，提供每个模型都需要的枯燥但必不可少的实用工具：日期、日历、算术和单位换算。使用它，让你的助手不再靠“预测下一个词元”来猜测数学和日期计算结果。

为什么

大模型天生不擅长算术和日期计算。它们会给出看似合理、却往往有细微误差的答案——这正是长篇回复中难以察觉的错误。gnomon-mcp 通过 MCP 提供确定性的 Python 实现，让你的模型可以计算，而不是猜测。

Agent 何时应该使用 gnomon

凡是下一个看似合理的词元并非正确答案的场景。具体来说：

• 重要的数学计算——任何超出简单心算的计算、任何涉及小数的计算、任何误差会累积的计算。调用 calc。
• “今天是星期几”／“还要多久”／“已经过了多久”——模型的训练截止日期并非今天。调用 now 获取当前快照；使用 until／since／diff 调用 calendar 计算经过的时间；使用 parse 解析自然语言日期（“下周四”）。
• 跨月／跨年的日期计算——增加 30 天、查找季度末、计算工作日。模型经常在这些计算中出现一日误差。使用 add／business_days 调用 calendar。
• 单位换算——调用 calc_convert。不要凭估算换算“kg → lb”或“°C → °F”。
• 表格行处理任务——当表格的每一行都需要执行同类计算时，两个批处理工具（calendar、calc）都可以接收列表，并按顺序返回列表。一次调用，获得 N 个结果。

经验法则：如果你会请同事“帮忙再核对一下这个数字”，那就改用 gnomon。

与其他 MCP 服务的比较

时间和数学领域已经有多个 MCP 服务——官方的 Time 参考实现（仅支持时区）、mcp-time 和 mcp-datetime（日期格式化／时区）、calculator-server（数学和单位，不支持日期），以及 agent-utils-mcp（正则表达式／哈希／JWT）等工具集。gnomon 的定位更专一：

• 批处理优先。 calendar(ops) 和 calc(expressions) 接收列表；一次工具调用即可处理整列数据，而不必调用 N 次。
• 真正的 now()。 一次调用即可返回 18 个字段——ISO 周、季度、财年、年内第几天、is_weekend，等等——而不只是 {iso, tz}。
• 日期、数学和单位一体化。 无需组合三个独立服务。
• 内置自然语言日期解析（“下周四”、“3 小时后”），无需单独的 NLP 服务。

如果你只需要时区转换，官方的 Time 服务就够了。如果你需要涵盖多种用途的工具集（正则表达式、哈希、编码、JWT），agent-utils-mcp 会更合适。gnomon 专注于枯燥的日期运算和算术核心，并支持批处理。

工具

Calendar

两个工具：

• now(tz?) — 独立工具。返回当前时刻的丰富字典快照。一次调用即可获取有关“此刻”的所有信息。
• calendar(ops) — 批量分派器。每个项目都可选择自己的操作。专为表格行工作负载设计（例如，一次调用即可计算每一行的已用时长）。

now(tz?) 返回：

{
  "iso": "2026-05-25T14:30:45+00:00",
  "date": "2026-05-25",
  "time": "14:30:45",
  "unix": 1779345045,
  "tz": "UTC",
  "year": 2026, "month": 5, "month_name": "May", "day": 25,
  "weekday": "Monday", "weekday_num": 0,          # 0=Monday
  "day_of_year": 145, "week_of_year": 22,         # ISO week
  "quarter": 2, "fiscal_year_us_gov": 2026,       # FY starts Oct 1
  "hour": 14, "minute": 30, "second": 45,
  "is_weekend": False,
}

calendar(ops) 操作：

操作	参数	返回值
diff	start, end, unit	end - start — 两个已知日期之间经过的时间
until	target, unit, tz?	target - now — 距未来某个时间点的剩余时间（若已过去则为负数）
since	source, unit, tz?	now - source — 自过去某个时间点起经过的时间（若在未来则为负数）
add	date, n, unit	date + n units 的 ISO 格式（seconds|...|weeks，以及支持日历计算的 months|years）
weekday	date	"Monday".."Sunday"
business_days	start, end	周一至周五的天数（包含开始日期，不包含结束日期）
parse	natural, tz?	将自然语言（“下周四”、“3 小时后”）转换为 ISO 格式
format	date, fmt	按 strftime 格式化的字符串

diff/until/since 的单位：seconds、minutes、hours、days、weeks。

示例 — 一次调用计算多项内容：

calendar([
  {"op": "until", "target": "2026-12-31", "unit": "days"},          # days left in year
  {"op": "since", "source": "2026-01-01", "unit": "days"},          # days elapsed in year
  {"op": "diff", "start": "2026-01-01", "end": "2026-12-31", "unit": "days"},
  {"op": "weekday", "date": "2026-05-25"},                           # "Monday"
  {"op": "add", "date": "2026-05-25", "n": 1, "unit": "months"},
  {"op": "parse", "natural": "next thursday", "tz": "America/Los_Angeles"},
])

Calculator

工具	用途
calc(expressions)	计算一组 Python 表达式，并返回结果列表。数学函数（sqrt、sin、log、pi、e 等）、统计函数（mean、median、stdev、variance）和实用内置函数（abs、round、min、max、sum、range、sorted 等）均已预加载。批量输入 / 批量输出，顺序保持不变。
calc_convert(value, from_unit, to_unit)	使用 Pint 进行单位换算（meter → foot、kg → lb、degC → degF 等）。

示例：

calc(["2 + 3 * 4"])                  # [14]
calc(["sqrt(16)", "sin(pi/2)"])      # [4.0, 1.0]
calc(["mean([1, 2, 3, 4])"])         # [2.5]
calc(["sum(range(101))"])            # [5050]
calc(["(25 / 100) * 100"])           # [25.0]

未来工具（构想）

同样的逻辑——如果模型很可能会信口开河，就提供一个确定性的版本——表明还有一些值得构建的基础工具。它们目前都尚未实现；以下是候选工具，大致按投入产出比排序：

1. 文本度量 — 使用 count(text, unit) 统计字符 / 单词 / 行 / 句子 / 大模型 Token 数。Agent 经常会数错“有多长”以及“能否放进上下文窗口”。
2. 正则匹配 / 替换 — regex_find(pattern, text) 和 regex_sub(pattern, repl, text)。模型会臆测哪些子字符串匹配正则；使用真正的引擎即可终结争论。
3. 结构化数据提取 — jq(path, json) / jsonpath(path, json)。通过路径从嵌套数据块中读取值，不会出现拼写错误。
4. 哈希与编码 — hash(text, algo)（sha256、md5、blake2）、encode(text, scheme) / decode(text, scheme)（base64、hex、url、jwt-payload）。这些都是模型会自信地编造错误结果的操作。
5. 十进制货币计算 — 使用 Python 的 Decimal 并明确指定舍入方式来计算 money(expr)。calc 基于浮点数，对货币计算而言并不安全，却不会明确提示。
6. 支持节假日的工作日计算 — 为 calendar.business_days 添加 country（或 calendar）参数，以排除美国 / 英国 / 印度的节假日。当前实现只考虑周末。
7. Cron 描述 / 下次触发时间 — cron_describe("0 9 * * 1-5") → 用英语描述；cron_next(expr, n) → 接下来 N 个触发时间。模型经常会误读 Cron 字段。
8. 针对指定模型的 Token 计数 — 通过 tiktoken / Anthropic tokenizer 使用 count_tokens(text, model)。这样 Agent 就能为自己的提示词和输出规划 Token 用量，而不是靠猜。

如果你需要其中某个工具，请提交一个 issue（或 PR——每个工具都是一个小型、独立的模块，可适配现有的 tools/ 布局）。

安装

推荐：无需安装，通过 uv 按需运行：

uvx gnomon-mcp           # serves stdio MCP, ready for any client
uvx gnomon-mcp --demo    # call every tool once and print the results (no MCP client needed)

或者全局安装：

pip install gnomon-mcp

接入你的 Agent

以下所有配置示例均使用 uvx gnomon-mcp。如果你更喜欢固定版本的安装方式，可将命令替换为 gnomon-mcp（不带 uvx）。

Claude Code

claude mcp add gnomon -- uvx gnomon-mcp

或者编辑 ~/.claude.json / 项目中的 .mcp.json：

{
  "mcpServers": {
    "gnomon": { "command": "uvx", "args": ["gnomon-mcp"] }
  }
}

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "gnomon": { "command": "uvx", "args": ["gnomon-mcp"] }
  }
}

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "gnomon": { "command": "uvx", "args": ["gnomon-mcp"] }
  }
}

Continue

~/.continue/config.yaml：

mcpServers:
  - name: gnomon
    command: uvx
    args: ["gnomon-mcp"]

其他客户端（通用 stdio）

将 uvx gnomon-mcp 作为子进程启动，并通过 stdin/stdout 使用 MCP 通信。集成就是这么简单。

托管 / 远程（HTTP 传输）

适用于团队共享实例或无法启动本地子进程的 Agent：

uvx gnomon-mcp --transport streamable-http --host 0.0.0.0 --port 8000
# also supported: --transport sse

然后将 MCP 客户端指向 http://<host>:8000/mcp（SSE 传输则指向 /sse）。

告诉你的 Agent 实际使用它

MCP 工具说明有意保持简洁，以尽量降低持久上下文的成本（全部四个工具约 150 个 token）。更详细的「何时使用 gnomon」指南位于 Claude Code 技能中，按需加载。

选项 A — Claude Code 插件（一条命令，推荐）

该插件一次性接入 MCP 服务和技能。在 Claude Code 中：

/plugin marketplace add lihtness/gnomon-mcp
/plugin install gnomon@gnomon-mcp

这会将 gnomon 注册为 MCP 服务（通过 uvx 自动启动），并安装按需加载的技能。只有任务触发技能时，才会加载技能正文；持久上下文仍约为四个工具说明的 150 个 token，加上技能名称和摘要的约 40 个 token。

选项 B — 手动安装技能（无插件）

如果你已经通过 claude mcp add gnomon -- uvx gnomon-mcp 接入 MCP 服务，且只需要技能：

mkdir -p ~/.claude/skills/gnomon
curl -fsSL https://raw.githubusercontent.com/lihtness/gnomon-mcp/main/skills/gnomon/SKILL.md \
  -o ~/.claude/skills/gnomon/SKILL.md

选项 C — 粘贴到系统提示词中（非 Claude Code Agent）

对于不支持技能的 Agent，将这个简短版本粘贴到系统提示词或 CLAUDE.md 中：

You have gnomon: deterministic tools for dates and math. Use them instead
of guessing.

- `now` — current moment (your training cutoff isn't today).
- `calendar(ops)` — batch date math: diff/until/since/add/weekday/
  business_days/parse (natural language)/format.
- `calc(expressions)` — batch Python eval; math + statistics + common
  builtins pre-loaded.
- `calc_convert(value, from, to)` — unit conversion via Pint.

Both batch tools take a list and return a list. Prefer one batched call
over many small ones.

开发

git clone https://github.com/lihtness/gnomon-mcp
cd gnomon-mcp
pip install -e ".[dev]"
pytest

许可证

MIT