mcp-tabula-api 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -0
- package/dist/index.js +31284 -0
- package/dist/index.sdk.js +28588 -0
- package/package.json +34 -0
package/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# mcp-tabula-api
|
|
2
|
+
|
|
3
|
+
**あなたのローカル Tabula を、クラウド AI（Claude など）から操作させるためのブリッジ MCP サーバー。**
|
|
4
|
+
|
|
5
|
+
AI は直接ファイルを触りません。すべて Tabula の **Headless API（`:14211`）** 経由で、
|
|
6
|
+
Tabula アプリの `vault_mutate` チョークポイント（監査 substrate）を通ります。
|
|
7
|
+
＝「この門を通らない vault の変更は存在しない」を保ったまま AI に編集させられます。
|
|
8
|
+
|
|
9
|
+
## 🔧 公開ツール
|
|
10
|
+
| ツール | 役割 |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `tabula_read` | ノートを読む |
|
|
13
|
+
| `tabula_write` | ノートを書く（overwrite / append / replace / move / mkdir / delete） |
|
|
14
|
+
| `tabula_copy` / `tabula_cut` | コピー / 切り取り |
|
|
15
|
+
| `tabula_eye` | vault の構造を一望 |
|
|
16
|
+
| `tabula_find` | ファイル名をファジー検索 |
|
|
17
|
+
| `tabula_grep` | 全文検索 |
|
|
18
|
+
|
|
19
|
+
書き込み系（`tabula_write` 等）は必ず Headless API `POST /api/notes` を通る＝監査ログに残る。
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🚀 AI に接続する
|
|
24
|
+
|
|
25
|
+
### 1. 前提
|
|
26
|
+
- **Tabula アプリが起動していること**（Headless API `:14211` が上がっている）。
|
|
27
|
+
- **API キーを取得**: Tabula → **設定 → Headless API** → キーをコピー。
|
|
28
|
+
（このキーは再発行できます。どの AI に渡したかはあなたが管理します。）
|
|
29
|
+
|
|
30
|
+
### 2. AI クライアントに登録する
|
|
31
|
+
キーは **env `TABULA_API_KEY` で渡します**（全 OS・全 MCP クライアント共通）。
|
|
32
|
+
|
|
33
|
+
**Claude Code**（`~/.claude.json` の `mcpServers`）:
|
|
34
|
+
```jsonc
|
|
35
|
+
{
|
|
36
|
+
"mcpServers": {
|
|
37
|
+
"tabula": {
|
|
38
|
+
"type": "stdio",
|
|
39
|
+
"command": "bunx",
|
|
40
|
+
"args": ["-y", "mcp-tabula-api"],
|
|
41
|
+
"env": { "TABULA_API_KEY": "<コピーしたキー>" }
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Claude Desktop**（`claude_desktop_config.json`）も同じ形（`command`/`args`/`env`）。
|
|
48
|
+
Cursor など他の MCP 対応クライアントでも、同じキーを `env` に入れれば繋がります。
|
|
49
|
+
|
|
50
|
+
> `TABULA_API_URL` は未指定なら `http://127.0.0.1:14211`（既定のローカル Tabula）。
|
|
51
|
+
> 別ホスト/ポートの Tabula を叩くときだけ `env` に足してください。
|
|
52
|
+
|
|
53
|
+
### 3. OS ごとの注意（キーの渡し方）
|
|
54
|
+
- **キーを渡す正規ルートは `TABULA_API_KEY` env で全 OS 共通**です。
|
|
55
|
+
- **Linux のおまけ**: env が無ければ GNOME キーリング（`secret-tool`, service=`tabula-headless-api` / username=`api-key`。Tabula アプリが自動で保存）から拾います。
|
|
56
|
+
- **macOS / Windows**: それぞれの Keychain / Credential Manager は `secret-tool` で読めないため、**env での指定が必要**です。
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## ⚙️ 環境変数
|
|
61
|
+
| 変数 | 既定 | 用途 |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `TABULA_API_KEY` | （必須※Linux は keyring fallback 可） | Headless API の `x-api-key` |
|
|
64
|
+
| `TABULA_API_URL` | `http://127.0.0.1:14211` | Tabula Headless API の場所 |
|
|
65
|
+
| `MCP_TRANSPORT` | `stdio` | `stdio` または `http`（`/mcp` stateless + `/sse` stateful） |
|
|
66
|
+
| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8080` | http transport 時のバインド先 |
|
|
67
|
+
| `MCP_ALLOWED_DIR` | （未設定） | Jail: 指定ディレクトリ外へのアクセスを MCP 層でブロック |
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 🔒 セキュリティ
|
|
72
|
+
- **監査経路の維持**: vault への書き込みは必ず Tabula の Headless API（＝`vault_mutate` チョークポイント）を通る。この MCP は fs 直書きをしない。
|
|
73
|
+
- **Jail**: `MCP_ALLOWED_DIR` を設定すると、LLM によるパストラバーサルを MCP Gateway 層で一括ブロック（`src/utils/security.ts`）。
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## 🛠 開発
|
|
78
|
+
```bash
|
|
79
|
+
bun run start # stdio で起動
|
|
80
|
+
bun run start:http # http (:8080) で起動
|
|
81
|
+
bun run build # dist/ に node ターゲットでビルド（publish 前）
|
|
82
|
+
bun run inspector # MCP Inspector で対話デバッグ
|
|
83
|
+
```
|
|
84
|
+
- ツール定義は `src/mcp.ts` のみ編集（インフラ層 `src/index.ts` は触らない）。
|
|
85
|
+
- Headless API クライアントは `src/utils/tabula-api.ts`。設計は `ARCHITECTURE.md`。
|
|
86
|
+
|
|
87
|
+
## 📦 デプロイ形態（3段）
|
|
88
|
+
|
|
89
|
+
**① 個人（既定）= stdio**
|
|
90
|
+
`bunx -y mcp-tabula-api` で叩けるよう `bin` / `files` / `prepublishOnly`(build) を用意済み。
|
|
91
|
+
Docker 不要・ユーザーの Tabula と自動的に同じマシン・軽い。配布のデフォルトはこれ。
|
|
92
|
+
（private 運用なら `command: "bun", args: ["run", "<path>/src/index.ts"]` 直指定でも可。）
|
|
93
|
+
|
|
94
|
+
**② インフラを持つ人 = Docker / HTTP（任意）**
|
|
95
|
+
`Dockerfile` + `docker-compose.yml` + http transport（`MCP_TRANSPORT=http`、`/mcp` `/sse`）で
|
|
96
|
+
常駐 HTTP MCP として動かせる。ただし **この MCP は「その Tabula の :14211」1つを指す**ので、
|
|
97
|
+
コンテナは Tabula と同居（`host.docker.internal:14211` / host network）か、LAN 越しに届く位置に置くこと。
|
|
98
|
+
env は keyring を持てないので `TABULA_API_KEY` で渡す（＝本 MCP のキー方針とそのまま噛む）。
|
|
99
|
+
|
|
100
|
+
**③ 会社・チーム導入 = 【あとでやる・要求ドリブン】**
|
|
101
|
+
> ⚠️ **注意（後で着手する時の勘所）**: 「一台コンテナで複数人」は、各人の**個人デスクトップ
|
|
102
|
+
> Tabula を橋渡し**する話ではない。一台の MCP は一つの `TABULA_API_URL` を指すので、成立するのは
|
|
103
|
+
> **チーム共有の Tabula が1インスタンス（共有 vault）動いている時だけ**。つまり会社導入の本丸は
|
|
104
|
+
> MCP コンテナでなく **「Tabula を個人デスクトップアプリ → ヘッドレス共有サーバ（1 vault 常駐）に
|
|
105
|
+
> する」一段大きい製品形態**。芋づるで要るもの: **マルチテナント認証**（今の Headless API はキー
|
|
106
|
+
> 1本＝単一テナント → 人ごとの key/actor）・**監査の多人数化**（`vault_mutate` journal を複数
|
|
107
|
+
> actor で記録）・権限/競合。これは組織レーンの有料デプロイ（audit が paywall）に地続き。
|
|
108
|
+
> **要求が出るまで着手しない**（YAGNI）。来たら「共有サーバ + 多人数 audit」から入ること。
|