Heptabase MCP

Implementation Reference

• src/server.ts:473-582 (handler)

  Main handler function for the getCard tool. Initializes data service if needed, calls dataService.getCard, and formats the output as a resource in JSON, Markdown, or HTML based on the format parameter. Handles related whiteboards and connections if requested.

  this.tools.getCard = {
    inputSchema: getCardSchema,
    handler: async (params) => {
      try {
        await this.ensureDataServiceInitialized();
  
        const result = await this.dataService!.getCard(params.cardId);
        const format = params.format || 'json';
        
        let text = '';
        
        if (format === 'markdown') {
          text = `# ${result.card.title || 'Untitled'}\n\n`;
          text += parseHeptabaseContentToMarkdown(result.card.content);
          
          if (params.includeRelated) {
            const instances = result.instances;
            if (instances.length > 0) {
              text += '\n## Appears on whiteboards:\n';
              for (const instance of instances) {
                const wb = await this.dataService!.getWhiteboard(instance.whiteboardId);
                text += `- ${wb.whiteboard.name}\n`;
              }
            }
            
            const connections = await this.dataService!.getConnections(params.cardId);
            if (connections.length > 0) {
              text += `\n## Related connections: ${connections.length}\n`;
            }
          }
          
          // Return as resource to bypass text size limits
          return {
            content: [{
              type: 'resource',
              resource: {
                uri: `heptabase://card/${result.card.id}`,
                mimeType: 'text/markdown',
                text
              }
            }]
          };
        } else if (format === 'html') {
          text = `<h1>${result.card.title || 'Untitled'}</h1>\n`;
          text += parseHeptabaseContentToHtml(result.card.content);
          
          if (params.includeRelated) {
            const instances = result.instances;
            if (instances.length > 0) {
              text += '<h2>Appears on whiteboards:</h2><ul>';
              for (const instance of instances) {
                const wb = await this.dataService!.getWhiteboard(instance.whiteboardId);
                text += `<li>${wb.whiteboard.name}</li>`;
              }
              text += '</ul>';
            }
          }
          
          // Return as resource to bypass text size limits
          return {
            content: [{
              type: 'resource',
              resource: {
                uri: `heptabase://card/${result.card.id}`,
                mimeType: 'text/html',
                text
              }
            }]
          };
        } else {
          // Default JSON format - return full card data as resource
          const cardData: any = {
            id: result.card.id,
            title: result.card.title,
            content: JSON.parse(result.card.content),
            createdTime: result.card.createdTime,
            lastEditedTime: result.card.lastEditedTime,
            instances: result.instances,
            isTrashed: result.card.isTrashed
        };
        
        if (params.includeRelated) {
          const connections = await this.dataService!.getConnections(params.cardId);
          cardData.connections = connections;
        }
        
        return {
          content: [{
            type: 'resource',
            resource: {
              uri: `heptabase://card/${result.card.id}`,
              mimeType: 'application/json',
              text: JSON.stringify(cardData, null, 2)
            }
          }]
        };
      }
      } catch (error) {
        console.error('Error in getCard:', error);
        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
        return {
          content: [{
            type: 'text',
            text: `Error: ${errorMessage}`
          }]
        };
      }
    }
  };

• src/server.ts:467-471 (schema)

  Zod input schema for the getCard tool defining required cardId and optional format (json/markdown/html) and includeRelated flag.

  const getCardSchema = z.object({
    cardId: z.string(),
    format: z.enum(['json', 'markdown', 'html']).optional(),
    includeRelated: z.boolean().optional()
  });

• src/server.ts:583-585 (registration)

  Registers the getCard tool with the MCP server, delegating to the defined handler.

  this.server.tool('getCard', getCardSchema.shape, async (params) => {
    return this.tools.getCard.handler(params);
  });

• src/services/HeptabaseDataService.ts:227-238 (helper)

  Helper method in HeptabaseDataService that retrieves the card by ID and all its instances across whiteboards from the loaded backup data.

  async getCard(cardId: string): Promise<CardResult> {
    const card = this.data.cards[cardId];
    if (!card) {
      throw new Error('Card not found');
    }
  
    const instances = Object.values(this.data.cardInstances).filter(
      instance => instance.cardId === cardId
    );
  
    return { card, instances };
  }