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 许可证。