金大哥 - tana-mcp-codemode MCP 详情

article

README

🚀 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

📚 详细文档

配置

| 变量 | 默认值 | 描述 | | ---- | ---- | ---- | | TANA_API_TOKEN | （必需） | 来自 Tana 桌面版的令牌 | | TANA_API_URL | http://127.0.0.1:8262 | Tana 本地 API 的 URL | | TANA_TIMEOUT | 10000 | 请求超时时间（毫秒） | | TANA_HISTORY_PATH | （平台默认） | SQLite 历史数据库的自定义路径 | | MAIN_TANA_WORKSPACE | （无） | 默认工作区名称或 ID，在启动时解析 | | TANA_SEARCH_WORKSPACES | （无） | 用于默认搜索范围的工作区名称或 ID，用逗号分隔 |

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"
      }
    }
  }
}

| 客户端 | 配置位置 | | ---- | ---- | | Claude 桌面版 | claude_desktop_config.json | | Claude 代码版 | .mcp.json（项目）或 ~/.claude/settings.json（全局） | | Cursor / Windsurf | IDE 的 MCP 设置 |

如果从源代码安装，请使用 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 调试仪表板

工作原理

人工智能将 TypeScript 代码发送到 execute 工具。
executor.ts 创建一个支持顶级异步等待的 AsyncFunction。
代码在注入 tana 和 console 对象的环境中运行。
通过 Promise.race 设置 10 秒超时，防止挂起。
捕获并返回 console.log() 的输出。
将脚本运行记录保存到 SQLite 历史记录中。

脚本历史记录

运行记录会持久化到 SQLite 中： | 平台 | 位置 | | ---- | ---- | | macOS | ~/Library/Application Support/tana-mcp/history.db | | Windows | %APPDATA%/tana-mcp/history.db | | Linux | ~/.local/share/tana-mcp/history.db |

启动时会自动清理超过 30 天的旧记录。

保存内容

每次脚本运行会记录以下信息： | 字段 | 描述 | | ---- | ---- | | script | 执行的 TypeScript 代码 | | output | 捕获的 console.log() 输出 | | error | 执行失败时的错误信息 | | api_calls | 调用的 Tana API 方法 | | node_ids_affected | 读取/修改的节点 ID | | workspace_id | 使用的工作区 ID（如果检测到） | | duration_ms | 执行时间 |

开发

# 开发模式，实时监听文件变化
bun run dev

# 类型检查
bun run typecheck

# 根据 OpenAPI 规范重新生成 API 类型
bun run generate

# 运行调试服务器
bun run debug

📄 许可证

本项目采用 MIT 许可证。

tana-mcp-codemode