mcp-tabula-api

あなたのローカル Tabula を、クラウド AI（Claude など）から操作させるためのブリッジ MCP サーバー。

AI は直接ファイルを触りません。すべて Tabula の Headless API（:14211） 経由で、 Tabula アプリの vault_mutate チョークポイント（監査 substrate）を通ります。 ＝「この門を通らない vault の変更は存在しない」を保ったまま AI に編集させられます。

🔧 公開ツール

| ツール | 役割 | |---|---| | tabula_read | ノートを読む | | tabula_write | ノートを書く（overwrite / append / replace / move / mkdir / delete） | | tabula_copy / tabula_cut | コピー / 切り取り | | tabula_eye | vault の構造を一望 | | tabula_find | ファイル名をファジー検索 | | tabula_grep | 全文検索 |

書き込み系（tabula_write 等）は必ず Headless API POST /api/notes を通る＝監査ログに残る。

🚀 AI に接続する

1. 前提

• Tabula アプリが起動していること（Headless API :14211 が上がっている）。
• API キーを取得: Tabula → 設定 → Headless API → キーをコピー。 （このキーは再発行できます。どの AI に渡したかはあなたが管理します。）

2. AI クライアントに登録する

キーは env TABULA_API_KEY で渡します（全 OS・全 MCP クライアント共通）。

Claude Code（~/.claude.json の mcpServers）:

{
  "mcpServers": {
    "tabula": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "mcp-tabula-api"],
      "env": { "TABULA_API_KEY": "<コピーしたキー>" }
    }
  }
}

Claude Desktop（claude_desktop_config.json）も同じ形（command/args/env）。 Cursor など他の MCP 対応クライアントでも、同じキーを env に入れれば繋がります。

TABULA_API_URL は未指定なら http://127.0.0.1:14211（既定のローカル Tabula）。 別ホスト/ポートの Tabula を叩くときだけ env に足してください。

3. OS ごとの注意（キーの渡し方）

• キーを渡す正規ルートは TABULA_API_KEY env で全 OS 共通です。
• Linux のおまけ: env が無ければ GNOME キーリング（secret-tool, service=tabula-headless-api / username=api-key。Tabula アプリが自動で保存）から拾います。
• macOS / Windows: それぞれの Keychain / Credential Manager は secret-tool で読めないため、env での指定が必要です。

⚙️ 環境変数

| 変数 | 既定 | 用途 | |---|---|---| | TABULA_API_KEY | （必須※Linux は keyring fallback 可） | Headless API の x-api-key | | TABULA_API_URL | http://127.0.0.1:14211 | Tabula Headless API の場所 | | MCP_TRANSPORT | stdio | stdio または http（/mcp stateless + /sse stateful） | | MCP_HOST / MCP_PORT | 127.0.0.1 / 8080 | http transport 時のバインド先 | | MCP_ALLOWED_DIR | （未設定） | Jail: 指定ディレクトリ外へのアクセスを MCP 層でブロック |

🔒 セキュリティ

• 監査経路の維持: vault への書き込みは必ず Tabula の Headless API（＝vault_mutate チョークポイント）を通る。この MCP は fs 直書きをしない。
• Jail: MCP_ALLOWED_DIR を設定すると、LLM によるパストラバーサルを MCP Gateway 層で一括ブロック（src/utils/security.ts）。

🛠 開発

bun run start           # stdio で起動
bun run start:http      # http (:8080) で起動
bun run build           # dist/ に node ターゲットでビルド（publish 前）
bun run inspector       # MCP Inspector で対話デバッグ

• ツール定義は src/mcp.ts のみ編集（インフラ層 src/index.ts は触らない）。
• Headless API クライアントは src/utils/tabula-api.ts。設計は ARCHITECTURE.md。

📦 デプロイ形態（3段）

① 個人（既定）= stdio bunx -y mcp-tabula-api で叩けるよう bin / files / prepublishOnly(build) を用意済み。 Docker 不要・ユーザーの Tabula と自動的に同じマシン・軽い。配布のデフォルトはこれ。 （private 運用なら command: "bun", args: ["run", "<path>/src/index.ts"] 直指定でも可。）

② インフラを持つ人 = Docker / HTTP（任意） Dockerfile + docker-compose.yml + http transport（MCP_TRANSPORT=http、/mcp /sse）で 常駐 HTTP MCP として動かせる。ただし この MCP は「その Tabula の :14211」1つを指すので、 コンテナは Tabula と同居（host.docker.internal:14211 / host network）か、LAN 越しに届く位置に置くこと。 env は keyring を持てないので TABULA_API_KEY で渡す（＝本 MCP のキー方針とそのまま噛む）。

③ 会社・チーム導入 = 【あとでやる・要求ドリブン】

⚠️ 注意（後で着手する時の勘所）: 「一台コンテナで複数人」は、各人の個人デスクトップ Tabula を橋渡しする話ではない。一台の MCP は一つの TABULA_API_URL を指すので、成立するのは チーム共有の Tabula が1インスタンス（共有 vault）動いている時だけ。つまり会社導入の本丸は MCP コンテナでなく 「Tabula を個人デスクトップアプリ → ヘッドレス共有サーバ（1 vault 常駐）に する」一段大きい製品形態。芋づるで要るもの: マルチテナント認証（今の Headless API はキー 1本＝単一テナント → 人ごとの key/actor）・監査の多人数化（vault_mutate journal を複数 actor で記録）・権限/競合。これは組織レーンの有料デプロイ（audit が paywall）に地続き。 要求が出るまで着手しない（YAGNI）。来たら「共有サーバ + 多人数 audit」から入ること。