Cursor Conversations MCP Server

Instructions

Implementation Reference

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

  The core handler function that performs the extraction logic: connects to the database reader, fetches conversation IDs if not provided, extracts specified elements with filters and context, applies grouping (by conversation, element, or flat), and handles errors.

  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/tools/extraction-tools.ts:17-27 (schema)

  Zod schema defining the input parameters for the extractConversationElements tool, used for validation and TypeScript typing.

  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/server.ts:297-338 (registration)

  MCP server registration of the 'extract_conversation_elements' tool, including name, description, input schema (matching the exported schema), and wrapper async handler that maps input, calls the core extractConversationElements function, formats the response, and handles errors.

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