Content
# @heptabase/mcp
A Model Context Protocol (MCP) service for interacting with Heptabase backup data. This service allows AI assistants like Claude to search, retrieve, analyze, and export Heptabase whiteboards and cards.
## Features
- 🔍 Search whiteboards and cards
- 📁 Automatic backup file management
- 📄 Export to multiple formats (Markdown, JSON, Mermaid)
- 🔗 Analyze card relationships
- 📊 Generate whiteboard summaries
- ⚡ Smart caching for performance
## Quick Start
### Installation and Setup
1. **Clone and install:**
```bash
git clone <repository-url>
cd heptabase-mcp
npm install
```
2. **Configure using environment variables:**
```bash
cp .env.example .env
# Edit .env with your actual paths
```
3. **Build the project:**
```bash
npm run build
```
4. **Test locally (optional):**
```bash
npm start
```
### Using with Claude Desktop
Configure Claude Desktop to use your local build:
**Edit your Claude Desktop config file:**
- **macOS**: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**Add this configuration:**
```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"
}
}
}
}
```
**Important:**
- Replace `/path/to/node` with your Node.js path (find with `which node`)
- Replace `/path/to/your/heptabase-mcp` with your actual project path
- Set `HEPTABASE_BACKUP_PATH` to your Heptabase backup directory
See [QUICK_START.md](./QUICK_START.md) for detailed setup instructions.
### Configuration
This project uses a privacy-safe configuration system:
- **Example files** (safe for git): `claude-config-example.json`, `.env.example`
- **Personal files** (gitignored): `claude-config-*personal*.json`, `.env`
See [CONFIG.md](./CONFIG.md) for detailed configuration instructions.
### Basic Usage
```typescript
// 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"
}
});
```
## Available Tools
### Backup Management
- `configureBackupPath` - Set backup directory
- `listBackups` - List available backups
- `loadBackup` - Load a specific backup
### Search Operations
- `searchWhiteboards` - Search whiteboards by name or content
- `searchCards` - Search cards across all whiteboards
### Data Retrieval
- `getWhiteboard` - Get complete whiteboard data
- `getCard` - Get card content in multiple formats
- `getCardContent` - Get card content as resource (bypasses size limits)
- `getCardsByArea` - Find cards by position on whiteboard
### Export Functions
- `exportWhiteboard` - Export to Markdown, JSON, HTML formats
- `summarizeWhiteboard` - Generate AI-powered summaries
### Analysis Tools
- `analyzeGraph` - Analyze card relationships and connections
- `compareBackups` - Compare different backup versions
### Debug Tools
- `debugInfo` - Get system status and diagnostics
## Development
### Project Structure
```
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
```
### Testing
```bash
# 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
```
### Building
```bash
# Build for production
npm run build
# Development mode with auto-reload
npm run dev
# Type checking only
npm run type-check
```
## Documentation
- [📚 Complete Specification](./SPECIFICATION.md) - Detailed API and architecture
- [🚀 Quick Start Guide](./QUICK_START.md) - Get up and running fast
- [⚙️ Configuration Guide](./CONFIG.md) - Safe configuration practices
- [📖 Claude Desktop Setup](./claude-desktop-setup.md) - Local development setup
## Privacy & Security
This project follows privacy-by-design principles:
- ✅ Personal paths are never committed to git
- ✅ Backup data stays local on your machine
- ✅ Configuration templates use safe placeholders
- ✅ Gitignore protects sensitive files
## Requirements
- **Node.js** 18+
- **Heptabase** with backup exports enabled
- **Claude Desktop** (for MCP integration)
## Troubleshooting
### Common Issues
- **"No backups found"** - Check your `HEPTABASE_BACKUP_PATH` points to the correct directory
- **"Command not found"** - Ensure Node.js is installed and paths are correct
- **Claude doesn't see tools** - Restart Claude Desktop completely after config changes
- **Build errors** - Run `npm install` and `npm run build` before using
### Debug Mode
Use the `debugInfo` tool to check system status:
```typescript
await mcpClient.callTool({ name: "debugInfo" });
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
See [SPECIFICATION.md](./SPECIFICATION.md) for architecture details.
## License
MIT License - see [LICENSE](./LICENSE) file for details.
## Support
- 🐛 **Bug reports**: [GitHub Issues](https://github.com/yourusername/heptabase-mcp/issues)
- 💬 **Questions**: [GitHub Discussions](https://github.com/yourusername/heptabase-mcp/discussions)
- 📧 **Security issues**: Please report privately
---
Made with ❤️ for the Heptabase community
