Cursor Conversations MCP Server

Instructions

Implementation Reference

• src/tools/extraction-tools.ts:135-219 (handler)

  Core implementation of the export_conversation_data tool handler. Connects to database, filters conversations, retrieves summaries/content, exports to JSON/CSV/Graph formats using utility functions, generates metadata, and returns structured ExportedData.

  export async function exportConversationData(
    input: ExportConversationDataInput
  ): Promise<ExportedData> {
    const reader = new CursorDatabaseReader();
  
    try {
      await reader.connect();
  
      // Build filters
      const filters: ConversationFilters = {
        format: 'both',
        minLength: input.filters?.minSize || 1000
      };
  
      if (input.filters?.hasCodeBlocks !== undefined) {
        filters.hasCodeBlocks = input.filters.hasCodeBlocks;
      }
  
      if (input.filters?.projectPath) {
        filters.projectPath = input.filters.projectPath;
      }
  
      // Get conversation IDs to export
      let conversationIds = input.conversationIds;
      if (!conversationIds || conversationIds.length === 0) {
        conversationIds = await reader.getConversationIds(filters);
      }
  
      // Get conversation summaries
      const summaries = await reader.getConversationSummariesForAnalytics(conversationIds);
  
      // Get full conversation data if needed
      let conversationData: Map<string, any> | undefined;
      if (input.includeContent) {
        conversationData = new Map();
        for (const id of conversationIds) {
          try {
            const conversation = await reader.getConversationById(id);
            if (conversation) {
              conversationData.set(id, conversation);
            }
          } catch (error) {
            console.error(`Failed to get full conversation data for ${id}:`, error);
          }
        }
      }
  
      // Export in requested format
      let exportedData: any;
  
      switch (input.format) {
        case 'json':
          exportedData = exportAsJSON(summaries, input.includeContent, conversationData);
          break;
  
        case 'csv':
          exportedData = exportAsCSV(summaries, input.flattenStructure);
          break;
  
        case 'graph':
          exportedData = exportAsGraph(summaries, input.includeRelationships);
          break;
  
        default:
          exportedData = exportAsJSON(summaries, input.includeContent, conversationData);
      }
  
      // Create metadata
      const metadata = createExportMetadata(
        summaries.length,
        conversationIds.length,
        input.filters || {}
      );
  
      return {
        format: input.format,
        data: exportedData,
        metadata
      };
  
    } catch (error) {
      throw new DatabaseError(`Failed to export conversation data: ${error instanceof Error ? error.message : 'Unknown error'}`);
    } finally {
      reader.close();
    }

• src/tools/extraction-tools.ts:29-40 (schema)

  Zod schema defining the input validation for exportConversationData function, exported for reuse.

  export const exportConversationDataSchema = z.object({
    conversationIds: z.array(z.string()).optional(),
    format: z.enum(['json', 'csv', 'graph']).optional().default('json'),
    includeContent: z.boolean().optional().default(false),
    includeRelationships: z.boolean().optional().default(false),
    flattenStructure: z.boolean().optional().default(false),
    filters: z.object({
      minSize: z.number().optional(),
      hasCodeBlocks: z.boolean().optional(),
      projectPath: z.string().optional()
    }).optional()
  });

• src/server.ts:340-383 (registration)

  MCP server registration of the 'export_conversation_data' tool, defining its description, input schema, and async handler wrapper that validates input, maps parameters, calls the core exportConversationData function, formats the response, and handles errors.

  server.tool(
    'export_conversation_data',
    'Export chat data in various formats (JSON, CSV, Graph) for external analysis, visualization, or integration with other tools. **TIP: Use filters.projectPath to export only project-specific conversations** for focused analysis of a particular codebase. Use this to create datasets for machine learning, generate reports for stakeholders, prepare data for visualization tools like Gephi or Tableau, or backup chat data in structured formats.',
    {
      conversationIds: z.array(z.string()).optional().describe('Specific conversation IDs to export (if not provided, exports all conversations)'),
      format: z.enum(['json', 'csv', 'graph']).optional().default('json').describe('Export format: JSON for structured data, CSV for spreadsheets, Graph for network analysis'),
      includeContent: z.boolean().optional().default(false).describe('Include full conversation content in the export'),
      includeRelationships: z.boolean().optional().default(false).describe('Include relationship data between conversations'),
      flattenStructure: z.boolean().optional().default(false).describe('Flatten nested structures for easier processing'),
      filters: z.object({
        minSize: z.number().optional().describe('Minimum conversation size to include'),
        hasCodeBlocks: z.boolean().optional().describe('Only include conversations with code blocks'),
                projectPath: z.string().optional().describe('**RECOMMENDED** Only include conversations related to this project/codebase name or path. Dramatically improves relevance by filtering to conversations that actually worked on files in that project.')
      }).optional().describe('Filters to apply when selecting conversations to export'),
      outputMode: z.enum(['json', 'compact-json']).optional().default('json').describe('Output format: "json" for formatted JSON (default), "compact-json" for minified JSON')
    },
    async (input) => {
      try {
        const mappedInput = {
          conversationIds: input.conversationIds,
          format: input.format,
          includeContent: input.includeContent,
          includeRelationships: input.includeRelationships,
          flattenStructure: input.flattenStructure,
          filters: input.filters
        };
  
        const result = await exportConversationData(mappedInput);
        return {
          content: [{
            type: 'text',
            text: formatResponse(result, input.outputMode)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `Error: ${error instanceof Error ? error.message : 'Unknown error occurred'}`
          }]
        };
      }
    }
  );