Tana MCP Codemode

🚀 Tana MCP Server

Tanaの知識管理用のコードモードMCPサーバーです。AIがTana Local APIに対して実行するTypeScriptコードを生成します。

✨ 主な機能

• コードモードパターン — AIが構造化されたAPI呼び出しではなく、実行可能なTypeScriptを生成します。
• Tana Local API — ワークスペース、ノード、タグ、フィールド、カレンダー、インポート機能をサポートします。
• トップレベルのawait — await tana.workspaces.list() を直接使用できます。
• タイムアウト保護 — 最大10秒の実行時間制限で無限ループを防止します。
• スクリプト履歴 — デバッグと再実行のためにSQLiteに保存されます。
• リトライロジック — 一時的なエラーに対して指数関数的なバックオフを行います。
• デバッグUI — WebSocketベースのダッシュボードでスクリプトをテストできます。

📦 インストール

オプション1: bun (推奨)

# Bunランタイムが必要です
bun add -g tana-mcp-codemode

オプション2: ソースからインストール

git clone https://github.com/fabiogaliano/tana-mcp-codemode
cd tana-mcp-codemode
bun install

🔧 設定

MCP統合

MCPクライアントの設定に追加します。

{
  "mcpServers": {
    "tana": {
      "command": "tana-mcp-codemode",
      "env": {
        "TANA_API_TOKEN": "your_token_here",
        // オプション
        "MAIN_TANA_WORKSPACE": "My Workspace",
        "TANA_SEARCH_WORKSPACES": "My Workspace",
        // オプション: SQLiteの履歴データベースの保存場所をカスタマイズ
        "TANA_HISTORY_PATH": "/path/to/history.db"
      }
    }
  }
}

ソースからインストールした場合、bun をコマンドとして使用します。

{
  "mcpServers": {
    "tana": {
      "command": "bun",
      "args": ["run", "/path/to/tana-mcp-codemode/src/index.ts"],
      "env": {
        "TANA_API_TOKEN": "your_token_here",
        // オプション
        "MAIN_TANA_WORKSPACE": "My Workspace",
        "TANA_SEARCH_WORKSPACES": "My Workspace",
        // オプション: SQLiteの履歴データベースの保存場所をカスタマイズ
        "TANA_HISTORY_PATH": "/path/to/history.db"
      }
    }
  }
}

💻 使用例

ノードの検索

const results = await tana.nodes.search({
  textContains: "meeting notes"
});
console.log("Found:", results.length, "nodes");

複雑なクエリ

const tasks = await tana.nodes.search({
  and: [
    { hasType: "taskTagId" },
    { is: "todo" },
    { created: { last: 7 } }
  ]
});
console.log({ tasks });

コンテンツのインポート

await tana.import(parentNodeId, `
- Project Alpha #[[^projectTagId]]
  - [[^statusFieldId]]:: Active
  - [[^dueDateFieldId]]:: [[date:2024-03-15]]
`);

デバッグUI

WebSocketベースのダッシュボードでスクリプトをテストできます。

# デバッグサーバーを起動
bun run src/debug-server.ts

# http://localhost:3333 を開く

ルート:

• http://localhost:3333/#debug — スクリプト実行コンソール
• http://localhost:3333/#benchmark — コードモードとtana-localのパフォーマンス比較

機能:

• リアルタイムのスクリプト実行
• ワークフローイベントのタイムライン
• エラー表示と提案
• ベンチマーク結果の可視化 (コスト、速度、トークン使用量)

ワークフローヘルパー (デバッグUIのみ)

タイムラインビューで多段階の操作を追跡します。

workflow.start("Processing nodes");
workflow.step("Fetching workspaces");
workflow.progress(5, 100, "Processing");
workflow.complete("Done!");
// または: workflow.abort("Error message");

注意: workflow はデバッグUIでのみ使用できます。本番環境のMCPプロンプトでは公開されていません。

React UIのビルド (オプション)

cd ui
bun install
bun run build
cd ..
bun run src/debug-server.ts

🔧 技術詳細

src/
├── index.ts              # MCPサーバーのエントリーポイント
├── prompts.ts            # ツールの説明
├── types.ts              # TypeScriptのインターフェース
├── debug-server.ts       # WebSocketデバッグUI
├── api/
│   ├── client.ts         # HTTPクライアント (認証、リトライ、タイムアウト)
│   ├── tana.ts           # APIラッパー → `tana` オブジェクト
│   └── types.ts          # APIの型定義
├── sandbox/
│   ├── executor.ts       # コード実行エンジン
│   └── workflow.ts       # 進捗追跡
├── storage/
│   └── history.ts        # SQLiteのスクリプト履歴
└── generated/
    └── api.d.ts          # 生成されたOpenAPIの型

ui/                       # Reactデバッグダッシュボード

動作原理

1. AIが execute ツールにTypeScriptコードを送信します。
2. executor.ts がトップレベルのawaitをサポートするAsyncFunctionを作成します。
3. コードは注入された tana と console オブジェクトを使用して実行されます。
4. Promise.raceを使用した10秒のタイムアウトでハングを防止します。
5. console.log() の出力がキャプチャされて返されます。
6. スクリプトの実行結果がSQLiteの履歴に保存されます。

スクリプト履歴

実行結果はSQLiteに保存されます。

30日以上前の実行結果は起動時に自動的に削除されます。

保存される内容

各スクリプトの実行結果には以下の情報が記録されます。

開発

# ウォッチモードで開発
bun run dev

# 型チェック
bun run typecheck

# OpenAPI仕様からAPIの型を再生成
bun run generate

# デバッグサーバーを実行
bun run debug

📚 詳細ドキュメント

サーバーは単一の execute ツールを公開しています。AIは tana オブジェクトにアクセスできるTypeScriptコードを生成します。

ワークスペース

const workspaces = await tana.workspaces.list();
// → Workspace[] (id, name, homeNodeId)

ノード

await tana.nodes.search(query, options?)     // → SearchResult[]
await tana.nodes.read(nodeId, maxDepth?)     // → string (markdown)
await tana.nodes.getChildren(nodeId, opts?)  // → { children, total, hasMore }
await tana.nodes.edit({ nodeId, name?, description? })
await tana.nodes.trash(nodeId)
await tana.nodes.check(nodeId)               // 完了としてマーク
await tana.nodes.uncheck(nodeId)             // 未完了としてマーク

タグ (スーパータグ)

await tana.tags.listAll(workspaceId)              // すべてのワークスペースのスーパータグ (ページネーション)
await tana.tags.getSchema(tagId, opts?)            // opts: { includeInheritedFields? }
await tana.tags.modify(nodeId, action, tagIds)     // action: "add" | "remove"
await tana.tags.create({ workspaceId, name, description?, extendsTagIds?, showCheckbox? })
await tana.tags.addField({ tagId, name, dataType, ... })
await tana.tags.setCheckbox({ tagId, showCheckbox, doneStateMapping? })

フィールド

await tana.fields.setOption(nodeId, attributeId, optionId)   // ドロップダウンフィールド
await tana.fields.setContent(nodeId, attributeId, content)   // テキスト/日付/URLフィールド

カレンダー

await tana.calendar.getOrCreate(workspaceId, granularity, date?)
// granularity: "day" | "week" | "month" | "year"

インポート (Tana Paste)

await tana.import(parentNodeId, tanaPasteContent)
// → { success, nodeIds?, error? }

ユーティリティ

tana.workspace                // 事前に解決されたデフォルトのワークスペース (MAIN_TANA_WORKSPACEから) または null
tana.format(data)             // 任意のAPIレスポンスのコンパクトな表示
await tana.health()           // → { status: "ok" }

📄 ライセンス

MIT