Гептабаза МЦП

@heptabase/mcp

Служба Model Context Protocol (MCP) для взаимодействия с резервными данными Heptabase. Эта служба позволяет помощникам ИИ, таким как Клод, искать, извлекать, анализировать и экспортировать доски и карточки Heptabase.

Функции

🔍 Поиск досок и карточек
📁 Автоматическое управление файлами резервного копирования
📄 Экспорт в несколько форматов (Markdown, JSON, Mermaid)
🔗 Анализируйте взаимосвязи карт
📊 Создавайте сводки на доске
⚡ Умное кэширование для производительности

Быстрый старт

Установка и настройка

Клонировать и установить:
git clone <repository-url> 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
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 .

Базовое использование

// 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 — создание сводок с использованием искусственного интеллекта

Инструменты анализа

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+
Heptabase с включенным экспортом резервных копий
Claude Desktop (для интеграции MCP)

Поиск неисправностей

Общие проблемы

«Резервные копии не найдены» — проверьте, указывает ли HEPTABASE_BACKUP_PATH на правильный каталог.
«Команда не найдена» — убедитесь, что Node.js установлен и пути указаны правильно.
Клод не видит инструменты - Полностью перезапустите Claude Desktop после изменения конфигурации
Ошибки сборки — запустите npm install и npm run build перед использованием

Режим отладки

Используйте инструмент debugInfo для проверки состояния системы:

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

Внося вклад

Вклады приветствуются! Пожалуйста:

Форк репозитория
Создать ветку функций
Внесите изменения
Добавить тесты для новых функций
Убедитесь, что все тесты пройдены
Отправить запрос на извлечение

Подробности архитектуры см. в SPECIFICATION.md .

Лицензия

Лицензия MIT — подробности см. в файле LICENSE .

Поддерживать

🐛 Отчеты об ошибках : Проблемы GitHub
💬 Вопросы : обсуждения на GitHub
📧 Проблемы безопасности : пожалуйста, сообщите в частном порядке.

Сделано с ❤️ для сообщества Heptabase

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

Служба протокола контекста модели, которая позволяет помощникам с искусственным интеллектом искать, извлекать, анализировать и экспортировать данные из резервных копий Heptabase.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
2
Python
MCP Kibela
kj455
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to search and access information stored in Kibela, supporting note search, retrieval, creation and updating.
Last updated -
6
107
9
TypeScript
MIT License
Tiny TODO MCP
tkc
-
security
F
license
-
quality
A Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.
Last updated -
1
TypeScript
Amadeus MCP Server
privilegemendes
A
security
F
license
A
quality
A Model Context Protocol server that connects to Amadeus API, enabling AI assistants to search flights, analyze prices, find best travel deals, and plan multi-city trips.
Last updated -
294
TypeScript

View all related MCP servers

Heptabase MCP