Scratchpad Mcp

scratchpad-mcp

AI エージェント向けの、永続的でトークン効率に優れたストレージです。同じファイルを読み直したり、毎回同じコンテキストを再読み込みしたりすることを防ぐ MCP サーバーです。

agent: "what changed in this file since I last read it?"
server: { diff: [...], current_version: 14 }   ← not the whole file

理由

エージェントはトークンを浪費します。すでに確認したファイルを読み直し、すでに処理したドキュメントを再要約し、すでに計算した状態を再発見します。このサーバーは、そうした作業を保存して後から再利用できる場所を提供し、モデルが低コストで推論できるようにします。

具体的には、次のとおりです。

• バージョン管理された書き込みにより、エージェントは作業中のドキュメントを保存し、「前回確認してから何が変わったか」を尋ねられます。サーバーは全文ではなく、構造化された差分を返します。
• 追記専用ログとカーソルベースのページネーションにより、エージェントは自身のアクション履歴を記録し、効率的に再生できます。
• 長いファイル（推定トークン数が 2000 を超える場合）のオンデマンド要約を Claude Haiku で生成し、ファイルのバージョンごとにキャッシュするため、要約を繰り返し呼び出しても追加コストはかかりません。
• エージェントごとの名前空間により、1 つのサーバーインスタンスで、状態を漏らすことなく複数のエージェントに対応できます。

ツール

すべてのツールは、最初の引数として agent_id を受け取ります。操作はそのエージェントのスコープ内に限定され、エージェント同士が互いのファイルやログを読み取ることはできません。

ツール	機能
write_file(agent_id, path, content)	パスにコンテンツを保存します。書き込みのたびに自動で新しいバージョンを作成します。最新の 10 バージョンを保持します。
read_file(agent_id, path, since_version?)	全文、または以前のバージョンとの JSON 行差分を読み取ります。since_version が整理済みの場合は、version_too_old: true を付けて全文を返します。
append_log(agent_id, path, entry)	追記専用ログにエントリを 1 件追加します。新しいエントリ ID を返します。
read_log(agent_id, path, since_entry?)	カーソルページネーションでログエントリを読み取ります。1 ページあたり 100 件で、has_more フラグと last_entry_id カーソルが返されます。
list_files(agent_id, prefix?)	ファイルを一覧表示します（メタデータのみ）。パスのプレフィックスで絞り込むこともできます。
delete_file(agent_id, path)	ファイルとそのすべてのバージョン、およびキャッシュされた要約を削除します。
summarize_file(agent_id, path)	長いファイル（8000 文字超）を LLM で要約します。バージョンごとにキャッシュされるため、変更されていないファイルへの再呼び出しにコストはかかりません。
get_usage_stats(agent_id)	エージェントの合計バイト数、ファイル数、ログ数、操作数を返します。

差分形式

since_version を指定した read_file は、チャンクの JSON 配列を返します。

{
  "diff": [
    { "op": "equal",  "lines": ["line that didn't change"] },
    { "op": "remove", "lines": ["line that was deleted"] },
    { "op": "add",    "lines": ["line that was added"] }
  ]
}

行単位の差分を採用しているのは意図的です。この形式はエージェントが最も確実に処理でき、ファイル全体を再処理するのではなく、何が変わったかを推論できるようにします。

パスのルール

パスは [a-zA-Z0-9/_.-]+ に一致し、最大 255 文字で、先頭に / を含まず、.. の連続を含まない必要があります。エラーには違反したルールが示されます。

制限

• ファイル書き込みは 1 MB まで
• ログエントリは 64 KB まで
• ファイルごとに 10 バージョンを保持（古いものは自動的に整理されます）
• read_log の 1 ページあたりログエントリ 100 件

インストール

Node 20 以降と Anthropic API キーが必要です（summarize_file のみ）。

git clone <this repo>
cd scratchpad-mcp
npm install
npm run build

これにより、実行可能なサーバー dist/index.js が生成されます。

Claude Desktop の設定

%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）に追加します。

{
  "mcpServers": {
    "scratchpad": {
      "command": "node",
      "args": ["C:\\path\\to\\scratchpad-mcp\\dist\\index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

ANTHROPIC_API_KEY が必要なのは、summarize_file を呼び出す場合のみです。 ほかの 7 つのツールは、このキーなしで動作します。

任意：SQLite の保存先を変更するには、SCRATCHPAD_DB_PATH を設定します。デフォルトではプロジェクトルートの scratchpad.db が使用されます。

Claude Desktop を再起動します。MCP サーバーの一覧に、8 つのツールを備えたサーバーが表示されます。

セキュリティモデル — ホスティング前にお読みください

agent_id は平文のツールパラメーターです。認証はありません。呼び出し元は任意の agent_id を名乗ることができ、サーバーはその値を信頼します。これは V1 では意図した仕様であり、想定するデプロイ形態では問題なく機能します。

• 1 サーバープロセスにつき 1 ユーザー。 エージェントと SQLite ファイルは同じ信頼境界を共有します。例：Claude Desktop のインストール、Smithery のローカルインストール、ユーザーごとの Apify Actor の実行（Apify は既定で、実行ごとに新しいデータベースファイルを持つ新しいコンテナーを起動します）。

以下の用途では安全ではありません。

• 1 つのサーバープロセスで複数の信頼できない呼び出し元にサービスを提供するマルチテナントのスタンバイモード。 誰でも別の呼び出し元の agent_id を渡して、そのデータを読み取ったり上書きしたりできます。

マルチテナントで運用する場合は、ラッパーレイヤーで呼び出し元の API キーから agent_id を導出する（V2 で予定）か、テナントごとに 1 つのプロセスを実行してください。

実装済みの多層防御

• すべての SQL はパラメーター化されているため、パス、agent_id、プレフィックスを介したインジェクションはできません。
• パス検証では、..、先頭の /、スペース、[a-zA-Z0-9/_.-] 以外の文字を拒否します。
• list_files のプレフィックス照合では、LIKE ではなく SUBSTR による等価比較を使用するため、SQL のワイルドカード _ と % は適用されず、大文字と小文字も区別されます。
• 呼び出しごとのサイズ上限（ファイルあたり 1 MB、ログエントリーあたり 64 KB）。
• エージェントごとのクォータ（ファイル 1000 件、ログエントリー 100k 件、合計 100 MB）により、制御不能になったエージェントがホスト型デプロイ環境の共有ディスクを使い果たすことを防ぎます。
• エラーとして返すのは err.message のみです。スタックトレース、SQLite のパス、API キーは返しません。

summarize_file の費用負担者は？

常に呼び出し元です。

• ローカルインストール（Smithery、Claude Desktop、mcp.so）： ユーザーは自分の設定で独自の ANTHROPIC_API_KEY を指定します。ユーザーのマシン、ユーザーのキー、ユーザーの請求です。
• Apify ホスト型： Actor の実行ごとに、実行単位の入力から anthropicApiKey を読み込みます。.actor/entrypoint.sh ランチャーがサーバー起動前にこの値を環境変数に設定します。呼び出し元は自分の要約について Anthropic に支払い、Actor の公開者は Apify の呼び出しごとの料金のみを受け取ります。

このプロジェクトをフォークしてホスティングする場合は、Dockerfile、Apify Actor の環境変数、または公開配布する設定に API キーをハードコードしないでください。ほかの 7 つのツールはキーなしで動作するため、未設定のままにしておくのが安全な既定値です。

デプロイ形態ごとの永続性

重要な点として、サーバーの実行方法によって永続性の保証が異なります。ワークロードに合った形態を選んでください。

デプロイ	永続性	失われるタイミング
Claude Desktop / Smithery ローカル / 直接 stdio	ローカルディスクに完全に永続化されます。 SQLite ファイルはプロジェクトの隣にある scratchpad.db に保存されます。ファイルを削除しない限り、再起動やクラッシュなどがあっても状態は保持されます。	ファイルを削除したとき。
Apify ホスト型（スタンバイモード）	セッション単位です。 ホット状態の Actor インスタンス内では、リクエスト間で状態が保持されます。コールドスタート時に失われます。	Actor インスタンスの再利用時：Idle timeout 秒を超えてアイドル状態になったとき、Max requests per run の予算に達したとき、または再デプロイ時。
Smithery ホスト型（予定）	未定 — Smithery の永続ボリューム対応待ちです。

Apify の形態は、単一タスクのエージェントセッション（エージェントが数分間動作し、数十回ツールを呼び出す間、スクラッチパッドがそのすべてで保持される）に最適です。セッションをまたぐ長期記憶（エージェントが昨日書き込んだ内容を読み返す必要がある場合）には適していません。その用途には、現時点ではローカルインストールを使用するか、v0.2.0 をお待ちください。ロードマップでは、この作業の進捗を追跡しています。

ストレージの仕組み

すべてのデータは、1 つの SQLite ファイルに格納されます。

• files — (agent_id, path) ごとに 1 行を格納し、現在のバージョンを追跡します。
• file_versions — バージョンごとの全コンテンツを格納します。各ファイルの最新 10 件まで保持します。書き込みのたびに古いバージョンを削除します。
• log_entries — 追記のみのエントリーで、変更されることはありません。
• summaries — ファイルごとの要約キャッシュです。バージョンの不一致があると無効になります。
• agent_usage — get_usage_stats 用のエージェントごとの操作カウンターです。

バージョン管理では、差分ではなく、バージョンごとの全コンテンツを保存します。これは、書き込みを高速にし、読み取りの曖昧さをなくすためです。差分は読み取り時に、2 つのバージョンを行単位の差分処理にかけて計算します。コストを負担するのは差分を要求した呼び出し元であり、すべての書き込み処理ではありません。

ロードマップ

• 従量課金に対応する Apify パッケージング。
• ホスト型デプロイ向けの HTTP/SSE トランスポート。
• Apify でのコールドスタートをまたいだ永続化。 書き込み時およびシャットダウン時に SQLite ファイルを Apify の Key-Value Store と同期し、インスタンスの再起動後も状態を維持します。v0.2.0 を目標としています。
• ホスト型バックエンドの選択肢。 libSQL/Turso（SQLite 互換のホスト型サービス）をローカルの SQLite の代替として接続し、KV ストア関連の複雑な仕組みを使わずに、ホスト型デプロイで長期的な永続化を実現します。
• パラメーターとして受け取るのではなく、API キーから agent_id を導出する。
• エージェントごとのレート制限。
• 運用状況を可視化するための構造化ログ。

ライセンス

MIT — LICENSE を参照してください。