---
title: MCP サーバ
description: zanei mcp が公開する read-only な MCP（Model Context Protocol）サーバ — ツール・スキーマ・エラー・登録方法。
---

`zanei mcp` は記録された行動履歴を MCP クライアントへ公開します — ターミナル型 agent（Claude Code・Codex・opencode・Hermes Agent）と、シェルを持たないクライアント（Claude Desktop・ChatGPT コネクタ）の接続経路です。

| | |
| --- | --- |
| サーバ名 | `zanei` |
| 起動コマンド | `zanei mcp` |
| トランスポート | stdio のみ（stdin/stdout 上の JSON-RPC 2.0）— **ネットワーク面ゼロ** |
| capability | `tools` のみ。`resources` / `prompts` は未提供（[将来拡張](#将来拡張)参照） |

**役割と境界。** サーバはローカルストアへの**read-only ビュー**です。記録デーモンとは独立プロセスで動き、記録の開始・停止も、設定変更も — 特に [capture-time フィルタ](/ja/guides/filters)の変更も — できません。`query_events` の `app` / `bundle_id` は保存済みデータへの query-time の絞り込みであり、プライバシー境界ではありません。

共有規約 — 時間表現・イベント型・イベントエンベロープ — は [CLI リファレンス](/ja/reference/cli#共通規約)と[イベントリファレンス](/ja/reference/events)に一致します。

## ツール

3 つのツールはすべて読み取り専用・副作用なしです。

### `get_timeline`

指定範囲の LLM-ready タイムラインを返します。`zanei timeline` と等価。agent が最もよく呼ぶツールです。

**入力**

| パラメータ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `since` | string | `"1h"` | 遡り開始。相対（`15m`・`2h`・`1d`）または RFC3339 |
| `until` | string | `now` | 終了 |
| `format` | `"markdown"` または `"structured"` | `"markdown"` | 出力の形 |
| `token_budget` | integer | `4000` | 概算トークン上限。超過分は粒度を粗くして収める |
| `granularity` | `"coarse"` または `"fine"` | `"coarse"` | セッション単位か操作単位か |

**出力**（`format: "markdown"`）

```json
{
  "range": { "since": "2026-08-16T08:00:00Z", "until": "2026-08-16T09:00:00Z" },
  "format": "markdown",
  "content": "## 08:12-08:31 Safari — PR #42 のレビュー\n- GitHub で 3 ファイルを閲覧\n- コメントを 2 件記入\n...",
  "token_estimate": 3810,
  "truncated": false
}
```

`format: "structured"` の場合、結果は [CLI リファレンス](/ja/reference/cli#timeline)の `timeline --format json` と同一の `sessions[]` 構造です。

### `query_events`

条件に合う生イベントを返します。`zanei query` と等価。粒度の細かい検証や、特定アプリ・型の抽出に使います。

**入力**

| パラメータ | 型 | 既定値 | 説明 |
| --- | --- | --- | --- |
| `since` | string | `"15m"` | 遡り開始 |
| `until` | string | `now` | 終了 |
| `types` | string[] | — | [イベント型](/ja/reference/events)。`browser.*` 等のワイルドカード可 |
| `app` | string | — | アプリ名で絞り込み |
| `bundle_id` | string | — | バンドル ID で絞り込み |
| `limit` | integer | `200`（最大 `1000`） | 最大件数 |

**出力**

```json
{
  "range": { "since": "2026-08-16T08:45:00Z", "until": "2026-08-16T09:00:00Z" },
  "count": 42,
  "truncated": false,
  "events": [
    {
      "v": 1, "id": "evt_01J...", "ts": "2026-08-16T08:46:12.120Z", "mono_ns": 128374651234,
      "source": "macos.applescript", "type": "browser.navigate",
      "app": { "name": "Google Chrome", "bundle_id": "com.google.Chrome", "pid": 501 },
      "window": { "title": "PR #42", "id": 42 },
      "element": null,
      "data": { "url": "https://github.com/...", "tab_title": "PR #42", "mode": "normal" },
      "redaction": { "applied": false, "rules": [] }
    }
  ]
}
```

`limit` を超えた場合は `truncated: true`。イベント内容は捕捉時点で既にプライバシー処理（secure field 除外・redaction）済みのものが格納されています — MCP 層で除外済みの情報が復元されることはありません。

### `get_status`

agent 向けの軽量チェック：記録は動いているか。`zanei status` のサブセットです。

**入力**：なし（`{}`）

**出力**

```json
{
  "running": true,
  "paused": false,
  "last_event_ts": "2026-08-16T08:59:58Z",
  "events_dropped": 2,
  "degraded": { "eventtap": "1 degraded collector operation observed" },
  "retention_hours": 48,
  "oldest_event_ts": "2026-08-14T09:00:00Z",
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false },
  "permissions_ok": true
}
```

| フィールド | 意味 |
| --- | --- |
| `events_dropped` | collector または記録 pipeline が破棄したイベントの累計 |
| `degraded` | component ごとの collector / runtime 劣化状態。既知の劣化がなければ空 |
| `permissions_ok` | heartbeat が新鮮な間は実行中 recorder 自身の権限判定。recorder 不在時はローカル probe の結果 |

`running: false` を見た agent は、何もないところから答えるのではなく「PC 操作履歴は現在記録されていない」とユーザーに伝えられます。

## エラー

| 状況 | 挙動 |
| --- | --- |
| ストア未初期化 / 記録未実施 | `get_status` が `running: false` を返す（エラーにしない）。`get_timeline` / `query_events` は空結果 |
| 権限不足による空 | 空結果。`get_status` の `permissions_ok: false` で判別可能 |
| 引数不正（不正な時間表現等） | JSON-RPC エラー（invalid params） |

MCP サーバは記録の開始も権限付与も行いません。権限問題の解決経路は CLI の `zanei doctor` です（同梱の skill にも明記されています）。

## 登録方法

`zanei setup --agent <name>` が以下をすべて自動化します — クライアント別の手順は [agent セットアップ](/ja/agents/setup)を参照。stdio サーバ共通の JSON 形：

```json
{
  "mcpServers": {
    "zanei": {
      "command": "zanei",
      "args": ["mcp"]
    }
  }
}
```

## 将来拡張

現在は未提供です。いずれも同じ read-only ストアビューの上に増設され、記録デーモンへの書き込み権限は将来も追加されません：

- **resources** — 直近タイムラインや現在の設定を read-only リソースとして公開（resources を好むクライアント向け）。
- **prompts** — 「作業を再開する」定型プロンプトのサーバ提供。
- **notifications** — 新規セッション検出時の push（需要が出れば）。

## セキュリティ境界

- サーバ自体は外部送信を行いません（stdio のみ）。
- ツール結果を受け取った agent がそれを LLM プロバイダへ送るのは **agent 側の責務**です。PC 操作履歴の機微性を踏まえ、同梱の skill ファイルは送信前に対象範囲を絞るよう agent に指示しています。
- ストア内容は捕捉時点でプライバシー処理済みです。既定の `text_content: false` では、入力内容はそもそもストアに存在しません。