Moving from v1 to v2
Choose documentation by the actual MCP interface and product release. This guide targets 2.0.0, desktop build 55. Signed v1.11.0 → v2 migration passed in the macOS 14.6.1 Apple silicon/Glyphs 4.1.1/build 4108 test environment; live Glyphs 3 coexistence remains unverified. Sidecar and bridge product versions are 2.0.0; lean interface revision and bridge protocol are independently 1. See version and identity and qualification.
| Area | v1 · 1.11.0 | v2 · 2.0.0 |
|---|---|---|
| Distribution | Released compatibility payload; retained for Glyphs 3. | Signed and notarized 2.0.0/build 55 for Glyphs 4. |
| Server | MCP runs in the legacy Glyphs plugin. | MCP runs externally; a small native bridge handles live access. |
| Tools | The v1 command catalog. | Twenty-two tools (including optional card display) and up to thirteen capability-gated job kinds. |
| Installation | Legacy dependency setup. | One Setup page with inline cards, a serialized queue and a private sidecar runtime. |
| Review | Legacy tool-specific review flows. | Prepare a job, inspect its report, apply it, review in Glyphs. |
| Acceptance | Follow each v1 workflow, including legacy save_font where documented. | accept_job performs verified whole-document saving; native Undo/Redo and whole-job discard remain available before acceptance. |
| Inspectors | Legacy integration. | Independent optional Curve and Reference Inspectors. |
Upgrade steps
- Finish current work and save accepted edits. Quit Glyphs normally.
- Install v2 for Glyphs 4 from Setup. Existing components and preferences are preserved; component and connector removal is explicit.
- Reopen Glyphs and check Edit → Glyphs MCP Server….
- Refresh the client's connection and use the matching v2 skills. Confirm the twenty-two tools with the tool reference.
- Try the first session on a disposable font.
The usual v2 client URL stays http://127.0.0.1:9680/mcp/ unless you changed it. For a separate v1 connection, configure v1 on another free loopback port and keep each catalog and document ID separate. Two servers cannot share a port. Glyphs 3 and Glyphs 4 can share a display name; identify them by com.GeorgSeifert.Glyphs3 and com.GeorgSeifert.Glyphs4. This does not create independent installations of two lean v2 builds.
Workflow differences
V1 calls such as list_open_fonts do not carry over. Discover the intended font once with list_documents, retain its connection-specific document_id, and reuse it for fresh v2 reads. Rediscover after document_not_found, a known Glyphs/bridge restart or an explicit target change; never silently substitute another font. V2 exposes native Python through python_script and script.native.v1 in the existing conversation workflow. It uses a detached pre-run copy and session-local whole-font restoration, without selective script Undo. Original task authorization permits Run without a separate source review; explicit previews wait. Generic export selectors, dedicated master replacement, Unicode allocation and a complete optical-italic engine remain outside the typed jobs. Keep native compilation/export jobs for their diagnostics.
V2 does not import or delegate to the legacy save_font implementation.
accept_job and save_document share a new coordinator around the direct
native document selector, reject overwriting Save As destinations and return
source-hash receipts. Git diff and commit remain outside Glyphs MCP.
Spacing preparation and reference comparison use an absolute 0.001 font-unit tolerance. That tolerance does not weaken exact application, rollback, native history, topology or source-hash checks.
V1 documentation remains available at its existing URLs. It is preserved from the v1.11.0 release, including historical workflows and contributor notes; those pages do not describe the v2 tool surface.