@heptabase/mcp

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

功能

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

快速开始

安装和设置

1. 克隆并安装：

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

2. 使用环境变量进行配置：

   cp .env.example .env
   # 编辑.env文件，填写实际路径
   

3. 构建项目：

   npm run build
   

4. 本地测试（可选）：

   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/hept/pebase-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"
  }
});

可用工具

备份管理

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

搜索操作

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

数据检索

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

导出功能

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

分析工具

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

调试工具

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

开发

项目结构

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

文档

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

隐私与安全

该项目遵循设计时考虑隐私的原则：

• ✅ 个人路径从不提交到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" });

贡献

欢迎贡献！请：

1. 分叉仓库
2. 创建功能分支
3. 进行修改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

详情参见SPECIFICATION.md中的架构细节。

许可证

MIT许可证 - 详情参见LICENSE文件。

支持

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

---

为Heptabase社区制作 ❤️