1 files changed, 121 insertions, 0 deletions
diff --git a/scripts/python/README.md b/scripts/python/README.md
new file mode 100644
index 0000000..7018313
--- /dev/null
+++ b/scripts/python/README.md
@@ -0,0 +1,121 @@
+# tiny-convmem-mcp ユーザ視点負荷テスト
+
+このディレクトリには、[Model Context Protocol (MCP) Python SDK](https://github.com/modelcontextprotocol/python-sdk) を使った、Windows 版 `tiny-convmem-mcp` サーバのエンドツーエンド負荷テスト＆ベンチマークスクリプトがあります。
+
+## 環境
+
+`scripts/python/.venv` は uv で構築済みで、以下が含まれています。
+
+- Python 3.12.9
+- `mcp` 1.28.1 (Python SDK)
+
+必要に応じて追加インストールする場合:
+
+```powershell
+uv pip install --python .venv\Scripts\python.exe mcp
+```
+
+## 実行方法
+
+最新の Release ビルドを自動検出して実行します。
+
+```powershell
+cd scripts\python
+..\.venv\Scripts\python.exe benchmark.py
+```
+
+オプション:
+
+| オプション | 説明 |
+|---|---|
+| `--server <path>` | `tiny-convmem-mcp.exe` のパスを明示 |
+| `--iterations N` | 各シナリオの反復回数（デフォルト 100、rebuild/recovery は最大 5） |
+| `--warmup N` | 未使用（後方互換） |
+| `--output <path>` | 出力 JSON（デフォルト `benchmark_results.json`） |
+
+例:
+
+```powershell
+.venv\Scripts\python.exe benchmark.py --server ..\..\build\windows-vs2026\src\Release\tiny-convmem-mcp.exe --iterations 100 --output mybench.json
+```
+
+## 測定内容
+
+すべての操作は stdio MCP プロトコル経由で実際のサーバプロセスに対して行います。
+
+1. **write_message** — 小 (~20B)、中 (1KiB)、大 (32KiB) content サイズ別
+2. **write_message (with tags)** — `metadata_json` 文字列に tags / `memory_tier` を含む書き込み
+3. **read_messages** — 100 件のメッセージを読み出し、件数を検証
+4. **search_messages** — 同じデータ・同じ query で global / session-scoped を比較
+5. **delete_message** — `message_id` 指定削除
+6. **rebuild_index** — compaction + snapshot 再生成（5 回反復）
+7. **get_system_health** — ストレージ健全性取得
+8. **recovery** — プロセス再起動後の復旧を 3 段階で計測
+   - restart + count check（1 回）
+   - restart + small read（5 回）
+   - restart + full read 100 msgs（5 回）
+
+各シナリオは独立した temp data directory で実行され、シナリオ間の状態累積を排除しています。
+
+## 出力
+
+- コンソール: p50/p95/p99/mean レイテンシと ops/sec のサマリ表
+- `<output>.json`: 詳細な計測結果（全サンプル含む）
+- `<output>.md`: Markdown レポート
+
+## 結果の見方
+
+```text
+=== tiny-convmem-mcp 負荷テスト結果 ===
+server      : C:\...\Release\tiny-convmem-mcp.exe
+exe_mtime   : 2026-06-30 01:46:57
+iterations  : 100
+
+scenario                                       succ  fail    p50[ms]    p95[ms]    p99[ms]   mean[ms]      ops/s
+----------------------------------------------------------------------------------------------------------------
+write_message (small ~20B)                      100     0      0.399      1.009      1.718      0.505    1981.27
+...
+```
+
+## 注意
+
+- `tiny-convmem-mcp` は単一stdio・単一スレッドサーバのため、リクエストは逐次送信されます。並行負荷テストは対象外です。
+- 計測値には子プロセス起動、JSON シリアライズ、OS I/O、同期耐久性フラッシュ（fsync/FlushFileBuffers）が含まれます。
+- 各シナリオ内の反復は同一プロセス・同一セッションで実行します。したがって `write_message` の大サイズ計測など、前の反復がストレージ状態を変化させる可能性があります。
+
+## 参考: MCP 準拠状況
+
+本テストで確認できる MCP 機能:
+
+- `initialize` / `notifications/initialized`
+- `tools/list`（schema 取得）
+- `tools/call`（明示登録された6ツール）
+- TextContent 内 JSON 応答
+- `isError=true` によるアプリケーションレベルエラー
+
+確認済みのP0契約:
+
+- `write_message.metadata_json` は任意のJSON文字列で、省略時は `{}`
+- `search_messages.session_id` は任意で、省略時はglobal検索
+- `search_messages.limit` は任意で、既定20、整数1～100
+- `delete_message.session_id` は任意
+- `inputSchema.required` とruntimeの必須条件が一致
+- 成功・エラーの全応答がJSON-RPC 2.0形式で、Python MCP SDKから解釈可能
+- `read_messages` は現状フル履歴を返し、paginationは未実装
+
+未対応・確認していない項目:
+
+- `structuredContent` / 出力 schema
+- `resources/*`, `prompts/*`, `sampling/*`, `roots/*`
+- 並行リクエスト / 複数クライアント
+
+## P0回帰テスト
+
+Python MCP SDKでglobal/session-scoped検索を同一接続上で1000回交互に実行できます。
+
+```powershell
+.venv\Scripts\python.exe p0_regression.py --server ..\..\build\windows-vs2026\src\Release\tiny-convmem-mcp.exe
+```
+
+従来の約254リクエストでの切断は、Windowsの符号なし`SOCKET`でstdio sentinelを
+ネットワーク接続と誤判定し、connection poolを消費していたことが原因でした。