MarkdownMCP

Live markdown preview for LLM agents. The agent calls one tool when a markdown file comes into scope; a shared hub watches the file, opens your OS default browser (managed profile) on the first create/change, and streams updates into a multi-tab Vue UI (unread dots, toggleable change marks, history).

Features

• One MCP tool: scope_markdown — call once before the first write (path may not exist yet)

• Singleton hub shared by all MCP clients; exits when no clients remain

• Sticky high port — hub reuses a preferred port from settings.json so preview tabs reconnect after restarts

• Managed browser profile — system default browser with an isolated profile under the app data dir; left open when the hub exits

• Reconnect-first — does not spawn a new window if a managed browser session is already running

• In-app tabs with subtle unread indicators

• Toggleable change highlights + snapshot history

• First-run settings (theme, bind host, preferred port, allowed path roots)

• Cross-platform (Windows, macOS, Linux)

Related MCP server: MCP Docs Server

Quick install (Grok)

From this repo (after build), or once published:

# From monorepo root
npm install
npm run build

# User-level MCP (Grok)
grok mcp add markdown-mcp -- node /absolute/path/to/live-markdown-mcp/packages/mcp/dist/cli.js

Or with a global/workspace link:

npm link -w markdown-mcp
grok mcp add markdown-mcp -- markdown-mcp

~/.grok/config.toml equivalent:

[mcp_servers.markdown-mcp]
command = "node"
args = ["/absolute/path/to/live-markdown-mcp/packages/mcp/dist/cli.js"]
enabled = true
startup_timeout_sec = 60

Copy the skill so the model knows when to call the tool:

# Windows PowerShell
Copy-Item -Recurse .grok/skills/markdown-scope $HOME/.grok/skills/markdown-scope

Other clients

Claude Code

claude mcp add markdown-mcp -- node /absolute/path/to/live-markdown-mcp/packages/mcp/dist/cli.js

Or project .mcp.json:

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/live-markdown-mcp/packages/mcp/dist/cli.js"]
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "markdown-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/live-markdown-mcp/packages/mcp/dist/cli.js"]
    }
  }
}

Agent usage

1. Decide you will create or edit a markdown doc the user should see rendered.
2. Call scope_markdown once with the path (absolute preferred).
3. Write/edit the file freely — do not call the tool again for edits.

Tool:

Architecture

MCP client(s)  --stdio-->  markdown-mcp bridge
                              |
                              +--> ensure hub up (singleton)
                              +--> register client
                              +--> scope_markdown → hub API

Hub  --chokidar--> disk
Hub  --WebSocket--> Vue UI (tabs, diffs, history)
Hub  --spawn--> system default browser + managed profile (first file event, if none running)

State lives under:

Development

npm install
npm run build
npm run start:hub          # hub only (stays up until Ctrl+C; no MCP client timeout if you register manually)
npm run start:mcp          # MCP stdio server (spawns hub as needed)
npm run dev:web            # Vite UI against a hub on :7420 (optional proxy)
npm run test:unit          # shared + hub unit tests
npm run test:local         # unit + sticky-port + browser policy + default-browser
npm run test:sticky-port   # sticky port integration (uses real app data dir)
npm run test:default-browser  # OS default product → binary (skips if browser missing)

Install-dependent checks (Brave/Chrome/Edge/Firefox present on disk, OS default detection) skip with a clear message when the browser is not installed — they do not fail CI machines without that browser.

Packages:

Settings

First browser open shows a short wizard. Later: Settings in the UI.

Changing bind host or preferred port requires a hub restart. Non-loopback binds ask for confirmation.

Sticky port & browser profile

1. On first start (or empty preferred port), the hub binds a free high port and writes it to settings.json as preferredPort.

2. Later starts try that port first. If it is taken, the hub picks another free high port and updates preferredPort.

3. On the first scoped file create/change (when enabled), the hub launches the system default browser with a dedicated profile under browser-profile/. Common engines are supported (Chrome/Edge/Brave/Chromium via --user-data-dir, Firefox via -profile). Safari and unknown browsers fall back to a normal URL open with limited isolation.

4. If a managed browser session is already running, the hub does not open another window (the open tab reconnects over WebSocket).

5. Stopping the hub does not close the browser.

Troubleshooting

License

MIT