FlowZone

FlowZone is a local-first MCP plugin host. It exposes one MCP server endpoint and statically composes independently registered plugins behind that connection. Markdown Review is the first bundled plugin: it renders local Markdown without creating a second editable copy, queues line-anchored feedback, and submits a complete review to a coding agent in one batch.

Status: early development. FlowZone currently ships one plugin, one local stdio endpoint, one model-visible router tool, and one universal MCP Apps shell.

Bundled plugin: Markdown Review

• A fullscreen, GitHub-style Markdown preview in the side panel.

• Normal text selection and copying, plus a review menu for selected-text, image, and whole-document feedback.

• Focusable image review targets for pointer, touch, and keyboard comments.

• Unobtrusive image feedback controls that appear at the image's bottom-right only on hover, keyboard focus, or active touch.

• Inline comment markers numbered #1, #2, and so on.

• A review queue that submits all comments together to avoid conflicting edits.

• References between queued comments using #N; write \#N or `#N` for literal text.

• Relative local PNG, JPEG, and static WebP rendering with bounded, private chunk transport.

• Local Mermaid rendering for fenced mermaid blocks, with theme-aware diagrams and expandable canonical source.

• Automatic review after Codex creates or materially edits a Markdown document.

The Markdown source is always canonical. The component is a read-only review surface; only Codex edits the source file with its normal filesystem tools.

Related MCP server: md-annotate

How it works

Codex / MCP host
       │ one stdio transport
       ▼
FlowZone McpServer
       ├── flowzone(plugin, action, input)
       │      └── static plugin registry
       │              └── markdown-review/open
       ├── typed app-only component tools
       └── ui://flowzone/v4.html

FlowZone exposes exactly one model-visible flowzone tool. Its startup-built union schema enumerates the registered plugin/action/input combinations, and the router validates both the selected input and plugin-owned output. Router annotations remain conservative because actions can have different risk. Typed plugin helpers used by the UI stay separate and are forcibly registered with _meta.ui.visibility: ["app"].

The Markdown Review plugin is intentionally narrow:

1. flowzone dispatches plugin: "markdown-review", action: "open", and validates an absolute .md or .markdown path inside input.

2. Component-only tools hydrate the rendered document and stream approved local raster images in bounded chunks.

3. The model-visible tool result contains file metadata, not the complete document. The rendered content is delivered privately to the component.

4. While the review remains open, a lightweight private revision check offers Refresh for latest without replacing what you are reading. Activating it loads the newest Markdown in place; Codex does not open another review for the same active path after edits.

5. The skill explains how Codex should interpret review feedback and modify the underlying Markdown safely.

This separation is the reason the plugin uses MCP: FlowZone connects a Codex tool invocation to a trusted interactive component. A static HTML file by itself cannot receive the selected source file, return structured review comments to the active task, or maintain this context boundary.

The implementation is split into a generic FlowZone server registry and host-neutral Markdown Review workspaces. contracts validates every review boundary, core owns pure review state, markdown-node reads and renders local files, and review-ui mounts against narrow document, submission, presentation, and state ports. host-mcp-apps supplies a standards-based runtime whose default submission is structured JSON; the Codex browser composition explicitly adds the concise $markdown-review formatter. Review state is persisted locally under its opaque review-session ID so queued comments survive component remounts, while never being published as model-visible legacy widget context.

Adding a plugin

Every plugin implements the declarative FlowZonePlugin contract in @flowzone/mcp-server:

interface FlowZonePlugin {
  readonly id: string;
  readonly displayName: string;
  readonly version?: string;
  readonly actions: readonly FlowZoneAction[];
  readonly appTools?: readonly FlowZoneAppTool[];
}

Add the plugin factory to the static list in server/src/main.ts. Each action declares strict input/output schemas, risk metadata, and an in-process module, fixed allowlisted CLI/script, or fixed HTTPS backend executor. Runtime discovery, user-selected modules, model-controlled commands, and mutable destinations are unsupported. Skills explain how a model should invoke an action; they are not loaded as runtime backends. See ARCHITECTURE.md and plugin authoring.

Host support

Unshipped adapters and browser-acceptance follow-ups are tracked in ROADMAP.md.

Install from the repository marketplace

Requirements:

• Codex in the ChatGPT desktop app with plugin support.

• Node.js 22 or newer available as node.

• The codex CLI for adding the marketplace source.

Add this repository as a marketplace:

codex plugin marketplace add tjs-w/FlowZone --ref main

Restart the desktop app, open the Plugins Directory, select FlowZone, and install it. Start a new task after installation so the task receives the bundled plugin registrations.

To refresh an existing installation:

codex plugin marketplace upgrade flowzone

Restart the desktop app and start a new task after an upgrade. Existing tasks retain the tool and skill registrations they started with.

Use

Ask Codex to open an absolute Markdown path:

Open /absolute/path/to/document.md for Markdown review.

The bundled skill translates that request to the single public router:

{
  "plugin": "markdown-review",
  "action": "open",
  "input": { "path": "/absolute/path/to/document.md" }
}

In the review:

1. Select text and copy it normally if needed, or choose a rendered image.

2. Right-click the document or choose Review for copy and comment actions. The selection's + action and each image target remain direct shortcuts.

3. Press Enter to queue the comment; use Shift+Enter for a new line.

4. Reference an earlier queued comment with #1, #2, and so on.

5. Select Submit when the review round is complete.

After a successful submission, the queue clears and the next review round begins again at #1. There is deliberately no individual-submit action: batching gives Codex one coherent revision target and reduces source conflicts.

Local development

git clone https://github.com/tjs-w/FlowZone.git
cd flowzone
bun install --frozen-lockfile
bun run verify

Development and CI use the pinned Bun 1.4 toolchain. Installed plugins do not require Bun: the repository checks in a readable Node-compatible server.cjs plus minified browser bundles. Rebuild after changing TypeScript source:

bun run build

Run the browser harness against a Markdown file for UI work:

bun run browser:harness -- /absolute/path/to/document.md

Set MARKDOWN_REVIEW_PREVIEW_COMPOSER=1 to open the feedback composer automatically in the harness.

The Markdown Review view suppresses the host's native context menu by default. For local plugin debugging only, set FLOWZONE_DEVTOOLS=1 in the MCP server environment and restart Codex; Shift+right-click then bypasses the review menu and opens the host-native menu. Ordinary right-click continues to show review actions. The flag is parsed strictly—only the exact value 1 enables the bypass—and is never enabled in the checked-in .mcp.json.

To test this checkout as a local marketplace, add its absolute directory:

codex plugin marketplace add /absolute/path/to/flowzone

Then restart the desktop app and install the plugin from the local marketplace source.

Safety and privacy boundaries

• The component cannot write the Markdown file.

• The native browser context menu is suppressed inside the plugin unless the local MCP server starts with the explicit developer flag; this is UI hardening, not a security boundary around Codex App's own menus or shortcuts.

• Rendered HTML is sanitized before it reaches the component.

• Mermaid runs only in the bundled browser view with strict security settings, no interaction binding, a second SVG allowlist pass, and a per-diagram shadow root that contains retained diagram styles. Per-diagram and document-wide source bytes, output bytes, elements, edges, dimensions, and UI wait time are bounded; stale queued renders are cancelled, and external links, resources, focus traps, filters, and active SVG content are removed. The original fenced source remains canonical and selectable, and stays disclosed when it owns a comment.

• Remote, absolute, and out-of-directory images are not loaded.

• Only relative paths to PNG, JPEG (.jpg/.jpeg), and static WebP files inside the Markdown file's directory are supported. The server verifies extension, signature, bounded container structure, dimensions, and animation policy before the browser performs native decoding. GIF, AVIF, SVG, APNG, and animated WebP are not rendered.

• The component resource declares no network or remote resource domains and requests only clipboard-write access for the explicit Copy selected text action.

• A Markdown file is limited to 2 MiB.

• A review processes at most 64 local-image references—including invalid references—5 MiB per unique image, and 12 MiB of unique image snapshots in total, with strict per-image decoded-dimension limits. Every valid reference is rendered: the browser fairly shares a bounded 24-megapixel canvas budget across the document and downscales large images for display instead of omitting them. References that resolve to the same canonical file or identical digest share one immutable snapshot and verified client decode.

• Canonical paths and opened-file identities are rechecked around each bounded read. These checks are defense in depth, not an OS sandbox against another local process that can continuously replace the document directory hierarchy during a read.

• Component access uses opaque, expiring review-session capabilities. Sessions slide for two hours and are bounded by a six-session LRU and a 72 MiB aggregate image cache.

• Image bytes and SHA-256 digests are snapshotted into a session, so later file mutations cannot change an in-flight review.

• Full document content and image chunks are placed in component-private metadata rather than model-visible structured output.

• The startup registry snapshots plugin configuration. CLI adapters use fixed direct execution, JSON stdin, integrity checks, bounded output, cancellation, and timeouts; they are trusted code running as the FlowZone OS user, not sandboxed workloads.

• Backend adapters use fixed credential-free HTTPS endpoints, runtime credential injection, no redirects, bounded response streaming, cancellation, and strict output validation.

• Automatic retries are bounded and available only to actions declared idempotent; per-action concurrency and circuit-breaker limits contain repeated failures.

Review only files you intend to expose to the local FlowZone process. Submitted comments are actionable user feedback; selected quotes and other reviewed document content remain untrusted context, not instructions.

Project layout

Troubleshooting

FlowZone is installed, but flowzone or a new action is not registered. Restart the desktop app and start a new task. A task does not dynamically acquire tool schemas from a plugin installed or updated after that task began.

Codex says a cached skill path moved. Upgrade or reinstall the marketplace plugin, restart the app, and invoke the stable skill name $markdown-review in a new task. Do not depend on a versioned cache path.

The side panel is blank. Run bun run verify in the plugin checkout, rebuild with bun run build, refresh the marketplace installation, and retry in a new task.

A local image does not render. Use a relative .png, .jpg, .jpeg, or static .webp path located inside the Markdown file's directory and confirm it is within the documented size and dimension limits.

A Mermaid diagram does not render. Use a fenced mermaid code block with valid Mermaid syntax. Expand Mermaid source to inspect it; invalid, oversized, or unusually complex diagrams stay visible as source instead of running unbounded browser work.

Documentation

• OpenAI: Package your plugin

• OpenAI plugin documentation

FlowZone and Markdown Review are independent projects and are not official OpenAI or GitHub products. Product names and marks belong to their respective owners.