easyeda-mcp-pro 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oaslananka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,24 +17,36 @@ 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)).
 
+For the recommended no-terminal workflow, let your MCP client auto-start the server:
+
+```bash
+npx easyeda-mcp-pro --setup-local
+```
+
+The setup command prints:
+
+- the EasyEDA Pro extension package path (`easyeda-bridge-extension.eext`)
+- a local MCP client config that starts `dist/index.js` automatically
+- an npm/npx MCP client config for published package usage
+
 ---
 
 ## 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.
+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 34 profile-gated MCP tools for schematic inspection and editing, controlled EasyEDA Pro API calls, 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     |
+| 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   |
 
 ---
 
@@ -42,7 +54,7 @@ The server connects to EasyEDA Pro via a WebSocket bridge extension, enabling re
 
 - **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
+- **EasyEDA Pro** with the bundled bridge extension installed and running
 - For supplier integration: API credentials from JLCPCB, LCSC, Mouser, or DigiKey
 
 ---
@@ -69,10 +81,19 @@ git clone https://github.com/oaslananka/easyeda-mcp-pro.git
 cd easyeda-mcp-pro
 cp .env.example .env
 pnpm install
-pnpm build
-pnpm start
+pnpm setup:local
 ```
 
+Install or reload the generated `easyeda-bridge-extension.eext` package in EasyEDA Pro. Then add the printed MCP config to your MCP client. After that, your MCP client starts the server automatically; do not keep a separate `node dist/index.js` terminal running.
+
+### Local health check
+
+```bash
+pnpm doctor
+```
+
+The doctor command checks the Node.js runtime, built server entry, generated EasyEDA extension package, and local bridge port reachability. If the bridge server is offline, that is normal until your MCP client starts `easyeda-mcp-pro`.
+
 ---
 
 ## Configuration
@@ -90,11 +111,14 @@ Copy `.env.example` to `.env` and edit. All variables have safe defaults — onl
 
 ### 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) |
+| Variable              | Default             | Description                      |
+| --------------------- | ------------------- | -------------------------------- |
+| `BRIDGE_HOST`         | `127.0.0.1`         | Bridge WebSocket host            |
+| `BRIDGE_PORT`         | `18601`             | Primary bridge port              |
+| `BRIDGE_PORT_SCAN`    | `18601,49620-49629` | Port scan spec (comma/range)     |
+| `BRIDGE_TIMEOUT_MS`   | `15000`             | Bridge call timeout (ms)         |
+| `BRIDGE_HEARTBEAT_MS` | `10000`             | Heartbeat interval (ms)          |
+| `BRIDGE_TOKEN`        | `''`                | Session token for extension auth |
 
 ### Storage
 
@@ -124,21 +148,42 @@ Configure an AI provider for LLM-assisted design review:
 
 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                       |
+| Variable              | Default     | Description                               |
+| --------------------- | ----------- | ----------------------------------------- |
+| `HTTP_HOST`           | `127.0.0.1` | Bind address (use `0.0.0.0` with caution) |
+| `HTTP_PORT`           | `3000`      | Port                                      |
+| `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. Tokens are validated against the JWKS endpoint if configured, or structurally validated otherwise.
+
+The server enforces a safety check at startup: **non-loopback `HTTP_HOST` without OAuth is rejected**.
 
-For production HTTP deployments, configure OAuth (`OAUTH_ENABLED=true` + issuer/JWKS).
+#### HTTP Security Features
 
-See `.env.example` for the complete list of 42 configuration variables.
+- **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
 
-All 25 tools are available via the MCP server. Tools are filtered by the active `TOOL_PROFILE`.
+The server currently registers 34 tools. Tools are filtered by the active `TOOL_PROFILE`: `core` exposes the normal workflow tools, `pro` adds manufacturing exports, `full` adds controlled documented EasyEDA API calls, and `dev` adds runtime probes for debugging.
 
 ### L0 — Diagnostics (core)
 
@@ -151,14 +196,38 @@ All 25 tools are available via the MCP server. Tools are filtered by the active
 | `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                              |
+| 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)
 
@@ -210,7 +279,7 @@ All 25 tools are available via the MCP server. Tools are filtered by the active
 │  (via Plugin)    │     Protocol      │  └───────────────┘  │
 └─────────────────┘                    │  ┌───────────────┐  │
                                        │  │  ToolRegistry  │  │
-                                       │  │  (25 tools)   │  │
+                                       │  │  (34 tools)   │  │
                                        │  └───────────────┘  │
                                        │  ┌───────────────┐  │
                                        │  │    Storage     │──┼──► SQLite
@@ -228,6 +297,19 @@ All 25 tools are available via the MCP server. Tools are filtered by the active
 - **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
 
+### 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
@@ -243,11 +325,13 @@ pnpm typecheck             # TypeScript
 pnpm lint                  # ESLint
 
 # Test
-pnpm test                  # Vitest (73 tests across 12 files)
+pnpm test                  # Vitest (97 tests across 13 files)
 pnpm test:coverage         # With coverage report
 
 # 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
 
@@ -259,9 +343,9 @@ pnpm inspector
 
 ```
 src/
-├── index.ts                 # Entry point
+├── index.ts                 # Entry point (stdio or HTTP)
 ├── bridge/                  # EasyEDA Pro WebSocket bridge protocol
-│   ├── manager.ts, client.ts, extension.ts, protocol.ts, types.ts
+│   ├── manager.ts, protocol.ts, types.ts
 ├── config/                  # Environment configuration
 │   ├── env.ts, profiles.ts, feature-flags.ts
 ├── schemas/                 # Shared Zod schemas
@@ -269,13 +353,15 @@ src/
 │   ├── 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
+├── storage/                 # Node.js sqlite storage (cache, artifacts)
+├── tools/                   # 34 MCP tool definitions (6 groups)
+│   ├── register.ts, 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/
+
+easyeda-bridge-extension/    # EasyEDA Pro bridge extension workspace package
 ```
 
 ---
@@ -283,10 +369,14 @@ src/
 ## Security
 
 - **Production safety**: Validates config at startup — rejects non-loopback HTTP without OAuth, blocks dangerous features in production
+- **OAuth/JWKS**: Optional Bearer token validation via JWKS endpoint for HTTP transport
+- **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**: `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
+- **Supply-chain hygiene**: pnpm workspace build, pinned GitHub Actions, and no native SQLite addon dependency
 - **Reporting**: See [SECURITY.md](SECURITY.md) for vulnerability disclosure
 
 ---
@@ -299,6 +389,5 @@ src/
 
 ## 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/manager.d.ts

@@ -2,36 +2,43 @@ import { EventEmitter } from 'node:events';
 import { type EnvConfig } from '../config/env.js';
 import { type BridgeHello } from './protocol.js';
 export type BridgeState = 'disconnected' | 'connecting' | 'connected' | 'error';
-export interface BridgeEvents {
-    stateChanged: (state: BridgeState, previous: BridgeState) => void;
-    connected: (hello: BridgeHello) => void;
-    disconnected: (reason: string) => void;
-    error: (error: Error) => void;
-    heartbeat: (timestamp: number) => void;
-}
 export declare class BridgeManager extends EventEmitter {
     state: BridgeState;
     hello: BridgeHello | null;
+    private wss;
     private ws;
     private heartbeatTimer;
     private reconnectTimer;
+    private _activePort;
+    private _connectedAtMs;
     private requestMap;
     private requestIdCounter;
     private config;
     private _lastHeartbeatMs;
     constructor(config: EnvConfig);
     get lastHeartbeatMs(): number;
+    get activePort(): number;
+    get uptimeMs(): number;
     get connected(): boolean;
     connect(): Promise<void>;
+    private tryListen;
+    private handleConnection;
     call<TParams, TResult>(method: string, params?: TParams, opts?: {
         timeoutMs?: number;
         traceparent?: string;
     }): Promise<TResult>;
     disconnect(reason?: string): void;
-    private tryConnect;
-    private sendHandshake;
-    private handleHello;
     private handleResponse;
+    private rejectPending;
     private startHeartbeat;
-    private parsePortScan;
+    private stopHeartbeat;
 }
+/**
+ * Parse a port scan specification string into an ordered array of ports.
+ * Supports comma-separated values and dash ranges:
+ *   "18601"           → [18601]
+ *   "18601,49620"     → [18601, 49620]
+ *   "49620-49629"     → [49620, 49621, ..., 49629]
+ *   "18601,49620-49629" → [18601, 49620, 49621, ..., 49629]
+ */
+export declare function parsePortScanSpec(spec: string): number[];