@heptabase/mcp

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

特征

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

Related MCP server: Supabase MCP Server

快速入门

安装和设置

克隆并安装：

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

使用环境变量进行配置：

cp .env.example .env
# Edit .env with your actual paths

构建项目：
```
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
个人文件（忽略）： claude-config-*personal*.json 、 .env

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

基本用法

// Configure backup path
await mcpClient.callTool({
  name: "configureBackupPath",
  parameters: {
    path: "/path/to/your/heptabase/backups"
  }
});

// List available backups
const backups = await mcpClient.callTool({
  name: "listBackups"
});

// Search for whiteboards
const whiteboards = await mcpClient.callTool({
  name: "searchWhiteboards",
  parameters: {
    query: "Project Planning"
  }
});

// Get full whiteboard content
const whiteboard = await mcpClient.callTool({
  name: "getWhiteboard",
  parameters: {
    whiteboardId: "your-whiteboard-id",
    includeCards: true,
    includeConnections: true
  }
});

// Export to 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 - 生成人工智能摘要

分析工具

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

调试工具

debugInfo - 获取系统状态和诊断

发展

项目结构

heptabase-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── services/             # Core business logic
│   │   ├── BackupManager.ts  # Backup file management
│   │   └── HeptabaseDataService.ts # Data querying
│   ├── tools/                # MCP tool implementations
│   ├── types/                # TypeScript definitions
│   └── utils/                # Helper functions
├── tests/                    # Test suites
├── docs/                     # Documentation
└── config files              # Configuration templates

测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

建筑

# Build for production
npm run build

# Development mode with auto-reload
npm run dev

# Type checking only
npm run type-check

文档

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

隐私和安全

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

✅ 个人路径永远不会提交给 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 。

执照

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

支持

🐛错误报告： GitHub Issues
💬问题： GitHub 讨论
📧安全问题：请私下报告

用❤️为 Heptabase 社区打造

Heptabase MCP