cyanheads-mcp-server

---

概要

cyanheads のフリートから、目的に合った MCP ツールを見つけましょう。タスクを平易な言葉で説明すると、すべてのツールとサーバーを検索し、説明、接続 URL、クライアント用のインストールスニペットを取得できます。

ツール

ツール	説明
cyanheads_search_catalog	自然言語のクエリで、フリート内のツールとサーバーを検索します。順位付けされた候補と簡単な概要、所有するサーバーを返します。
cyanheads_describe_entry	名前を指定したツールまたはサーバーの説明、接続 URL、クライアントごとのインストールスニペットを返します。

機能リファレンス

cyanheads_search_catalog _ツール

• query は 1～500 文字の生の文字列で、空白以外の文字を含める必要があります。埋め込み処理とエコーの前に、前後の空白はトリミングされます。scope は tools（デフォルト）または servers を選択します。category は省略可能で、research、government、public-data、utility を指定できます。limit は 1～1000（デフォルトは 5）で、1 回の呼び出しで返される結果は最大 20 件です。limit がこれを上回り、次のページにも一致結果が残る場合、レスポンスには truncated、shown、cap と、続きの取得に使うオフセットを示す notice が追加されます。
• 結果にはコサイン類似度の score（[0, 1]。同一レスポンス内で比較可能）が含まれます。ツール検索には、1 ページあたり 10 件のエントリーを含む servers の集計と serversTotal が含まれます。カタログが読み込まれていない場合は、再試行可能な catalog_empty が返されます。
• ページ結果には offset を指定し、ツールスコープの集計には独立して serversOffset を指定します（どちらもデフォルトは 0）。同じ query、scope、category、limit を指定し、nextOffset／nextServersOffset を使って続きの結果を取得します。null は結果がないことを意味します。各呼び出しでは最新のカタログが使用されるため、ページ間に更新があると並び順が変わることがあります。servers スコープでは serversOffset: 0 が必須で、集計フィールドは省略されます。
• SIMILARITY_FLOOR（デフォルトは 0.3）により、limit が適用される前に一致結果がフィルタリングされます。
• 空の category 文字列は省略されたものとして扱われます。それ以外の不明なカテゴリー値は拒否されます。

---

cyanheads_describe_entry _ツール

• name は 1～64 文字で、ツール名またはサーバー名を指定します。kind による自動検出または固定が可能です。完全一致の名前が優先され、次に大文字・小文字を区別しない一意の名前が使われます。出力では正規名が使用されます。client は省略可能で、claude-code、cline、codex、cursor、gemini、streamable-http（汎用の mcpServers JSON）、または curl を選択できます。
• server（省略可能、1～64 文字）には所有元のサーバー名を指定します。検索結果の name と server を指定すると、どちらのスコープでもその行を正確に説明します。複数のサーバーが同じツール名を所有している場合は必須です。サーバー名を指定する場合は、同じサーバー名である必要があります。
• 空の kind、client、server 文字列は省略されたものとして扱われます。それ以外の不明な kind または client の値は拒否されます。
• どちらの種類も接続メタデータとインストール用スニペットを返します。サーバーの結果には、ツールの全インベントリも含まれます。公開されているサーバーにはローカル用スニペットが、ホスト型サーバーには HTTP 用スニペットも提供されます。ローカル専用エントリーの場合、client: "curl" は成功メタデータと、試すべき stdio クライアントを示す installNotice を返します。必須の環境変数は、スニペットがなくても表示されます。
• 説明はカタログ内のテキストです。ツールスキーマは、接続済みサーバーの tools/list から取得してください。
• エラー時は not_found、ambiguous_kind（kind を指定してください）、ambiguous_owner（server を指定してください。エラーには所有元が一覧表示されます）、または再試行可能な catalog_empty が返されます。

機能

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

カタログ固有の機能：

• 1 時間ごとにバックグラウンドでカタログを更新します（CATALOG_REFRESH_SECONDS、デフォルトは 3600）。generatedAt が変わるとインデックスをアトミックに切り替えるため、再起動は不要です。
• 空のカタログ、競合する重複 ID、正規化できないベクトル（次元が異なる、すべてゼロ、または有限でない成分がある場合）は、インデックスを置き換える前にエラーになります。更新に失敗した場合は、最後に有効だったカタログを保持します。同一の重複はインデックス作成前に統合され、警告は上限付きで出力されます。ツールを持たないサーバーも有効です。
• クエリの埋め込みはリクエスト時に @huggingface/transformers で計算します。ドキュメントの埋め込みは事前計算され、L2 正規化と Matryoshka 切り詰めが行われたうえで、fleet.json に含まれています。サーバーは読み込み時に各ドキュメントベクトルを再度正規化するため、カタログ内のベクトルが単位長からずれていてもスコアはコサイン類似度を保ちます。1e-4 を超えてずれているベクトルについては、上限付きの警告で名前を示します。
• OpenTelemetry の HTTP 計装が fetch にパッチを適用する前に、起動時に埋め込みモデルをウォームアップします。これにより、OTEL 環境でモデル読み込み時にコールドキャッシュによるエラーが発生するのを防ぎます。
• 自己記述型です。cyanheads_describe_entry は静的なフォールバックレコードからこのサーバー自身の名前とツールを解決します。このレコードは、リモートカタログにこのサーバーのエントリがない場合にのみ参照されます。
• CATALOG_URL は、同じスキーマを提供する任意のエンドポイントを指定でき、カスタムフリートを利用できます。

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

• 検索レスポンスには、実際に使用されたクエリ、上限を適用する前の一致件数、該当する結果がない場合の検索範囲を広げるための案内が含まれます。また、limit が 20 を超えていて、呼び出しごとの上限に達した場合は、続きの取得に使うオフセットを示します。
• cyanheads_describe_entry の判別可能な result.kind（tool | server）を使うと、文字列の解析ではなくデータに基づいて呼び出し元が処理を分岐できます。
• すべての検索結果には、信頼度の調整に使える score フィールドが含まれます。また、servers の集計情報により、エージェントは別の呼び出しを行わずに、どのサーバーが一致したかを確認できます。

はじめに

公開ホストインスタンス

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

Claude Code の場合：

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

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

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

Claude Desktop では、「設定」→「コネクタ」からリモートサーバーを追加します。

Claude Desktop バンドル

ローカルの stdio インストールには、MCPB バンドルをダウンロードしてください。ONNX WebAssembly 推論が含まれているため、プラットフォーム固有のネイティブライブラリは不要です。初回起動時に埋め込みモデルをダウンロードし、以降の起動ではモデルキャッシュを再利用します。npm と Docker によるインストールでは、ネイティブ CPU 推論を使用します。

セルフホスト／ローカル

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

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

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

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

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

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

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 以降）。

インストール

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

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

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

cd cyanheads-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env to override any defaults

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマによって検証されます。各変数には適切なデフォルト値が設定されており、初期状態ではサーバーは正規の cyanheads フリートを参照します。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_HOST	HTTP サーバーのバインド先ホスト	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	MCP サーバーがマウントされる HTTP エンドポイントのパス	/mcp
MCP_AUTH_MODE	認証方式：none、jwt、または oauth	none
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。src/index.ts では stateless が宣言されています。これを上書きする場合にのみ設定してください。	stateless
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）	info
CATALOG_URL	リモートの fleet.json エンドポイント（埋め込みベクトルを含むスキーマ v2）。絶対 URL を指定する必要があります。独自のフリートを参照させるには上書きしてください。	https://caseyjhand.com/fleet.json
CATALOG_FETCH_TIMEOUT_MS	fleet.json の取得ごとのタイムアウト：整数のミリ秒、1～2147483647。	10000
CATALOG_REFRESH_SECONDS	fleet.json をバックグラウンドで再取得する間隔。0 で無効になります。正の値は最大 2147483.647 秒まで指定でき、ランタイムのミリ秒単位のタイマー分解能が使われます。	3600
EMBEDDING_MODEL_ID	クエリの埋め込みに使う Hugging Face モデル ID。fleet.json.embeddingModel と一致する必要があります。	Snowflake/snowflake-arctic-embed-m-v1.5
SIMILARITY_FLOOR	cyanheads_search_catalog の結果に対するコサイン類似度のしきい値。[0, 1] の範囲内で指定する必要があります。	0.3
OTEL_ENABLED	OpenTelemetry を有効にする	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースおよびメトリクス用の OTLP ベース URL	未設定
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	明示的な OTLP ログ URL。デフォルトの Docker ビルドに含まれる OTel ログ用のピア依存関係が必要です。	未設定
LOG_TOOL_FAILURE_PAYLOADS	キー名に基づいて編集したうえで、失敗した引数と結果をログに記録します。自由形式の値に含まれるシークレットは編集されません。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	ログに記録する各失敗ペイロードの UTF-8 バイト数の上限	16384

省略可能な上書き項目の一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• 本番版をビルドして実行する：

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

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

  bun run devcheck  # Lints, formats, type-checks, runs MCP and packaging linters
  bun run test      # Runs the test suite
  

Docker

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

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

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools	ツール定義（*.tool.ts）。cyanheads_search_catalog と cyanheads_describe_entry の 2 つのツールがあります。
src/services/catalog	カタログサービス。アトミックな切り替えによる更新機能を備えたリモート fleet.json プロバイダー、ベクトルインデックス、スニペットビルダー、自己説明用のフォールバックレコード、およびクエリ時の埋め込みランタイム（@huggingface/transformers。決定論的なテストのため、注入可能なインターフェースの背後にあります）。
src/config	サーバー固有の環境変数の解析と、Zod による検証。
tests/	src/ の構成に対応する単体テストと統合テスト。
docs/	設計ドキュメントとスキーマリファレンス。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使わないでください
• ログには ctx.log、ストレージには ctx.state を使用してください
• 新しいツールは、src/index.ts の createApp() に渡される tools 配列に登録してください
• 外部データは、検証（生データ）→ ドメイン型への正規化 → 出力スキーマの返却という手順で扱い、不足しているフィールドを捏造しないでください

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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