Mermy

Mermy is a SwiftUI macOS app plus local MCP server for opening Mermaid diagrams from Codex.

Build

xcodegen generate
open Mermy.xcodeproj

The YAML project definition is in project.yml. Generate the Xcode project with XcodeGen, then build and run the Mermy app target in Xcode. The app targets macOS 26.0 and should be built with the macOS 26 SDK.

For a command-line build, use Xcode directly:

xcodebuild -project Mermy.xcodeproj -scheme Mermy -configuration Release build
xcodebuild -project Mermy.xcodeproj -scheme MermyMCP -configuration Release build

The app uses the SwiftUI lifecycle and SwiftUI window content. WebKit is bridged through NSViewRepresentable for Mermaid rendering, while editor and viewer controls stay native SwiftUI controls. Launching the app normally opens an editable diagram window. Use the sidebar button to toggle the editor. Edits are validated with Mermaid automatically; valid input repaints the diagram, invalid input leaves the last valid render visible. Mermy can also open Mermaid .mmd files from Finder, from File > Open MMD, or by dragging files onto the app icon. The app declares .mmd as its Mermaid Diagram document type, so built apps register with Launch Services during build/run.

The app icon lives in Resources/AppIcon.icon, the macOS 26 Icon Composer bundle format. It is checked in and compiled by Xcode with the app target; there are no custom icon generation scripts.

Releases and Updates

Mermy uses Sparkle for in-app updates. The appcast URL is:

https://github.com/coryoso/Mermy/releases/latest/download/appcast.xml

Publishing a GitHub Release with a semantic version tag, such as v0.1.1, runs .github/workflows/release.yml. The workflow builds the app on macos-26, signs it with a Developer ID Application certificate, notarizes and staples the app, packages Mermy-<version>.zip, generates a signed Sparkle appcast.xml, and uploads both files back to the release.

Configure these repository secrets before publishing the first release:

• APPLE_CERTIFICATE_BASE64: base64-encoded Developer ID Application .p12.
• APPLE_CERTIFICATE_PASSWORD: password for that .p12.
• APPLE_ID: Apple ID used with notarytool.
• APPLE_APP_SPECIFIC_PASSWORD: app-specific password for notarization.
• APPLE_TEAM_ID: Apple developer team ID.
• SPARKLE_PRIVATE_KEY: private EdDSA key produced by Sparkle's generate_keys.

Configure SPARKLE_PUBLIC_KEY as a repository variable, or as a secret if preferred. Local builds leave the public key empty, which disables the update menu item without affecting development builds.

GitHub's generated release notes are grouped by the labels in .github/release.yml. Pull requests are labeled automatically by .github/workflows/label-pr.yml from branch prefixes: feat/, fix/, docs/, chore/, build/, or ci/. PR titles should stay human-readable because GitHub uses them as release-note entries.

MCP Tool

The MCP server exposes show_mermaid:

{
  "definition": "flowchart LR\n  A --> B",
  "title": "Example"
}

Each call opens a new Mermy window. Two-finger scrolling pans the canvas. Trackpad pinch zooms around the pointer, and the SVG is repainted at the active zoom level so text and lines stay sharp.

Codex should point at bin/mermy-mcp. The wrapper gives Codex a stable executable path and uses xcodegen/xcodebuild directly when the Xcode products are missing or stale.