3.1.1 • Published yesterdayCLI

mcp-tabula-api

Licence

MIT

Version

3.1.1

Deps

Size

1.0 MB

Vulns

Weekly

Summary Dependency Versions

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。

① 個人（既定）= 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」から入ること。