calculator-mcp-server

---

概要

math.js を利用した電卓です。1 つのツールで数値の結果を検証し、代数式を簡約し、記号微分を計算できます。

ツール

ツール	説明
calculate	数式を評価し、代数式を簡約するか、記号微分を計算します。

リソース

リソース	説明
calculator://help	利用可能な関数、演算子、定数、および構文のリファレンスです。

機能リファレンス

calculate _tool

• 1 回の呼び出しにつき expression は 1 つです。operation では evaluate（デフォルト）、simplify、または derivative を選択します。導関数を求める場合は variable（例："x"）が必要です。
• 算術、三角関数、対数、統計、行列、複素数、単位、組み合わせ論の計算に対応します。数値変数は scope で割り当てます（例：{ "x": 5 }）。
• numericType では number、BigNumber（有効桁数 64 桁。64 ビット浮動小数点数でオーバーフローする値に使用）、または Fraction（正確な有理数）を選択します。結果が正確な有理数にならない場合（sqrt(2)）、Fraction モードでは計算できない関数を式が呼び出す場合（sqrt(4)、5!）、または Fraction モードが丸めた浮動小数点数としてのみ保持する値を使用する場合（pi、2^(1/2)）、Fraction モードは fraction_unsupported を返し、数値型を変更するよう案内します。
• precision では数値結果の有効桁数を 1～16 桁に設定します。空欄の省略可能な variable と precision は省略されたものとして扱います。scope と precision は記号演算に影響しません。
• 簡略化には代数および三角関数の恒等式が含まれます（2x + 3x → 5 * x）。unchanged: true は、多項式の因数分解や有理式の約分など、簡略化できない式を示します。
• 結果の文字列、結果の型、元の式、演算を返します。検証エラーには、型付きの理由と復旧のヒントが含まれます。

---

calculator://help _resource

• 関数、演算子、定数、単位、式の構文についての Markdown リファレンスです。パラメーターはありません。
• 使用例では、scope、行列、複素数、精度、3 種類すべての演算を扱います。
• 公開 scope の cacheHint を使用して 24 時間キャッシュできます。実行時に変更されない静的コンテンツです。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

計算機固有の機能：

• 強化された math.js v15 インスタンス。危険な関数は無効化され、評価は vm タイムアウト内で実行されます
• 認証は不要です。すべての操作は読み取り専用で、ステートレスです
• 入力検証：式の長さ制限と複数ステートメントの拒否。行列の行区切り文字と文字列の内容は引き続き有効です
• 結果検証：結果の型（関数、パーサー、結果セット）をブロックし、結果サイズの最大値を設定できます
• サイズ制限：サイズ、積、ブロードキャスト、インデックス、精度の引数から行列または文字列を構築する関数には、呼び出しごとの上限を設定します。また、各評価には要素数の合計上限があり、上限を超えるリクエストは result_too_large で速やかに失敗します
• scope のサニタイズ：数値のみを許可し、プロトタイプ汚染を防止します（__proto__、constructor などをブロック）

エージェント向けの出力：

• 実際の呼び出し内容をエコー：すべての応答で式と演算をエコーし、適用した scope 変数と精度も示すため、エージェントは実際に計算された内容を確認できます
• 判別可能な出力コントラクト：simplify の unchanged: true は、同じ式を黙って返すのではなく、結果が変化しなかったことを示します
• 型付きのエラー理由：検証および評価の失敗には、生の例外ではなく、型付きの reason（例：fraction_unsupported、evaluation_timeout、disallowed_result_type）と、実行可能な復旧のヒントが含まれます

はじめに

公開ホストインスタンス

公開インスタンスは https://calculator.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http calculator-mcp-server https://calculator.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "streamableHttp",
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

次のいずれかを MCP クライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/calculator-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してビルド済みサーバーを起動します。

MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/calculator-mcp-server.git

2. ディレクトリに移動します。

cd calculator-mcp-server

3. 依存関係をインストールします。

bun install

設定

変数	説明	デフォルト
CALC_MAX_EXPRESSION_LENGTH	許可される式文字列の最大長（10～10,000）。	1000
CALC_EVALUATION_TIMEOUT_MS	評価の最大時間（ミリ秒、100～30,000）。	5000
CALC_MAX_RESULT_LENGTH	結果文字列の最大長（文字数、1,000～1,000,000）。	100000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP サーバーのホスト名。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP MCP エンドポイントのパス。	/mcp
MCP_HTTP_MAX_BODY_BYTES	HTTP リクエストの最大受信サイズ。0 にすると制限が無効になります。	1048576
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_SESSION_MODE	auto、stateful、または stateless。サーバーはコード内で stateless を宣言しているため、どの起動方法でも同じ設定が適用されます。この値を設定すると、その宣言が上書きされます。	stateless
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info

セッション、再開可能性、ログ記録、テレメトリの任意の設定については、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行します。

  bun run build
  bun run start:http   # or start:stdio
  

• チェックとテストを実行します。

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker build -t calculator-mcp-server .
docker run -p 3010:3010 calculator-mcp-server

イメージのデフォルト設定は、ポート 3010 での Streamable HTTP、ステートレスセッション、/var/log/calculator-mcp-server へのログ出力です。OpenTelemetry の依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools/	ツールの定義（*.tool.ts）。
src/mcp-server/resources/	リソースの定義（*.resource.ts）。
src/services/	ドメインサービスとの連携（MathService）。
src/config/	Zod による環境変数の解析と検証。
docs/	生成されたディレクトリツリー。
tests/	計算、設定、レスポンス契約のテスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、AGENTS.md または CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• ログ記録には ctx.log を使用してください。
• 新しいツールとリソースは src/index.ts に登録してください。

コントリビューション

Issue を歓迎します。提出前にチェックを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。