Tana MCP Codemode

🚀 Tana MCP Server

Tana MCP Server 是一個用於 Tana 知識管理的代碼模式 MCP 服務器。藉助人工智能編寫的 TypeScript 代碼，可針對 Tana 本地 API 執行操作。

🚀 快速開始

在使用 Tana MCP Server 之前，你需要滿足以下要求：

• Bun 運行時環境。
• 啟用本地 API 的 Tana 桌面版。
• 從 Tana 獲取 API 令牌（設置 → API → 生成令牌）。

✨ 主要特性

• 代碼模式：人工智能編寫可執行的 TypeScript 代碼，而非結構化的 API 調用。
• Tana 本地 API：支持工作區、節點、標籤、字段、日曆和導入功能。
• 頂級異步等待：可直接使用 await tana.workspaces.list() 進行操作。
• 超時保護：最大執行時間為 10 秒，防止無限循環。
• 腳本歷史記錄：使用 SQLite 持久化存儲，便於調試和重現。
• 重試邏輯：採用指數退避算法處理臨時故障。
• 調試界面：基於 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]]
`);

高級用法

調試界面

基於 WebSocket 的儀表板，用於測試腳本：

# 啟動調試服務器
bun run src/debug-server.ts

# 打開 http://localhost:3333

路由：

• http://localhost:3333/#debug — 腳本執行控制檯
• http://localhost:3333/#benchmark — 代碼模式與 tana-local 的性能比較

特性：

• 即時腳本執行
• 工作流事件時間線
• 錯誤顯示及建議
• 基準測試結果可視化（成本、速度、令牌使用情況）

工作流助手（僅調試界面可用）

使用時間線視圖跟蹤多步操作：

workflow.start("Processing nodes");
workflow.step("Fetching workspaces");
workflow.progress(5, 100, "Processing");
workflow.complete("Done!");
// 或者：workflow.abort("Error message");

⚠️ 重要提示

workflow 僅在調試界面中可用，在生產環境的 MCP 提示中不會暴露。

構建 React 界面（可選）

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 調試界面
├── 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. 人工智能將 TypeScript 代碼發送到 execute 工具。
2. executor.ts 創建一個支持頂級異步等待的 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

📄 許可證

本項目採用 MIT 許可證。