# Text2Sch

English | [简体中文](README.zh-CN.md)

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.

![GPT-generated STM32 schematic in Altium Designer](docs/images/stm32-text-to-schematic.png)

<p align="center"><sub>Text to Schematic for Altium Designer · Generated with GPT</sub></p>

## 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](docs/testing.md) for the distinction between offline checks and native acceptance.

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

```powershell
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.

| Variable | Meaning |
|---|---|
| ALTIUM_EXE | Path to X2.EXE |
| ALTIUM_DBLIB | Configured DbLib, including locally managed database access |
| ALTIUM_JOB_ROOT | Writable ASCII output path without spaces, quotes, parentheses or pipes |
| ALTIUM_SEED_SCHDOC | Your blank schematic bootstrap file |

`.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](docs/data-formats.md#multi-sheet-projects), [flat example](examples/flat.json), and [three-level hierarchy](examples/hierarchical.json). References must be unique across the project; repeated channels and buses are not supported.

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

## CLI

```powershell
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:

```json
{"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](docs/mcp.example.json). 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](docs/data-formats.md).

## 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](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.