Heptabase MCP

🚀 @heptabase/mcp

這是一個用於與 Heptabase 備份數據進行交互的模型上下文協議（MCP）服務。該服務允許像 Claude 這樣的 AI 助手搜索、檢索、分析和導出 Heptabase 白板和卡片。

🚀 快速開始

安裝與設置

1. 克隆並安裝：

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

2. 使用環境變量進行配置：

   cp .env.example .env
   # 使用實際路徑編輯 .env
   

3. 構建項目：

   npm run build
   

4. 本地測試（可選）：

   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
• 個人文件（被 git 忽略）：claude-config-*personal*.json、.env

詳細配置說明請參閱 CONFIG.md。

基本用法

// 配置備份路徑
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"
  }
});

✨ 主要特性

• 🔍 搜索白板和卡片
• 📁 自動備份文件管理
• 📄 導出為多種格式（Markdown、JSON、Mermaid）
• 🔗 分析卡片關係
• 📊 生成白板摘要
• ⚡ 智能緩存以提高性能

📦 可用工具

備份管理

• configureBackupPath - 設置備份目錄
• listBackups - 列出可用的備份
• loadBackup - 加載特定的備份

搜索操作

• searchWhiteboards - 按名稱或內容搜索白板
• searchCards - 在所有白板中搜索卡片

數據檢索

• getWhiteboard - 獲取完整的白板數據
• getCard - 以多種格式獲取卡片內容
• getCardContent - 以資源形式獲取卡片內容（繞過大小限制）
• getCardsByArea - 根據白板上的位置查找卡片

導出功能

• exportWhiteboard - 導出為 Markdown、JSON、HTML 格式
• summarizeWhiteboard - 生成由 AI 驅動的摘要

分析工具

• analyzeGraph - 分析卡片關係和連接
• compareBackups - 比較不同的備份版本

調試工具

• debugInfo - 獲取系統狀態和診斷信息

📚 詳細文檔

• 📚 完整規範 - 詳細的 API 和架構說明
• 🚀 快速入門指南 - 快速上手
• ⚙️ 配置指南 - 安全的配置實踐
• 📖 Claude Desktop 設置 - 本地開發設置

🔧 技術細節

項目結構

heptabase-mcp/
├── src/
│   ├── index.ts              # 主入口點
│   ├── server.ts             # MCP 服務器實現
│   ├── services/             # 核心業務邏輯
│   │   ├── BackupManager.ts  # 備份文件管理
│   │   └── HeptabaseDataService.ts # 數據查詢
│   ├── tools/                # MCP 工具實現
│   ├── types/                # TypeScript 定義
│   └── utils/                # 輔助函數
├── tests/                    # 測試套件
├── docs/                     # 文檔
└── config files              # 配置模板

測試

# 運行所有測試
npm test

# 以監視模式運行測試
npm run test:watch

# 運行並生成覆蓋率報告
npm run test:coverage

# 運行集成測試
npm run test:integration

構建

# 生產環境構建
npm run build

# 開發模式，自動重新加載
npm run dev

# 僅進行類型檢查
npm run type-check

📄 許可證

本項目採用 MIT 許可證，詳細信息請參閱 LICENSE 文件。

⚠️ 隱私與安全

本項目遵循隱私設計原則：

• ✅ 個人路徑從不提交到 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" });

🤝 貢獻

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 確保所有測試通過
6. 提交拉取請求

架構詳細信息請參閱 SPECIFICATION.md。

📞 支持

• 🐛 報告 bug：GitHub Issues
• 💬 提問：GitHub Discussions
• 📧 安全問題：請私下報告

為 Heptabase 社區精心打造 ❤️