toolkit-mcp-server

---

概要

日常的な開発者向けユーティリティです。ID、QR コード、ハッシュを生成し、値をエンコードおよびデコードし、パブリック IP またはホスト名の位置情報を取得します。位置情報の検索を除き、すべてローカルで実行されます。

ツール

ツール	説明
toolkit_hash_value	ダイジェスト（sha256／sha384／sha512／sha1／md5）を hex、base64、または SRI 形式で生成するか、値と期待されるダイジェストを定時間比較します
toolkit_generate_id	暗号学的に安全なランダム UUIDv4、UUIDv7、または ULID の識別子を生成します。1 回の呼び出しにつき最大 1000 個まで生成できます
toolkit_generate_qr	テキストまたは URL を、SVG、base64 PNG、またはターミナルの半ブロック文字で表示する QR コードにエンコードします
toolkit_encode_value	base64、base64url、hex、または URL パーセントエンコーディングでエンコードまたはデコードします
toolkit_geolocate_ip	パブリック IP またはホスト名から、国、都市、座標、ASN、タイムゾーンを取得します
toolkit_check_network	制限付き。デフォルトでは無効です。 サーバーホストから ping、traceroute、TCP 接続確認、または外向き IP の確認を実行します
toolkit_check_system	制限付き。デフォルトでは無効です。 サーバーホストの OS、CPU、メモリ、ロードアベレージ、またはネットワークインターフェースを確認します

機能リファレンス

toolkit_hash_value _ツール

• value は inputEncoding に従って読み取られます（デフォルトは utf8、hex、base64）。algorithm は sha256（デフォルト）、sha384、sha512、またはチェックサム互換性のためだけの sha1 と md5 です。operation は generate または compare で、省略して expected を指定した場合は比較します
• generate は digestEncoding（デフォルトは hex、base64、または SHA-2 アルゴリズムの場合は sri）で digest と lengthInBytes を返します。compare は、複数エントリーの npm integrity 値を含め、hex、base64、または SRI で指定された expected と照合した matches を返します
• 不正な expected の場合は、expected_malformed、expected_length_mismatch（ヒントで長さが一致するアルゴリズムを示します）、または expected_algorithm_mismatch として失敗します

---

toolkit_generate_id _ツール

• type は uuid_v4（デフォルト）、uuid_v7、または ulid です。count は 1～1000（デフォルトは 1）です
• ids には常に count とちょうど同じ数の値が格納されます。uuid_v7 と ulid の一括生成では、同じミリ秒内でも厳密な昇順となり、ある ID から別の ID を導き出せないようランダムな間隔が設けられます

---

toolkit_generate_qr _ツール

• errorCorrection が L の場合、data は最大 2953 UTF-8 バイトです。M（デフォルト）、Q、H では上限が少なくなります。format は svg（デフォルト）、png_base64、または terminal です。margin は 0～20 モジュール（デフォルトは 4）、scale はモジュールあたり 1～32 px（デフォルトは 4）です
• シンボルの version（1～40）、画像形式の場合は mimeType、PNG の場合は byteLength とともに、content を返します。png_base64 は MCP 画像ブロックとしても返されます。terminal は暗い背景向けに描画された、プレーンな Unicode の半ブロック文字です
• 容量超過の入力はバイト数とともに data_too_large として失敗します。片側が 2048 px を超える PNG は、収まるスケールとともに raster_too_large として失敗しますが、svg と terminal にはピクセル上限がありません

---

toolkit_encode_value _ツール

• operation（encode または decode）と encoding（base64、base64url、hex、url）は必須です。hex、base64、base64url の入力では空白が無視されるため、折り返された MIME や PEM の本文もそのままデコードできます
• デコード結果は、outputEncoding で hex または base64 が指定されない限り、utf8 テキストとして result に返されます。これらを指定すると、バイトを損失なく返し、エンコーディング間の変換を行います。不正な入力は decode_failed として失敗し、バイナリバイトは置換文字ではなく decode_not_utf8 として失敗します

---

toolkit_geolocate_ip _ツール

• target は IPv4/IPv6 アドレスまたはドット区切りのホスト名です。ホスト名は最初に DNS で解決されます。プライベートまたは予約済みのアドレスは private_target、解決できないホスト名は unresolvable_host として失敗します
• 代わりに最大 1000 件の targets を送信することもできますが、両方を同時に指定することはできません。先頭の 100 件が順序を保った results として、ターゲットごとのエラーとともに返されます。failedCount は失敗数を示し、unprocessedTargets には再送信用の残りのターゲットが格納されます
• resolvedIp と source とともに、country、countryCode、region、city、latitude/longitude、asn、org、timezone を返します。proxy、hosting、mobile のいずれかが true の場合、その位置情報は人ではなくインフラストラクチャを示しています
• デフォルトでは、キー不要の ip-api 無料プランを暗号化されていない HTTP 経由で使用します（TOOLKIT_GEO_BASE_URL、TOOLKIT_GEO_API_KEY）。結果は解決済み IP ごとにキャッシュされます
• 単一検索と一括検索には、それぞれ別のレート制限があります（TOOLKIT_GEO_RATE_LIMIT_PER_MIN=45、TOOLKIT_GEO_BATCH_RATE_LIMIT_PER_MIN=15）。拒否された場合は、待機する秒数とともに rate_limited が報告され、キャッシュヒットは無料です

---

toolkit_check_network _ツール

• mode は ping、traceroute、connectivity、public_ip のいずれかです。public_ip 以外では target が必須で、connectivity では port（1～65535）も必要です。count は ping の回数（1～10、デフォルトは 3）、timeoutMs はタイムアウト（100～30000、デフォルトは 3000）です。
• 応答しないホストはエラーではなく、reachable: false になります。ping では rttMs、sent、received、packetLossPercent が追加され、connectivity では outcome（open、refused、timeout、unreachable）が追加されます。traceroute は hops を返します。名前解決できないホスト、または実行できない ping／traceroute バイナリは、unreachable として失敗します。
• TOOLKIT_ENABLE_NET_DIAGNOSTICS=true の場合にのみ登録されます。プライベートおよび予約済みのターゲットは、TOOLKIT_ALLOW_PRIVATE_NETWORK=true でない限り、private_target_blocked として失敗します。

---

toolkit_check_system _ツール

• what は os、cpu、memory、load、interfaces のいずれかです。対応するファセットオブジェクトが一つだけ設定されます。
• memory.availableBytes は割り当て可能な余裕を示し、コンテナのメモリー制限がある場合は limitBytes が設定されます。totalBytes、freeBytes、usedBytes は OS の生の値で、再利用可能なキャッシュも使用済みとしてカウントされます。
• os と interfaces はホストのトポロジーやバージョンの詳細を開示するため、TOOLKIT_ENABLE_SYSTEM_INFO=true の場合にのみ登録されます。

特長

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

このツールキット固有の特長：

• ハッシュ化、ID の生成、QR エンコード、エンコード／デコードは node:crypto と qrcode ライブラリーを使ってプロセス内で実行され、外部への呼び出しはありません。
• ジオロケーションではターゲットではなくプロバイダーに接続し、DNS で解決した IP をプライベート範囲と照合するため、ホスト名から内部アドレスにアクセスすることはできません。
• フェイルクローズ方式の制御：有効にしない限り、toolkit_check_network と toolkit_check_system は tools/list に表示されません。どちらも呼び出し元ではなくサーバーのホストを対象とするため、ローカル環境またはセルフホスト環境での利用に適しています。
• 2 段階のネットワークゲート：診断が有効な場合でも、プライベート、ループバック、リンクローカル、予約済みのターゲット（クラウドメタデータのエンドポイントを含む）は、TOOLKIT_ALLOW_PRIVATE_NETWORK=true にするまでブロックされます。

エージェントに適した出力：

• データの出所：ジオロケーションでは resolvedIp と source が返されます。プロバイダーが報告していないフィールドは推測で補わず、省略されます。
• レスポンスの整形：プロバイダーの文字列は 256 文字に制限され、制御文字が除去されます。そのため、org のようなレジストリーが制御するテキストが、モデルのコンテキストを埋め尽くしたり書式を乱したりすることはありません。
• 識別可能な出力：operation、format、mode、what に実行した処理が反映され、その分岐に対応するフィールドのみが設定されます。
• 型付きの失敗：宣言されたすべての失敗に reason と復旧のヒントが含まれます。また、競合する入力（expected と generate、outputEncoding と encode）は無視されず、名前を示して拒否されます。

はじめに

公開ホストインスタンス

https://toolkit.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "toolkit-mcp-server": {
      "type": "streamable-http",
      "url": "https://toolkit.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。API キーは不要です。

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

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

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

または Docker を使用します。

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

ホストを調査する制限付きツールを有効にするには、env にフラグを追加します（Docker の場合は -e）。

"env": {
  "MCP_TRANSPORT_TYPE": "stdio",
  "TOOLKIT_ENABLE_NET_DIAGNOSTICS": "true",
  "TOOLKIT_ENABLE_SYSTEM_INFO": "true"
}

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します。

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

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• API キーは不要です。ジオロケーションでは、デフォルトでキー不要の ip-api 無料枠を使用します。

インストール

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

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

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

cd toolkit-mcp-server

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

bun install

設定

すべての変数は任意です。

変数	説明	デフォルト
TOOLKIT_ENABLE_NET_DIAGNOSTICS	制限付きの toolkit_check_network ツールを登録します。ホスト型または共有型のデプロイではオフにしてください。	false
TOOLKIT_ENABLE_SYSTEM_INFO	制限付きの toolkit_check_system ツールを登録します。	false
TOOLKIT_ALLOW_PRIVATE_NETWORK	ネットワーク診断を有効にした状態で、プライベート、予約済み、ループバック、リンクローカルのターゲットを許可します。	false
TOOLKIT_GEO_API_KEY	ジオロケーションエンドポイントで必要な場合に使用する API キーです。	なし
TOOLKIT_GEO_BASE_URL	ip-api 互換エンドポイントのベース URL です。キー不要のデフォルトは平文 HTTP です。ip-api の HTTPS エンドポイントには有料キーが必要です。	http://ip-api.com
TOOLKIT_GEO_CACHE_TTL_SECONDS	メモリ内ジオロケーションキャッシュの TTL（秒）です。	3600
TOOLKIT_GEO_RATE_LIMIT_PER_MIN	1 分あたりのジオロケーションリクエストの最大数です。キャッシュヒットはカウントされません。	45
TOOLKIT_GEO_BATCH_RATE_LIMIT_PER_MIN	1 分あたりのバッチジオロケーションリクエストの最大数です。個別にカウントされます。	15
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。stateless、stateful、または auto を指定します。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（RFC 5424）。	info
OTEL_ENABLED	OpenTelemetry を有効にします。	false

任意のオーバーライドの一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t toolkit-mcp-server .
docker run --rm -p 3010:3010 toolkit-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、および /var/log/toolkit-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。常時有効な 5 つのツールを登録し、制限付きの 2 つのツールは該当フラグが有効な場合にのみ登録します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。7 つのツールがあり、5 つは常時有効、2 つは制限付きです。
src/services/geo	ジオロケーションサービスです。DNS 解決、リトライ付きのプロバイダー呼び出し、正規化、メモリ内キャッシュを行います。
src/services/network	ネットワーク診断サービスと、共有ターゲットスキーマおよびプライベート範囲判定機能です。
tests/	ツール（tests/tools）およびサービス（tests/services）の Vitest テストスイートです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません。
• リクエスト単位のログ記録には ctx.log、テナント単位のストレージには ctx.state を使用します。
• 新しいツールは src/index.ts の createApp() 配列に登録します。ホストを調査するツールは、有効化フラグが設定された場合にのみ登録します。
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造してはいけません。

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

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