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 文档。
• 在项目仓库中提交问题。