@七碱/mcp
用于与Heptabase备份数据交互的模型上下文协议（MCP）服务。这项服务允许像克劳德这样的人工智能助手搜索、检索、分析和导出Heptabase白板和卡片。
特性
- 🔍 搜索白板和卡片
- 📁 自动备份文件管理
- 📄 导出为多种格式（Markdown、JSON、Mermaid）
- 🔗 分析卡片关系
- 📊 生成白板摘要
- ⚡ 智能缓存提高性能
快速开始
安装和设置
- 克隆并安装：
git clone
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 - 视窗:
%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备份目录
看 快速启动.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-生成基于AI的摘要
分析工具
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+
- 乙酰肝素酶 启用了备份导出
- 克劳德桌面 （用于MCP集成）
故障排除
常见问题
- “未找到备份” -检查你的
HEPTABASE_BACKUP_PATH指向正确的目录 - “找不到命令” -确保Node.js已安装且路径正确
- 克劳德看不到工具 -配置更改后完全重新启动Claude Desktop
- 构建错误 -快跑
npm install和npm run build使用前
调试模式
使用 debugInfo 检查系统状态的工具：
await mcpClient.callTool({ name: "debugInfo" });贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
看 规格.md 了解架构细节。
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
支持
- 🐛 错误报告:
- 💬 问题:
- 📧 安全问题：请私下举报
______________________________________________________________________
由以下材料制成❤️ 为Heptabase社区