Cursor Conversations MCP Server

Instructions

Implementation Reference

• src/tools/extraction-tools.ts:48-130 (handler)

  The primary handler function that executes the tool's core logic: connects to the database reader, fetches conversation IDs if not provided, extracts elements using the reader, and applies grouping/flattening based on input parameters.
  export async function extractConversationElements( input: ExtractConversationElementsInput ): Promise<ExtractedElements> { const reader = new CursorDatabaseReader(); try { await reader.connect(); // Get conversation IDs to process let conversationIds = input.conversationIds; if (!conversationIds || conversationIds.length === 0) { // Get all conversation IDs if none specified conversationIds = await reader.getConversationIds({ format: 'both', minLength: 1000 }); } // Extract elements from conversations const extractedData = await reader.extractConversationElements( conversationIds, input.elements, { includeContext: input.includeContext, filters: input.filters } ); // Group data based on groupBy parameter if (input.groupBy === 'conversation') { return { conversations: extractedData }; } else if (input.groupBy === 'element') { // Group by element type const groupedData: Record<string, any[]> = {}; for (const elementType of input.elements) { groupedData[elementType] = []; for (const conversation of extractedData) { if (conversation.elements[elementType]) { if (Array.isArray(conversation.elements[elementType])) { groupedData[elementType].push(...conversation.elements[elementType]); } else { groupedData[elementType].push(conversation.elements[elementType]); } } } } return { conversations: groupedData } as any; } else { // Flatten all data const flatData: any[] = []; for (const conversation of extractedData) { for (const elementType of input.elements) { if (conversation.elements[elementType]) { if (Array.isArray(conversation.elements[elementType])) { flatData.push(...conversation.elements[elementType].map((item: any) => ({ ...item, conversationId: conversation.composerId, elementType }))); } else { flatData.push({ ...conversation.elements[elementType], conversationId: conversation.composerId, elementType }); } } } } return { conversations: flatData } as any; } } catch (error) { throw new DatabaseError(`Failed to extract conversation elements: ${error instanceof Error ? error.message : 'Unknown error'}`); } finally { reader.close(); } }
• src/server.ts:297-338 (registration)

  MCP server registration of the 'extract_conversation_elements' tool, including description, input schema definition, and thin wrapper handler that maps input and calls the main extraction function.
  server.tool( 'extract_conversation_elements', 'Extract specific elements from conversations such as file references, code blocks, programming languages, folder paths, metadata, or conversation structure. Use this to build knowledge bases, analyze code patterns, extract reusable snippets, understand project file usage, or prepare data for further analysis and documentation.', { conversationIds: z.array(z.string()).optional().describe('Specific conversation IDs to extract elements from (if not provided, extracts from all conversations)'), elements: z.array(z.enum(['files', 'folders', 'languages', 'codeblocks', 'metadata', 'structure'])).optional().default(['files', 'codeblocks']).describe('Types of elements to extract from conversations'), includeContext: z.boolean().optional().default(false).describe('Include surrounding context for extracted elements'), groupBy: z.enum(['conversation', 'element', 'none']).optional().default('conversation').describe('How to group the extracted elements in the output'), filters: z.object({ minCodeLength: z.number().optional().describe('Minimum length for code blocks to include'), fileExtensions: z.array(z.string()).optional().describe('Only include files with these extensions'), languages: z.array(z.string()).optional().describe('Only include code blocks in these programming languages') }).optional().describe('Filters to apply when extracting elements'), 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, elements: input.elements, includeContext: input.includeContext, groupBy: input.groupBy, filters: input.filters }; const result = await extractConversationElements(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/tools/extraction-tools.ts:17-27 (schema)

  Zod schema for validating the input parameters to the extractConversationElements function.
  export const extractConversationElementsSchema = z.object({ conversationIds: z.array(z.string()).optional(), elements: z.array(z.enum(['files', 'folders', 'languages', 'codeblocks', 'metadata', 'structure'])).optional().default(['files', 'codeblocks']), includeContext: z.boolean().optional().default(false), groupBy: z.enum(['conversation', 'element', 'none']).optional().default('conversation'), filters: z.object({ minCodeLength: z.number().optional(), fileExtensions: z.array(z.string()).optional(), languages: z.array(z.string()).optional() }).optional() });
• src/database/reader.ts:1237-1310 (helper)

  Core helper method in CursorDatabaseReader class that performs the actual extraction of specified elements (files, folders, languages, codeblocks, metadata, structure) from conversations by delegating to specialized extract* methods.
  async extractConversationElements( conversationIds: string[], elements: Array<'files' | 'folders' | 'languages' | 'codeblocks' | 'metadata' | 'structure'>, options?: { includeContext?: boolean; filters?: { minCodeLength?: number; fileExtensions?: string[]; languages?: string[]; }; } ): Promise<Array<{ composerId: string; format: 'legacy' | 'modern'; elements: any; }>> { this.ensureConnected(); const results: Array<{ composerId: string; format: 'legacy' | 'modern'; elements: any; }> = []; for (const composerId of conversationIds) { try { const conversation = await this.getConversationById(composerId); if (!conversation) continue; const format = isLegacyConversation(conversation) ? 'legacy' : 'modern'; const extractedElements: any = {}; // Extract files if (elements.includes('files')) { extractedElements.files = await this.extractFiles(conversation, options); } // Extract folders if (elements.includes('folders')) { extractedElements.folders = await this.extractFolders(conversation, options); } // Extract languages if (elements.includes('languages')) { extractedElements.languages = await this.extractLanguages(conversation, options); } // Extract code blocks if (elements.includes('codeblocks')) { extractedElements.codeblocks = await this.extractCodeBlocks(conversation, options); } // Extract metadata if (elements.includes('metadata')) { extractedElements.metadata = await this.extractMetadata(conversation); } // Extract structure if (elements.includes('structure')) { extractedElements.structure = await this.extractStructure(conversation); } results.push({ composerId, format, elements: extractedElements }); } catch (error) { console.error(`Failed to extract elements from conversation ${composerId}:`, error); } } return results; }