io.github.oaslananka/easyeda-mcp-pro

Official

by oaslananka · TypeScript

MCP server for EasyEDA Pro: PCB inspection, BOM, exports, and hardware review.

EasyEDA Pro integration for PCB inspection, BOM generation, and hardware review.

Topics

ai-toolsbomdigikeyeasyedaeasyeda-proedaelectronicsgerberhardware-designjlcpcblcscmcpmodel-context-protocolmousernodejspcbtypescript

README.md35 KBView on GitHub

easyeda-mcp-pro

Production-grade MCP server for EasyEDA Pro: safe PCB design inspection, BOM sourcing, manufacturing export, and AI-assisted hardware review. <a href="https://www.npmjs.com/package/easyeda-mcp-pro"> <img src="https://img.shields.io/npm/v/easyeda-mcp-pro.svg?logo=npm" alt="npm version" /> </a> <a href="https://www.npmjs.com/package/easyeda-mcp-pro"> <img src="https://img.shields.io/npm/dt/easyeda-mcp-pro?logo=npm&label=total%20downloads" alt="npm total downloads" /> </a> <a href="https://www.npmjs.com/package/easyeda-mcp-pro"> <img src="https://img.shields.io/node/v/easyeda-mcp-pro" alt="supported Node.js version" /> </a> <a href="LICENSE"> <img src="https://img.shields.io/npm/l/easyeda-mcp-pro.svg" alt="license" /> </a> <a href="https://pnpm.io/"> <img src="https://img.shields.io/badge/pnpm-11.5.1-blue.svg" alt="pnpm" /> </a> <a href="https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/ci.yml"> <img src="https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/ci.yml/badge.svg" alt="CI status" /> </a> <a href="https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/deploy-docs.yml"> <img src="https://github.com/oaslananka/easyeda-mcp-pro/actions/workflows/deploy-docs.yml/badge.svg" alt="Docs status" /> </a> <a href="https://github.com/oaslananka/easyeda-mcp-pro/security/policy"> <img src="https://img.shields.io/badge/security-policy-blue" alt="Security policy" /> </a> <a href="https://www.bestpractices.dev/projects/13406"> <img src="https://www.bestpractices.dev/projects/13406/badge" alt="OpenSSF Best Practices" /> </a> <a href="https://scorecard.dev/viewer/?uri=github.com/oaslananka/easyeda-mcp-pro"> <img src="https://api.scorecard.dev/projects/github.com/oaslananka/easyeda-mcp-pro/badge" alt="OpenSSF Scorecard" /> </a> <a href="https://deepwiki.com/oaslananka/easyeda-mcp-pro">Ask DeepWiki</a> · <a href="docs/ROADMAP.md">Roadmap</a> · <a href="docs/OPENSSF_BEST_PRACTICES.md">OpenSSF evidence</a> · <a href="docs/SECURITY_ASSURANCE_CASE.md">Security assurance case</a> Compliance docs: <a href="THIRD_PARTY_NOTICES.md">Third-Party Notices</a> · <a href="docs/vendor-terms.md">Vendor Terms and Unsupported Workflows</a> · <a href="docs/REMOTE_MCP_MODES.md">Remote MCP Modes</a> <a href="https://www.buymeacoffee.com/oaslananka"> <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Inter&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" /> </a> </div>

Trust and Supply Chain

easyeda-mcp-pro keeps its public OpenSSF Best Practices evidence in docs/OPENSSF_BEST_PRACTICES.md and its security assurance case in docs/SECURITY_ASSURANCE_CASE.md. The header badges link to workflow-backed signals only: CI, generated docs deployment, the project security policy, OpenSSF Best Practices self-certification, and the OpenSSF Scorecard. Release integrity evidence (npm provenance, signed-release status) is tracked in docs/RELEASE_VERIFICATION.md.

Current OpenSSF Best Practices status: Passing (100%) — see live badge and Silver evidence map for in-progress Silver criteria.

Quick Start

The fastest way to install and configure easyeda-mcp-pro for your favorite AI assistant or IDE:

Auto-configure your MCP client:
bash
```
npx easyeda-mcp-pro setup all
```
This detects and configures Claude Desktop, Cursor, VS Code, Windsurf, Cline, Gemini, Zed, etc. to run the MCP server automatically. (Or run for a specific client, e.g., npx easyeda-mcp-pro setup claude)
Locate and install the EasyEDA Pro bridge extension:
bash
```
npx easyeda-mcp-pro extension --open
```
This opens the folder containing the extension package easyeda-bridge-extension.eext. Import it via EasyEDA Pro → Settings → Extensions → Extension Manager.
Connect the bridge: In EasyEDA Pro, click MCP Bridge → Connect in the menu bar.

For advanced configurations, manual instructions, and specific clients, see Installation & Client Configuration.

Overview

easyeda-mcp-pro is a Model Context Protocol (MCP) server that bridges AI assistants with hardware design workflows in EasyEDA Pro. It exposes up to 60 profile-gated MCP tools for schematic inspection and editing, controlled EasyEDA Pro API calls, BOM management, design rule checks, PCB board analysis, fabrication exports, diagnostics, 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/components, search and place devices, edit wires/primitives
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, API inventory, 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 bundled bridge extension installed and running
For supplier integration: API credentials from JLCPCB, LCSC, Mouser, or DigiKey

Installation & Client Configuration

You can configure easyeda-mcp-pro automatically or manually.

1. Automatic Configuration (CLI)

The CLI setup automates editing the configuration files for your client:

bash

# Configure all detected clients automatically
npx easyeda-mcp-pro setup all

# Or configure a specific client
npx easyeda-mcp-pro setup <client>

Supported Client Keys:

claude (Claude Desktop)
cursor (Cursor IDE)
vscode (VS Code Copilot)
windsurf (Windsurf)
cline (Cline)
gemini (Gemini CLI / Antigravity)
zed (Zed Editor)
amazonq (Amazon Q Developer)
continue (Continue.dev)

Options:

--profile <name>: Specify the tool profile. Options: core (default), pro, full, dev. Example: npx easyeda-mcp-pro setup cursor --profile full

2. Extension Installation

To bridge the MCP server with EasyEDA Pro:

bash

# Open the directory containing the .eext extension package in your file manager
npx easyeda-mcp-pro extension --open

# Or copy it to a specific directory
npx easyeda-mcp-pro extension --copy /path/to/destination

Installation steps in EasyEDA Pro:

Open EasyEDA Pro.
Go to Settings → Extensions → Extension Manager.
Click Import Extension and select the easyeda-bridge-extension.eext file.
Ensure Allow External Interaction is enabled for the extension.
Click MCP Bridge → Connect in the menu bar.

3. Manual Client Configurations

If you prefer to configure your clients manually, add the following configuration to the respective settings files:

<details> <summary>🟣 Claude Desktop</summary>

Config Path:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "core"
      }
    }
  }
}

</details> <details> <summary>🔵 Cursor IDE</summary>

Config Path: Project-specific .cursor/mcp.json or global ~/.cursor/mcp.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details> <details> <summary>🟢 VS Code (GitHub Copilot)</summary>

Config Path: %APPDATA%\Code\User\mcp.json (Windows), ~/Library/Application Support/Code/User/mcp.json (macOS), or ~/.config/Code/User/mcp.json (Linux)

json

{
  "servers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details> <details> <summary>🏄 Windsurf (Codeium)</summary>

Config Path: ~/.codeium/windsurf/mcp_config.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details> <details> <summary>🤖 Cline</summary>

Config Path: Cline VS Code extension global storage (cline_mcp_settings.json)

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

</details> <details> <summary>✨ Gemini CLI / Antigravity</summary>

Config Path: ~/.gemini/settings.json or ~/.gemini/config/mcp_config.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details> <details> <summary>⚡ Zed Editor</summary>

Config Path: ~/.config/zed/settings.json

json

{
  "context_servers": {
    "easyeda-mcp-pro": {
      "command": {
        "path": "npx",
        "args": ["-y", "easyeda-mcp-pro@latest"]
      },
      "settings": {}
    }
  }
}

</details> <details> <summary>🔄 Continue.dev</summary>

Config Path: ~/.continue/config.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details> <details> <summary>👑 Amazon Q Developer</summary>

Config Path: ~/.aws/amazonq/mcp.json

json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": ["-y", "easyeda-mcp-pro@latest"],
      "env": {
        "TOOL_PROFILE": "pro"
      }
    }
  }
}

</details>

4. Running from Source (Development)

If you are developing or running a modified local build:

bash

git clone https://github.com/oaslananka/easyeda-mcp-pro.git
cd easyeda-mcp-pro
cp .env.example .env
pnpm install

# Build the server and the bridge extension package
pnpm build
pnpm build:extension

To configure your clients to use the local development build:

bash

# Print instructions and local config block pointing to dist/index.js
node dist/index.js --setup-local

Local Diagnostics & Health Check

You can diagnose your environment and bridge connectivity at any time:

bash

pnpm doctor

This checks:

Node.js version compatibility.
Existence of build files and the .eext extension package.
Bridge port availability. Note: The bridge status will show as offline until an MCP client starts the server and connects to the EasyEDA Pro extension.

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`
`TOOL_SCOPES`	empty	Optional capability allowlist such as `schematic:read,bom:read`
`MCP_PROTOCOL_VERSION`	`2025-11-25`	MCP protocol version string
`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`	`49620`	Primary bridge port
`BRIDGE_PORT_SCAN`	`49620-49629`	Port scan spec (comma/range)
`BRIDGE_TIMEOUT_MS`	`15000`	Bridge call timeout (ms)
`BRIDGE_HEARTBEAT_MS`	`10000`	Heartbeat interval (ms)
`BRIDGE_RECONNECT_MAX_ATTEMPTS`	`0`	Max reconnect attempts (`0` = infinite)
`BRIDGE_WAIT_FOR_EDA_MS`	`30000`	Wait for EasyEDA Pro on startup (ms)
`BRIDGE_MAX_PAYLOAD_SIZE`	`1048576`	Max bridge payload (bytes, default 1 MiB)
`BRIDGE_TOKEN`	`''`	Session token for extension auth
`BRIDGE_RAW_EXEC_ENABLED`	`false`	First explicit gate for raw EasyEDA runtime JavaScript execution
`MCP_RAW_EXEC_EXPERIMENTAL`	`false`	Second experimental gate required before `easyeda_execute` is registered

Storage

Variable	Default	Description
`DATA_DIR`	`.easyeda-mcp-pro`	Data directory (cache, database, artifacts)
`SQLITE_PATH`	`.easyeda-mcp-pro/easyeda-mcp-pro.sqlite`	SQLite database path
`ARTIFACT_DIR`	`.easyeda-mcp-pro/artifacts`	Artifact export directory
`CACHE_DIR`	`.easyeda-mcp-pro/cache`	Cache directory

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 (e.g., `claude-sonnet-4-20250514`)
`AI_API_KEY`	`''`	AI provider API key
`AI_MAX_TOKENS`	`8000`	Max tokens per AI response
`AI_TIMEOUT_MS`	`60000`	AI request timeout in ms
`AI_ALLOW_DESIGN_MUTATIONS`	`false`	Allow AI to modify schematic/board designs

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
`HTTP_AUTH_DISABLED`	`false`	Disable HTTP auth for non-production loopback only
`HTTP_RATE_LIMIT_MAX`	`100`	Max requests per minute per IP
`CORS_ORIGIN`	`''`	Allowed CORS origin

Production HTTP Security

For remote HTTP deployments, OAuth 2.0 / OpenID Connect is strongly recommended:

Variable	Default	Description
`OAUTH_ENABLED`	`false`	Enable Bearer token validation
`OAUTH_ISSUER`	`''`	Expected token issuer (`iss` claim)
`OAUTH_AUDIENCE`	`easyeda-mcp-pro`	Expected token audience (`aud` claim)
`OAUTH_JWKS_URI`	`''`	JWKS endpoint for token signature validation
`OAUTH_REQUIRED_SCOPES`	`easyeda:read`	Required token scope

When OAUTH_ENABLED=true, every request to /mcp must include an Authorization: Bearer <token> header unless HTTP_AUTH_DISABLED=true is explicitly set for non-production loopback development. Tokens are verified against OAUTH_JWKS_URI, iss/aud claims are validated, and OAUTH_REQUIRED_SCOPES is enforced against scope, scp, permissions, or roles claims.

The server enforces startup safety checks: non-loopback HTTP_HOST without OAuth is rejected, and HTTP_AUTH_DISABLED=true is rejected outside non-production loopback deployments.

Docker defaults

The Docker image starts in HTTP mode with HTTP_HOST=127.0.0.1 so the default container boot path is safe and passes the same startup safety checks as local HTTP mode. For an externally reachable container, override the bind address and configure OAuth plus an explicit origin allowlist:

bash

docker run --rm \
  -e HTTP_HOST=0.0.0.0 \
  -e ALLOWED_ORIGINS=https://your-client.example.com \
  -e OAUTH_ENABLED=true \
  -e OAUTH_ISSUER=https://issuer.example.com/ \
  -e OAUTH_JWKS_URI=https://issuer.example.com/.well-known/jwks.json \
  -e OAUTH_AUDIENCE=easyeda-mcp-pro \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/oaslananka/easyeda-mcp-pro:latest

Do not expose non-loopback HTTP without OAuth. Use a reverse proxy or platform gateway for TLS termination and external access.

HTTP Security Features

Rate limiting: Per-IP sliding window (configurable via HTTP_RATE_LIMIT_MAX), returns 429 Too Many Requests with retry-after header
Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 0, Referrer-Policy: strict-origin-when-cross-origin
Health endpoints: /healthz (liveness) and /readyz (readiness) return JSON status

See .env.example for the complete list of configuration variables.

MCP Tools

The server currently registers up to 60 profile-gated tools. Tools are filtered by the active TOOL_PROFILE:

core: 42 tools
pro: 47 tools
full: 56 tools
dev: 60 tools

core exposes the standard workflow tools, pro adds manufacturing exports, full adds controlled documented EasyEDA API calls, and dev adds runtime probes for debugging.

Capability scopes add a second authorization layer when TOOL_SCOPES is set. Leave it empty for the default local all-capabilities mode, or restrict it with comma/space separated scopes such as diagnostics:read, schematic:read, schematic:write, bom:read, bom:source, checks:read, pcb:read, pcb:write, export:write, api:read, api:write, and bridge:execute.

Raw JavaScript execution is intentionally not part of the default dev tool set. easyeda_execute is registered only when both BRIDGE_RAW_EXEC_ENABLED=true and MCP_RAW_EXEC_EXPERIMENTAL=true are set; when TOOL_SCOPES is set it also requires bridge:execute.

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
`easyeda_api_inventory`	Live EasyEDA API classes, runtime paths, and methods

L0 — Full-control and dev probes

Tool	Profile	Description
`easyeda_api_call`	full	Call a documented EasyEDA `Class.method` path through the bridge
`easyeda_bridge_probe_methods`	dev	Probe bridge method availability
`easyeda_component_probe`	dev	Inspect live schematic component runtime objects and state getters

easyeda_api_call is intentionally not raw JavaScript execution. It only accepts documented EasyEDA Pro API class prefixes (DMT_, SCH_, PCB_, LIB_) and a direct method name such as SCH_PrimitiveWire.getAll. Methods that can mutate project state, such as create, delete, modify, openProject, save, import, or export, require confirmWrite=true.

To enable the controlled full-control API tool in your MCP client, set:

bash

TOOL_PROFILE=full

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
`easyeda_schematic_search_device`	Search EasyEDA library devices
`easyeda_schematic_place_component`	Place a library component on the active schematic sheet
`easyeda_schematic_add_wire`	Add a schematic wire segment
`easyeda_schematic_delete_primitive`	Delete schematic components or wires by primitive ID
`easyeda_schematic_modify_primitive`	Modify schematic component or wire properties

The schematic write APIs use EasyEDA Pro extension APIs that EasyEDA currently marks as beta. The bridge checks for the documented API class names at runtime and returns an explicit error when the installed EasyEDA Pro build does not expose a required method.

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

code

┌─────────────────┐     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  │  │
                                       │  │ (up to 60 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

Deployment modes

Beyond local stdio/HTTP, the server supports a hosted remote runtime (gateway, session router, and approval-scoped relay under src/remote/) for managed connector deployments such as Claude Web or ChatGPT app integrations, plus a self-hosted remote mode for user-managed endpoints. See Remote MCP Modes for the full mode matrix and network/security boundaries of each.

Bridge extension

bash

pnpm build:extension
pnpm verify:extension

The extension build writes easyeda-bridge-extension.eext at the repository root. It contains extension.json, the bundled browser script, and the image assets required by EasyEDA Pro.

Installation: Open EasyEDA Pro → Settings → Extensions → Extension Manager... → Import Extension, then select the .eext file. Make sure Allow External Interaction is enabled for the extension.

Development

Prerequisites

Node.js >=24 <27
pnpm >=11
Go Task (optional, for Taskfile commands)

Quick Start

bash

# Setup
pnpm install
cp .env.example .env

# All quality gates (lint + format + typecheck + test + build)
task verify

# Or use pnpm directly:
pnpm format:check          # Prettier
pnpm typecheck             # TypeScript
pnpm lint                  # ESLint

# Test
pnpm test                  # Vitest (804 tests across 66 files)
pnpm test:coverage         # With coverage report

# Golden E2E fixture smoke tests are included in `pnpm test`
# See docs/golden-fixtures.md for fixture architecture

# Build & run
pnpm build                 # tsc -> dist/
pnpm build:extension       # Bundle EasyEDA Pro extension
pnpm verify:extension      # Verify extension package contents
pnpm dev                   # Hot-reload dev mode
pnpm start                 # Run compiled build

# MCP Inspector (debug UI)
pnpm inspector

Available Taskfile Commands

This project includes a Taskfile.yml with the following commands:

Command	Description
`task install`	Install dependencies
`task lint`	Run ESLint
`task format`	Check formatting with Prettier
`task typecheck`	Run TypeScript type checking
`task test`	Run tests
`task build`	Build the project
`task verify`	Run all quality gates (CI gate)

Install Go Task to use these commands.

Project structure

code

src/
├── index.ts                 # Entry point (stdio or HTTP)
├── bridge/                  # EasyEDA Pro WebSocket bridge protocol
│   ├── manager.ts, protocol.ts, types.ts
├── cli/                     # Client auto-setup (setup/extension CLI commands)
├── config/                  # Environment, tool profiles, feature flags
│   ├── env.ts, profiles.ts, feature-flags.ts, version.ts
├── remote/                  # Hosted/self-hosted remote MCP gateway, session router, scopes
├── schemas/                 # Shared Zod schemas
├── server/                  # MCP server core
│   ├── factory.ts, resources-prompts.ts
│   └── transports/
│       ├── http.ts                    # HTTP/Streamable HTTP transport
│       └── oauth-resource-metadata.ts
├── storage/                 # Node.js sqlite storage (cache, artifacts)
├── tools/                   # Up to 60 profile-gated MCP tool definitions
│   ├── register.ts, registry.ts, types.ts, transaction.ts
│   ├── L0_diagnostics_core.ts, L0_diagnostics_api.ts
│   ├── L1_schematic_read.ts, L1_schematic_write.ts
│   ├── L1_bom_core.ts, L1_bom_sourcing.ts
│   └── L1_drc_erc.ts, L1_board.ts, L1_export.ts, L1_pcb_constraints.ts, L1_pcb_write.ts
├── vendors/                 # Supplier API clients (lcsc/, jlcpcb/, mouser/, digikey/)
└── ...                      # circuit, pcb-layout, net-validation, power-tree, production-qa,
                              # quote-gating, safety, observability, catalog, bom-quality,
                              # export-manifest, live, easyeda-runtime

easyeda-bridge-extension/    # EasyEDA Pro bridge extension workspace package

Security

See Security Architecture & Threat Model for the complete security reference, including deployment modes, authentication, tool safety controls, secrets management, safe defaults, supplier API security, threat scenarios, and deployment checklists.

Production safety: Validates config at startup — rejects non-loopback HTTP without OAuth, blocks dangerous features in production
OAuth/JWKS: Bearer token validation via JWKS endpoint for HTTP transport (see OAuth section)
Rate limiting: Per-IP sliding window rate limiter on HTTP transport (default 100 req/min)
Path traversal protection: All file export paths validated against ARTIFACT_DIR
Secret redaction: API keys, tokens, passwords are redacted from logs and diagnostic output
Branch protection: Governance policy requires code reviews and status checks on the main branch (see Repository Governance)
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
Supply-chain hygiene: pnpm workspace build, pinned GitHub Actions, and no native SQLite addon dependency
Reporting: See SECURITY.md for vulnerability disclosure

Release & Dependency Automation

This repository uses automated workflows to manage dependencies and releases:

Renovate: Automatically scans and updates dependencies based on rules configured in .github/renovate.json. For details on PR policies and automerging, see Repository Governance.
Release Please: Automatically bumps package versions, updates files (like package.json, server.json, extension.json), and generates CHANGELOG.md upon merging Release PRs. For the full release procedure and Conventional Commit conventions, see Release Process.
Secure Publishing: The release workflow builds all assets (including easyeda-bridge-extension.eext), publishes to the NPM registry with cryptographic provenance, and uploads assets directly to the GitHub release.

Support the project

If this project helps you save time while working with EasyEDA Pro, BOM workflows, or MCP integrations, you can support ongoing development via the Buy me a coffee button at the top of this README.

License

MIT

Model Context Protocol — Standard protocol for AI tool integration
EasyEDA Pro — Professional PCB design tool

Install

Configuration

Environment variables

NODE_ENVdefault development

Environment mode

LOG_LEVELdefault info

Pino log level

TOOL_PROFILEdefault core

Active tool profile (core, pro, full, dev, experimental)

MCP_PROTOCOL_VERSIONdefault 2025-11-25

MCP protocol version string

TRANSPORTdefault stdio

Server transport mode (stdio or http)

HTTP_HOSTdefault 127.0.0.1

HTTP bind address

HTTP_PORTdefault 3000

HTTP port

HTTP_AUTH_DISABLEDdefault false

Disable HTTP transport authentication

HTTP_RATE_LIMIT_MAXdefault 100

Max requests per minute per IP

CORS_ORIGIN

Allowed CORS origin for HTTP transport

ALLOWED_ORIGINS

Comma-separated list of allowed origins for HTTP transport (use * for wildcard)

MCP_TASKS_ENABLEDdefault false

Enable experimental MCP tasks

MCP_APPS_ENABLEDdefault false

Enable experimental MCP apps

MCP_V2_EXPERIMENTALdefault false

Enable experimental MCP v2 features

MCP_RAW_EXEC_EXPERIMENTALdefault false

Enable experimental raw EasyEDA runtime execution gate (dangerous; requires BRIDGE_RAW_EXEC_ENABLED)

BRIDGE_HOSTdefault 127.0.0.1

Bridge WebSocket host for EasyEDA Pro connection

BRIDGE_PORTdefault 49620

Bridge primary port

BRIDGE_PORT_SCANdefault 49620-49629

Port scan specification (comma-separated ports or ranges)

BRIDGE_TIMEOUT_MSdefault 15000

Bridge call timeout in ms

BRIDGE_HEARTBEAT_MSdefault 10000

Bridge heartbeat interval in ms

BRIDGE_RECONNECT_MAX_ATTEMPTSdefault 0

Max reconnect attempts (0 = infinite)

BRIDGE_WAIT_FOR_EDA_MSdefault 30000

How long to wait for EasyEDA Pro to become available on startup (ms)

BRIDGE_MAX_PAYLOAD_SIZEdefault 1048576

Max bridge payload size in bytes

BRIDGE_TOKENsecret

Session token for extension auth

EASYEDA_DEV_BRIDGEdefault false

Enable EasyEDA dev bridge mode

BRIDGE_RAW_EXEC_ENABLEDdefault false

Enable raw method execution on bridge (dangerous)

DATA_DIRdefault .easyeda-mcp-pro

Data directory for storage

SQLITE_PATHdefault .easyeda-mcp-pro/easyeda-mcp-pro.sqlite

SQLite database path

ARTIFACT_DIRdefault .easyeda-mcp-pro/artifacts

Artifact export directory

CACHE_DIRdefault .easyeda-mcp-pro/cache

Cache directory

AI_PROVIDERdefault none

AI provider (none, anthropic, openai, openrouter, local)

AI_MODEL

AI model name

AI_API_KEYsecret

AI provider API key

AI_MAX_TOKENSdefault 8000

Max tokens for AI responses

AI_TIMEOUT_MSdefault 60000

AI request timeout in ms

AI_ALLOW_DESIGN_MUTATIONSdefault false

Allow AI to modify designs

JLCPCB_MODEdefault disabled

JLCPCB API mode (disabled, mock, approved_api)

JLCPCB_CLIENT_IDsecret

JLCPCB API client ID

JLCPCB_CLIENT_SECRETsecret

JLCPCB API client secret

JLCPCB_API_BASE_URLdefault https://api.jlcpcb.com

JLCPCB API base URL

JLCPCB_ENABLE_ORDERINGdefault false

Enable JLCPCB ordering

JLCPCB_DEFAULT_CURRENCYdefault USD

JLCPCB default currency (USD, CNY)

JLCSEARCH_ENABLEDdefault true

Enable LCSC component search

JLCSEARCH_BASE_URLdefault https://jlcsearch.tscircuit.com

LCSC search API base URL

LCSC_API_KEYsecret

LCSC API key

LCSC_API_SECRETsecret

LCSC API secret

MOUSER_ENABLEDdefault false

Enable Mouser integration

MOUSER_API_KEYsecret

Mouser API key

MOUSER_API_BASE_URLdefault https://api.mouser.com

Mouser API base URL

DIGIKEY_ENABLEDdefault false

Enable DigiKey integration

DIGIKEY_CLIENT_IDsecret

DigiKey OAuth2 client ID

DIGIKEY_CLIENT_SECRETsecret

DigiKey OAuth2 client secret

DIGIKEY_SANDBOXdefault true

Use DigiKey sandbox environment

DIGIKEY_LOCALEdefault en-US

DigiKey locale

DIGIKEY_CURRENCYdefault USD

DigiKey pricing currency

OAUTH_ENABLEDdefault false

Enable OAuth for HTTP mode

OAUTH_ISSUER

Expected OAuth token issuer

OAUTH_AUDIENCEdefault easyeda-mcp-pro

Expected OAuth token audience

OAUTH_JWKS_URI

JWKS endpoint for token signature validation

OAUTH_REQUIRED_SCOPESdefault easyeda:read

Required OAuth token scope

OTEL_ENABLEDdefault false

Enable OpenTelemetry

OTEL_SERVICE_NAMEdefault easyeda-mcp-pro

OpenTelemetry service name

OTEL_EXPORTER_OTLP_ENDPOINT

OpenTelemetry OTLP endpoint

TRACE_SAMPLE_RATEdefault 1.0

OpenTelemetry trace sample rate (0.0 to 1.0)

claude_desktop_config.json

{
  "mcpServers": {
    "easyeda-mcp-pro": {
      "command": "npx",
      "args": [
        "-y",
        "easyeda-mcp-pro@0.20.0"
      ],
      "env": {
        "NODE_ENV": "development",
        "LOG_LEVEL": "info",
        "TOOL_PROFILE": "core",
        "MCP_PROTOCOL_VERSION": "2025-11-25",
        "TRANSPORT": "stdio",
        "HTTP_HOST": "127.0.0.1",
        "HTTP_PORT": "3000",
        "HTTP_AUTH_DISABLED": "false",
        "HTTP_RATE_LIMIT_MAX": "100",
        "CORS_ORIGIN": "<YOUR_CORS_ORIGIN>",
        "ALLOWED_ORIGINS": "<YOUR_ALLOWED_ORIGINS>",
        "MCP_TASKS_ENABLED": "false",
        "MCP_APPS_ENABLED": "false",
        "MCP_V2_EXPERIMENTAL": "false",
        "MCP_RAW_EXEC_EXPERIMENTAL": "false",
        "BRIDGE_HOST": "127.0.0.1",
        "BRIDGE_PORT": "49620",
        "BRIDGE_PORT_SCAN": "49620-49629",
        "BRIDGE_TIMEOUT_MS": "15000",
        "BRIDGE_HEARTBEAT_MS": "10000",
        "BRIDGE_RECONNECT_MAX_ATTEMPTS": "0",
        "BRIDGE_WAIT_FOR_EDA_MS": "30000",
        "BRIDGE_MAX_PAYLOAD_SIZE": "1048576",
        "BRIDGE_TOKEN": "<YOUR_BRIDGE_TOKEN>",
        "EASYEDA_DEV_BRIDGE": "false",
        "BRIDGE_RAW_EXEC_ENABLED": "false",
        "DATA_DIR": ".easyeda-mcp-pro",
        "SQLITE_PATH": ".easyeda-mcp-pro/easyeda-mcp-pro.sqlite",
        "ARTIFACT_DIR": ".easyeda-mcp-pro/artifacts",
        "CACHE_DIR": ".easyeda-mcp-pro/cache",
        "AI_PROVIDER": "none",
        "AI_MODEL": "<YOUR_AI_MODEL>",
        "AI_API_KEY": "<YOUR_AI_API_KEY>",
        "AI_MAX_TOKENS": "8000",
        "AI_TIMEOUT_MS": "60000",
        "AI_ALLOW_DESIGN_MUTATIONS": "false",
        "JLCPCB_MODE": "disabled",
        "JLCPCB_CLIENT_ID": "<YOUR_JLCPCB_CLIENT_ID>",
        "JLCPCB_CLIENT_SECRET": "<YOUR_JLCPCB_CLIENT_SECRET>",
        "JLCPCB_API_BASE_URL": "https://api.jlcpcb.com",
        "JLCPCB_ENABLE_ORDERING": "false",
        "JLCPCB_DEFAULT_CURRENCY": "USD",
        "JLCSEARCH_ENABLED": "true",
        "JLCSEARCH_BASE_URL": "https://jlcsearch.tscircuit.com",
        "LCSC_API_KEY": "<YOUR_LCSC_API_KEY>",
        "LCSC_API_SECRET": "<YOUR_LCSC_API_SECRET>",
        "MOUSER_ENABLED": "false",
        "MOUSER_API_KEY": "<YOUR_MOUSER_API_KEY>",
        "MOUSER_API_BASE_URL": "https://api.mouser.com",
        "DIGIKEY_ENABLED": "false",
        "DIGIKEY_CLIENT_ID": "<YOUR_DIGIKEY_CLIENT_ID>",
        "DIGIKEY_CLIENT_SECRET": "<YOUR_DIGIKEY_CLIENT_SECRET>",
        "DIGIKEY_SANDBOX": "true",
        "DIGIKEY_LOCALE": "en-US",
        "DIGIKEY_CURRENCY": "USD",
        "OAUTH_ENABLED": "false",
        "OAUTH_ISSUER": "<YOUR_OAUTH_ISSUER>",
        "OAUTH_AUDIENCE": "easyeda-mcp-pro",
        "OAUTH_JWKS_URI": "<YOUR_OAUTH_JWKS_URI>",
        "OAUTH_REQUIRED_SCOPES": "easyeda:read",
        "OTEL_ENABLED": "false",
        "OTEL_SERVICE_NAME": "easyeda-mcp-pro",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_OTEL_EXPORTER_OTLP_ENDPOINT>",
        "TRACE_SAMPLE_RATE": "1.0"
      }
    }
  }
}

Topics

easyeda-mcp-pro

Trust and Supply Chain

Quick Start

Overview

Key Capabilities

Prerequisites

Installation & Client Configuration

1. Automatic Configuration (CLI)

Supported Client Keys:

Options:

2. Extension Installation

3. Manual Client Configurations

4. Running from Source (Development)

Local Diagnostics & Health Check

Configuration

Essential

Bridge (EasyEDA Pro connection)

Storage

Supplier integration

AI Assistance (experimental)

HTTP transport

Production HTTP Security

Docker defaults

HTTP Security Features

MCP Tools

L0 — Diagnostics (core)

L0 — Full-control and dev probes

L1 — Schematic (core)

L1 — BOM (core)

L1 — DRC/ERC (core)

L1 — Board (core)

L1 — Export (core/pro)

Architecture

Transports

Deployment modes

Bridge extension

Development

Prerequisites

Quick Start

Available Taskfile Commands

Project structure

Security

Release & Dependency Automation

Support the project

License

Related

Install

Configuration