md-log-mcp

md-log-mcp

差分ではなく、レポートをレビューしましょう。 AI コーディングエージェント（Claude Code、Claude Desktop、Codex、Cursor）が作業内容と分析を、変更不可でバージョン管理された Markdown レポートとして md-log に保存できる MCP サーバーです。md-log は、「バイブコーディング」のための人間が介在するレビューおよびアーカイブレイヤーです。保存したレポートは、ウェブ、スマートフォン、タブレットで読み、スタイラスペンで注釈を付けられます（S-Pen／Apple Pencil）。保存するたびに、新しい変更不可のバージョンが作成されます。

Model Context Protocol サーバーです。2 種類のトランスポートで、1 組のツールを提供し、Claude Code（およびその他のエージェント）が .md ファイルをテキストと埋め込みスクリーンショットの両方を含めて、バイブコーディングのための人間が介在するレビューおよびアーカイブレイヤーである md-log に直接保存できます。接続方法として推奨されるのは、ホスト型リモートエンドポイント（https://mcp.md-log.com/mcp、URL とキーがあればよく、インストール不要）です。代替手段として、ローカルの stdio（npx -y md-log-mcp）トランスポートも利用できます。エージェントはレポートをパスで指定して書き込みます（my-project/2026-07-07-error-report.md）。存在しないフォルダーは自動作成され、画像はアップロードされて参照が asset:// リンクに書き換えられ、保存するたびに新しい変更不可のバージョンが作成されます。同じレポートは、スマートフォンやタブレット、ウェブ上で読んだり、編集したり、（対応端末では S-Pen／Apple Pencil で）注釈を付けたりできます。

md-log は https://app.md-log.com で提供されているホスト型サービスです。サーバーをご自身で実行する必要はありません。このパッケージは接続用のコンポーネントであり、POSIX パスの検証、アセットのアップロードの調整、エラーの安定したエージェントコードへの変換を行い、すべてをホスト型の md-log サービスに転送する、薄い認証済み HTTP クライアントです。認証、ストレージ、バージョン管理、クォータを一元的に管理するのは、このサービスだけです。必要なのは、ウェブアプリから取得した Personal Access Token だけです。

スタック

• @modelcontextprotocol/sdk（TypeScript）— 1 つの McpServer（17 個のツール）と 2 種類のトランスポート。
• stdio トランスポート（md-log-mcp）— stdin/stdout 上の JSON-RPC。デフォルトのローカルモードです（stdout はプロトコル専用のため、ログは stderr に出力されます）。PAT は環境変数から取得します。
• Streamable HTTP トランスポート（md-log-mcp-http）— リモートモードです。エージェントはローカルへのインストールなしで URL 経由で接続します。PAT はリクエストごとに Authorization ヘッダーから取得します。 リモート（Streamable HTTP）モードを参照してください。
• TypeScript を tsup で ESM の dist/server.js（stdio）および dist/http.js（HTTP）にバンドルします。 実行時依存関係は MCP SDK と zod（入力スキーマ）です。ネットワーク処理には Node 組み込みの fetch／http のみを使用し、ウェブフレームワークは使用しません。
• PAT 認証 — md-log Personal Access Token を Authorization: Bearer としてバックエンドに送信します。

要件

• Node 22+
• md-log ウェブアプリの Settings → Tokens で発行した Personal Access Token（PAT。表示されるのは一度だけです）

以上です。md-log サービスは https://app.md-log.com でホストされているため、インストールもセルフホストも不要です。

ツール（17 個）

すべてのツールは、人間が読める content[].text と機械可読な structuredContent の 2 種類の出力を返します。また、バックエンドへの呼び出しを行う前に POSIX パスを検証します（NFC 正規化、..／.、制御文字、空または空白のみのセグメント、バックスラッシュ、予約名を拒否し、名前は 255 バイト、パスは 1024 バイトまでに制限し、ファイルには .md を必須とします）。すべてのリクエストは MDLOG_API_BASE_URL のベース URL（/api/v1 を含みます）に送信されます。

ツール	機能
save_markdown ⭐	中心となるツールです。パスを指定して .md を作成または上書きします（常に最後に書き込まれた内容を優先）。存在しないフォルダーは自動的に作成されます。任意で、埋め込み画像を先にアップロードし（各画像は data_base64 またはローカルの file_path で指定）、コンテンツ内の各 placeholder を asset://<key> リンクに書き換えます。バージョン履歴に表示される、推奨形式の1～2行の変更概要 commit_message を指定できます。
upload_asset	画像を1つアップロードし（予約 → 署名付き 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）。競合時に自動で1回再試行し、その後は CONFLICT を返します。バージョン履歴に表示される、推奨形式の1～2行の変更概要 commit_message を指定できます。
edit_markdown	正確な文字列置換によってファイルの一部を変更します（読み込み → 適用 → base_version_no を使って条件付き PUT。競合時には自動で1回再試行し、すべての編集を再適用します）。複数の変更を一度に edits: [{old_string, new_string, replace_all?}, …] として渡せます（最大50件、順番に適用）。これらは 1回の書き込み = 1つのバージョン = 1件の通知 として処理されます。変更が1件の場合は、old_string／new_string の省略形も引き続き使用できます（両方を同時に使うことはできません）。各 old_string は、重複する位置も数えて 完全に1回だけ 一致する必要があります（"\n\n\n" 内の "\n\n" は曖昧な一致となり、detail.overlapping: true が返されます）。一致が0件、または曖昧な一致が複数ある場合は、呼び出し全体 が 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（1回の呼び出しで、置換された箇所がドキュメントの上限を超える）、BATCH_TOO_SLOW（呼び出し開始から2秒経過すると、最初の編集以降の編集は停止します。複数回に分けて呼び出してください）。競合時の再試行で一致に失敗した場合は、detail.after_concurrent_write: true が返されます。ファイルは作成されません（パスが存在しない場合は NOT_FOUND）。強制モードはありません。部分的な変更には、update_markdown よりこちらを優先してください。
update_markdown	ファイルの 全コンテンツ を置き換えます。楽観的同時実行制御には expected_version を指定します（不一致の場合は CONFLICT）。指定しない場合は、常に最後に書き込まれた内容が優先されます。存在しないパスに expected_version を指定すると、現在は暗黙に作成されるのではなく CONFLICT が返されます（detail.server_version_no = 0）。部分的な変更には、代わりに edit_markdown を使用してください。バージョン履歴に表示される、推奨形式の1～2行の変更概要 commit_message を指定できます。
restore_version	ファイルを以前の version_no（list_versions から取得）に戻します。そのバージョンのコンテンツが新しい現行バージョンになります。履歴は変更されないため、ロールバック自体も元に戻せます。すでにファイルが現在使用しているバージョンへの復元は、何も変更しない操作として受け付けられます。commit_message を指定できます。
get_markdown	パスを指定してファイルのコンテンツを読み込みます（インラインコンテンツ、または大きなドキュメントの場合は署名付きコンテンツ URL を返します）。古い変更不可能なバージョンを読み込むには、list_versions から取得した version_no を version に指定します。
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）。

エージェントに返されるエラーコード

バックエンドの障害は、structuredContent.error.code にマッピングされたコードを含む { isError: true, content:[{type:"text", ...}] } を返します。

NOT_FOUND · CONFLICT（detail にサーバーの最新情報 {server_version_no, server_checksum, …} を含みます） · UNAUTHORIZED · RATE_LIMITED · QUOTA_EXCEEDED · BACKEND_UNAVAILABLE · VALIDATION · FOLDER_EXISTS（create_folder では成功として処理されます） · ERROR

認証

MCP／PC の経路では、ウェブアプリの Settings で一度だけ発行し、環境変数で指定する Personal Access Token（mdlog_pat_…）を使用して認証します。クライアントはリクエストごとに 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 バイト（韓国語は 1 文字あたり 3 バイト）です。上限を超える保存は、内容が不明瞭なバックエンドの 400 ではなく、実際のサイズを示す VALIDATION エラーですぐに失敗します。両方のトランスポートに適用されます。上限の異なるセルフホストのバックエンドを使用する場合に限り、変更してください。

どちらかの変数が設定されていない場合、またはベース URL の形式が不正な場合、サーバーは明確なメッセージを表示して起動時にただちに失敗します。

ビルド

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

スモークテスト

scripts/smoke.mjs は、stdio 経由でビルド済みサーバーを起動し（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

クライアントの接続

ウェブアプリの Settings → Tokens で PAT を発行して安全に保管し、md-log を MCP クライアントに追加します。PAT は絶対にコミットしないでください。

📄 接続ガイド（HTML） — md-log.com/guides/customer-guide.html：ウェブアプリで発行した 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 経由の stdio）

このコネクターをローカルのサブプロセスとして実行します（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 の発行と安全な保管。 ウェブアプリの Settings → Tokens で PAT を作成します（表示されるのは一度だけです）。バージョン管理には含めず、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 が漏えいした場合は、ウェブアプリでその PAT を失効させ、新しい PAT を発行してください。

リモート（Streamable HTTP）モード

2 つ目の実行ファイル md-log-mcp-http は、MCP の Streamable HTTP トランスポートを使って 同じ 17 個のツールを提供します。エンドポイントは単一の POST /mcp で、エージェントはローカルにインストールせず、URL で接続できます。各ユーザーが npx を実行する代わりに、コネクターを一元的にホストする場合（TLS リバースプロキシの背後にあるコンテナー／小規模 VM）に使用してください。

stdio との違い：

• リクエストごとの PAT。 トークンは環境変数から読み込まれません。各リクエストに個別の Authorization: Bearer <mdlog_pat_…> ヘッダーを含めるため、1 つのエンドポイントで複数のユーザーに対応できます。それぞれが独自の 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	バインドするインターフェース。デフォルトでは localhost のみです。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 トークンを必須とします。DNS リバインディングを防ぐため、Origin を許可リストと照合して検証し、ボディサイズに上限を設けます。認証不要の GET /health ライブネスプローブは {"status":"ok"} を返します。MCP エンドポイントへの GET／DELETE は 405 を返します（ステートレスのため、単独の SSE ストリームも終了するセッションもありません）。

URL でエージェントを接続する

{
  "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 トランスポートのスモークテストです（ハンドシェイクと認証／Origin／file_path のガードを確認します）。
• npm start — ビルド済みの stdio サーバーを実行します（node dist/server.js）。
• npm run start:http — ビルド済みの HTTP サーバーを実行します（node dist/http.js）。