AI导哈

Heptabase数据交互协议

用于与Heptabase备份数据交互的模型上下文协议服务，支持搜索、检索、分析和导出白板及卡片内容。

  • by LarryStanley
  • TypeScript
  • 本地部署
  • 17 星标
  • 更新于
在 GitHub 查看 LarryStanley/heptabse-mcp

使用说明

@七碱/mcp

用于与Heptabase备份数据交互的模型上下文协议（MCP）服务。这项服务允许像克劳德这样的人工智能助手搜索、检索、分析和导出Heptabase白板和卡片。

特性

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

快速开始

安装和设置

  1. 克隆并安装：

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

  2. 使用环境变量进行配置：

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

  3. 构建项目：

    npm run build

  4. 本地测试（可选）：

    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

文档

隐私和安全

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

  • ✅ 个人路径永远不会提交给git
  • ✅ 备份数据保留在您的计算机本地
  • ✅ 配置模板使用安全占位符
  • ✅ Gitignore保护敏感文件

需求

  • Node.js 18+
  • 乙酰肝素酶 启用了备份导出
  • 克劳德桌面 （用于MCP集成）

故障排除

常见问题

  • “未找到备份” -检查你的 HEPTABASE_BACKUP_PATH 指向正确的目录
  • “找不到命令” -确保Node.js已安装且路径正确
  • 克劳德看不到工具 -配置更改后完全重新启动Claude Desktop
  • 构建错误 -快跑 npm install 和 npm run build 使用前

调试模式

使用 debugInfo 检查系统状态的工具：

await mcpClient.callTool({ name: "debugInfo" });

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加新功能的测试
  5. 确保所有测试通过
  6. 提交拉取请求

看 规格.md 了解架构细节。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

由以下材料制成❤️ 为Heptabase社区

相关 MCP