This document describes the architecture of the MCP server.
The AI handles the intelligence. The tool handles file I/O.
See VISION.md for the full responsibility split and architectural rationale.
This architecture means the AI can create any footprint — not just pre-programmed package types. The tool is package-agnostic.
src/
├── lib.rs # Library crate root
├── main.rs # CLI entry point
├── error.rs # Top-level error types
├── util.rs # Path redaction, CSV escaping, UniqueId generation
│
├── config/ # Configuration
│ ├── mod.rs # Module exports
│ └── settings.rs # Config file parsing + defaults
│
├── security/ # Safety controls
│ ├── mod.rs # Module exports
│ ├── audit.rs # Append-only audit log for mutating tools
│ └── rate_limit.rs # Token-bucket rate limiter (mutating tools)
│
├── altium/ # Altium file I/O
│ ├── mod.rs # Shared helpers: Windows-1252, OLE names, atomic save
│ ├── error.rs # Altium-specific errors (path-sanitised Display)
│ ├── bytes.rs # Bounds-checked little-endian scalar readers
│ ├── base64_opt.rs # Serde base64 codec for embedded image bytes
│ ├── framing.rs # Shared block / Pascal-string / C-string frames
│ ├── text.rs # TextJustification (shared enum)
│ ├── serde_round.rs # 6-decimal f64 rounding on serialise
│ ├── libpkg.rs # .LibPkg project-file generator
│ ├── pcblib/
│ │ ├── mod.rs # PcbLib + Footprint types, CRUD
│ │ ├── read_io.rs # OLE stream orchestration (read)
│ │ ├── write_io.rs # OLE stream orchestration (write)
│ │ ├── reader/ # Binary parsing (dispatch, per-primitive, 3D models)
│ │ ├── writer.rs # Binary encoding (byte templates)
│ │ ├── primitives/ # Pad, Via, Track, Arc, Region, Text, Fill, bodies
│ │ ├── flags.rs # On-disk flag-word bits
│ │ ├── units.rs # mm ↔ Altium internal units
│ │ └── assets/ # Captured Library/Data stack + FileVersionInfo
│ └── schlib/ # (mirrors pcblib/ — same module shape)
│ ├── mod.rs # SchLib + Symbol types, CRUD
│ ├── read_io.rs # OLE stream orchestration (read)
│ ├── write_io.rs # OLE stream orchestration (write)
│ ├── reader/ # Record parsing (dispatch + per-record parsers)
│ ├── writer.rs # Record encoding (omit-when-default)
│ ├── primitives/ # Pin, shapes, text, footprint models
│ ├── coord.rs # Fractional (_Frac) coordinate codec
│ ├── pin_aux.rs # PinFrac / PinSymbolLineWidth aux streams
│ └── storage.rs # /Storage stream + compressed-storage framing
│
└── mcp/ # MCP server implementation
├── mod.rs # Module exports
├── server.rs # JSON-RPC dispatch, path validation, backups, audit
├── protocol.rs # MCP protocol types
├── transport.rs # stdio transport
├── tool_definitions.rs # Tool schemas (source of truth for docs/TOOLS.md)
├── tool_docs.rs # docs/TOOLS.md generator + drift guard (test-only)
└── tools/ # One file per tool family (read_write, compare, …)
├── allowed_keys.rs # JSON keys the write tools accept, derived from the structs
└── mutation_fidelity.rs # (test-only) every mutating tool leaves untouched components byte-identical
See README § How It Works for the sequence diagram of a
component-creation call (engineer → AI → MCP server): the AI computes the geometry and
calls write_pcblib / write_schlib; the server writes the OLE compound document.
See README.md § Primitive Types for the complete primitive reference.
See README.md § Standard Altium Layers for the layer reference.
Altium libraries use OLE Compound File Binary (CFB) format:
┌─────────────────────────────────────────────────────────────────────────────┐
│ .PcbLib File Structure │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ OLE Compound File │
│ ├── /FileHeader # Library metadata (ASCII) │
│ ├── /Footprint1/ # Storage for first footprint │
│ │ ├── Data # Binary primitive data │
│ │ └── Parameters # Component parameters (ASCII) │
│ ├── /Footprint2/ │
│ │ ├── Data │
│ │ └── Parameters │
│ └── ... │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
The Data stream contains binary records for each primitive. The diagram above
is a simplification; the full stream inventory and every record's byte layout are
documented in PCBLIB_FORMAT.md and
SCHLIB_FORMAT.md, reverse-engineered from Altium-authored
golden fixtures and prior art (AltiumSharp, python-altium) and enforced at three layers,
each holding the golden's bytes through a different route:
| Layer | Suite | Route |
|---|---|---|
| Library API | tests/golden_fidelity.rs |
PcbLib::open → save, every stream and parameter block; two saves of a library, and a save of our own output, are byte-identical |
| JSON boundary | fidelity_replay in src/mcp/tools/read_write.rs |
read_* → write_* and read_* → update_component, re-reading the server's own output save after save |
| Mutating tools | src/mcp/tools/mutation_fidelity.rs |
each tool on a copy of the golden; every component it was not asked to touch must be byte-identical, and export → import / merge must be too |
See README.md § MCP Tools for the complete tool reference with examples.
See docs/SECURITY.md for the threat model, the concrete controls (path confinement, error sanitisation, rate limiting, bounded decompression), and where each lives in the source.
This is a local tool — no network access required.
| Feature | Network Required |
|---|---|
| Read/write libraries | No |
| Primitive placement | No |
| STEP model attachment | No |