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

可用工具

备份管理

• 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/                     # 文档
└── 配置文件                  # 配置模板

测试

# 运行所有测试
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社区制作