内容
# @heptabase/mcp
一款用于与 Heptabase 备份数据交互的模型上下文协议（MCP）服务。该服务允许像 Claude 这样的 AI 助手搜索、检索、分析以及导出 Heptabase 白板和卡片。
## 功能
- 🔍 搜索白板和卡片
- 📁 自动备份文件管理
- 📄 导出多种格式（Markdown、JSON、Mermaid）
- 🔗 分析卡片关系
- 📊 生成白板摘要
- ⚡ 性能智能缓存
## 快速开始
### 安装和设置
1. **克隆和安装：**
```bash
git clone <仓库网址>
cd heptabase-mcp
npm install
```
2. **使用环境变量配置：**
```bash
cp .env.example .env
# 编辑 .env 为实际路径
```
3. **构建项目：**
```bash
npm run build
```
4. **本地测试（可选）：**
```bash
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`
**添加此配置：**
```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](./QUICK_START.md) 获取详细设置说明。
### 配置
该项目使用隐私安全的配置系统：
- **示例文件** （适用于 git）：`claude-config-example.json`、` .env.example`
- **个人文件** （gitignored）：`claude-config-*personal*.json`、` .env`
参见 [CONFIG.md](./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: "项目规划"
}
});
// 获取完整白板内容
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
```
## 文档
- [📚 完整规范](./SPECIFICATION.md) - 详细 API 和架构
- [🚀 快速入门指南](./QUICK_START.md) - 快速上手
- [⚙️ 配置指南](./CONFIG.md) - 安全配置实践
- [📖 Claude Desktop 设置](./claude-desktop-setup.md) - 本地开发设置
## 隐私与安全
该项目遵循隐私设计原则：
- ✅ 个人路径从不提交到 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" });
```
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求
参见 [SPECIFICATION.md](./SPECIFICATION.md) 获取架构详情。
## 许可证
MIT 许可证 - 参见 [LICENSE](./LICENSE) 文件获取详情。
## 支持
- 🐛 **错误报告**：[GitHub 问题](https://github.com/yourusername/heptabase-mcp/issues)
- 💬 **问题**：[GitHub 讨论](https://github.com/yourusername/heptabase-mcp/discussions)
- 📧 **安全问题**：请私下报告
---
为 Heptabase 社区打造 ❤️
MCP 市场
