path: root/docs/mcp.md

# 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"
  }
}
```

`metadata_json`の検証errorでは、`error.message`に問題のあるfield名と制約が含まれる。
入力値そのものはmessageへ転載されない。allocation失敗は`INTERNAL_ERROR`として区別される。

主な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、content、context、sessionsの4種類を返す。`view`省略時は`history`。

### 共通Input

| Parameter | 必須 | 型 | 説明 |
|---|---:|---|---|
| `view` | No | string | `history` / `content` / `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`を渡す。

### `content` view

live message 1件のcontentを、保存状態を変更せずにUTF-8 byte rangeで取得する。MCP hostの
tool-result上限を避けるため、`next_content_offset`を使って末尾まで反復する。

追加parameter:

| Parameter | 必須 | 型 | Default | 説明 |
|---|---:|---|---:|---|
| `message_id` | Yes | string | — | 対象の26文字ULID |
| `content_offset` | No | integer | 0 | UTF-8 byte offset。0、末尾、またはcode point境界 |
| `content_limit` | No | integer | 4096 | 目標chunk bytes、1～65536 |
| `expected_revision` | No | integer | — | 指定時は現在revisionとの一致を要求 |

```json
{
  "content_range": {
    "message_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "revision": 1,
    "total_bytes": 14420,
    "content_offset": 4096,
    "next_content_offset": 8191,
    "complete": false,
    "content": "..."
  }
}
```

`complete`がfalseなら、同じ`message_id`、返された`next_content_offset`、最初のresponseで得た
`revision`を`expected_revision`として次を取得する。limit位置がUTF-8 code point途中なら、
通常は直前の境界まで短くする。limitが1 code pointより小さい場合だけ、その1文字を完全に
返すため最大3 bytes超えることがある。

messageが存在しないか削除済みなら`NOT_FOUND`、offsetが範囲外またはUTF-8境界でなければ
`VALIDATION_ERROR`、`expected_revision`不一致なら`CONFLICT`を返す。このviewはlogical I/O
counterを含む永続状態を変更しない。

### `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`は使用しない。
`limit`到達時に加え、response budgetへ到達した場合もそこでpageを終了し、続きがあれば
`nextCursor`を返す。`representative_summary`の内容は短縮されない。

```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,
  "session_count": 18,
  "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`となる。
`session_count`は現在live messageを持つsessionの数で、memory上のhistory indexから集計される。
`memory_estimate`はprojectが管理する主要allocationの概算で、runtimeやallocator overheadは
含まない。