gnomon

gnomon-mcp

日時計の影を時刻に変える指針。

モデルに必要な、日付、カレンダー、算術、単位変換といった、地味ながら欠かせないユーティリティを提供する小規模な MCP サーバーです。これを使えば、アシスタントが数学や日付計算を「次のトークンを推測」するのをやめさせられます。

理由

LLM は、何もしなければ算術や日付計算が苦手です。もっともらしく見えて、わずかに間違った答えを返すことがよくあります。長い回答の中では特に見つけにくい種類の間違いです。gnomon-mcp は、決定論的な Python 実装を MCP 経由で公開するため、モデルは推測せずに計算できます。

エージェントが gnomon を使うべき場面

次にもっともらしいトークンを続けるだけでは正解にならない、あらゆる場面です。具体的には次のとおりです。

• 重要な計算 — 単純な暗算を超える計算、小数点を含む計算、誤差が積み重なる計算には calc を呼び出します。
• 「今日は何日？」／「あとどれくらい？」／「どれくらい前？」 — モデルの学習データの期限は今日ではありません。現在の状態を取得するには now を、経過時間には until／since／diff を指定した calendar を、自然言語の日付（「次の木曜日」など）には parse を呼び出します。
• 月や年をまたぐ日付計算 — 30 日を足す、四半期末を求める、営業日を数えるといった計算です。モデルは頻繁に 1 日ずれた答えを返します。add／business_days を指定して calendar を呼び出します。
• 単位変換 — calc_convert を呼び出します。「kg → lb」や「°C → °F」を決して目分量で換算しないでください。
• 表の行ごとの処理 — 表の各行に同じ種類の計算を行う必要がある場合、バッチ処理ツール（calendar、calc）はどちらもリストを受け取り、同じ順序でリストを返します。呼び出し 1 回で結果を N 件取得できます。

目安は、「その数字をちょっと確認して」と同僚に頼むようなときは、代わりに gnomon を呼び出すことです。

他の MCP サーバーとの比較

時刻や数学を扱う MCP サーバーはすでにいくつかあります。公式の Time リファレンス（タイムゾーンのみ）、mcp-time と mcp-datetime（日付形式／タイムゾーン）、calculator-server（数学と単位、日付なし）、さらに agent-utils-mcp（正規表現／ハッシュ化／JWT）のようなユーティリティ集があります。gnomon の役割はより限定的です。

• バッチ処理を優先。 calendar(ops) と calc(expressions) はリストを受け取るため、N 回呼び出す代わりに、ツール呼び出し 1 回で表の列全体を処理できます。
• 本格的な now()。 1 回の呼び出しで、ISO 週、四半期、会計年度、年初からの日数、is_weekend など、18 個のフィールドを返します。{iso, tz} だけではありません。
• 日付、数学、単位をまとめて利用。 3 つの別々のサーバーを組み合わせる必要はありません。
• 自然言語の日付に標準対応（"next thursday"、"in 3 hours"）。別途 NLP サーバーを用意する必要はありません。

タイムゾーン変換だけが必要なら、公式の Time サーバーで十分です。正規表現、ハッシュ化、エンコード、JWT などの幅広いユーティリティ集が必要なら、agent-utils-mcp のほうが適しています。gnomon は、日付計算と算術という地味な中核機能を、バッチ処理で利用するためのものです。

ツール

カレンダー

2 つのツールがあります。

• now(tz?) — 単独で使用します。現在の瞬間の詳細なスナップショットを辞書で返します。1 回の呼び出しで、「今」に関する情報をすべて取得できます。
• calendar(ops) — 一括ディスパッチャーです。各項目でそれぞれの操作を選択します。表の行を処理する用途向けに設計されており（例：1 回の呼び出しで各行の経過時間を計算）、一括処理に適しています。

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 — 既知の 2 つの日付の間の経過時間
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?	自然言語（「next thursday」「in 3 hours」など）から ISO 形式を返します
format	date, fmt	strftime 形式の文字列

diff／until／since の単位：seconds、minutes、hours、days、weeks。

例 — 1 回の呼び出しで複数の値を計算します。

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"},
])

計算機

ツール	用途
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. テキストの測定 — 文字数／単語数／行数／文の数／LLM トークン数を返す count(text, unit)。エージェントは「どれくらいの長さか」や「コンテキストウィンドウに収まるか」を頻繁に数え間違えます。
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. 対象モデルのトークン数カウント — tiktoken／Anthropic のトークナイザーを使った count_tokens(text, model)。エージェントが推測に頼らず、自身のプロンプトと出力のトークン数を見積もれるようになります。

これらのいずれかを希望する場合は、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

エージェントに接続する

以下の設定例はすべて 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 トランスポート）

チームで共有するインスタンスや、ローカルのサブプロセスを起動できないエージェントの場合：

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

次に、MCP クライアントを http://<host>:8000/mcp（SSE トランスポートの場合は /sse）に接続します。

エージェントに実際に使うよう指示する

MCP ツールの説明は、永続的なコンテキストのコストを最小限に抑えるため、意図的に簡潔にしています（4 つのツールすべてで約 150 トークン）。gnomon を使うタイミングに関する詳しいガイダンスは、必要に応じて読み込まれる Claude Code のスキルに記載されています。

オプション A — Claude Code プラグイン（コマンド 1 つ、おすすめ）

このプラグインは、MCP サーバーとスキルをまとめて設定します。Claude Code 内で次を実行します：

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

これにより、gnomon が MCP サーバーとして登録され（uvx 経由で自動起動）、必要に応じて読み込まれるスキルがインストールされます。スキルの本文はタスクに応じて読み込まれるため、永続的なコンテキストは、4 つのツールの説明に約 150 トークン、スキル名と概要に約 40 トークンを加えた分にとどまります。

オプション 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 以外のエージェント）

スキルに対応していないエージェントの場合は、次の短縮版をシステムプロンプトまたは 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