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 stdio Model Context Protocol server 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 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) — McpServer + StdioServerTransport.

• stdio transport — JSON-RPC over stdin/stdout (so stdout is reserved for the protocol; logs go to stderr).

• TypeScript, bundled with tsup to ESM dist/server.js. Runtime deps: the MCP SDK and zod (input schemas). Node's built-in fetch is the only HTTP layer.

• PAT auth — a long-lived md-log Personal Access Token sent as Authorization: Bearer.

Related MCP server: kontexta

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

MCP client config

📄 연결 가이드 (HTML) — md-log.com/guides/customer-guide.html: md-log 웹 앱에서 발급받은 MCP 키(PAT) 와 고정 서비스 주소(https://app.md-log.com/api/v1)만으로 npx 연결 (Claude Code · Desktop · Codex · Cursor). 빌드·레포 불필요.

Mint the PAT in the web app's Settings → Tokens, store it securely, then add the server to your ~/.claude.json (user-scoped) or a project-local .mcp.json. No install or build step — npx fetches the published package. Never commit a PAT.

{
  "mcpServers": {
    "md-log": {
      "command": "npx",
      "args": ["-y", "md-log-mcp"],
      "env": {
        "MDLOG_API_BASE_URL": "https://app.md-log.com/api/v1",
        "MDLOG_PAT": "mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Mint & secure the PAT. Create it in the web Settings → Tokens (it is shown only once) and keep it out of version control — prefer the OS keychain. On macOS, for example:

security add-generic-password -a "$USER" -s md-log-pat -w "mdlog_pat_xxxx"
export MDLOG_PAT="$(security find-generic-password -a "$USER" -s md-log-pat -w)"

If a PAT leaks, revoke it in the web app and mint a new one.

Scripts

• npm run build — bundle to dist/server.js (tsup, ESM, Node 22).

• npm run dev — rebuild on change (tsup --watch).

• npm run typecheck — tsc --noEmit.

• npm run smoke — run the smoke test (needs env + a build).

• npm start — run the built server directly (node dist/server.js).