Tscircuit MCP

🚀 tscircuit MCP 服务器

tscircuit MCP 服务器是一个模型上下文协议（MCP）服务器，它为 Claude 提供了访问 tscircuit 电子组件注册表的能力。借助该服务器，Claude 可以搜索、浏览和分析 tscircuit 生态系统中的电子组件和电路包。

✨ 主要特性

• 组件搜索：可按名称、类型或描述搜索电子组件。
• 封装详情：获取 tscircuit 封装的全面信息。
• 源代码访问：检索组件源代码和实现细节。
• 组件分析：分析电气规格、封装尺寸和兼容性。
• 缓存功能：内置响应缓存，提升性能。
• 错误处理：具备强大的错误处理机制，提供有意义的错误信息。

📦 安装指南

前提条件

• Bun 1.0.0 或更高版本。
• 或者，使用 Node.js 18.0.0 或更高版本并搭配 npm。

安装步骤

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 注册表进行交互：

示例使用场景

1. 组件搜索

Claude 查询：“帮我查找 SOT - 23 封装的 3.3V 电压调节器” Claude 将使用 search_components 工具：

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

2. 封装分析

Claude 查询：“ESP32 模块封装的规格是什么？” Claude 将使用 get_package_details 工具：

{
  "packageName": "AnasSarkiz/ESP32_module"
}

3. 代码审查

Claude 查询：“给我展示红色 LED 组件的实现代码” Claude 将使用 get_package_code 工具：

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

4. 组件比较

Claude 查询：“比较这两个电阻封装的规格” Claude 将多次调用 analyze_component 工具来比较组件。

📚 详细文档

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