md-log-mcp

md-log-mcp

审阅报告，而非差异。 MCP 服务可让你的 AI 编码 Agent — Claude Code、Claude Desktop、Codex、Cursor — 将工作和分析保存为不可变、有版本记录的 Markdown 报告，并写入 md-log。md-log 是面向 “氛围编程” 的人工参与审阅与归档层。随后，你可以在网页、手机和平板上阅读这些报告，并用触控笔添加批注（S-Pen / Apple Pencil）——每次保存都会生成一个新的不可变版本。

这是一个 Model Context Protocol 服务 — 两种传输方式，一套工具 — 可让 Claude Code（以及其他 Agent）将 .md 文件 — 包括文本 和 嵌入式截图 — 直接保存到 md-log，这个面向氛围编程的人工参与审阅与归档层。推荐使用托管远程端点（https://mcp.md-log.com/mcp，只需 URL + 密钥，无需安装）；也可以选择本地 stdio（npx -y md-log-mcp）传输方式。Agent 按路径写入报告（my-project/2026-07-07-error-report.md）；缺少的文件夹会自动创建，图片会上传，其引用会改写为 asset:// 链接，每次保存都会生成一个新的不可变版本。之后，你可以在手机、平板和网页上阅读、编辑报告，并使用触控笔添加批注（支持时可使用 S-Pen / Apple Pencil）。

md-log 是一项托管在 https://app.md-log.com 的服务——你无需自行运行任何服务。此软件包只是连接器：一个轻量级的身份验证 HTTP 客户端，用于验证 POSIX 路径、协调资源上传、将错误映射为稳定的 Agent 代码，并将所有内容转发给托管的 md-log 服务——该服务是身份验证、存储、版本管理和配额的唯一管理方。你只需要从 Web 应用获取一个 Personal Access Token。

技术栈

• @modelcontextprotocol/sdk（TypeScript）——一个 McpServer（17 个工具），两种传输方式。
• stdio 传输（md-log-mcp）——通过 stdin/stdout 传输 JSON-RPC；默认的本地模式（因此 stdout 专用于协议，日志写入 stderr）。PAT 从环境变量读取。
• Streamable HTTP 传输（md-log-mcp-http）——远程模式：Agent 通过 URL 连接，无需本地安装；每个请求都会从 Authorization 标头中读取 PAT。请参阅远程（Streamable HTTP）模式。
• TypeScript，使用 tsup 打包为 ESM dist/server.js（stdio）和 dist/http.js（HTTP）。运行时依赖：MCP SDK 和 zod（输入架构）。网络层仅使用 Node 内置的 fetch/http——不使用 Web 框架。
• PAT 身份验证——将 md-log Personal Access Token 作为 Authorization: Bearer 发送给后端。

要求

• Node 22+
• 一个在 md-log Web 应用中创建的 Personal Access Token（PAT）（Settings → Tokens；令牌仅显示一次）

仅此而已——md-log 服务托管在 https://app.md-log.com；无需安装或自托管。

工具（17 个）

每个工具都会返回双重输出——供人阅读的 content[].text 和机器可读的 structuredContent——并会在任何后端调用之前验证 POSIX 路径（NFC 规范化；拒绝 ../.、控制字符、空/空白路径段、反斜杠和保留名称；限制名称最长 255 字节、路径最长 1024 字节；文件必须使用 .md 扩展名）。所有请求都会发送到 MDLOG_API_BASE_URL 中的基础 URL（其中已包含 /api/v1）。

工具	功能
save_markdown ⭐	核心工具。按路径创建或覆盖 .md 文件（强制采用最后写入者胜出）；缺失的文件夹会自动创建。可选择先上传嵌入的图片（每张图片通过 data_base64 或本地 file_path 提供），并将内容中的每个 placeholder 替换为 asset://<key> 链接。接受 commit_message——建议填写 1-2 行变更摘要，显示在版本历史中。
upload_asset	上传一张图片（预留 → 预签名 PUT → 完成），并返回可嵌入为  的 asset://<key> 引用。图片通过 data_base64（内联 base64）或 file_path（由服务端读取的本地文件） 二选一提供，且必须且只能提供一项；使用 file_path 时，filename 默认为文件名，content_type 根据扩展名推断（png/jpg/jpeg/gif/webp/avif）。
append_to_markdown	使用乐观并发控制向现有文件追加内容（GET 当前内容 → 拼接 → 携带 base_version_no 条件 PUT）。发生冲突时自动重试一次，之后返回 CONFLICT。接受 commit_message——建议填写 1-2 行变更摘要，显示在版本历史中。
edit_markdown	通过精确字面替换修改文件的部分内容（读取 → 应用修改 → 携带 base_version_no 条件 PUT；发生冲突时自动重试一次，并重新应用每项修改）。一次可传入多项修改：edits: [{old_string, new_string, replace_all?}, …]（最多 50 项，按顺序应用）——它们会作为 一次写入 = 一个版本 = 一条通知 完成；修改单项时仍可使用 old_string/new_string 简写（不可同时使用）。每个 old_string 必须恰好匹配一次，重叠位置也计入匹配（"\n\n" 出现在 "\n\n\n" 中时存在歧义 → detail.overlapping: true）——0 次匹配或存在歧义的 >1 次匹配都会以 VALIDATION 拒绝整个调用（detail.reason = NO_MATCH / AMBIGUOUS_MATCH，detail.edit_index = 失败的修改项），且不会写入任何内容；如需有意修改所有匹配项，请设置 replace_all:true。其他 detail.reason 包括：输入格式 — MIXED_INPUT、MISSING_EDIT、EMPTY_EDITS、TOO_MANY_EDITS、EMPTY_OLD_STRING、IDENTICAL_STRINGS（读取前拒绝）；结果 — NO_CHANGE（修改相互抵消）、DOCUMENT_TOO_LARGE（某一步会超过 25 MiB 上限）、TOO_MANY_REPLACEMENTS（一次调用中替换的匹配项超过文档上限）、BATCH_TOO_SLOW（调用运行 2 s 后停止执行第一项之后的修改——请拆分为多次调用）。冲突重试时发生的匹配失败会带有 detail.after_concurrent_write: true。不会创建文件（路径不存在时返回 NOT_FOUND），且没有强制模式——进行任何部分修改时，请优先使用此工具，而不是 update_markdown。
update_markdown	替换文件的全部内容。传入 expected_version 进行乐观并发控制（不匹配时返回 CONFLICT）；省略该参数则强制采用最后写入者胜出。现在，对不存在的路径传入 expected_version 会返回 CONFLICT（detail.server_version_no = 0），而不会静默创建文件。进行部分修改时请改用 edit_markdown。接受 commit_message——建议填写 1-2 行变更摘要，显示在版本历史中。
restore_version	将文件回滚到较早的 version_no（来自 list_versions）：该版本的内容会成为一个新的当前版本——历史记录不可变，因此回滚操作本身也可以撤销。恢复到文件当前所在版本会被接受为无操作。接受 commit_message。
get_markdown	按路径读取文件内容（直接返回内联内容，或为大型文档返回预签名内容 URL）。传入 version（来自 list_versions 的 version_no）可读取旧的不可变版本。
list_versions	列出文件不可变的版本历史，按从新到旧排序（version_no、commit_message、作者、registered_at、大小）。
delete_markdown	软删除文件。必须设置 confirm:true（否则返回 VALIDATION）；会先将路径解析为文档键。
create_folder	相当于 mkdir -p——创建所有缺失的路径段；已存在的文件夹也视为成功。
list_folders	返回完整的文件夹树。
list_files	列出文件夹路径下的文档和直接子文件夹。
search_markdown	按标题（子串）和正文全文搜索（当前版本；整词匹配，按相关度排序，正文匹配会附带片段）。
move_markdown	按路径移动和/或重命名 .md 文件（from_path → to_path）；目标文件夹会自动创建；文档保留其键，因此版本历史和审阅者批注都会保留。
move_folder	将文件夹（整个子树）移至新的父文件夹下（new_parent_path 为空/省略时移至根目录）；父文件夹会自动创建；服务端会拒绝循环移动。
rename_folder	就地重命名文件夹（由服务端重写所有后代路径）。
delete_folder	删除文件夹。必须设置 confirm:true；默认仅删除空文件夹——传入 cascade:true 可软删除整个子树（rm -r）。

向 Agent 显示的错误代码

后端故障会返回 { isError: true, content:[{type:"text", ...}] }，并在 structuredContent.error.code 中提供映射后的代码：

NOT_FOUND · CONFLICT（在 detail 中包含服务端头信息 {server_version_no, server_checksum, …}）· UNAUTHORIZED · RATE_LIMITED · QUOTA_EXCEEDED · BACKEND_UNAVAILABLE · VALIDATION · FOLDER_EXISTS（create_folder 会将其作为成功吞掉）· ERROR。

身份验证

MCP/PC 通道使用个人访问令牌（mdlog_pat_…）进行身份验证。该令牌在 Web 应用的设置中生成一次，并通过环境变量提供。客户端会在每个请求中附加 Authorization: Bearer <PAT>（以及兼容性所需的 X-API-Token）。后端是身份验证和配额的唯一真实来源。

变量	必需	示例	说明
MDLOG_API_BASE_URL	是	https://app.md-log.com/api/v1	托管服务的基础 URL，包括 /api/v1。不会追加版本后缀；末尾的斜杠会被移除。
MDLOG_PAT	是	mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx	Bearer PAT。请安全存储（OS 钥匙串）——切勿提交。
MDLOG_MAX_DOCUMENT_BYTES	否	26214400（25 MiB）	客户端预检后端的单文档正文大小上限，单位为 UTF-8 字节（韩文每个字符占 3 字节）。超出上限的保存操作会立即失败，并返回指出实际大小的 VALIDATION 错误，而不是含糊的后端 400。两种传输方式均适用。仅在使用具有不同上限的可自托管后端时更改。

如果缺少任一变量，或基础 URL 格式错误，服务端会在启动时立即失败并显示清晰的提示信息。

构建

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

冒烟测试

scripts/smoke.mjs 会通过标准输入输出启动构建后的服务端（MCP SDK Client + StdioClientTransport），然后依次运行 initialize → tools/list → save_markdown（嵌入了一个微型 data: PNG 的简短报告）→ get_markdown（读回内容并检查标记）→ search_markdown——逐步输出 PASS/FAIL，任何步骤失败都会以非零状态码退出。使用真实 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

连接客户端

在 Web 应用的设置 → Tokens中生成 PAT，安全存储后，将 md-log 添加到 MCP 客户端。切勿提交 PAT。

📄 连接指南（HTML） — md-log.com/guides/customer-guide.html：使用 Web 应用中生成的 MCP 密钥（PAT） 通过 URL 连接（推荐），或通过 npx 本地连接（Claude Code · Desktop · Codex · Cursor）。

推荐 — 远程（URL），无需安装

将客户端指向托管端点，并将 PAT 作为 Bearer 标头传入。无需安装任何内容——不需要 Node.js，也不需要 npx。（连接托管服务甚至不需要此软件包。）

# 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" }
    }
  }
}

通过远程端点连接时，请以内嵌方式（base64）嵌入图像；通过路径（file_path）上传本地图像仅适用于下文的本地方式。

备选方案 — 本地（通过 npx 使用标准输入输出）

此方式会将此连接器作为本地子进程运行（需要 Node 22+；npx 会获取已发布的软件包，无需构建）。如果你更倾向于使用本地进程、需要上传本地文件（file_path）图像，或在没有托管 MCP 端点的情况下自托管 md-log，请使用此方式。

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

生成并保护 PAT。 在 Web 设置 → Tokens中创建令牌（仅显示一次），并确保不将其纳入版本控制——建议使用 OS 钥匙串。在 macOS 上，例如：

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

如果 PAT 泄露，请在 Web 应用中撤销该令牌并生成新令牌。

远程（Streamable HTTP）模式

第二个可执行文件 md-log-mcp-http 通过 MCP 的 Streamable HTTP 传输提供相同的 17 个工具——使用单个 POST /mcp 端点——因此 Agent 可通过URL 连接，无需本地安装。如果你想集中托管连接器（在 TLS 反向代理后运行容器或小型 VM），而不是让每位用户都运行 npx，请使用此模式。

与 stdio 模式的区别：

• 每个请求使用独立 PAT。 不会从环境变量读取令牌；每个请求都携带自己的 Authorization: Bearer <mdlog_pat_…> 标头，因此一个端点可供多位用户使用——每位用户使用自己的 md-log 令牌。（此模式下会忽略 MDLOG_PAT。）
• 无状态。 每个请求都会创建新的客户端和服务；没有会话存储（适合副本部署和自动扩缩）。
• 不访问本地文件。 file_path 图像来源会被拒绝（否则将读取服务端的磁盘）；请以内联 data_base64 方式发送图像。其他方面完全相同。

运行

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

配置（环境变量）

变量	必需	默认值	说明
MDLOG_API_BASE_URL	是	—	托管的 md-log 基础 URL，包括 /api/v1。
MDLOG_HTTP_HOST	否	127.0.0.1	绑定接口。默认仅限本地主机；只有在 TLS 反向代理后方才设置为 0.0.0.0。
MDLOG_HTTP_PORT	否	8787	TCP 端口。
MDLOG_HTTP_PATH	否	/mcp	MCP 端点路径。
MDLOG_HTTP_ALLOWED_ORIGINS	否	(无)	以逗号分隔的浏览器 Origin 允许列表（防御 DNS 重绑定）。请求若携带不在列表中的 Origin，将返回 403；非浏览器客户端（不带 Origin）始终允许访问。
MDLOG_HTTP_ALLOWED_HOSTS	否	(无)	可选的、以逗号分隔的 Host 允许列表（额外防御 DNS 重绑定）。
MDLOG_HTTP_MAX_BODY_BYTES	否	33554432 (32 MiB)	请求正文最大字节数（base64 图像会膨胀约 33%）。

安全措施（符合 MCP 规范）：默认绑定到 127.0.0.1，每个 MCP 请求都要求携带 Bearer 令牌，通过允许列表验证 Origin 以防御 DNS 重绑定，并限制正文大小。GET /health 存活探测（无需身份验证）会返回 {"status":"ok"}。对 MCP 端点执行 GET/DELETE 会返回 405（无状态：没有独立的 SSE 流，也没有可终止的会话）。

通过 URL 连接 Agent

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

客户端配置格式因工具而异（Claude Code / Cursor / 等）——必需项是端点URL和 Authorization: Bearer <PAT> 标头。公开部署前务必终止 TLS；每个请求都会携带 PAT。

脚本

• npm run build — 打包为 dist/server.js（stdio）和 dist/http.js（Streamable HTTP）（tsup、ESM、Node 22）。
• npm run dev — 文件变更时重新构建（tsup --watch）。
• npm run typecheck — tsc --noEmit。
• npm run smoke — 针对在线后端运行 stdio 冒烟测试（需要环境变量和已构建的程序）。
• npm run smoke:http — 无需后端的 HTTP 传输冒烟测试（握手 + 身份验证/来源/file_path 防护）。
• npm start — 运行已构建的 stdio 服务（node dist/server.js）。
• npm run start:http — 运行已构建的 HTTP 服务（node dist/http.js）。