### Setup and Build Project

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/QUICK_START.md

Commands to clone the repository, install dependencies, and build the project for production use.

```bash
git clone <repository-url>
cd heptabase-mcp
npm install
npm run build
```

--------------------------------

### Copy Example Configuration Files (Bash)

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/CONFIG.md

Demonstrates how to copy example configuration files to create personal versions for local development. This is a common first step to set up the project's configuration.

```bash
cp claude-config-example.json claude-config-personal.json
cp .env.example .env
```

--------------------------------

### Build and Start Heptabase MCP Server

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/ENV_SETUP.md

Commands to build the project and start the Heptabase MCP server. The server will silently start and be ready to handle MCP messages without outputting startup messages to stdout.

```bash
npm run build
npm start
```

--------------------------------

### Example Heptabase MCP Desktop Configurations

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/ENV_SETUP.md

Example JSON configurations for setting up the Heptabase MCP server on different desktop operating systems. These configurations specify the command to run Node.js, the arguments for the server script, and environment variables.

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.0/bin/node",
      "args": ["/Users/yourusername/Code/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/Users/yourusername/Documents/Heptabase-auto-backup"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\yourusername\\Code\\heptabase-mcp\\dist\\index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "C:\\Users\\yourusername\\Documents\\Heptabase-auto-backup"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/usr/bin/node",
      "args": ["/home/yourusername/Code/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/home/yourusername/Documents/Heptabase-auto-backup"
      }
    }
  }
}
```

--------------------------------

### Install and Build Heptabase MCP

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/README.md

Commands to clone the repository, install dependencies, and build the project for local use.

```bash
git clone <repository-url>
cd heptabase-mcp
npm install
npm run build
npm start
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/QUICK_START.md

JSON configuration structure for registering the Heptabase MCP server within the Claude Desktop application, including platform-specific path examples.

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

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.0/bin/node",
      "args": ["/Users/yourusername/Code/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/Users/yourusername/Documents/Heptabase-auto-backup",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\yourusername\\Code\\heptabase-mcp\\dist\\index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "C:\\Users\\yourusername\\Documents\\Heptabase-auto-backup",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}
```

--------------------------------

### Example Windows Heptabase MCP Configuration

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

An example JSON configuration for Heptabase MCP on Windows. It provides the standard Windows path for the Node.js executable and the MCP script, along with environment variables for managing Heptabase backups and extractions.

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\yourusername\\Code\\heptabase-mcp\\dist\\index.js"
      ],
      "env": {
        "HEPTABASE_BACKUP_PATH": "C:\\Users\\yourusername\\Documents\\Heptabase-auto-backup",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}
```

--------------------------------

### Environment Variables Configuration Example (env)

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/CONFIG.md

An example of environment variables used for configuring Heptabase MCP. These variables control backup paths, auto-extraction, and directory watching. This configuration is typically stored in a '.env' file.

```env
HEPTABASE_BACKUP_PATH=/path/to/your/heptabase/backups
HEPTABASE_AUTO_EXTRACT=true
HEPTABASE_WATCH_DIRECTORY=true
```

--------------------------------

### Example macOS Heptabase MCP Configuration

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

An example JSON configuration for Heptabase MCP on macOS, specifically tailored for users managing Node.js versions with nvm. It specifies the Node.js executable path and the MCP script location, along with environment variables for backups and extraction.

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/Users/yourusername/.nvm/versions/node/v20.18.0/bin/node",
      "args": [
        "/Users/yourusername/Code/heptabase-mcp/dist/index.js"
      ],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/Users/yourusername/Documents/Heptabase-auto-backup",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true",
        "HEPTABASE_EXTRACTION_PATH": "/Users/yourusername/Code/heptabase-mcp/data/extracted"
      }
    }
  }
}
```

--------------------------------

### Example Linux Heptabase MCP Configuration

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

An example JSON configuration for Heptabase MCP on Linux. It specifies the typical system path for the Node.js executable and the MCP script, along with environment variables for Heptabase backup and extraction settings.

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/usr/bin/node",
      "args": [
        "/home/yourusername/Code/heptabase-mcp/dist/index.js"
      ],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/home/yourusername/Documents/Heptabase-auto-backup",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true"
      }
    }
  }
}
```

--------------------------------

### MCP Settings Configuration Example (JSON)

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/CONFIG.md

An example JSON structure for MCP settings, including paths to the Node.js command and script arguments, as well as environment variables. This file is typically named 'claude-config-personal.json' or '.mcp-settings.json'.

```json
{
  "command": "/path/to/your/node",
  "args": ["/path/to/your/heptabase-mcp/dist/index.js"],
  "env": {
    "HEPTABASE_BACKUP_PATH": "/Users/yourusername/Documents/Heptabase-auto-backup"
  }
}
```

--------------------------------

### Build Heptabase MCP Project

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

Installs project dependencies and builds the project for use with Claude Desktop. Ensure you are in the project's root directory before running these commands.

```bash
cd /path/to/your/heptabase-mcp
npm install
npm run build
```

--------------------------------

### Interact with Heptabase via MCP Client

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/README.md

TypeScript examples demonstrating how to use the MCP client to call tools for backup management, searching, and exporting whiteboard data.

```typescript
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 }
});

const markdown = await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: { whiteboardId: "your-whiteboard-id", format: "markdown" }
});
```

--------------------------------

### Test Heptabase MCP Server Manually

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

Starts the Heptabase MCP server locally for testing purposes. This command is useful for troubleshooting connection issues. Note that the server is designed to not output messages to stdout.

```bash
cd /path/to/your/heptabase-mcp
npm start
```

--------------------------------

### Invoke MCP Tools via Client

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Examples of how to interact with the Heptabase MCP server using the MCP client SDK to perform configuration, search, retrieval, and export operations.

```typescript
// Configure backup location
await mcpClient.callTool({
  name: "configureBackupPath",
  parameters: {
    path: "/path/to/your/heptabase/backups",
    watchForChanges: true,
    autoExtract: true
  }
});

// Search for whiteboards
const { whiteboards } = await mcpClient.callTool({
  name: "searchWhiteboards",
  parameters: {
    query: "Button Refactor"
  }
});

// Search for cards
const { cards } = await mcpClient.callTool({
  name: "searchCards",
  parameters: {
    tags: ["important", "todo"],
    dateRange: {
      start: "2024-01-01",
      end: "2024-12-31"
    }
  }
});

// Get whiteboard with all content
const whiteboard = await mcpClient.callTool({
  name: "getWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    includeCards: true,
    includeConnections: true
  }
});

// Export to Markdown
const { markdown } = await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    format: "markdown",
    includeImages: true
  }
});
```

--------------------------------

### Summarize Whiteboard - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Generates a summary of the whiteboard's content. Users can specify a maximum length for the summary and focus areas to guide the summarization process.

```typescript
tool: "summarizeWhiteboard"
parameters: {
  whiteboardId: string
  maxLength?: number
  focusAreas?: string[]
}
```

--------------------------------

### Get Whiteboard Data - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Retrieves complete whiteboard data, including cards and connections. Options include specifying whether to include cards, connections, and the depth for nested cards.

```typescript
tool: "getWhiteboard"
parameters: {
  whiteboardId: string
  includeCards?: boolean
  includeConnections?: boolean
  depth?: number          // For nested cards
}
```

--------------------------------

### Get Card Data - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Retrieves individual card data in various formats such as JSON, Markdown, or HTML. It can also optionally include related cards.

```typescript
tool: "getCard"
parameters: {
  cardId: string
  format?: "json" | "markdown" | "html"
  includeRelated?: boolean
}
```

--------------------------------

### Run Project Tests and Build Scripts

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/README.md

Standard npm scripts for testing, building, and developing the Heptabase MCP service.

```bash
npm test
npm run test:watch
npm run test:coverage
npm run build
npm run dev
```

--------------------------------

### Verify Node.js Path

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/claude-desktop-setup.md

Checks the system's PATH environment variable to find the location of the Node.js executable. This is crucial for correctly configuring the `command` field in the Claude Desktop MCP settings.

```bash
which node
```

--------------------------------

### Get Cards by Area - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Retrieves cards located within a specific circular area on a whiteboard. Requires the whiteboard ID, center coordinates (x, y), and an optional radius.

```typescript
tool: "getCardsByArea"
parameters: {
  whiteboardId: string
  x: number
  y: number
  radius?: number
}
```

--------------------------------

### Call debugInfo Tool with MCP Client

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/ENV_SETUP.md

TypeScript code to call the 'debugInfo' tool using the mcpClient. This is used to verify that the server's configuration is loaded correctly.

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

--------------------------------

### Analyze Graph - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Analyzes the relationships between cards in a graph format. It allows specifying a starting card ID, maximum depth for analysis, and filtering by specific relationship types.

```typescript
tool: "analyzeGraph"
parameters: {
  startCardId: string
  maxDepth?: number
  relationshipTypes?: string[]
}
```

--------------------------------

### Configure Backup Path for Heptabase MCP

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Initializes the service by setting the directory path for Heptabase backups. It supports optional file watching and automatic extraction features to keep the AI context updated.

```typescript
await mcpClient.callTool({
  name: "configureBackupPath",
  parameters: {
    path: "/path/to/your/heptabase/backups",
    watchForChanges: true,
    autoExtract: true
  }
});
```

--------------------------------

### Get Debug Information - Heptabase MCP

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Retrieves system status and diagnostic information, including configuration details, the state of the backup manager, and statistics from the data service. This is useful for troubleshooting and monitoring the service.

```typescript
// Get system debug information
const result = await mcpClient.callTool({
  name: "debugInfo",
  parameters: {}
});
// Output (JSON):
// {
//   "config": {
//     "backupPath": "/path/to/backups",
//     "autoExtract": true,
//     "watchDirectory": true,
//     "cacheEnabled": true,
//     "cacheTTL": 3600
//   },
//   "backupManager": {
//     "status": "Initialized",
//     "backupCount": 5,
//     "latestBackup": {...}
//   },
//   "dataService": {
//     "status": "Initialized",
//     "whiteboardCount": 12,
//     "cardCount": 156,
//     "cardInstanceCount": 234,
//     "connectionCount": 89
//   }
// }
```

--------------------------------

### Configure Heptabase MCP via Environment Variables

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Configures the Heptabase MCP service by setting environment variables within a Claude Desktop configuration file. This allows for detailed customization of backup paths, extraction behavior, caching, and more.

```json
{
  "mcpServers": {
    "heptabase": {
      "command": "/path/to/node",
      "args": ["/path/to/heptabase-mcp/dist/index.js"],
      "env": {
        "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups",
        "HEPTABASE_AUTO_EXTRACT": "true",
        "HEPTABASE_WATCH_DIRECTORY": "true",
        "HEPTABASE_EXTRACTION_PATH": "./data/extracted",
        "HEPTABASE_KEEP_EXTRACTED": "true",
        "HEPTABASE_MAX_BACKUPS": "10",
        "HEPTABASE_CACHE_ENABLED": "true",
        "HEPTABASE_CACHE_TTL": "3600",
        "HEPTABASE_AUTO_SELECT_LATEST": "true",
        "HEPTABASE_DATE_FORMAT": "YYYY-MM-DD",
        "HEPTABASE_TIMEZONE": "UTC"
      }
    }
  }
}
```

--------------------------------

### Configure Heptabase MCP via Settings File

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Configures the Heptabase MCP service by creating a `.mcp-settings.json` file in the project root. This provides an alternative method for setting backup paths, extraction options, caching, and other operational parameters.

```json
{
  "backupPath": "/path/to/your/heptabase/backups",
  "autoExtract": true,
  "watchDirectory": true,
  "extractionPath": "./data/extracted",
  "keepExtracted": true,
  "maxBackups": 10,
  "cacheEnabled": true,
  "cacheTTL": 3600,
  "autoSelectLatest": true,
  "dateFormat": "YYYY-MM-DD",
  "timezone": "UTC"
}
```

--------------------------------

### List and Load Heptabase Backups

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Tools to discover available backup files and load them into memory. Supports filtering, sorting, and automatic zip extraction for efficient data access.

```typescript
const result = await mcpClient.callTool({
  name: "listBackups",
  parameters: { sortBy: "size", limit: 3 }
});

await mcpClient.callTool({
  name: "loadBackup",
  parameters: {
    backupId: "Heptabase-Data-Backup-2025-05-18",
    extract: true
  }
});
```

--------------------------------

### Export Whiteboard to File (TypeScript)

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Exports a whiteboard's content into Markdown, JSON, or HTML format and saves it to a specified file path. This process can include cards, connections, and metadata.

```typescript
// Export whiteboard to markdown
await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    format: "markdown",
    includeCards: true,
    includeConnections: true,
    includeMetadata: true,
    outputPath: "/path/to/output/project-planning.md"
  }
});
// Output: "Exported whiteboard to /path/to/output/project-planning.md
// Included metadata in export"

// Export as JSON for programmatic use
await mcpClient.callTool({
  name: "exportWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    format: "json",
    includeCards: true,
    outputPath: "/path/to/output/project-planning.json"
  }
});
```

--------------------------------

### Claude Desktop MCP Server Configuration (JSON)

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/CONFIG.md

A JSON configuration snippet for setting up MCP servers within Claude Desktop, specifically for Heptabase. It defines the command to run, arguments for the script, and environment variables for the Heptabase server.

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

--------------------------------

### Data Retrieval Tools

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Tools for retrieving detailed information about whiteboards.

```APIDOC
## getWhiteboard

### Description
Retrieves complete whiteboard data including metadata, cards, and connections. Use this to get full details about a specific whiteboard.

### Method
CALL_TOOL

### Endpoint
getWhiteboard

### Parameters
#### Path Parameters
None

#### Query Parameters
- **whiteboardId** (string) - Required - The ID of the whiteboard to retrieve.
- **includeCards** (boolean) - Optional - If true, includes all cards associated with the whiteboard.
- **includeConnections** (boolean) - Optional - If true, includes all connections between cards on the whiteboard.

#### Request Body
- **parameters** (object) - Contains optional parameters for retrieving whiteboard data.

### Request Example
```json
{
  "name": "getWhiteboard",
  "parameters": {
    "whiteboardId": "553bb6e7-4bda-48bf-8f1c-d18891364077",
    "includeCards": true,
    "includeConnections": true
  }
}
```

### Response
#### Success Response (200)
- **whiteboard** (object) - An object containing the full details of the whiteboard, including metadata, cards, and connections.

#### Response Example
```json
{
  "whiteboard": {
    "id": "553bb6e7-4bda-48bf-8f1c-d18891364077",
    "name": "Project Planning 2025",
    "created": "2025-01-15T10:30:00Z",
    "lastEdited": "2025-05-17T14:22:00Z",
    "cards": [
      {
        "id": "card-001",
        "title": "Requirements Document",
        "content": "..."
      },
      {
        "id": "card-002",
        "title": "Architecture Overview",
        "content": "..."
      }
    ],
    "connections": [
      {
        "fromCardId": "card-001",
        "toCardId": "card-002",
        "type": "depends on"
      }
    ]
  }
}
```
```

--------------------------------

### Backup Management Tools

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Tools for configuring backup paths, listing available backups, and loading specific backups for processing.

```APIDOC
## configureBackupPath

### Description
Configures the backup directory path and monitoring settings. This is typically the first tool called to initialize the service with the location of your Heptabase backup files.

### Method
CALL_TOOL

### Endpoint
configureBackupPath

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **path** (string) - Required - The absolute path to the Heptabase backup directory.
- **watchForChanges** (boolean) - Optional - If true, the service will monitor the directory for new backup files.
- **autoExtract** (boolean) - Optional - If true, newly discovered zip backups will be automatically extracted.

### Request Example
```json
{
  "name": "configureBackupPath",
  "parameters": {
    "path": "/path/to/your/heptabase/backups",
    "watchForChanges": true,
    "autoExtract": true
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the backup path was configured successfully.

#### Response Example
```json
{
  "message": "Backup path configured successfully: /path/to/your/heptabase/backups"
}
```
```

```APIDOC
## listBackups

### Description
Lists all available backup files in the configured directory, sorted by date (newest first) by default. Supports filtering by custom path, sorting by size, and limiting results.

### Method
CALL_TOOL

### Endpoint
listBackups

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sortBy** (string) - Optional - Specifies the sorting criteria. Can be 'date' (default) or 'size'.
- **limit** (integer) - Optional - Limits the number of backups returned.
- **customPath** (string) - Optional - A specific path within the configured backup directory to list backups from.

#### Request Body
- **parameters** (object) - Contains optional parameters for listing backups.

### Request Example
```json
{
  "name": "listBackups",
  "parameters": {
    "sortBy": "size",
    "limit": 3
  }
}
```

### Response
#### Success Response (200)
- **backups** (array) - A list of backup objects, each containing details like name, size, and date.

#### Response Example
```json
{
  "backups": [
    {
      "name": "Heptabase-Data-Backup-2025-05-18",
      "size": 245678,
      "date": "2025-05-18"
    },
    {
      "name": "Heptabase-Data-Backup-2025-05-15",
      "size": 234567,
      "date": "2025-05-15"
    }
  ]
}
```
```

```APIDOC
## loadBackup

### Description
Loads a specific backup file into memory for querying. Supports loading by full path or backup ID, with optional automatic extraction of zip files.

### Method
CALL_TOOL

### Endpoint
loadBackup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **backupId** (string) - Optional - The ID of the backup to load (e.g., 'Heptabase-Data-Backup-2025-05-18').
- **backupPath** (string) - Optional - The full path to the backup file to load.
- **extract** (boolean) - Optional - If true and the backup is a zip file, it will be extracted before loading.

### Request Example
```json
{
  "name": "loadBackup",
  "parameters": {
    "backupId": "Heptabase-Data-Backup-2025-05-18",
    "extract": true
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the backup was loaded successfully.

#### Response Example
```json
{
  "message": "Backup loaded successfully: Heptabase-Data-Backup-2025-05-18"
}
```
```

--------------------------------

### Summarize Whiteboard Content (TypeScript)

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Generates a summary of a whiteboard's content in either text or a structured format. It can optionally include statistics such as word count and character count for the content.

```typescript
// Generate text summary with statistics
const result = await mcpClient.callTool({
  name: "summarizeWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    format: "text",
    includeStatistics: true
  }
});
// Output: "Project Planning 2025
//
// Summary: 15 cards, 8 connections
//
// Statistics:
// - Word count: 2450
// - Character count: 14567
//
// Cards:
// - Requirements Document
// - Architecture Overview
// ..."

// Generate structured summary
const result = await mcpClient.callTool({
  name: "summarizeWhiteboard",
  parameters: {
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077",
    format: "structured"
  }
});
```

--------------------------------

### Search Tools

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Tools for searching whiteboards and cards based on various criteria.

```APIDOC
## searchWhiteboards

### Description
Searches for whiteboards by name, date range, or other criteria. Returns matching whiteboards with their IDs and last edited timestamps.

### Method
CALL_TOOL

### Endpoint
searchWhiteboards

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (string) - Optional - A search term to match against whiteboard names.
- **dateRange** (object) - Optional - An object with 'start' and 'end' dates (YYYY-MM-DD) to filter by last edited date.
- **hasCards** (boolean) - Optional - If true, only returns whiteboards that contain cards.

#### Request Body
- **parameters** (object) - Contains optional parameters for searching whiteboards.

### Request Example
```json
{
  "name": "searchWhiteboards",
  "parameters": {
    "query": "Project Planning",
    "dateRange": {
      "start": "2025-01-01",
      "end": "2025-06-30"
    },
    "hasCards": true
  }
}
```

### Response
#### Success Response (200)
- **whiteboards** (array) - A list of matching whiteboard objects, each with an ID, name, and last edited timestamp.

#### Response Example
```json
{
  "whiteboards": [
    {
      "id": "553bb6e7-4bda-48bf-8f1c-d18891364077",
      "name": "Project Planning 2025",
      "lastEdited": "2025-05-17T14:22:00Z"
    },
    {
      "id": "7a2c9e1f-8d3b-4c5a-9e6f-0a1b2c3d4e5f",
      "name": "Project Planning Q1",
      "lastEdited": "2025-03-20T09:00:00Z"
    }
  ]
}
```
```

```APIDOC
## searchCards

### Description
Searches for cards across all whiteboards by content, tags, content type, or date range. Returns card titles and IDs for further retrieval.

### Method
CALL_TOOL

### Endpoint
searchCards

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (string) - Optional - Text content to search for within cards.
- **tags** (array of strings) - Optional - Tags to filter cards by.
- **whiteboardId** (string) - Optional - The ID of the whiteboard to search within.
- **dateRange** (object) - Optional - An object with 'start' and 'end' dates (YYYY-MM-DD) to filter by creation or last edited date.

#### Request Body
- **parameters** (object) - Contains optional parameters for searching cards.

### Request Example
```json
{
  "name": "searchCards",
  "parameters": {
    "query": "API design",
    "tags": ["important", "todo"],
    "whiteboardId": "553bb6e7-4bda-48bf-8f1c-d18891364077",
    "dateRange": {
      "start": "2025-01-01",
      "end": "2025-12-31"
    }
  }
}
```

### Response
#### Success Response (200)
- **cards** (array) - A list of matching card objects, each with a title and ID.

#### Response Example
```json
{
  "cards": [
    {
      "title": "API Design Principles",
      "id": "card-123-abc"
    },
    {
      "title": "REST API Endpoints",
      "id": "card-456-def"
    }
  ]
}
```
```

--------------------------------

### Configure Claude Desktop for Heptabase MCP

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/README.md

JSON configuration schema for integrating the Heptabase MCP server into the Claude Desktop application.

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

--------------------------------

### Search Tools

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Tools for searching whiteboards and cards within the loaded Heptabase backups.

```APIDOC
## searchWhiteboards

### Description
Search for whiteboards by various criteria.

### Method
TOOL

### Endpoint
searchWhiteboards

### Parameters
#### Request Body
- **query** (string) - Optional - Search query string
- **dateRange** (object) - Optional - Date range for search
  - **start** (Date) - Required - Start date
  - **end** (Date) - Required - End date
- **hasCards** (boolean) - Optional - Filter for whiteboards with cards
- **spaceId** (string) - Optional - Filter by space ID

### Request Example
```json
{
  "tool": "searchWhiteboards",
  "parameters": {
    "query": "AI",
    "dateRange": {
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-12-31T23:59:59Z"
    },
    "hasCards": true
  }
}
```

### Response
#### Success Response (200)
- **whiteboards** (array) - List of matching whiteboard objects
  - **id** (string) - Whiteboard ID
  - **name** (string) - Whiteboard name
  - **createdAt** (string) - Creation date

#### Response Example
```json
{
  "whiteboards": [
    {
      "id": "wb-abc",
      "name": "AI Research",
      "createdAt": "2023-10-26T14:30:00Z"
    }
  ]
}
```
```

```APIDOC
## searchCards

### Description
Search for cards across all whiteboards.

### Method
TOOL

### Endpoint
searchCards

### Parameters
#### Request Body
- **query** (string) - Optional - Search query string for card content
- **tags** (array) - Optional - List of tags to filter by
- **whiteboardId** (string) - Optional - Filter cards within a specific whiteboard
- **contentType** (string) - Optional - Filter by content type (`text`, `image`, `link`)
- **dateRange** (object) - Optional - Date range for card creation or modification
  - **start** (Date) - Required - Start date
  - **end** (Date) - Required - End date

### Request Example
```json
{
  "tool": "searchCards",
  "parameters": {
    "query": "machine learning",
    "tags": ["AI", "research"],
    "contentType": "text"
  }
}
```

### Response
#### Success Response (200)
- **cards** (array) - List of matching card objects
  - **id** (string) - Card ID
  - **content** (string) - Card content
  - **tags** (array) - List of tags
  - **whiteboardId** (string) - ID of the whiteboard the card belongs to

#### Response Example
```json
{
  "cards": [
    {
      "id": "card-xyz",
      "content": "Details about machine learning algorithms.",
      "tags": ["AI", "research", "ML"],
      "whiteboardId": "wb-abc"
    }
  ]
}
```
```

--------------------------------

### List Backups - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Lists available backup files within the configured directory. This tool supports overriding the default path, sorting the results by date or size, and limiting the number of returned backups.

```typescript
tool: "listBackups"
parameters: {
  path?: string            // Override default path
  sortBy?: "date" | "size" // Sort order
  limit?: number          // Max results
}
```

--------------------------------

### Compare Backups - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Compares two different backup versions. Supports different comparison types: 'summary', 'detailed', or 'changes' to highlight differences between backups.

```typescript
tool: "compareBackups"
parameters: {
  backup1: string
  backup2: string
  compareType: "summary" | "detailed" | "changes"
}
```

--------------------------------

### Data Retrieval Tools

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Tools for retrieving detailed information about whiteboards and cards.

```APIDOC
## getWhiteboard

### Description
Retrieve complete whiteboard data, including cards and connections.

### Method
TOOL

### Endpoint
getWhiteboard

### Parameters
#### Request Body
- **whiteboardId** (string) - Required - The ID of the whiteboard to retrieve
- **includeCards** (boolean) - Optional - Whether to include cards in the response
- **includeConnections** (boolean) - Optional - Whether to include connections between cards
- **depth** (number) - Optional - Depth for nested cards (if applicable)

### Request Example
```json
{
  "tool": "getWhiteboard",
  "parameters": {
    "whiteboardId": "wb-abc",
    "includeCards": true,
    "includeConnections": true,
    "depth": 2
  }
}
```

### Response
#### Success Response (200)
- **whiteboard** (object) - Whiteboard data
  - **id** (string) - Whiteboard ID
  - **name** (string) - Whiteboard name
  - **cards** (array) - List of cards (if requested)
  - **connections** (array) - List of connections (if requested)

#### Response Example
```json
{
  "whiteboard": {
    "id": "wb-abc",
    "name": "AI Research",
    "cards": [...],
    "connections": [...] 
  }
}
```
```

```APIDOC
## getCard

### Description
Retrieve card data in various formats, with options to include related information.

### Method
TOOL

### Endpoint
getCard

### Parameters
#### Request Body
- **cardId** (string) - Required - The ID of the card to retrieve
- **format** (string) - Optional - Desired output format (`json`, `markdown`, `html`)
- **includeRelated** (boolean) - Optional - Whether to include related cards or information

### Request Example
```json
{
  "tool": "getCard",
  "parameters": {
    "cardId": "card-xyz",
    "format": "markdown",
    "includeRelated": true
  }
}
```

### Response
#### Success Response (200)
- **cardData** (string or object) - The card data in the requested format

#### Response Example
```json
{
  "cardData": "# Card Title\n\nThis is the content of the card in Markdown format."
}
```
```

```APIDOC
## getCardsByArea

### Description
Get cards located within a specific area on a whiteboard.

### Method
TOOL

### Endpoint
getCardsByArea

### Parameters
#### Request Body
- **whiteboardId** (string) - Required - The ID of the whiteboard
- **x** (number) - Required - The X-coordinate of the area center
- **y** (number) - Required - The Y-coordinate of the area center
- **radius** (number) - Optional - The radius of the circular area

### Request Example
```json
{
  "tool": "getCardsByArea",
  "parameters": {
    "whiteboardId": "wb-abc",
    "x": 100,
    "y": 200,
    "radius": 50
  }
}
```

### Response
#### Success Response (200)
- **cards** (array) - List of card objects within the specified area
  - **id** (string) - Card ID
  - **content** (string) - Card content

#### Response Example
```json
{
  "cards": [
    {
      "id": "card-1",
      "content": "Card content here."
    }
  ]
}
```
```

--------------------------------

### Backup Management Tools

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Tools for managing Heptabase backup files, including configuring paths, listing backups, and loading specific backup files.

```APIDOC
## configureBackupPath

### Description
Configure the backup directory path and monitoring settings.

### Method
TOOL

### Endpoint
configureBackupPath

### Parameters
#### Request Body
- **path** (string) - Required - Path to backup directory
- **watchForChanges** (boolean) - Optional - Auto-detect new backups
- **autoExtract** (boolean) - Optional - Auto-extract zip files

### Request Example
```json
{
  "tool": "configureBackupPath",
  "parameters": {
    "path": "/path/to/backups",
    "watchForChanges": true,
    "autoExtract": true
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message

#### Response Example
```json
{
  "status": "Backup path configured successfully."
}
```
```

```APIDOC
## listBackups

### Description
List available backup files in the configured directory.

### Method
TOOL

### Endpoint
listBackups

### Parameters
#### Query Parameters
- **path** (string) - Optional - Override default path
- **sortBy** (string) - Optional - Sort order (`date` or `size`)
- **limit** (number) - Optional - Maximum number of results

### Request Example
```json
{
  "tool": "listBackups",
  "parameters": {
    "sortBy": "date",
    "limit": 10
  }
}
```

### Response
#### Success Response (200)
- **backups** (array) - List of backup objects
  - **id** (string) - Unique backup identifier
  - **name** (string) - Backup file name
  - **date** (string) - Backup creation date
  - **size** (number) - Backup size in bytes

#### Response Example
```json
{
  "backups": [
    {
      "id": "backup-123",
      "name": "backup_2023-10-27.zip",
      "date": "2023-10-27T10:00:00Z",
      "size": 10485760
    }
  ]
}
```
```

```APIDOC
## loadBackup

### Description
Load a specific backup file into memory.

### Method
TOOL

### Endpoint
loadBackup

### Parameters
#### Request Body
- **backupPath** (string) - Optional - Full path to backup
- **backupId** (string) - Optional - Or use backup ID
- **extract** (boolean) - Optional - Extract if zipped

### Request Example
```json
{
  "tool": "loadBackup",
  "parameters": {
    "backupId": "backup-123",
    "extract": true
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message
- **backupId** (string) - Loaded backup ID

#### Response Example
```json
{
  "status": "Backup loaded successfully.",
  "backupId": "backup-123"
}
```
```

--------------------------------

### Analysis Tools

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Tools for analyzing relationships between cards and comparing different backup versions.

```APIDOC
## analyzeGraph

### Description
Analyze the relationships between cards, starting from a specific card and traversing connections up to a defined depth.

### Method
TOOL

### Endpoint
analyzeGraph

### Parameters
#### Request Body
- **startCardId** (string) - Required - The ID of the card to start the graph analysis from
- **maxDepth** (number) - Optional - The maximum depth to explore relationships
- **relationshipTypes** (array) - Optional - Filter analysis by specific relationship types

### Request Example
```json
{
  "tool": "analyzeGraph",
  "parameters": {
    "startCardId": "card-xyz",
    "maxDepth": 3,
    "relationshipTypes": ["depends_on", "related_to"]
  }
}
```

### Response
#### Success Response (200)
- **graphAnalysis** (object) - Results of the graph analysis, detailing connections and paths

#### Response Example
```json
{
  "graphAnalysis": {
    "nodes": [...],
    "edges": [...] 
  }
}
```
```

```APIDOC
## compareBackups

### Description
Compare two different backup versions to identify differences or similarities.

### Method
TOOL

### Endpoint
compareBackups

### Parameters
#### Request Body
- **backup1** (string) - Required - Identifier for the first backup version
- **backup2** (string) - Required - Identifier for the second backup version
- **compareType** (string) - Required - Type of comparison (`summary`, `detailed`, `changes`)

### Request Example
```json
{
  "tool": "compareBackups",
  "parameters": {
    "backup1": "backup-123",
    "backup2": "backup-456",
    "compareType": "changes"
  }
}
```

### Response
#### Success Response (200)
- **comparisonResult** (object or string) - The result of the backup comparison, format depends on `compareType`

#### Response Example
```json
{
  "comparisonResult": {
    "addedCards": [...],
    "removedCards": [...],
    "modifiedCards": [...] 
  }
}
```
```

--------------------------------

### Search Whiteboards and Cards

Source: https://context7.com/larrystanley/heptabase-mcp/llms.txt

Enables querying of whiteboards and cards using various filters such as text content, tags, date ranges, and parent whiteboard IDs.

```typescript
const whiteboards = await mcpClient.callTool({
  name: "searchWhiteboards",
  parameters: { query: "Project Planning" }
});

const cards = await mcpClient.callTool({
  name: "searchCards",
  parameters: {
    tags: ["important", "todo"],
    whiteboardId: "553bb6e7-4bda-48bf-8f1c-d18891364077"
  }
});
```

--------------------------------

### Search Whiteboards - TypeScript

Source: https://github.com/larrystanley/heptabase-mcp/blob/main/SPECIFICATION.md

Searches for whiteboards based on various criteria. Supports searching by query string, date range, presence of cards, and filtering by space ID.

```typescript
tool: "searchWhiteboards"
parameters: {
  query?: string
  dateRange?: { start: Date, end: Date }
  hasCards?: boolean
  spaceId?: string
}
```