Tscircuit Mcp

开发 TypeScript

🚀 tscircuit MCP 服务器

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

✨ 主要特性

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

📦 安装指南

前提条件

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

安装步骤

克隆或下载此仓库。
安装依赖项：

bun install

构建项目：

bun run build

测试服务器：

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`（可选）：组件类别过滤器
封装详情	`tscircuit://packages/{packageName}`	详细的封装信息	无
封装源代码	`tscircuit://packages/{packageName}/code?version={version}`	组件源代码	`version`（可选）：特定版本（默认为最新版本）

可用工具

Claude 可使用以下工具与 tscircuit 注册表进行交互：

工具名称	描述	参数	示例
`search_components`	在 tscircuit 注册表中搜索电子组件	`query`（字符串，必需）：搜索词；`limit`（数字，可选）：最大结果数（默认：10）；`category`（字符串，可选）：组件类别过滤器	`json { "query": "3.3V voltage regulator", "limit": 5, "category": "ic" }`
`get_package_details`	获取特定 tscircuit 封装的详细信息	`packageName`（字符串，必需）：完整的封装名称	`json { "packageName": "seveibar/red-led" }`
`get_package_code`	检索 tscircuit 组件的源代码	`packageName`（字符串，必需）：封装名称；`version`（字符串，可选）：特定版本	`json { "packageName": "seveibar/red-led", "version": "1.0.0" }`
`analyze_component`	分析组件的电气规格和封装尺寸	`packageName`（字符串，必需）：要分析的封装	`json { "packageName": "seveibar/red-led" }`

示例使用场景

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 秒
并发请求：可高效处理多个并发请求
缓存统计：内置缓存监控功能

故障排除

常见问题

服务器无法启动：检查 Node.js 版本（需要 18.0.0 或更高版本）
连接错误：验证与 registry.tscircuit.com 的网络连接
未找到封装：确保封装名称正确且存在于注册表中
响应缓慢：检查网络连接和注册表状态

调试模式

设置 DEBUG 环境变量以启用详细日志记录：

DEBUG=tscircuit-mcp npm start

缓存管理

以编程方式清除缓存：

// 通过服务器实例访问
server.getAPI().clearCache();

// 获取缓存统计信息
const stats = server.getAPI().getCacheStats();
console.log(`Cache size: ${stats.size} entries`);

贡献指南

分叉仓库
创建功能分支
进行更改
添加测试
提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

若遇到问题或有疑问：

查看上述故障排除部分。
查阅 tscircuit 文档。
在项目仓库中创建问题。

0 条评论
分类：开发