Skip to main content
Glama
md-log-mcp

md-log-mcp

Official
by md-log

md-log-mcp

npm version MCP Registry License: MIT Node

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 (17 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.

Related MCP server: io.github.ymxlx/polis-protocol

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 (17)

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 ![alt](asset://<key>). 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.

edit_markdown

Change PART of a file by exact literal replacement (read → apply → conditional PUT with base_version_no; auto-retries once on conflict, re-applying every edit). Pass several changes at once as edits: [{old_string, new_string, replace_all?}, …] (max 50, applied in order) — they land as one write = one version = one notification; for a single change the old_string/new_string shorthand still works (never both). Each old_string must match exactly once, counting overlapping positions too ("\n\n" inside "\n\n\n" is ambiguous → detail.overlapping: true) — 0 matches or an ambiguous >1 rejects the whole call with VALIDATION (detail.reason = NO_MATCH / AMBIGUOUS_MATCH, detail.edit_index = the failing edit) and nothing is written; set replace_all:true to change every occurrence on purpose. Other detail.reasons: input shape — MIXED_INPUT, MISSING_EDIT, EMPTY_EDITS, TOO_MANY_EDITS, EMPTY_OLD_STRING, IDENTICAL_STRINGS (rejected before any read); result — NO_CHANGE (edits cancel out), DOCUMENT_TOO_LARGE (a step would pass the 25 MiB cap), TOO_MANY_REPLACEMENTS (more occurrences replaced in one call than the document cap allows), BATCH_TOO_SLOW (edits after the first stopped once the call has run 2 s — split them across calls). A match failure on the conflict retry carries detail.after_concurrent_write: true. Never creates a file (missing path → NOT_FOUND) and has no force mode — prefer it over update_markdown for any partial change.

update_markdown

Replace a file's ENTIRE content. Pass expected_version for optimistic concurrency (mismatch → CONFLICT); omit it to force LWW. Passing expected_version for a path that does not exist now returns CONFLICT (detail.server_version_no = 0), not a silent create. For a partial change use edit_markdown instead. Accepts commit_message — a recommended 1-2 line change summary shown in the version history.

restore_version

Roll a file back to an earlier version_no (from list_versions): that version's content becomes a NEW current version — history is immutable, so the rollback is itself undoable. Restoring the version the file is already on is an accepted no-op. Accepts commit_message.

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.

MDLOG_MAX_DOCUMENT_BYTES

no

26214400 (25 MiB)

Client-side pre-flight for the backend's per-document body cap, in UTF-8 bytes (Korean is 3 bytes/char). An over-cap save fails immediately with a VALIDATION error naming the actual size, instead of an opaque backend 400. Applies to both transports. Change only against a self-hosted backend with a different cap.

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

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)

Runs this connector as a local subprocess (needs Node 22+; npx fetches the published package, nothing to build). Use it if you prefer a local process, need local-file (file_path) image uploads, or self-host md-log without a hosted MCP endpoint.

{
  "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.

Remote (Streamable HTTP) mode

The second bin, md-log-mcp-http, serves the same 17 tools over MCP's Streamable HTTP transport — a single POST /mcp endpoint — so agents connect by URL with no local install. Use it when you want to host the connector centrally (a container / small VM behind a TLS reverse proxy) instead of every user running npx.

How it differs from stdio:

  • PAT per request. The token is not read from env; each request carries its own Authorization: Bearer <mdlog_pat_…> header, so one endpoint serves many users — each with their own md-log token. (MDLOG_PAT is ignored in this mode.)

  • Stateless. A fresh client + server per request; no session store (replica / autoscale friendly).

  • No local files. The file_path image source is refused (it would read the server's disk); send images inline as data_base64. Everything else is identical.

Run it

npm run build
MDLOG_API_BASE_URL="https://app.md-log.com/api/v1" \
node dist/http.js            # or: npm run start:http
# → md-log-mcp-http ready — POST http://127.0.0.1:8787/mcp

Configuration (env)

Variable

Required

Default

Notes

MDLOG_API_BASE_URL

yes

—

Hosted md-log base, including /api/v1.

MDLOG_HTTP_HOST

no

127.0.0.1

Bind interface. Localhost-only by default; set 0.0.0.0 only behind a TLS reverse proxy.

MDLOG_HTTP_PORT

no

8787

TCP port.

MDLOG_HTTP_PATH

no

/mcp

The MCP endpoint path.

MDLOG_HTTP_ALLOWED_ORIGINS

no

(none)

Comma-separated browser Origin allowlist (DNS-rebinding defense). A request that carries an Origin not on the list is 403d; non-browser clients (no Origin) are always allowed.

MDLOG_HTTP_ALLOWED_HOSTS

no

(none)

Optional comma-separated Host allowlist (extra DNS-rebinding defense).

MDLOG_HTTP_MAX_BODY_BYTES

no

33554432 (32 MiB)

Max request body (base64 images inflate ~33%).

Security posture (per the MCP spec): binds to 127.0.0.1 by default, requires a Bearer token on every MCP request, validates Origin against the allowlist to defeat DNS-rebinding, and caps the body size. A GET /health liveness probe (no auth) returns {"status":"ok"}. GET/DELETE on the MCP endpoint return 405 (stateless: no standalone SSE stream, no session to terminate).

Connect an agent by URL

{
  "mcpServers": {
    "md-log": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": { "Authorization": "Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Client config shape varies (Claude Code / Cursor / etc.) — the essentials are the endpoint URL and an Authorization: Bearer <PAT> header. Always terminate TLS in front of a public deployment; the PAT rides on every request.

Scripts

  • npm run build — bundle to dist/server.js (stdio) + dist/http.js (Streamable HTTP) (tsup, ESM, Node 22).

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

  • npm run typecheck — tsc --noEmit.

  • npm run smoke — stdio smoke test against a live backend (needs env + a build).

  • npm run smoke:http — backend-free HTTP-transport smoke test (handshake + auth/origin/file_path guards).

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

  • npm run start:http — run the built HTTP server (node dist/http.js).

Available Tools

15 tools
append_to_markdownAppend to MarkdownA

Append content to the end of an existing .md file using optimistic concurrency (GET current -> concat -> PUT with base_version_no). Auto-retries once on conflict, then surfaces CONFLICT.

Inputs: path (required), content (required), commit_message.

create_folderCreate FolderA

Create a folder path, creating every missing parent segment (mkdir -p). Already-existing folders are treated as success.

Inputs: path (required).

delete_folderDelete FolderA

Delete a folder. Requires confirm:true (otherwise VALIDATION). By default only an EMPTY folder is deleted (a non-empty one is refused); pass cascade:true to soft-delete the whole subtree — every subfolder and document under it (like rm -r). Documents are soft-deleted (recoverable), but prefer move_folder/move_markdown when reorganizing.

Inputs: path (required), confirm (required), cascade.

delete_markdownDelete MarkdownA

Soft-delete a .md file. Requires confirm:true (otherwise VALIDATION). Resolves the path to a document key, then DELETE /documents/{key}.

Inputs: path (required), confirm (required).

get_markdownGet MarkdownA

Read a .md file's content by path. Pass version (a version_no from list_versions) to read an OLD immutable version instead of the current one.

Inputs: path (required), version.

list_filesList FilesA

List the documents (and immediate subfolders) inside a folder path. Omit path (or pass '' / '/') to list the ROOT folder.

Inputs: path.

list_foldersList FoldersC

Return the full folder tree.

Inputs: no named parameters.

list_versionsList VersionsA

List a .md file's immutable version history, newest first (version_no, commit_message, author, registered_at, size). Read an old version's content with get_markdown + version.

Inputs: path (required).

move_folderMove FolderA

Move a folder (with its whole subtree: documents, versions, annotations) under a new parent. new_parent_path '' or omitted = move to the root. Parent folders are auto-created. Moving a folder into its own subtree is rejected by the server.

Inputs: path (required), new_parent_path.

move_markdownMove MarkdownA

Move and/or rename a .md file: from_path -> to_path. Destination folders are auto-created (mkdir -p). The document KEEPS its identity (same document key), so its whole version history and reviewers' annotations survive the move — never re-save + delete to relocate a file. Fails if a different file already occupies to_path.

Inputs: to_path (required), from_path (required).

rename_folderRename FolderA

Rename a folder in place (descendant paths are rewritten automatically; documents, versions and annotations are untouched).

Inputs: path (required), new_name (required).

save_markdownSave MarkdownA

Save (create or overwrite) a .md file in md-log by path; missing folders are auto-created. Optionally upload embedded images as assets first and rewrite their refs to asset:// links. This is a force-write (last-writer-wins) — the headline agent tool.

Inputs: path (required), content (required), assets, commit_message.

search_markdownSearch MarkdownA

Search documents by TITLE (substring) and BODY (full-text over current versions; whole-word match, ranked, body hits carry a bolded snippet). Use it to find a prior report by its content or name.

Inputs: query (required).

update_markdownUpdate MarkdownA

Replace the content of an existing .md file. Pass expected_version for optimistic concurrency (mismatch -> CONFLICT); omit it to force last-writer-wins.

Inputs: path (required), content (required), commit_message, expected_version.

upload_assetUpload AssetA

Upload a single image as an asset (reserve -> presigned PUT -> complete) and return an 'asset://' reference you can embed in markdown image syntax: alt. Provide the image as EITHER data_base64 (inline base64) OR file_path (a local file to read) — exactly one.

Inputs: path (required), filename, file_path, data_base64, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct operation: content manipulation, folder management, listing, search, asset upload, and concurrency control. No overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., save_markdown, delete_folder, list_versions).

    Tool Count5/5

    15 tools cover the domain comprehensively without bloat. Each tool serves a clear need for managing markdown files and folders with versioning.

    Completeness4/5

    Covers full CRUD for documents and folders, plus listing, search, version history, assets, and concurrency. Minor gaps: no explicit tool to restore a previous version, but that can be done via get_markdown (old version) and save_markdown.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that logs AI-assisted scientific computing sessions, capturing prompts, responses, decisions, and environment snapshots to human-readable markdown files for reproducibility.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      This MCP server provides a local-first control plane for coding agents, enabling task routing, contract management, and shared learning across multiple AI vendors via markdown files.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that lets multiple AI coding agents share state, preserve context across sessions, and coordinate via a knowledge graph, messaging, and branch-preserving checkpoint/resume with conflict handling.
      57 npm
      1
      Apache 2.0