From dda043b0ec9d8d9e5da7fe51fc48791086417a9b Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sat, 4 Jul 2026 19:19:00 +0900 Subject: ドキュメント更新 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/mcp.md | 390 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 docs/mcp.md (limited to 'docs/mcp.md') diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 0000000..639946f --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,390 @@ +# MCP Tool Reference + +Tiny ConvMem MCPが公開する7つのtoolの仕様をまとめる。実際のJSON SchemaはMCPの +`tools/list`からも取得できる。 + +## 共通仕様 + +### Tool result + +toolのapplication responseは、MCP `TextContent.text`に格納された**JSON文字列**である。 +呼出側はTextContentを取得した後、その`text`をJSONとしてparseする。 + +成功例: + +```json +{"status":"OK"} +``` + +application errorではMCP tool resultの`isError`がtrueになり、`text`は次の形式になる。 + +```json +{ + "status": "ERROR", + "error": { + "code": "VALIDATION_ERROR", + "message": "invalid arguments" + } +} +``` + +主なerror code: + +| Code | 意味 | +|---|---| +| `VALIDATION_ERROR` | parameter、JSON文字列、値域が不正 | +| `NOT_FOUND` | 対象messageまたはcontextが存在しない | +| `CONFLICT` | `expected_revision`が現在のrevisionと一致しない | +| `BUSY` | resourceが使用中 | +| `IO_ERROR` | logの書込み、flush、置換などに失敗 | +| `CORRUPT_STORE` | 永続化dataの整合性error | +| `INTERNAL_ERROR` | allocationや内部状態のerror | + +### Message object + +各toolが返すmessageは次の形式である。 + +```json +{ + "message_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", + "session_id": "conversation-1", + "timestamp": 1720843200000, + "role": "user", + "content": "Remember this", + "revision": 1, + "updated_at": 1720843200000, + "metadata": { + "tool_call_id": "optional", + "tags": ["project", "decision"], + "memory_tier": "short", + "memory_kind": "conversation", + "importance": 50, + "summary": "optional summary", + "relations": [ + {"type": "derived_from", "message_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW"} + ], + "source_message_ids": ["01ARZ3NDEKTSV4RRFFQ69G5FAW"] + } +} +``` + +`tool_call_id`と`summary`は未設定時に省略される。その他のmetadata fieldは空配列やdefault値を +含めて出力される。 + +### Metadata JSON + +`write_message.metadata_json`、`update_message.metadata_json`はJSON objectを表す文字列である。 +MCP arguments内では次のように渡す。 + +```json +{ + "metadata_json": "{\"tags\":[\"project\"],\"memory_kind\":\"semantic\",\"importance\":80}" +} +``` + +| Field | 型・制限 | Default | +|---|---|---| +| `tool_call_id` | string、最大256 UTF-8 bytes | 未設定 | +| `tags` | string配列、最大32件、各128 bytes、空文字不可 | `[]` | +| `memory_tier` | `short` / `mid` / `long` / `discard` | `short` | +| `memory_kind` | `conversation` / `episode` / `semantic` / `procedure` / `preference` / `summary` | `conversation` | +| `importance` | integer、0～100 | `50` | +| `summary` | string、最大4096 bytes。空文字は未設定扱い | 未設定 | +| `relations` | 最大32件の`{"type", "message_id"}` | `[]` | +| `source_message_ids` | 26文字ULIDの配列、最大64件 | `[]` | + +relation typeは`depends_on`、`derived_from`、`supersedes`、`related_to`のいずれかである。 + +## `write_message` + +新しいmessageを生成し、diskへflushしてから成功を返す。 + +### Input + +| Parameter | 必須 | 型 | 説明 | +|---|---:|---|---| +| `session_id` | Yes | string | 1～256 UTF-8 bytes | +| `role` | Yes | string | `user` / `assistant` / `system` | +| `content` | Yes | string | 1 byte～1 MiBのUTF-8 text | +| `metadata_json` | No | string | Metadata JSON。defaultは`{}` | + +### Output + +```json +{"status":"OK","message":{...Message object...}} +``` + +`message_id`、`timestamp`、`updated_at`はserverが生成し、初期`revision`は1となる。 + +## `update_message` + +messageのidentity、session、role、作成時刻を維持し、contentまたはmetadataを更新する。 + +### Input + +| Parameter | 必須 | 型 | 説明 | +|---|---:|---|---| +| `message_id` | Yes | string | 対象の26文字ULID | +| `content` | No | string | 新しいcontent。最大1 MiB | +| `metadata_json` | No | string | 更新するmetadata fieldを含むJSON文字列 | +| `expected_revision` | No | integer | 1以上。現在値と違う場合は`CONFLICT` | + +`content`と`metadata_json`の少なくとも一方が必要である。`metadata_json`に含まれないfieldは +維持される。同じ値への更新はno-opとなり、`changed`はfalse、revisionとlogは変更されない。 + +### Output + +```json +{"status":"OK","changed":true,"message":{...Message object...}} +``` + +## `read_messages` + +`view`によりhistory、context、sessionsの3種類を返す。`view`省略時は`history`。 + +### 共通Input + +| Parameter | 必須 | 型 | 説明 | +|---|---:|---|---| +| `view` | No | string | `history` / `context` / `sessions` | +| `limit` | No | integer | 1～1000、default 100 | +| `cursor` | No | string | 前回responseの`nextCursor`。内容はopaque | + +responseは約8 MiBのbudget内で打ち切られる場合がある。 + +### `history` view + +session内のlive messageを作成順に返す。 + +追加parameter: + +| Parameter | 必須 | 型 | 説明 | +|---|---:|---|---| +| `session_id` | Yes | string | 対象session、最大256 bytes | + +```json +{ + "history": [{...Message object...}], + "nextCursor": "optional opaque cursor" +} +``` + +続きを読む場合は同じ`session_id`と`nextCursor`を渡す。 + +### `context` view + +指定message、同一sessionの前後message、relation graphを返す。 + +追加parameter: + +| Parameter | 必須 | 型 | Default | 説明 | +|---|---:|---|---:|---| +| `message_id` | Yes | string | — | 対象の26文字ULID | +| `before` | No | integer | 1 | 同一sessionから前に返す件数、0～10 | +| `after` | No | integer | 1 | 同一sessionから後に返す件数、0～10 | +| `relation_depth` | No | integer | 1 | relation traversal depth、0～2 | +| `relation_types_json` | No | string | 全type | relation type配列を表すJSON文字列 | + +`relation_types_json`の例: + +```json +{"relation_types_json":"[\"derived_from\",\"supersedes\"]"} +``` + +```json +{ + "message": {...Message object...}, + "chronological_context": { + "before": [{...Message object...}], + "after": [{...Message object...}] + }, + "relations": [ + { + "type": "derived_from", + "direction": "outgoing", + "depth": 1, + "message": {...Message object...} + } + ], + "session": {"session_id":"conversation-1","message_count":12}, + "truncated": false +} +``` + +削除済みrelation先では`message`の代わりに`message_id`と`"status":"deleted"`が返る。 +最大50 message相当またはresponse budget到達時は`truncated`がtrueになる。 + +### `sessions` view + +session一覧を時刻とIDの安定順序でpage取得する。`session_id`は使用しない。 + +```json +{ + "sessions": [ + { + "session_id": "conversation-1", + "message_count": 12, + "kind_counts": { + "conversation": 8, + "episode": 1, + "semantic": 2, + "procedure": 0, + "preference": 0, + "summary": 1 + }, + "representative_summary": "latest summary or content", + "started_at": 1720843200000, + "last_message_at": 1720846800000 + } + ], + "nextCursor": "optional opaque cursor" +} +``` + +## `search_messages` + +content、summary、tagsを検索し、scoreの高い順に返す。同scoreではimportance等がtie-breakに +使われる。search自体はmessageやaccess履歴を書き換えない。 + +### Input + +| Parameter | 必須 | 型 | Default | 説明 | +|---|---:|---|---:|---| +| `query` | Yes | string | — | 1～4096 UTF-8 bytes | +| `session_id` | No | string | 全session | 指定sessionだけを検索 | +| `filters_json` | No | string | `{}` | filter objectを表すJSON文字列 | +| `min_importance` | No | integer | 0 | 0～100 | +| `context_size` | No | integer | 0 | 各結果の前後message数、0～3 | +| `limit` | No | integer | 20 | 1～100 | + +`filters_json`の形式: + +```json +{ + "kinds": ["semantic", "preference"], + "tiers": ["mid", "long"], + "tags": ["project", "confirmed"] +} +``` + +argumentsとして渡す場合はescapeした文字列にする。 + +```json +{ + "query": "database decision", + "filters_json": "{\"kinds\":[\"semantic\"],\"tags\":[\"project\"]}", + "min_importance": 60, + "context_size": 1, + "limit": 10 +} +``` + +`kinds`と`tiers`は各配列内でOR、category間はANDとなる。`tags`は指定した全tagを持つmessage +だけが一致する。 + +### Output + +```json +{ + "results": [ + { + ...Message object fields..., + "score": 1.0, + "score_breakdown": {"content":1.0,"summary":0.0,"tags":0.0}, + "matched_fields": ["content"], + "relation_count": 0, + "context_preview": { + "before": [{...Message object...}], + "after": [{...Message object...}] + } + } + ] +} +``` + +`context_preview`は`context_size > 0`の場合だけ出力される。response budgetへ到達すると、 +`limit`未満でも後続結果が省略される。 + +## `delete_message` + +messageを論理削除し、直ちにread/search対象から除外する。 + +### Input + +| Parameter | 必須 | 型 | 説明 | +|---|---:|---|---| +| `message_id` | Yes | string | canonical 26文字ULID | +| `session_id` | No | string | 一致する場合だけ削除するsession guard | + +### Output + +削除した場合: + +```json +{"status":"OK"} +``` + +対象なし、削除済み、またはsession guard不一致の場合: + +```json +{"status":"NOT_FOUND"} +``` + +`NOT_FOUND`はapplication errorではない。本文がlogから物理的に除去されるのは +`rebuild_index`成功後である。 + +## `rebuild_index` + +parameterなし。live messageだけでlogをcompactし、snapshotとmemory indexを再構築する。 +同期処理のため、完了まで他requestを処理しない。 + +```json +{ + "status": "OK", + "messages_indexed": 120, + "records_removed": 35, + "bytes_before": 1048576, + "bytes_after": 524288 +} +``` + +## `get_system_health` + +parameterなし。永続化状態、logical I/O counter、memory estimateを返す。 + +```json +{ + "status": "OK", + "format_version": 2, + "log_size": 524288, + "snapshot_size": 262144, + "active_messages": 120, + "deleted_messages": 3, + "last_sequence": 150, + "update_records": 12, + "dead_bytes": 4096, + "memory_estimate": { + "total_bytes": 2097152, + "store_entries_bytes": 32768, + "body_bytes": 524288, + "metadata_bytes": 65536, + "search_index_bytes": 1048576, + "history_index_bytes": 131072, + "relation_index_bytes": 65536 + }, + "io": { + "write_bytes": 1048576, + "write_calls": 80, + "flush_calls": 20, + "truncate_calls": 0, + "replace_calls": 1 + }, + "recovered_tail": false, + "snapshot_valid": true, + "last_error": "" +} +``` + +`status`は`last_error`が空なら`OK`、診断messageが残っていれば`DEGRADED`となる。 +`memory_estimate`はprojectが管理する主要allocationの概算で、runtimeやallocator overheadは +含まない。 -- cgit v1.2.3