LarryStanley
服务介绍
@heptabase/mcp
一个用于与 Heptabase 备份数据交互的 Model Context Protocol (MCP) 服务。该服务允许像 Claude 这样的 AI 助手搜索、检索、分析和导出 Heptabase 白板和卡片。
特性
- 🔍 搜索白板和卡片
- 📁 自动备份文件管理
- 📄 导出为多种格式（Markdown、JSON、Mermaid）
- 🔗 分析卡片关系
- 📊 生成白板摘要
- ⚡ 智能缓存以提高性能
快速开始
安装与设置
-
克隆并安装：
bash
git clone
cd heptabase-mcp
npm install -
使用环境变量进行配置：
bash
cp .env.example .env使用实际路径编辑 .env 文件
-
构建项目：
bash
npm run build -
本地测试（可选）：
bash
npm start
与 Claude Desktop 一起使用
配置 Claude Desktop 以使用您的本地构建：
编辑 Claude Desktop 配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%Claudeclaude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
添加以下配置：
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 获取详细的配置说明。
基本用法
typescript
// 配置备份路径
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 # 配置模板### 测试
bash
运行所有测试
npm test
以监视模式运行测试
npm run test:watch
运行带有覆盖率的测试
npm run test:coverage
运行集成测试
npm run test:integration
构建
bash
生产环境构建
npm run build
开发模式，带自动重载
npm run dev
仅类型检查
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 工具检查系统状态：
typescript
await mcpClient.callTool({ name: "debugInfo" });
贡献
欢迎贡献！请按照以下步骤操作：
- 叉取仓库
- 创建功能分支
- 进行修改
- 为新功能添加测试
- 确保所有测试通过
- 提交拉取请求
有关架构详情，请参阅 SPECIFICATION.md。
许可证
MIT 许可证 - 详情请参阅 LICENSE 文件。
支持
- 🐛 报告 Bug: GitHub Issues
- 💬 提问: GitHub Discussions
- 📧 安全问题: 请私下报告
由 ❤️ 为 Heptabase 社区制作
