Text2Sch

English | 简体中文

Generate single-sheet and multi-sheet Altium schematics from structured circuit data through a CLI or a Model Context Protocol server. An accompanying Agent Skill teaches tool-capable agents how to use the runtime. No Computer Use is required. This is an independent project, not an Altium product.

This is an experimental release for single-sheet, flat and hierarchical workflows on a configured Windows workstation.

Capabilities

• Query a configured Celestial-style SQL Server DbLib, place its real SchLib symbols, and attach recorded PcbLib footprints and supplier parameters.

• Generate an isolated native project, save/reopen it, and compare Altium's compiled pin-net membership against the input.

• Read back saved part numbers, manufacturers, supplier references and footprint links. Render a local SVG of the saved schematic.

• Use explicit custom symbols for experiments. Serialize desktop execution and retain the job lock on timeout.

The existing backend passed a 24-component STM32 example with 125/125 pin-net matches and saved metadata verification. This repository reorganizes that backend and replaces the handwritten MCP transport with the official SDK. See testing for the distinction between offline checks and native acceptance.

Related MCP server: MCP-KiCad

How it works

Flow: Agent → circuit JSON → CLI / MCP → DelphiScript → native Altium APIs → read-back verification.

The agent describes components, positions, and pin-to-net connections as structured data. The Node.js engine validates it, generates Job.pas and a script project, then invokes Altium's RunScript entry point. The script uses SchServer and library APIs to place real SchLib components, attach footprints and parameters, and connect pins with wires and net labels. Normal drawing requires no mouse automation or screen recognition.

Altium saves, reopens, and compiles the project. The engine compares the resulting component/pin/net relationships with the input; library builds also parse the saved SchDoc to verify parameters and footprint links and generate an SVG preview. MCP exposes the tools, the Skill guides the agent, and the local Altium application performs the drawing.

Requirements and setup

Windows with licensed Altium Designer; Node.js >=22.16; Windows PowerShell and the OLE DB provider required by your DbLib. Native execution was tested with AD26.1.1.7 and Node26.13.0. There is no model SDK or model credential in this server. The agent host may use any model with tools.

cd D:/Text2Sch
npm ci
Copy-Item .env.example .env
# Edit .env for this computer before running live jobs.
npm test
npm run cli -- doctor

Local .env and .local/ files are not part of a Git/npm release. Supply an Altium-created blank schematic via ALTIUM_SEED_SCHDOC. The engine copies this file, then clears only the new job copy. Source libraries are installed into AD's available libraries during placement.

.env is loaded from the repository root; externally supplied environment variables take precedence. Library paths can contain spaces. Credentials stay in the user's DbLib; do not commit it. Use a single Altium instance. Check doctor before live execution; it cannot detect all modal/license dialogs. Never clear a retained lock until the previous script is confirmed stopped.

Multi-sheet projects

Use sheets with topology: "flat" or "hierarchical" in the existing CLI/MCP tools. Flat projects connect matching ports; hierarchical projects use native sheet symbols and matching sheet entries/child ports, including multiple levels and component-free block diagrams. Local net labels remain sheet-local. Both custom symbols and DbLib parts are supported; existing single-sheet JSON stays compatible.

See the format, flat example, and three-level hierarchy. References must be unique across the project; repeated channels and buses are not supported.

npm run cli -- build examples/flat.json
npm run cli -- build examples/hierarchical.json
npm run test:projects:live

CLI

npm run cli -- library-query "$env:ALTIUM_DBLIB" "Embedded - Microcontrollers" "STM32F103CBT6" 1
npm run cli -- library-prepare examples/library-fixture.json
npm run cli -- library-build examples/library-fixture.json
npm run cli -- library-build examples/stm32-minimum.json

If ALTIUM_DBLIB is only in .env, pass the actual DbLib path to library-query (PowerShell does not itself load .env). Example snapshots use relative resource paths. ALTIUM_DBLIB rebases these paths, but does not refresh their parameter values. Query fresh records for new designs. A result is successful only when ok is true; library builds also require libraryVerification.ok. CLI output is JSON and failures exit nonzero.

MCP

Use the local stdio server in an MCP-capable host:

{"mcpServers":{"text2sch":{"command":"node","args":["D:/Text2Sch/src/mcp/server.mjs"]}}}

Replace the path on other machines. Use an absolute node.exe path if the host lacks Node in PATH. The server loads the repository's local .env. See the configuration example. It uses the official @modelcontextprotocol/sdk with a pinned dependency/lockfile; protocol messages alone go to stdout.

Tools: altium_doctor, altium_library_query, altium_library_validate, altium_library_prepare, altium_library_build, plus altium_validate, altium_prepare, altium_build for the separate custom-symbol format. Circuit tools accept {spec: object}. See data formats.

Agent Skill

Install the whole skills/text2sch folder in your host's skills directory, or provide its SKILL.md as instructions. The folder follows the Agent Skills format. The runtime and MCP server are separate dependencies: copying the skill alone does not install Text2Sch. Supply the runtime path or connect its MCP server in the host.

Scope

Not supported: automatic discovery of every Components-panel library, arbitrary DbLib providers/mappings, IntLib/Workspace adapters, repeated sheet instances / multi-channel projects, multi-part SoCs, buses, PCB routing, complete ERC extraction, and native database-update linkage. ERC remains an engineer's task. Matching an input netlist does not prove the circuit is electrically correct. Existing model data and links do not prove native 3D rendering. Altium remains a licensed desktop process; this is not a headless service. Cancellation does not stop an already executing Altium script.

Repository and publication

src/core contains execution/library code; src/mcp contains the SDK transport and tool handlers; src/cli is the CLI; skills contains agent instructions; examples, tests, and docs contain only reusable material. Personal jobs, database files, binary demonstrations and historical troubleshooting records are excluded.

License: MIT License (MIT).

Fresh-clone checklist

The repository includes all runtime source code; no code from the original development workspace is required. Paths such as D:/Text2Sch are examples: replace them with your clone location in commands and MCP configuration. Run npm ci and npm test before configuring live execution.

Create .env from .env.example and set all four paths for your computer. Provide a genuine blank SchDoc saved by Altium, a licensed Altium installation, and your own supported SQL Server DbLib with its SchLib/PcbLib resources and OLE DB provider. These external applications and library assets are not included. The bundled library snapshots require the matching library records; other libraries require fresh queries and circuit data. Merely installing a library in the Components panel is insufficient. See docs/data-formats.md for the supported field mapping.