diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 96 |
1 files changed, 57 insertions, 39 deletions
@@ -1,7 +1,8 @@ # tiny-convmem-mcp -LLMとの会話履歴を扱うための、小さなC言語製MCPサーバです。現在は設計前の -基盤段階で、stdioによるMCP初期化と`health` toolだけを実装しています。 +LLMの会話メッセージをローカルの追記ログへ保存する、Windows向けC17製MCP +サーバです。書込みと削除はディスクへの同期完了後に成功を返し、プロセス再起動時は +ログまたはsnapshotから状態を復旧します。 ## 必要環境 @@ -9,64 +10,81 @@ LLMとの会話履歴を扱うための、小さなC言語製MCPサーバです - Visual Studio Community 2026（Desktop development with C++） - CMake 4.3以降 - Git -- vcpkg（PATHから`vcpkg`を実行できること） +- vcpkg（PATHから実行可能であること） -vcpkgはコンパイラを導入するためではなく、今後SQLite等のライブラリを管理する -ためにmanifest modeで使用します。現時点の`vcpkg.json`に外部依存はありません。 - -## 初回構築 - -PowerShellで次を実行します。スクリプトは不足ツールを自動インストールしません。 +## ビルドとテスト ```powershell git submodule update --init --recursive .\scripts\bootstrap.ps1 -Configuration Debug ``` -Releaseも確認する場合は次を実行します。 - -```powershell -.\scripts\bootstrap.ps1 -Configuration Release -``` - -## 手動ビルドとテスト - -presetを直接使う場合は、先にvcpkgルートを設定します。 +手動実行する場合は次のとおりです。 ```powershell $config = vcpkg z-print-config | ConvertFrom-Json $env:VCPKG_ROOT = $config.'vcpkg-root' - cmake --preset windows-vs2026 cmake --build --preset windows-vs2026-debug ctest --preset windows-vs2026-debug ``` -成果物は`build/windows-vs2026/`以下に生成されます。サーバはstdoutをMCP -プロトコル専用、stderrを診断メッセージ専用として使用します。 - -## mcpcの管理 +## 起動 -mcpcは`third_party/mcpc`のGit submoduleとしてコミット -`4025fddfedcfa7573803a47236b147733fcb3c07`へ固定しています。更新時は新しい -コミットを明示的にcheckoutし、Debug/Releaseのsmoke testを両方実行してください。 +保存先は必ず明示します。相対パスも使用できます。同じdata directoryを使用する +プロセスの二重起動は拒否されます。 ```powershell -git -C third_party/mcpc fetch origin -git -C third_party/mcpc checkout <reviewed-commit> -git add third_party/mcpc +.\build\windows-vs2026\src\Debug\tiny-convmem-mcp.exe --data-dir .\data ``` -固定コミットの上流CMakeには、欠落fixtureの参照、Makefileに対するソース列挙漏れ、 -MSVC互換マクロ名の不整合があります。そのため上流を変更せず、 -`cmake/mcpc.cmake`でMakefileと同じ13ソースを静的ライブラリ化しています。 +stdoutはMCP JSON-RPC専用、stderrは診断専用です。 + +## MCP tools + +- `write_message`: サーバ生成ULID・UTC timestamp付きメッセージを同期永続化 +- `read_messages`: sessionの有効メッセージを時系列順に取得 +- `search_messages`: contentとtagsをUTF-8コードポイントの2/3-gramで検索 +- `delete_message`: DELレコードを同期永続化して即時不可視化 +- `rebuild_index`: 有効PUTだけにcompactionしsnapshotを再生成 +- `get_system_health`: ログ、snapshot、復旧状態、件数を報告 -また、上流は同じ階層に`LICENSE`ファイルと`license/`ディレクトリを保持しており、 -Windowsでは名前が衝突します。`bootstrap.ps1`はライセンス本文を含む`license/`を -維持し、checkoutできないトップレベル`LICENSE`だけをローカルsubmodule indexで -`skip-worktree`に設定します。上流の追跡ファイルやコミットは変更しません。 +ツール結果はMCP TextContent内のJSON文字列です。入力schema、サイズ制限、エラーコード +および物理フォーマットは[architecture](docs/architecture.md)を参照してください。 +実装済み・未実装・テスト状況の追跡表は +[implementation status](docs/implementation-status.md)にまとめています。 -## 現在の境界 +## 永続化と復旧 -会話・メッセージのデータモデル、保持期限、検索方式、ストレージAPI、SQLite採用は -未決定です。責務の境界は[docs/architecture.md](docs/architecture.md)を参照してください。 +`active.log` はversion付きlittle-endianレコード、payload CRC32、単調sequenceを持ちます。 +PUT/DELは `FlushFileBuffers` が成功するまで `OK` を返しません。末尾で中断したレコード +だけは正常境界まで自動切詰めし、途中のCRC不一致はデータを保存したまま起動を拒否します。 + +`rebuild_index` は新しいgeneration markerを持つログを作成後、同じgenerationとログoffsetを +記録した `snapshot.bin` を置換します。起動時に両者が一致するとsnapshotをロードし、後続 +レコードだけを再生します。不一致または不正なsnapshotは変更せず、ログ全体を再生します。 + +削除は呼出時には論理削除です。元本文が `active.log` から除去されるのはcompaction成功時で、 +SSD、バックアップ等からの安全消去は保証しません。`memory_tier` は初期版では属性であり、 +自動要約・昇格・破棄を行いません。 + +## mcpcの管理 + +mcpc submoduleはコミット `4025fddfedcfa7573803a47236b147733fcb3c07` に固定しています。 +固定版tool APIではoptional/object/array schemaとcallback contextを表現できないため、 +プロジェクト側MCP互換境界がmcpc同梱のmjson parserを利用してraw argumentsとschemaを扱います。 +submoduleのソースは変更しません。詳細は[src/mcp/README.md](src/mcp/README.md)を参照してください。 + +## コーディングスタイル + +プロジェクト所有のCソースとヘッダーは、リポジトリ直下の +[`.clang-format`](.clang-format)に従います。制御文には常に波括弧を付け、1行には +1つのstatementだけを記述します。`third_party/` は整形対象外です。 + +Visual Studio同梱のclang-formatを使う場合は、PowerShellで次のように整形できます。 + +```powershell +$formatter = 'C:\Program Files\Microsoft Visual Studio\18\Community\VC\Tools\Llvm\bin\clang-format.exe' +$files = rg --files src tests -g '*.c' -g '*.h' +& $formatter -i --style=file $files +``` |