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. Coverage, Test Analytics, and extension bundle monitoring are documented in docs/CODECOV_ANALYTICS.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:

1. Auto-configure your MCP client:

   Terminal

   Copy

   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)

2. Locate and install the EasyEDA Pro bridge extension:

   Terminal

   Copy

   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.

3. 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 115 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

Prerequisites

• Node.js: Node.js 24.x is required; repository automation is pinned to 24.18.0.
• pnpm: local development and automation require exactly 11.5.1.

Prepare the supported runtime before installing dependencies:

nvm install 24.18.0
nvm use 24.18.0
corepack enable
corepack prepare pnpm@11.5.1 --activate
node scripts/check-runtime.mjs --require-pnpm

• EasyEDA Pro with the bundled bridge extension installed and running
• For supplier integration: API credentials from JLCPCB, LCSC, Mouser, or DigiKey

Installation & Client Configuration

Testing the v1 release candidate? Follow Migrating to v1. Stable npm and container channels remain on 0.35.4 during the candidate soak.

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

1. Automatic Configuration (CLI)

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

# 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:

# 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:

1. Open EasyEDA Pro.
2. Go to Settings → Extensions → Extension Manager.
3. Click Import Extension and select the easyeda-bridge-extension.eext file.
4. Ensure Allow External Interaction is enabled for the extension.
5. 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:

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

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

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

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

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

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

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

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

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

4. Running from Source (Development)

If you are developing or running a modified local build:

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:

# 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:

pnpm doctor

This checks:

1. Node.js version compatibility.
2. Runtime mode: source checkout, installed package, or production runtime.
3. The CLI entry shebang and the .eext extension package checksum.
4. 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.

pnpm is required only for a source checkout and must match the repository pin. pnpm is not required for an installed package or production runtime, including the hardened Docker image. Doctor exits with status 1 for unsupported required runtimes, invalid configuration, or missing/corrupt runtime artifacts; an offline bridge by itself remains informational.

Configuration

Copy .env.example to .env and edit. All variables have safe defaults — only configure what you need.

Boolean environment variables use strict literals: true / 1 enable a setting and false / 0 disable it. Matching is case-insensitive and surrounding whitespace is ignored. Other values—including yes, no, on, off, enabled, disabled, empty strings, and misspellings—fail startup validation and report the offending variable. Leave a variable unset to use its documented default.

Essential

For Remote Relay experiments, run npx easyeda-mcp-pro doctor --fix after setting MCP_BRIDGE_BACKEND=remote_relay; the doctor output validates HTTP transport, session selection, OAuth, and loopback-only development auth settings.

Bridge (EasyEDA Pro connection)

Storage

Storage paths are resolved in two stages. DATA_DIR is resolved first; each subordinate path is then derived from it with the current operating system's native path separator unless that variable was explicitly supplied. Setting only DATA_DIR therefore relocates the default database, artifact, and cache paths together. Explicit overrides are applied independently and retain their supplied absolute or relative semantics; relative paths remain relative to the MCP process working directory. Changing these settings does not migrate existing data automatically.

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

Shared sourcing behavior is controlled independently of any one vendor:

Reserved AI configuration

No in-process AI provider client is currently implemented. The AI_* variables remain accepted for configuration compatibility but are reported as reserved, are always ineffective, and must not be used to infer that the server sends design data to an AI provider. Do not supply an API key.

Use easyeda_get_feature_flags or easyeda_get_capabilities to inspect configured, effective, and maturity values for optional settings.

HTTP transport

When using TRANSPORT=http:

Remote HTTP Security

Every non-loopback HTTP deployment requires OAuth 2.0 / OpenID Connect authentication, regardless of NODE_ENV:

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 in every environment: non-loopback HTTP_HOST without OAuth is rejected, OAUTH_JWKS_URI / OAUTH_ISSUER / OAUTH_AUDIENCE are required, wildcard ALLOWED_ORIGINS=* is rejected, and HTTP_AUTH_DISABLED=true remains limited to non-production loopback development. Requests without an Origin header still require a valid bearer token on authenticated deployments; CORS is not an authentication boundary.

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, non-wildcard origin allowlist:

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. ALLOWED_ORIGINS restricts browsers but never replaces authentication. 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 registers profile-gated tools according to the active TOOL_PROFILE. The table below is generated from the same registry used at runtime:

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)

L0 — Full-control and dev probes

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:

TOOL_PROFILE=full

L1 — Schematic (core)

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)

L1 — DRC/ERC (core)

L1 — Board (core)

L1 — Export (core/pro)

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  │  │
                                       │  │ (up to 115 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

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.

For local bridge development, an experimental loopback-only CDP transport is documented in the CDP Bridge guide. The extension remains the recommended transport for normal use. Public delivery targets and milestone lifecycle rules are maintained in the roadmap.

Agent plugin and skills

This repository owns the product-level agent plugin and EasyEDA-specific skills for EasyEDA MCP Pro. The central agent-tools repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server, bridge extension, tool profiles, and EasyEDA runtime behavior.

Agent setup

EasyEDA MCP Pro can be launched with the published npm package or from a source checkout:

npx easyeda-mcp-pro
TRANSPORT=http HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npx easyeda-mcp-pro
pnpm build && node dist/index.js

For live EasyEDA Pro workflows, install the EasyEDA bridge extension and confirm the bridge is reachable with easyeda_health_check and easyeda_bridge_status. Tool availability depends on TOOL_PROFILE and optional TOOL_SCOPES restrictions.

For source checkouts, run the normal validation path before publishing plugin changes:

python3 -m json.tool .claude-plugin/plugin.json >/dev/null
claude plugin validate .
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
pnpm check:metadata

Validation workflow

Before listing this plugin as active from agent-tools, verify at least one compatible agent runtime can:

1. Discover .claude-plugin/plugin.json.
2. Launch or connect to easyeda-mcp-pro over stdio or HTTP.
3. Call easyeda_health_check, easyeda_bridge_status, or easyeda_get_capabilities.
4. Load a skill from skills/ and follow the workflow without referencing missing tools.
5. Report bridge state, tool profile, ERC, DRC, BOM, export artifacts, assumptions, and human-review requirements separately.

EasyEDA MCP Pro is an engineering assistant, not an autonomous manufacturing sign-off authority. Generated designs, component selections, and fabrication outputs require qualified human review before purchase, fabrication, or assembly.

Development

Prerequisites

• Node.js: Node.js 24.x is required; repository automation is pinned to 24.18.0.
• pnpm: local development and automation require exactly 11.5.1.

Prepare the supported runtime before installing dependencies:

nvm install 24.18.0
nvm use 24.18.0
corepack enable
corepack prepare pnpm@11.5.1 --activate
node scripts/check-runtime.mjs --require-pnpm

• Go Task (optional, for Taskfile commands)

Quick Start

# Setup
pnpm install
cp .env.example .env

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

# Or, if you use Go Task:
task verify

# Use focused checks while iterating:
pnpm format:check          # Prettier
pnpm typecheck             # TypeScript
pnpm lint                  # ESLint

# Test
pnpm test                  # Vitest suite
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:

The package also exposes pnpm verify, which runs the same CI-equivalent local gate without requiring Go Task.

Install Go Task to use these commands.

Project structure

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 115 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.

• Network safety: Validates config at startup in every environment — rejects non-loopback HTTP without complete OAuth and an explicit non-wildcard origin allowlist
• 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: Automates stable version bumps, release metadata, and CHANGELOG.md. Numbered rc.N candidates use the isolated prerelease path. See the Release Policy and Release Process.
• Secure Publishing: The release workflow rebuilds and verifies all assets, publishes npm with provenance to channel-safe latest or next dist-tags, uploads the extension and SBOM to the matching GitHub Release, and keeps GHCR/MCP Registry promotion aligned with the selected channel.

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

Related

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