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.

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).

Tool	What it does
save_markdown ⭐	The headline tool. Create or overwrite a .md by path (force last-writer-wins); missing folders auto-created. Optionally uploads embedded images first (each given as data_base64 or a local file_path) and rewrites each placeholder in the content to an asset://<key> link. Accepts commit_message — a recommended 1-2 line change summary shown in the version history.
upload_asset	Upload one image (reserve → presigned PUT → complete) and return an asset://<key> reference to embed as . Provide the image as either data_base64 (inline base64) or file_path (a local file the server reads) — exactly one; with file_path, filename defaults to the basename and content_type is inferred from the extension (png/jpg/jpeg/gif/webp/avif).
append_to_markdown	Append to an existing file with optimistic concurrency (GET current → concat → conditional PUT with base_version_no). Auto-retries once on conflict, then surfaces CONFLICT. Accepts commit_message — a recommended 1-2 line change summary shown in the version history.
update_markdown	Replace a file's content. Pass expected_version for optimistic concurrency (mismatch → CONFLICT); omit it to force LWW. Accepts commit_message — a recommended 1-2 line change summary shown in the version history.
get_markdown	Read a file's content by path (materializes inline content or a presigned content URL for large docs). Pass version (a version_no from list_versions) to read an old immutable version.
list_versions	List a file's immutable version history, newest first (version_no, commit_message, author, registered_at, size).
delete_markdown	Soft-delete a file. Requires confirm:true (otherwise VALIDATION); resolves the path to a document key first.
create_folder	mkdir -p — create every missing segment; already-existing folders count as success.
list_folders	Return the full folder tree.
list_files	List the documents and immediate subfolders inside a folder path.
search_markdown	Search by TITLE (substring) + BODY full-text (current versions; whole-word match, ranked, body hits include a snippet).
move_markdown	Move and/or rename a .md by path (from_path → to_path); destination folders auto-created; the document KEEPS its key, so version history and reviewers' annotations survive.
move_folder	Move a folder (whole subtree) under a new parent (new_parent_path empty/omitted = root); parent auto-created; cyclic moves rejected server-side.
rename_folder	Rename a folder in place (descendant paths rewritten server-side).
delete_folder	Delete a folder. Requires confirm:true; by default only an EMPTY folder is deleted — pass cascade:true to soft-delete the whole subtree (rm -r).

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.

Variable	Required	Example	Notes
MDLOG_API_BASE_URL	yes	https://app.md-log.com/api/v1	The hosted service base, including /api/v1. No version suffix is appended; a trailing slash is stripped.
MDLOG_PAT	yes	mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx	Bearer PAT. Store it securely (OS keychain) — never commit it.

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).