easyeda-mcp-pro 0.2.0

package/README.md

@@ -0,0 +1,304 @@
+# easyeda-mcp-pro
+
+**Production-grade MCP server for EasyEDA Pro: safe PCB design inspection, BOM sourcing, manufacturing export, and AI-assisted hardware review.**
+
+[![CI](https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/easyeda-mcp-pro.svg)](https://www.npmjs.com/package/easyeda-mcp-pro)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/oaslananka/easyeda-mcp-pro)
+
+---
+
+## Quick Start
+
+```bash
+npx easyeda-mcp-pro
+```
+
+Point your MCP client (Claude, Cursor, etc.) to the stdio transport. Create a `.env` file to configure suppliers and AI providers (see [Configuration](#configuration)).
+
+---
+
+## Overview
+
+easyeda-mcp-pro is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that bridges AI assistants with hardware design workflows in EasyEDA Pro. It exposes 25 MCP tools for schematic inspection, BOM management, design rule checks, PCB board analysis, fabrication exports, and supplier integration.
+
+The server connects to EasyEDA Pro via a WebSocket bridge extension, enabling real-time access to open project data. It integrates with JLCPCB, LCSC, Mouser, and DigiKey for BOM sourcing and pricing.
+
+### Key Capabilities
+
+| Area            | What you can do                                          |
+| --------------- | -------------------------------------------------------- |
+| **Schematic**   | List nets and components, get net details                |
+| **BOM**         | Generate, validate, export, and source bill of materials |
+| **DRC/ERC**     | Run design rule and electrical rule checks               |
+| **Board**       | Inspect layers, stackup, dimensions, features            |
+| **Export**      | Export Gerbers, pick-and-place, PDF, netlist             |
+| **Diagnostics** | Health check, bridge status, capabilities, self-test     |
+
+---
+
+## Prerequisites
+
+- **Node.js** >=24 <27 (required for the latest JavaScript features)
+- **pnpm** >=11 (for local development; the npm package is self-contained)
+- **EasyEDA Pro** with the [bridge extension](https://github.com/oaslananka/easyeda-bridge) installed and running
+- For supplier integration: API credentials from JLCPCB, LCSC, Mouser, or DigiKey
+
+---
+
+## Installation
+
+### Via npm (recommended)
+
+```bash
+npm install -g easyeda-mcp-pro
+easyeda-mcp-pro
+```
+
+### Via npx
+
+```bash
+npx easyeda-mcp-pro
+```
+
+### From source
+
+```bash
+git clone https://github.com/oaslananka/easyeda-mcp-pro.git
+cd easyeda-mcp-pro
+cp .env.example .env
+pnpm install
+pnpm build
+pnpm start
+```
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and edit. All variables have safe defaults — only configure what you need.
+
+### Essential
+
+| Variable       | Default       | Description                                                                  |
+| -------------- | ------------- | ---------------------------------------------------------------------------- |
+| `NODE_ENV`     | `development` | Set to `production` in production                                            |
+| `LOG_LEVEL`    | `info`        | Pino log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent` |
+| `TOOL_PROFILE` | `core`        | Tool set: `core`, `pro`, `full`, `dev`, `experimental`                       |
+| `TRANSPORT`    | `stdio`       | Server transport: `stdio` (default) or `http`                                |
+
+### Bridge (EasyEDA Pro connection)
+
+| Variable            | Default     | Description              |
+| ------------------- | ----------- | ------------------------ |
+| `BRIDGE_HOST`       | `127.0.0.1` | Bridge WebSocket host    |
+| `BRIDGE_PORT`       | `18601`     | Bridge port              |
+| `BRIDGE_TIMEOUT_MS` | `15000`     | Bridge call timeout (ms) |
+
+### Storage
+
+| Variable   | Default            | Description                                 |
+| ---------- | ------------------ | ------------------------------------------- |
+| `DATA_DIR` | `.easyeda-mcp-pro` | Data directory (cache, database, artifacts) |
+
+### Supplier integration
+
+Enable suppliers by setting their credentials. All suppliers are disabled by default.
+
+- **JLCPCB**: `JLCPCB_MODE=approved_api` + client ID/secret
+- **LCSC**: `JLCSEARCH_ENABLED=true` (default, no key required for basic search)
+- **Mouser**: `MOUSER_ENABLED=true` + API key
+- **DigiKey**: `DIGIKEY_ENABLED=true` + OAuth2 client ID/secret
+
+### AI Assistance (experimental)
+
+Configure an AI provider for LLM-assisted design review:
+
+| Variable      | Default | Description                                     |
+| ------------- | ------- | ----------------------------------------------- |
+| `AI_PROVIDER` | `none`  | `anthropic`, `openai`, `openrouter`, or `local` |
+| `AI_MODEL`    | `''`    | Model name                                      |
+
+### HTTP transport
+
+When using `TRANSPORT=http`:
+
+| Variable      | Default     | Description                               |
+| ------------- | ----------- | ----------------------------------------- |
+| `HTTP_HOST`   | `127.0.0.1` | Bind address (use `0.0.0.0` with caution) |
+| `HTTP_PORT`   | `3000`      | Port                                      |
+| `CORS_ORIGIN` | `''`        | Allowed CORS origin                       |
+
+For production HTTP deployments, configure OAuth (`OAUTH_ENABLED=true` + issuer/JWKS).
+
+See `.env.example` for the complete list of 42 configuration variables.
+
+---
+
+## MCP Tools
+
+All 25 tools are available via the MCP server. Tools are filtered by the active `TOOL_PROFILE`.
+
+### L0 — Diagnostics (core)
+
+| Tool                        | Description                                           |
+| --------------------------- | ----------------------------------------------------- |
+| `easyeda_health_check`      | Server health, runtime version, profile, bridge state |
+| `easyeda_bridge_status`     | Bridge connection status, version, capabilities       |
+| `easyeda_get_capabilities`  | Available profiles, features, supported operations    |
+| `easyeda_get_server_config` | Safe/redacted server configuration                    |
+| `easyeda_get_tool_profiles` | Available tool profiles                               |
+| `easyeda_get_feature_flags` | Current feature flags                                 |
+| `easyeda_run_self_test`     | Internal self-test                                    |
+
+### L1 — Schematic (core)
+
+| Tool                           | Description                                                 |
+| ------------------------------ | ----------------------------------------------------------- |
+| `easyeda_schematic_nets`       | List all nets with node connections                         |
+| `easyeda_schematic_components` | List components with ref, value, footprint, LCSC, datasheet |
+| `easyeda_schematic_net_detail` | Full detail for a specific net                              |
+
+### L1 — BOM (core)
+
+| Tool                   | Description                             |
+| ---------------------- | --------------------------------------- |
+| `easyeda_bom_generate` | Generate bill of materials              |
+| `easyeda_bom_validate` | Validate BOM against LCSC inventory     |
+| `easyeda_bom_export`   | Export BOM to file                      |
+| `easyeda_bom_sourcing` | Pricing and availability from suppliers |
+
+### L1 — DRC/ERC (core)
+
+| Tool                         | Description                         |
+| ---------------------------- | ----------------------------------- |
+| `easyeda_drc_run`            | Design rule check for PCB           |
+| `easyeda_erc_run`            | Electrical rule check for schematic |
+| `easyeda_rule_check_summary` | Combined DRC + ERC summary          |
+
+### L1 — Board (core)
+
+| Tool                       | Description                                     |
+| -------------------------- | ----------------------------------------------- |
+| `easyeda_board_layers`     | List PCB layers with type, color, visibility    |
+| `easyeda_board_stackup`    | Layer stackup with thickness, material          |
+| `easyeda_board_dimensions` | Board outline, shape, mounting holes            |
+| `easyeda_board_features`   | Counts of vias, tracks, zones, pads, components |
+
+### L1 — Export (core/pro)
+
+| Tool                        | Profile | Description                         |
+| --------------------------- | ------- | ----------------------------------- |
+| `easyeda_export_gerbers`    | core    | Export Gerber files for fabrication |
+| `easyeda_export_pick_place` | pro     | Export pick-and-place centroid file |
+| `easyeda_export_pdf`        | pro     | Export schematic/board to PDF       |
+| `easyeda_export_netlist`    | pro     | Export netlist                      |
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐     WebSocket      ┌─────────────────────┐
+│   AI Assistant   │ ◄──── MCP ──────► │  easyeda-mcp-pro    │
+│  (Claude, etc.)  │     Protocol      │  (MCP Server)       │
+└─────────────────┘                    │                     │
+                                       │  ┌───────────────┐  │
+┌─────────────────┐     WebSocket      │  │  BridgeManager │──┼──► EasyEDA Pro
+│  EasyEDA Pro     │ ◄── Bridge ──────►│  │  (WS Client)   │  │   (Plugin)
+│  (via Plugin)    │     Protocol      │  └───────────────┘  │
+└─────────────────┘                    │  ┌───────────────┐  │
+                                       │  │  ToolRegistry  │  │
+                                       │  │  (25 tools)   │  │
+                                       │  └───────────────┘  │
+                                       │  ┌───────────────┐  │
+                                       │  │    Storage     │──┼──► SQLite
+                                       │  │  (Cache/DB)   │  │
+                                       │  └───────────────┘  │
+                                       │  ┌───────────────┐  │
+                                       │  │   Vendors     │──┼──► JLCPCB/LCSC/
+                                       │  │ (API Clients) │  │    Mouser/DigiKey
+                                       │  └───────────────┘  │
+                                       └─────────────────────┘
+```
+
+### Transports
+
+- **stdio** (default): Standard MCP transport — works with Claude Desktop, Cursor, and most MCP clients
+- **HTTP**: Streamable HTTP transport with `/healthz`, `/readyz`, `/mcp` endpoints, CORS, and optional OAuth — suitable for remote deployments
+
+---
+
+## Development
+
+```bash
+# Setup
+pnpm install
+cp .env.example .env
+
+# Code quality
+pnpm format:check          # Prettier
+pnpm typecheck             # TypeScript
+pnpm lint                  # ESLint
+
+# Test
+pnpm test                  # Vitest (73 tests across 12 files)
+pnpm test:coverage         # With coverage report
+
+# Build & run
+pnpm build                 # tsc -> dist/
+pnpm dev                   # Hot-reload dev mode
+pnpm start                 # Run compiled build
+
+# MCP Inspector (debug UI)
+pnpm inspector
+```
+
+### Project structure
+
+```
+src/
+├── index.ts                 # Entry point
+├── bridge/                  # EasyEDA Pro WebSocket bridge protocol
+│   ├── manager.ts, client.ts, extension.ts, protocol.ts, types.ts
+├── config/                  # Environment configuration
+│   ├── env.ts, profiles.ts, feature-flags.ts
+├── schemas/                 # Shared Zod schemas
+├── server/                  # MCP server core
+│   ├── factory.ts, errors.ts
+│   └── transports/
+│       └── http.ts          # HTTP/Streamable HTTP transport
+├── storage/                 # SQLite storage (cache, artifacts)
+├── tools/                   # 25 MCP tool definitions (6 groups)
+│   ├── registry.ts, types.ts
+│   ├── L0_diagnostics.ts, L1_schematic.ts, L1_bom.ts
+│   ├── L1_drc_erc.ts, L1_board.ts, L1_export.ts
+└── vendors/                 # Supplier API clients
+    ├── lcsc/, jlcpcb/, mouser/, digikey/
+```
+
+---
+
+## Security
+
+- **Production safety**: Validates config at startup — rejects non-loopback HTTP without OAuth, blocks dangerous features in production
+- **Secret redaction**: API keys, tokens, passwords are redacted from logs and diagnostic output
+- **Branch protection**: `main` branch requires review and up-to-date status checks
+- **Code scanning**: CodeQL analysis runs on every push and PR (security-extended + security-and-quality queries)
+- **Dependency management**: Renovate automatically updates dependencies with security patches
+- **Reporting**: See [SECURITY.md](SECURITY.md) for vulnerability disclosure
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## Related
+
+- [easyeda-bridge](https://github.com/oaslananka/easyeda-bridge) — EasyEDA Pro plugin that exposes the bridge WebSocket API
+- [Model Context Protocol](https://modelcontextprotocol.io) — Standard protocol for AI tool integration
+- [EasyEDA Pro](https://pro.easyeda.com) — Professional PCB design tool

package/dist/bridge/client.d.ts

@@ -0,0 +1,16 @@
+import { type BridgeManager } from './manager.js';
+import { type EasyedaApiMethod, type BridgeCallOptions, type BridgeCallResult } from './types.js';
+export declare class EasyedaClient {
+    private bridge;
+    constructor(bridge: BridgeManager);
+    call<T = unknown>(method: EasyedaApiMethod, params?: Record<string, unknown>, opts?: BridgeCallOptions): Promise<BridgeCallResult<T>>;
+    openProject(projectId: string): Promise<BridgeCallResult>;
+    listNets(projectId: string): Promise<BridgeCallResult>;
+    listComponents(projectId: string): Promise<BridgeCallResult>;
+    generateBom(projectId: string): Promise<BridgeCallResult>;
+    runDrc(projectId: string): Promise<BridgeCallResult>;
+    runErc(projectId: string): Promise<BridgeCallResult>;
+    exportGerbers(projectId: string, options?: Record<string, unknown>): Promise<BridgeCallResult>;
+    searchInventory(query: string): Promise<BridgeCallResult>;
+    getPrice(lcsc: string): Promise<BridgeCallResult>;
+}

package/dist/bridge/client.js

@@ -0,0 +1,48 @@
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger();
+export class EasyedaClient {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async call(method, params, opts) {
+        try {
+            logger.debug({ method }, 'bridge call');
+            const result = await this.bridge.call(method, params, opts);
+            return { success: true, data: result };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn({ method, err: message }, 'bridge call failed');
+            return { success: false, error: { code: 'BRIDGE_ERROR', message } };
+        }
+    }
+    async openProject(projectId) {
+        return this.call('project.open', { projectId });
+    }
+    async listNets(projectId) {
+        return this.call('schematic.listNets', { projectId });
+    }
+    async listComponents(projectId) {
+        return this.call('schematic.listComponents', { projectId });
+    }
+    async generateBom(projectId) {
+        return this.call('bom.generate', { projectId });
+    }
+    async runDrc(projectId) {
+        return this.call('design.drc', { projectId });
+    }
+    async runErc(projectId) {
+        return this.call('design.erc', { projectId });
+    }
+    async exportGerbers(projectId, options) {
+        return this.call('board.exportGerbers', { projectId, ...options });
+    }
+    async searchInventory(query) {
+        return this.call('inventory.search', { query });
+    }
+    async getPrice(lcsc) {
+        return this.call('inventory.getPrice', { lcsc });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/bridge/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI/C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;AAE3B,MAAM,OAAO,aAAa;IACJ;IAApB,YAAoB,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE7C,KAAK,CAAC,IAAI,CACR,MAAwB,EACxB,MAAgC,EAChC,IAAwB;QAExB,IAAI,CAAC;YACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAA6B,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YACxF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,oBAAoB,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,CAAC;QACtE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,SAAiB;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,SAAiB;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,SAAiB;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,SAAiB,EACjB,OAAiC;QAEjC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,KAAa;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/bridge/extension.d.ts

@@ -0,0 +1,26 @@
+import { EventEmitter } from 'node:events';
+import { type EnvConfig } from '../config/env.js';
+export type ExtensionState = 'idle' | 'listening' | 'connected' | 'error';
+export interface ExtensionEvents {
+    stateChanged: (state: ExtensionState, previous: ExtensionState) => void;
+    clientConnected: () => void;
+    clientDisconnected: (reason: string) => void;
+    error: (error: Error) => void;
+}
+export declare class BridgeExtension extends EventEmitter {
+    state: ExtensionState;
+    private config;
+    private wss;
+    private client;
+    private heartbeatTimer;
+    constructor(config: EnvConfig);
+    start(): Promise<void>;
+    private handleHandshake;
+    private handleHeartbeat;
+    private handleRequest;
+    private executeMethod;
+    private executeDevMock;
+    private startHeartbeat;
+    private stopHeartbeat;
+    stop(): void;
+}