Heptabase MCP

🚀 @heptabase/mcp

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

🚀 快速开始

安装与设置

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

🤝 贡献

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

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

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

📞 支持

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

为 Heptabase 社区精心打造 ❤️