Tscircuit MCP

🚀 tscircuit MCP 服務器

tscircuit MCP 服務器是一個模型上下文協議（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 可以讀取的資源：

可用工具

Claude 可以使用以下工具與 tscircuit 註冊表進行交互：

• search_components：在 tscircuit 註冊表中搜索電子元件。

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

• get_package_details：獲取特定 tscircuit 封裝的詳細信息。

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

• get_package_code：檢索 tscircuit 元件的源代碼。

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

• analyze_component：分析元件的電氣規格和引腳佈局。

{
  "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 工具來比較元件。

📚 詳細文檔

API 參考

tscircuit 註冊表 API

服務器與官方 tscircuit 註冊表 https://registry-api.tscircuit.com 集成：

• 搜索：POST /packages/search，請求體為 {"query": "search term"}
• 封裝信息：通過搜索獲取（目前暫無直接端點）
• 封裝代碼：通過 npm 包鏈接訪問

封裝名稱遵循 author/package-name 格式（例如，seveibar/usb-c-flashlight），並以 @tsci/author.package-name 的形式發佈到 npm。

元件類別

支持用於過濾的元件類別如下：

• resistor - 電阻器
• capacitor - 電容器
• inductor - 電感器
• diode - 二極管
• transistor - 晶體管
• ic - 集成電路
• connector - 連接器
• 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 文檔。
• 在項目倉庫中提交問題。