@hepbase/mcp

Un servicio de Protocolo de Contexto de Modelo (MCP) para interactuar con los datos de respaldo de Hepbase. Este servicio permite a asistentes de IA como Claude buscar, recuperar, analizar y exportar pizarras y tarjetas de Hepbase.

Características

🔍Buscar pizarras y tarjetas
📁 Gestión automática de archivos de respaldo
📄 Exportar a múltiples formatos (Markdown, JSON, Mermaid)
🔗 Analizar las relaciones entre las tarjetas
📊 Generar resúmenes de pizarra
⚡ Almacenamiento en caché inteligente para un mejor rendimiento

Related MCP server: Supabase MCP Server

Inicio rápido

Instalación y configuración

Clonar e instalar:

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

Configurar usando variables de entorno:

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

Construir el proyecto:
```
npm run build
```
Prueba localmente (opcional):
```
npm start
```

Uso con Claude Desktop

Configurar Claude Desktop para utilizar su compilación local:

Edite el archivo de configuración de Claude Desktop:

macOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json
Ventanas : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Añade esta configuración:

{
  "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"
      }
    }
  }
}

Importante:

Reemplace /path/to/node con su ruta Node.js (busque con which node )
Reemplace /path/to/your/heptabase-mcp con la ruta de su proyecto actual
Establezca HEPTABASE_BACKUP_PATH en su directorio de respaldo de Hepbase

Consulte QUICK_START.md para obtener instrucciones de configuración detalladas.

Configuración

Este proyecto utiliza un sistema de configuración que protege la privacidad:

Archivos de ejemplo (seguros para git): claude-config-example.json , .env.example
Archivos personales (gitignored): claude-config-*personal*.json , .env

Consulte CONFIG.md para obtener instrucciones de configuración detalladas.

Uso básico

// 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"
  }
});

Herramientas disponibles

Gestión de copias de seguridad

configureBackupPath - Establecer directorio de respaldo
listBackups - Lista de copias de seguridad disponibles
loadBackup - Cargar una copia de seguridad específica

Operaciones de búsqueda

searchWhiteboards - Busca pizarras por nombre o contenido
searchCards : busca tarjetas en todas las pizarras

Recuperación de datos

getWhiteboard - Obtenga datos completos de la pizarra
getCard - Obtenga el contenido de la tarjeta en múltiples formatos
getCardContent : obtiene el contenido de la tarjeta como recurso (evita los límites de tamaño)
getCardsByArea - Encuentra tarjetas por posición en la pizarra

Funciones de exportación

exportWhiteboard : Exportación a formatos Markdown, JSON y HTML
summarizeWhiteboard : genera resúmenes con tecnología de IA

Herramientas de análisis

analyzeGraph : analiza las relaciones y conexiones de las tarjetas
compareBackups - Comparar diferentes versiones de copia de seguridad

Herramientas de depuración

debugInfo : obtener el estado y los diagnósticos del sistema

Desarrollo

Estructura del proyecto

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

Pruebas

# 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

Edificio

# Build for production
npm run build

# Development mode with auto-reload
npm run dev

# Type checking only
npm run type-check

Documentación

📚 Especificación completa : API y arquitectura detalladas
🚀 Guía de inicio rápido : comience a trabajar rápidamente
⚙️ Guía de configuración : Prácticas de configuración segura
📖 Configuración de escritorio de Claude : configuración de desarrollo local

Privacidad y seguridad

Este proyecto sigue los principios de privacidad desde el diseño:

✅ Los caminos personales nunca están comprometidos con git
✅ Los datos de respaldo permanecen locales en su máquina
✅ Las plantillas de configuración utilizan marcadores de posición seguros
✅ Gitignore protege archivos confidenciales

Requisitos

Node.js 18+
Hepbase con exportaciones de respaldo habilitadas
Claude Desktop (para integración con MCP)

Solución de problemas

Problemas comunes

"No se encontraron copias de seguridad" : verifique que HEPTABASE_BACKUP_PATH apunte al directorio correcto
"Comando no encontrado" : asegúrese de que Node.js esté instalado y que las rutas sean correctas
Claude no ve las herramientas : reinicie Claude Desktop por completo después de los cambios de configuración
Errores de compilación : ejecute npm install y npm run build antes de usar

Modo de depuración

Utilice la herramienta debugInfo para comprobar el estado del sistema:

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

Contribuyendo

¡Agradecemos sus contribuciones! Por favor:

Bifurcar el repositorio
Crear una rama de características
Realiza tus cambios
Agregar pruebas para nuevas funcionalidades
Asegúrese de que todas las pruebas pasen
Enviar una solicitud de extracción

Consulte SPECIFICATION.md para obtener detalles de la arquitectura.

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles.

Apoyo

🐛 Informes de errores : Problemas de GitHub
💬 Preguntas : Discusiones de GitHub
📧 Problemas de seguridad : Por favor, informe de forma privada.

Hecho con ❤️ para la comunidad Hepbase

Heptabase MCP