Codex Visio Replica

Public Beta — v0.3.0-beta.2 · Windows only

Codex Visio Replica is a local-first toolkit for rebuilding a supplied reference image as editable Microsoft Visio shapes. It combines two Model Context Protocol (MCP) servers, Visio COM/ShapeSheet rendering, a reusable Codex Skill, resumable large-Scene execution, and measurable visual QA.

This is an unofficial community project and is not affiliated with, endorsed by, or sponsored by Microsoft or OpenAI.

Architecture

flowchart LR
    A["User-provided reference image"] --> B["visual-qa MCP"]
    B --> C["Validated Scene JSON"]
    C --> D["visio-com MCP"]
    D --> E["Editable Visio document"]
    E --> F["Local export"]
    F --> B
    G["visio-image-replica Skill"] --> B
    G --> C
    G --> D

All image analysis and QA run locally. Visio drawing state is owned by a server-created COM session on a single STA worker.

Features

• Editable shapes, text, connectors, groups, layers, and ShapeSheet cells.
• A JSON Schema-backed Scene contract with explicit coordinates and styles.
• Local-only image probing, bbox measurement, edge metrics, SSIM, pixel error, overlays, and difference heatmaps.
• Transactional rendering with overwrite disabled by default.
• Resumable, dependency-aware chunked rendering for large Scenes.
• A reusable visio-image-replica Skill with structural-first acceptance gates.
• Deterministic synthetic examples that contain no user or research data.

Requirements

• Windows 10 or Windows 11 x64.
• Microsoft Visio desktop, installed and licensed separately by the user.
• CPython 3.11 or 3.12 x64.
• uv.
• Codex with MCP and Skill support.
• GitHub CLI is required only for release maintainers.

This project does not distribute Visio, Codex, Microsoft binaries, fonts, or commercial stencils.

Installation

Review INSTALL.md, then run a no-change preflight:

.\installer\install.ps1 -DryRun

After reviewing the JSON result, install without elevation:

.\installer\install.ps1

The installer refuses to overwrite an existing installation, backs up affected Codex configuration, rolls back on failure, and performs MCP and Skill checks.

Quick start

1. Place a reference image inside the configured workspace input directory.
2. Start a Codex task from the installed project root.
3. Invoke $visio-image-replica and request an editable VSDX.
4. Review unresolved text, fonts, structure, and QA metrics before delivery.

The Skill never treats an embedded page-sized bitmap as an editable reconstruction.

Examples

• examples/simple-flowchart: generic start/process/decision flowchart.
• examples/synthetic-gnn-diagram: invented nodes and message-passing blocks.

Each example includes generation code, a Scene, a deterministic preview PNG, and regeneration instructions. No third-party logo, institution, paper layout, or real dataset is used.

MCP architecture

visual-qa-mcp owns local raster inspection and measurable comparisons. visio-com-mcp owns server-created Visio sessions and editable document state. Both enforce workspace allowlists, reject unsafe file types, and expose annotated MCP tools over STDIO.

Skill workflow

The Skill runs preflight, reference analysis, Scene validation, Visio rendering, structural QA, connector QA, visual QA, evidence-based iteration, font checks, and guarded packaging. Structure and editability take precedence over one image similarity score.

Large Scene rendering

Large Scenes use dependency planning, bounded batches, checkpoints, and resume-validation. A timed-out monolithic render is not retried unchanged. Completed batches are preserved only when Scene, document, version, and shape identity evidence remains consistent.

QA metrics

The public API includes bbox errors, text/type checks, connector endpoints and Glue semantics, Edge F1/IoU, SSIM, pixel MAE/RMSE, and generated overlays. These metrics are evidence, not a guarantee of pixel-perfect reconstruction.

Security model

• Windows-only COM control on one STA worker.
• Only Visio.Application is allowed; macro-enabled VSDM and arbitrary ProgIDs are rejected.
• User paths must stay inside configured roots.
• Overwrite is opt-in and never the default.
• The server tracks and cleans up only processes and documents it owns.
• Reference images, generated diagrams, logs, and credentials are excluded from source control.

See SECURITY.md and docs/security-audit.md.

Limitations

• Requires locally installed Microsoft Visio; macOS and Linux cannot run the Visio COM server.
• Does not guarantee absolute pixel identity or reliable recovery of illegible text.
• Complex freeforms, routing, fonts, and antialiasing can require iteration.
• Real Visio integration tests run only in a maintainer-controlled local Windows+Visio environment, not on public GitHub-hosted runners.

Roadmap

• Harden rollback and repair telemetry.
• Expand synthetic Scene coverage.
• Improve connector and freeform diagnostics.
• Add reproducible package signing when a public signing identity is available.

Contributing

Read CONTRIBUTING.md. Do not attach private diagrams, credentials, or customer data to public issues.

License and trademarks

Source code is licensed under Apache-2.0. Dependency notices are in THIRD_PARTY_NOTICES.md.

Microsoft, Microsoft Visio, Windows, OpenAI, Codex, GitHub and related marks are trademarks of their respective owners. Their names are used only to describe interoperability and requirements.