Cursor Conversations MCP Server

Instructions

Implementation Reference

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

  The core handler function that implements the export_conversation_data tool logic. It connects to the database, applies filters, fetches conversation data or summaries, exports to JSON/CSV/Graph formats using helper functions, generates metadata, and handles errors.
  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-43 (schema)

  Zod schema and TypeScript type definition for the input parameters of the exportConversationData handler.
  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() }); export type ExtractConversationElementsInput = z.infer<typeof extractConversationElementsSchema>; export type ExportConversationDataInput = z.infer<typeof exportConversationDataSchema>;
• src/server.ts:340-383 (registration)

  MCP server registration of the 'export_conversation_data' tool, including the tool description, Zod input schema (matching the handler schema), and the async handler that maps inputs and calls the exportConversationData function.
  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'}` }] }; } } );
• src/server.ts:40-42 (registration)

  Import statement in server.ts that brings in the exportConversationData handler function from extraction-tools.js for use in the MCP tool registration.
  extractConversationElements, exportConversationData } from './tools/extraction-tools.js';