金大哥 - heptabase-mcp MCP 详情

article

README

🚀 @heptabase/mcp

这是一个用于与 Heptabase 备份数据进行交互的模型上下文协议（MCP）服务。该服务允许像 Claude 这样的 AI 助手搜索、检索、分析和导出 Heptabase 白板和卡片。

🚀 快速开始

安装与设置

克隆并安装：

git clone <repository-url>
cd heptabase-mcp
npm install

使用环境变量进行配置：

cp .env.example .env
# 使用实际路径编辑 .env

构建项目：
```
npm run build
```
本地测试（可选）：
```
npm start
```

与 Claude Desktop 配合使用

配置 Claude Desktop 以使用本地构建版本：

编辑 Claude Desktop 配置文件：

macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "heptabase": {
      "command": "/path/to/node",
      "args": ["/path/to/your/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}

重要提示：

将 /path/to/node 替换为你的 Node.js 路径（使用 which node 查找）
将 /path/to/your/heptabase-mcp 替换为你的实际项目路径
将 HEPTABASE_BACKUP_PATH 设置为你的 Heptabase 备份目录

详细设置说明请参阅 QUICK_START.md。

配置

本项目使用了安全的隐私配置系统：

示例文件（可安全提交到 git）：claude-config-example.json、.env.example
个人文件（被 git 忽略）：claude-config-*personal*.json、.env

详细配置说明请参阅 CONFIG.md。

基本用法

// 配置备份路径
await mcpClient.callTool({
  name: "configureBackupPath",
  parameters: {
    path: "/path/to/your/heptabase/backups"
  }
});

// 列出可用的备份
const backups = await mcpClient.callTool({
  name: "listBackups"
});

// 搜索白板
const whiteboards = await mcpClient.callTool({
  name: "searchWhiteboards",
  parameters: {
    query: "Project Planning"
  }
});

// 获取完整的白板内容
const whiteboard = await mcpClient.callTool({
  name: "getWhiteboard",
  parameters: {
    whiteboardId: "your-whiteboard-id",
    includeCards: true,
    includeConnections: true
  }
});

// 导出为 Markdown 格式
const markdown = await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: {
    whiteboardId: "your-whiteboard-id",
    format: "markdown"
  }
});

✨ 主要特性

🔍 搜索白板和卡片
📁 自动备份文件管理
📄 导出为多种格式（Markdown、JSON、Mermaid）
🔗 分析卡片关系
📊 生成白板摘要
⚡ 智能缓存以提高性能

📦 可用工具

备份管理

configureBackupPath - 设置备份目录
listBackups - 列出可用的备份
loadBackup - 加载特定的备份

搜索操作

searchWhiteboards - 按名称或内容搜索白板
searchCards - 在所有白板中搜索卡片

数据检索

getWhiteboard - 获取完整的白板数据
getCard - 以多种格式获取卡片内容
getCardContent - 以资源形式获取卡片内容（绕过大小限制）
getCardsByArea - 根据白板上的位置查找卡片

导出功能

exportWhiteboard - 导出为 Markdown、JSON、HTML 格式
summarizeWhiteboard - 生成由 AI 驱动的摘要

分析工具

analyzeGraph - 分析卡片关系和连接
compareBackups - 比较不同的备份版本

调试工具

debugInfo - 获取系统状态和诊断信息

📚 详细文档

📚 完整规范 - 详细的 API 和架构说明
🚀 快速入门指南 - 快速上手
⚙️ 配置指南 - 安全的配置实践
📖 Claude Desktop 设置 - 本地开发设置

🔧 技术细节

项目结构

heptabase-mcp/
├── src/
│   ├── index.ts              # 主入口点
│   ├── server.ts             # MCP 服务器实现
│   ├── services/             # 核心业务逻辑
│   │   ├── BackupManager.ts  # 备份文件管理
│   │   └── HeptabaseDataService.ts # 数据查询
│   ├── tools/                # MCP 工具实现
│   ├── types/                # TypeScript 定义
│   └── utils/                # 辅助函数
├── tests/                    # 测试套件
├── docs/                     # 文档
└── config files              # 配置模板

测试

# 运行所有测试
npm test

# 以监视模式运行测试
npm run test:watch

# 运行并生成覆盖率报告
npm run test:coverage

# 运行集成测试
npm run test:integration

构建

# 生产环境构建
npm run build

# 开发模式，自动重新加载
npm run dev

# 仅进行类型检查
npm run type-check

📄 许可证

本项目采用 MIT 许可证，详细信息请参阅 LICENSE 文件。

⚠️ 隐私与安全

本项目遵循隐私设计原则：

✅ 个人路径从不提交到 git
✅ 备份数据保留在本地机器上
✅ 配置模板使用安全的占位符
✅ .gitignore 保护敏感文件

📋 要求

Node.js 18+
Heptabase 启用备份导出功能
Claude Desktop（用于 MCP 集成）

🛠️ 故障排除

常见问题

“未找到备份” - 检查 HEPTABASE_BACKUP_PATH 是否指向正确的目录
“命令未找到” - 确保已安装 Node.js 且路径正确
Claude 看不到工具 - 配置更改后完全重启 Claude Desktop
构建错误 - 在使用前运行 npm install 和 npm run build

调试模式

使用 debugInfo 工具检查系统状态：

await mcpClient.callTool({ name: "debugInfo" });

🤝 贡献

欢迎贡献代码！请按以下步骤操作：

分叉仓库
创建功能分支
进行更改
为新功能添加测试
确保所有测试通过
提交拉取请求

架构详细信息请参阅 SPECIFICATION.md。

📞 支持

🐛 报告 bug：GitHub Issues
💬 提问：GitHub Discussions
📧 安全问题：请私下报告

为 Heptabase 社区精心打造 ❤️

heptabase-mcp