Heptabase MCP

🚀 @heptabase/mcp

Heptabaseのバックアップデータとやり取りするためのモデルコンテキストプロトコル（MCP）サービスです。このサービスにより、ClaudeなどのAIアシスタントがHeptabaseのホワイトボードやカードを検索、取得、分析、エクスポートできます。

✨ 主な機能

• 🔍 ホワイトボードとカードを検索する
• 📁 バックアップファイルを自動管理する
• 📄 複数の形式（Markdown、JSON、Mermaid）にエクスポートする
• 🔗 カードの関係性を分析する
• 📊 ホワイトボードの要約を生成する
• ⚡ パフォーマンス向上のためのスマートキャッシュ

🚀 クイックスタート

インストールとセットアップ

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
• 個人用ファイル（gitignoreされる）: 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"
  }
});

💻 使用例

基本的な使用法

// バックアップパスを設定する
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"
  }
});

高度な使用法

// 高度な機能の使用例
// ここに高度なシナリオの説明を記述する
await mcpClient.callTool({
  name: "advancedFunction",
  parameters: {
    // パラメータの詳細
  }
});

📚 ドキュメント

• 📚 完全な仕様書 - 詳細なAPIとアーキテクチャ
• 🚀 クイックスタートガイド - すぐに始める方法
• ⚙️ 設定ガイド - 安全な設定方法
• 📖 Claude Desktopのセットアップ - ローカル開発のセットアップ

🔧 利用可能なツール

バックアップ管理

• 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              # 設定テンプレート

テスト

# すべてのテストを実行する
npm test

# ウォッチモードでテストを実行する
npm run test:watch

# カバレッジを含めて実行する
npm run test:coverage

# 統合テストを実行する
npm run test:integration

ビルド

# 本番用にビルドする
npm run build

# 自動リロードの開発モード
npm run dev

# 型チェックのみ実行する
npm run type-check

🔒 プライバシーとセキュリティ

このプロジェクトはプライバシーを設計段階から考慮した原則に従っています。

• ✅ 個人用のパスは決してgitにコミットされません
• ✅ バックアップデータはあなたのマシン上にローカルに留まります
• ✅ 設定テンプレートは安全なプレースホルダーを使用しています
• ✅ .gitignoreにより機密ファイルが保護されています

📋 要件

• Node.js 18以上
• Heptabase バックアップエクスポートが有効になっていること
• Claude Desktop (MCP統合に必要)

🛠️ トラブルシューティング

一般的な問題

• "No backups found" - HEPTABASE_BACKUP_PATH が正しいディレクトリを指していることを確認してください
• "Command not found" - Node.jsがインストールされていて、パスが正しいことを確認してください
• Claudeがツールを認識しない - 設定を変更した後、Claude Desktopを完全に再起動してください
• ビルドエラー - 使用する前に npm install と npm run build を実行してください

デバッグモード

debugInfo ツールを使用してシステムの状態を確認します。

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

🤝 コントリビューション

コントリビューションは歓迎されます！以下の手順に従ってください。

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を加える
4. 新しい機能に対してテストを追加する
5. すべてのテストが通過することを確認する
6. プルリクエストを送信する

アーキテクチャの詳細は SPECIFICATION.md を参照してください。

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。

🆘 サポート

• 🐛 バグ報告: GitHub Issues
• 💬 質問: GitHub Discussions
• 📧 セキュリティ問題: 個別に報告してください

Heptabaseコミュニティのために愛を込めて作られました