Tscircuit MCP

🚀 tscircuit MCP Server

このサーバーはModel Context Protocol (MCP) を使用して、Claudeがtscircuitの電子部品レジストリにアクセスできるようにするものです。Claudeはこれを通じて、tscircuitエコシステム内の電子部品や回路パッケージの検索、閲覧、分析が可能になります。

✨ 主な機能

• 部品検索: 名前、タイプ、または説明で電子部品を検索できます。
• パッケージ詳細: tscircuitパッケージに関する包括的な情報を取得できます。
• ソースコードアクセス: 部品のソースコードと実装詳細を取得できます。
• 部品分析: 電気的仕様、フットプリント、互換性を分析できます。
• キャッシュ: パフォーマンス向上のためのレスポンスキャッシュが組み込まれています。
• エラーハンドリング: 意味のあるエラーメッセージを伴う堅牢なエラーハンドリングが実装されています。

📦 インストール

前提条件

• Bun 1.0.0以上
• または、npm付きのNode.js 18.0.0以上

セットアップ

1. このリポジトリをクローンまたはダウンロードします。
2. 依存関係をインストールします。

bun install

3. プロジェクトをビルドします。

bun run build

4. サーバーをテストします。

bun start

開発

ホットリロードで開発するには：

bun run dev

型チェックを行うには：

bun run typecheck

💻 使用例

Claude Desktopでの使用

設定

Claude DesktopのMCP設定ファイルに以下を追加します。 macOSの場合: ~/Library/Application Support/Claude/claude_desktop_config.json Windowsの場合: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tscircuit": {
      "command": "bun",
      "args": ["/path/to/tscircuit-mcp/build/index.js"]
    }
  }
}

または、Node.jsを使用する場合は：

{
  "mcpServers": {
    "tscircuit": {
      "command": "node",
      "args": ["/path/to/tscircuit-mcp/build/index.js"]
    }
  }
}

/path/to/tscircuit-mcp を実際のインストールパスに置き換えてください。

利用可能なリソース

MCPサーバーは、Claudeが読み取ることができる以下のリソースを提供します。

部品検索

• URI: tscircuit://packages/search?q={query}&limit={limit}&category={category}
• 説明: tscircuitレジストリからの検索結果
• パラメータ:
  • q (必須): 検索クエリ
  • limit (オプション): 最大結果数 (デフォルト: 10)
  • category (オプション): 部品カテゴリフィルタ

パッケージ詳細

• URI: tscircuit://packages/{packageName}
• 説明: パッケージの詳細情報
• 例: tscircuit://packages/seveibar/red-led

パッケージソースコード

• URI: tscircuit://packages/{packageName}/code?version={version}
• 説明: 部品のソースコード
• パラメータ:
  • version (オプション): 特定のバージョン (デフォルトは最新版)

利用可能なツール

Claudeは、tscircuitレジストリとやり取りするために以下のツールを使用できます。

search_components

tscircuitレジストリ内の電子部品を検索します。

パラメータ:

• query (文字列、必須): 検索用語
• limit (数値、オプション): 最大結果数 (デフォルト: 10)
• category (文字列、オプション): 部品カテゴリフィルタ

例:

{
  "query": "3.3V voltage regulator",
  "limit": 5,
  "category": "ic"
}

get_package_details

特定のtscircuitパッケージに関する詳細情報を取得します。

パラメータ:

• packageName (文字列、必須): 完全なパッケージ名

例:

{
  "packageName": "seveibar/red-led"
}

get_package_code

tscircuit部品のソースコードを取得します。

パラメータ:

• packageName (文字列、必須): パッケージ名
• version (文字列、オプション): 特定のバージョン

例:

{
  "packageName": "seveibar/red-led",
  "version": "1.0.0"
}

analyze_component

部品の電気的仕様とフットプリントを分析します。

パラメータ:

• packageName (文字列、必須): 分析するパッケージ

例:

{
  "packageName": "seveibar/red-led"
}

具体的な使用シナリオ

1. 部品検索

Claudeクエリ: "Find me a 3.3V voltage regulator in SOT-23 package"

Claudeは search_components ツールを使用します。

{
  "query": "3.3V voltage regulator SOT-23",
  "category": "ic"
}

2. パッケージ分析

Claudeクエリ: "What are the specifications of the ESP32 module package?"

Claudeは get_package_details ツールを使用します。

{
  "packageName": "AnasSarkiz/ESP32_module"
}

3. コードレビュー

Claudeクエリ: "Show me the implementation of the red LED component"

Claudeは get_package_code ツールを使用します。

{
  "packageName": "seveibar/red-led"
}

4. 部品比較

Claudeクエリ: "Compare the specifications of these two resistor packages"

Claudeは複数の analyze_component 呼び出しを使用して部品を比較します。

📚 ドキュメント

tscircuitレジストリAPI

サーバーは https://registry-api.tscircuit.com の公式tscircuitレジストリと統合されています。

• 検索: POST /packages/search でボディに {"query": "search term"} を指定
• パッケージ情報: 検索を通じて取得 (直接のエンドポイントはまだありません)
• パッケージコード: npmパッケージリンクを通じてアクセス

パッケージ名は author/package-name の形式 (例: seveibar/usb-c-flashlight) で、npmには @tsci/author.package-name として公開されます。

部品カテゴリ

フィルタリングにサポートされている部品カテゴリは以下の通りです。

• resistor - 抵抗器
• capacitor - コンデンサ
• inductor - インダクタ
• diode - ダイオード
• transistor - トランジスタ
• ic - 集積回路
• connector - コネクタ
• led - LED
• switch - スイッチ
• sensor - センサ
• crystal - クリスタルおよびオシレータ
• relay - リレー
• transformer - トランス
• fuse - ヒューズ
• battery - 電池
• motor - モータ
• display - ディスプレイ
• antenna - アンテナ
• other - その他の部品

🔧 技術詳細

スクリプト

• bun run build - TypeScriptをJavaScriptにビルド
• bun start - MCPサーバーを起動
• bun run dev - ホットリロードで開発モードを起動
• bun test - テストを実行
• bun run typecheck - コンパイルせずに型チェックを行う

プロジェクト構造

tscircuit-mcp/
├── src/
│   ├── index.ts           # メインエントリポイント
│   ├── server.ts          # MCPサーバーの実装
│   ├── types.ts           # TypeScriptの型定義
│   └── tscircuit-api.ts   # レジストリAPIクライアント
├── build/                 # コンパイルされたJavaScript出力
├── package.json
├── tsconfig.json
└── README.md

エラーハンドリング

サーバーには包括的なエラーハンドリングが組み込まれています。

• ネットワークタイムアウトとレジストリのダウンタイム
• 無効なパッケージ名 (404エラー)
• 不正なリクエスト
• APIレート制限
• キャッシュ管理

パフォーマンス機能

• レスポンスキャッシュ: レジストリレスポンスのTTLは5分
• リクエストタイムアウト: API呼び出しのタイムアウトは10秒
• 並列リクエスト: 複数の同時リクエストを効率的に処理
• キャッシュ統計: 組み込みのキャッシュモニタリング

トラブルシューティング

一般的な問題

1. サーバーが起動しない: Node.jsのバージョンを確認 (18.0.0以上が必要)
2. 接続エラー: registry.tscircuit.comへのネットワーク接続を確認
3. パッケージが見つからない: パッケージ名が正しく、レジストリに存在することを確認
4. レスポンスが遅い: ネットワーク接続とレジストリの状態を確認

デバッグモード

詳細なログを有効にするには DEBUG 環境変数を設定します。

DEBUG=tscircuit-mcp npm start

キャッシュ管理

プログラムでキャッシュをクリアします。

// サーバーインスタンスを介してアクセス
server.getAPI().clearCache();

// キャッシュ統計を取得
const stats = server.getAPI().getCacheStats();
console.log(`Cache size: ${stats.size} entries`);

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

サポート

問題や質問については：

• 上記のトラブルシューティングセクションを確認してください。
• tscircuitのドキュメントを確認してください。
• プロジェクトリポジトリで問題を開いてください。