md-log-mcp

Review the report, not the diff. An MCP server that lets your AI coding agent — Claude Code, Claude Desktop, Codex, Cursor — save its work and analysis as immutable, versioned Markdown reports into md-log, a human-in-the-loop review & archive layer for "vibe coding." You then read and stylus-annotate (S-Pen / Apple Pencil) those reports on web, phone, and tablet — every save a new immutable version.

A Model Context Protocol server — two transports, one tool set — that lets Claude Code (and other agents) save .md files — text and embedded screenshots together — straight into md-log, a human-in-the-loop review & archive layer for vibe coding. The recommended way to connect is the hosted remote endpoint (https://mcp.md-log.com/mcp, a URL + your key — no install); a local stdio (npx -y md-log-mcp) transport is the alternative. The agent writes a report by path (my-project/2026-07-07-error-report.md); missing folders are auto-created, images are uploaded and their references rewritten to asset:// links, and every save becomes an immutable new version. The same report is then readable, editable, and stylus-annotatable (S-Pen / Apple Pencil where supported) on a phone or tablet, and on the web.

md-log is a hosted service at https://app.md-log.com — you don't run any server yourself. This package is just the connector: a thin authenticated HTTP client that validates POSIX paths, orchestrates asset uploads, maps errors to stable agent codes, and forwards everything to the hosted md-log service — the single authority for auth, storage, versioning and quota. All you need is a Personal Access Token from the web app.

Stack

• @modelcontextprotocol/sdk (TypeScript) — one McpServer (15 tools), two transports.
• stdio transport (md-log-mcp) — JSON-RPC over stdin/stdout; the default local mode (so stdout is reserved for the protocol; logs go to stderr). PAT from env.
• Streamable HTTP transport (md-log-mcp-http) — the remote mode: agents connect by URL with no local install; the PAT is taken per request from the Authorization header. See Remote (Streamable HTTP) mode.
• TypeScript, bundled with tsup to ESM dist/server.js (stdio) + dist/http.js (HTTP). Runtime deps: the MCP SDK and zod (input schemas). Node's built-in fetch/http are the only network layers — no web framework.
• PAT auth — a md-log Personal Access Token sent to the backend as Authorization: Bearer.

Requirements

• Node 22+
• A Personal Access Token (PAT) minted in the md-log web app (Settings → Tokens; shown once)

That's it — the md-log service itself is hosted at https://app.md-log.com; there is nothing to install or self-host.

Tools (15)

Every tool returns dual output — a human-readable content[].text and a machine-readable structuredContent — and validates the POSIX path (NFC-normalize; reject ../., control chars, empty/whitespace segments, backslashes, reserved names; enforce 255-byte name / 1024-byte path limits; require .md for files) before any backend call. All requests hit the base URL in MDLOG_API_BASE_URL (which already includes /api/v1).

Error codes surfaced to the agent

Backend failures return { isError: true, content:[{type:"text", ...}] } with a mapped code in structuredContent.error.code:

NOT_FOUND · CONFLICT (carries the server head {server_version_no, server_checksum, …} in detail) · UNAUTHORIZED · RATE_LIMITED · QUOTA_EXCEEDED · BACKEND_UNAVAILABLE · VALIDATION · FOLDER_EXISTS (swallowed as success by create_folder) · ERROR.

Authentication

The MCP/PC lane authenticates with a Personal Access Token (mdlog_pat_…) — minted once in the web app's Settings and supplied via env. The client attaches it as Authorization: Bearer <PAT> (plus X-API-Token for compatibility) on every request. The backend is the single source of truth for auth and quota.

The server fails fast at startup with a clear message if either var is missing or the base URL is malformed.

Build

npm install
npm run build      # tsup → dist/server.js (ESM, Node 22)
npm run typecheck  # tsc --noEmit (optional)

Smoke test

scripts/smoke.mjs spawns the built server over stdio (MCP SDK Client + StdioClientTransport), then runs initialize → tools/list → save_markdown (a small report embedding a tiny data: PNG) → get_markdown (reads it back, checks the marker) → search_markdown — printing PASS/FAIL per step and exiting non-zero on any failure. Run it against a live backend with a real PAT:

npm run build
MDLOG_API_BASE_URL="http://localhost:8080/api/v1" \
MDLOG_PAT="mdlog_pat_xxxx" \
node scripts/smoke.mjs        # or: npm run smoke

Connect a client

Mint the PAT in the web app's Settings → Tokens, store it securely, then add md-log to your MCP client. Never commit a PAT.

📄 연결 가이드 (HTML) — md-log.com/guides/customer-guide.html: 웹 앱에서 발급받은 MCP 키(PAT) 로 URL 연결(권장) 또는 npx 로컬 연결 (Claude Code · Desktop · Codex · Cursor).

Recommended — remote (URL), no install

Point your client at the hosted endpoint and pass the PAT as a Bearer header. Nothing to install — no Node.js, no npx. (You don't even need this package for the hosted connection.)

# Claude Code
claude mcp add --transport http md-log https://mcp.md-log.com/mcp \
  --header "Authorization: Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx"

// Cursor / Claude Desktop / any client that takes JSON — the `type` field MUST be "http"
{
  "mcpServers": {
    "md-log": {
      "type": "http",
      "url": "https://mcp.md-log.com/mcp",
      "headers": { "Authorization": "Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Over the remote endpoint, embed images inline (base64); uploading a local image by path (file_path) works only with the local method below.

Alternative — local (stdio via npx)