Tscircuit MCP

🚀 tscircuit MCP Server

A Model Context Protocol (MCP) server that empowers Claude to access the tscircuit electronics component registry. It allows Claude to search, browse, and analyze electronic components and circuit packages within the tscircuit ecosystem.

🚀 Quick Start

This MCP server offers Claude access to the tscircuit electronics component registry. Follow the installation steps below to get started.

✨ Features

• Component Search: Search for electronic components by name, type, or description
• Package Details: Get comprehensive information about tscircuit packages
• Source Code Access: Retrieve component source code and implementation details
• Component Analysis: Analyze electrical specifications, footprints, and compatibility
• Caching: Built-in response caching for improved performance
• Error Handling: Robust error handling with meaningful error messages

📦 Installation

Prerequisites

• Bun 1.0.0 or higher
• Alternatively, Node.js 18.0.0 or higher with npm

Setup

1. Clone or download this repository
2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Test the server:

bun start

Development

For development with hot reload:

bun run dev

For type checking:

bun run typecheck

💻 Usage Examples

Usage with Claude Desktop

Configuration

Add the following to your Claude Desktop MCP configuration file: On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Or if you prefer to use Node.js:

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

Replace /path/to/tscircuit-mcp with the actual path to your installation.

Available Resources

The MCP server provides these resources that Claude can read:

Available Tools

Claude can use these tools to interact with the tscircuit registry:

Example Usage Scenarios

1. Component Search

Claude Query: "Find me a 3.3V voltage regulator in SOT-23 package" Claude will use the search_components tool:

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

2. Package Analysis

Claude Query: "What are the specifications of the ESP32 module package?" Claude will use the get_package_details tool:

{
  "packageName": "AnasSarkiz/ESP32_module"
}

3. Code Review

Claude Query: "Show me the implementation of the red LED component" Claude will use the get_package_code tool:

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

4. Component Comparison

Claude Query: "Compare the specifications of these two resistor packages" Claude will use multiple analyze_component calls to compare components.

📚 Documentation

API Reference

tscircuit Registry API

The server integrates with the official tscircuit registry at https://registry-api.tscircuit.com:

• Search: POST /packages/search with body {"query": "search term"}
• Package Info: Retrieved via search (no direct endpoint yet)
• Package Code: Accessed via npm package links

Package names follow the format author/package-name (e.g., seveibar/usb-c-flashlight) and are published to npm as @tsci/author.package-name.

Component Categories

Supported component categories for filtering:

• resistor - Resistors
• capacitor - Capacitors
• inductor - Inductors
• diode - Diodes
• transistor - Transistors
• ic - Integrated circuits
• connector - Connectors
• led - LEDs
• switch - Switches
• sensor - Sensors
• crystal - Crystals and oscillators
• relay - Relays
• transformer - Transformers
• fuse - Fuses
• battery - Batteries
• motor - Motors
• display - Displays
• antenna - Antennas
• other - Other components

Development

Scripts

• bun run build - Build TypeScript to JavaScript
• bun start - Start the MCP server
• bun run dev - Development mode with hot reload
• bun test - Run tests
• bun run typecheck - Type checking without compilation

Project Structure

tscircuit-mcp/
├── src/
│   ├── index.ts           # Main entry point
│   ├── server.ts          # MCP server implementation
│   ├── types.ts           # TypeScript type definitions
│   └── tscircuit-api.ts   # Registry API client
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Error Handling

The server includes comprehensive error handling:

• Network timeouts and registry downtime
• Invalid package names (404 errors)
• Malformed requests
• API rate limiting
• Cache management

Performance Features

• Response Caching: 5-minute TTL for registry responses
• Request Timeouts: 10-second timeout for API calls
• Concurrent Requests: Efficient handling of multiple simultaneous requests
• Cache Statistics: Built-in cache monitoring

Troubleshooting

Common Issues

1. Server won't start: Check Node.js version (requires 18.0.0+)
2. Connection errors: Verify network connectivity to registry.tscircuit.com
3. Package not found: Ensure package name is correct and exists in registry
4. Slow responses: Check network connection and registry status

Debug Mode

Set the DEBUG environment variable to enable detailed logging:

DEBUG=tscircuit-mcp npm start

Cache Management

Clear the cache programmatically:

// Access through the server instance
server.getAPI().clearCache();

// Get cache statistics
const stats = server.getAPI().getCacheStats();
console.log(`Cache size: ${stats.size} entries`);

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🛠️ Support

For issues and questions:

• Check the troubleshooting section above
• Review the tscircuit documentation
• Open an issue on the project repository