Baloosearch MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.js:93-104 (handler)

  MCP server tool handler for 'search_files' that executes the search by calling the searchFiles helper and returns the results as JSON text.
  async ({ query, limit, offset, directory, type }) => { try { const results = await searchFiles({ query, limit, offset, directory, type }) return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] } } catch (error) { return { content: [{ type: "text", text: `Error searching files: ${error.message}` }] } } }
• src/server/mcp-server.js:28-92 (schema)

  Zod-based input schema defining parameters for the search_files tool: query (required string), limit/offset (optional numbers), directory/type (optional strings). Includes detailed descriptions supporting Baloo search syntax.
  { query: z.string().describe(`The search query terms. Supports advanced search syntax: - Basic search: Simple terms like "project plan" - AND queries: "budget AND marketing" (requires both terms) - OR queries: "report OR presentation" (requires either term) - NOT queries: "financial -tax" or "financial NOT tax" (excludes terms) - Phrase searches: "\\"exact phrase\\"" (matches exact phrases) - Wildcards: "report*" (matches partial words) - Property searches: "Artist:\\"Coldplay\\"" or "Author:\\"Smith\\"" - File type filters: "type:Audio", "type:Document", "type:Image", etc. - Grouping: Use parentheses "(term1 AND term2) OR term3" - Property comparisons: "rating>3", "modified>2024-01-01" Supported file types: - "Archive" (zip, tar, etc.) - "Folder" (directories) - "Audio" (mp3, wav, etc.) - "Video" (mp4, avi, etc.) - "Image" (jpg, png, etc.) - "Document" (pdf, doc, etc.) - "Spreadsheet" (xls, xlsx, etc.) - "Presentation" (ppt, pptx, etc.) - "Text" (txt, etc.) Common properties for all files: - filename (name of the file) - modified (last modification date) - mimetype (MIME type of file) - tags (user-defined tags) - rating (numeric rating 0-10) - userComment (user comments) Audio-specific properties: - Artist, Album, AlbumArtist, Composer, Lyricist - Genre, Duration, BitRate, Channels, SampleRate - TrackNumber, ReleaseYear, Comment Document-specific properties: - Author, Title, Subject, Keywords - PageCount, WordCount, LineCount - Language, Copyright, Publisher - CreationDate, Generator Media-specific properties (Video/Images): - Width, Height, AspectRatio, FrameRate Image-specific properties: - ImageMake, ImageModel, ImageDateTime - PhotoFlash, PhotoFNumber, PhotoISOSpeedRatings - PhotoGpsLatitude, PhotoGpsLongitude, PhotoGpsAltitude`), limit: z.number().optional().describe("Maximum number of results to return (default: 10)"), offset: z.number().optional().describe("Offset from which to start the search (default: 0)"), directory: z.string().optional().describe("Limit search to specified directory (absolute path)"), type: z.string().optional().describe(`Type of data to be searched. Common types include: - "Archive" (zip, tar, etc.) - "Folder" (directories) - "Audio" (mp3, wav, etc.) - "Video" (mp4, avi, etc.) - "Image" (jpg, png, etc.) - "Document" (pdf, doc, etc.) - "Spreadsheet" (xls, xlsx, etc.) - "Presentation" (ppt, pptx, etc.) - "Text" (txt, etc.) Note: This parameter is an alternative to using "type:" in the query.`) },
• src/server/mcp-server.js:14-105 (registration)

  Registration of the 'search_files' MCP tool via server.tool(), including name, multi-line description of query syntax, schema, and handler function.
  server.tool( "search_files", `Search for terms in files using KDE baloosearch. Query Syntax Examples: - Simple search: "project plan" - Multiple terms: "budget AND marketing" (finds files with both terms) - OR search: "report OR presentation" (finds files with either term) - Phrase search: "\\"strategic plan\\"" (finds exact phrase) - Exclusion: "financial -tax" (finds files with "financial" but not "tax") - Wildcard: "report*" (finds files with words starting with "report") - Property search: "Artist:\\"Coldplay\\"" (finds audio files by artist) - File type search: "type:Audio" (finds audio files) - Combined expressions: "(type:Audio AND Artist:\\"Coldplay\\") OR (type:Document AND subject:\\"music\\")"`, { query: z.string().describe(`The search query terms. Supports advanced search syntax: - Basic search: Simple terms like "project plan" - AND queries: "budget AND marketing" (requires both terms) - OR queries: "report OR presentation" (requires either term) - NOT queries: "financial -tax" or "financial NOT tax" (excludes terms) - Phrase searches: "\\"exact phrase\\"" (matches exact phrases) - Wildcards: "report*" (matches partial words) - Property searches: "Artist:\\"Coldplay\\"" or "Author:\\"Smith\\"" - File type filters: "type:Audio", "type:Document", "type:Image", etc. - Grouping: Use parentheses "(term1 AND term2) OR term3" - Property comparisons: "rating>3", "modified>2024-01-01" Supported file types: - "Archive" (zip, tar, etc.) - "Folder" (directories) - "Audio" (mp3, wav, etc.) - "Video" (mp4, avi, etc.) - "Image" (jpg, png, etc.) - "Document" (pdf, doc, etc.) - "Spreadsheet" (xls, xlsx, etc.) - "Presentation" (ppt, pptx, etc.) - "Text" (txt, etc.) Common properties for all files: - filename (name of the file) - modified (last modification date) - mimetype (MIME type of file) - tags (user-defined tags) - rating (numeric rating 0-10) - userComment (user comments) Audio-specific properties: - Artist, Album, AlbumArtist, Composer, Lyricist - Genre, Duration, BitRate, Channels, SampleRate - TrackNumber, ReleaseYear, Comment Document-specific properties: - Author, Title, Subject, Keywords - PageCount, WordCount, LineCount - Language, Copyright, Publisher - CreationDate, Generator Media-specific properties (Video/Images): - Width, Height, AspectRatio, FrameRate Image-specific properties: - ImageMake, ImageModel, ImageDateTime - PhotoFlash, PhotoFNumber, PhotoISOSpeedRatings - PhotoGpsLatitude, PhotoGpsLongitude, PhotoGpsAltitude`), limit: z.number().optional().describe("Maximum number of results to return (default: 10)"), offset: z.number().optional().describe("Offset from which to start the search (default: 0)"), directory: z.string().optional().describe("Limit search to specified directory (absolute path)"), type: z.string().optional().describe(`Type of data to be searched. Common types include: - "Archive" (zip, tar, etc.) - "Folder" (directories) - "Audio" (mp3, wav, etc.) - "Video" (mp4, avi, etc.) - "Image" (jpg, png, etc.) - "Document" (pdf, doc, etc.) - "Spreadsheet" (xls, xlsx, etc.) - "Presentation" (ppt, pptx, etc.) - "Text" (txt, etc.) Note: This parameter is an alternative to using "type:" in the query.`) }, async ({ query, limit, offset, directory, type }) => { try { const results = await searchFiles({ query, limit, offset, directory, type }) return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] } } catch (error) { return { content: [{ type: "text", text: `Error searching files: ${error.message}` }] } } } )
• src/tools/baloosearch-tool.js:16-71 (helper)

  Helper function implementing the core search logic using 'baloosearch' CLI command. Validates inputs, constructs command with options, executes via child_process, parses output into array of file paths.
  export async function searchFiles({ query, limit = 10, offset = 0, directory, type }) { // Validate inputs if (!query || typeof query !== 'string') { throw new Error('Query is required and must be a string') } if (limit && (typeof limit !== 'number' || limit <= 0)) { throw new Error('Limit must be a positive number') } if (offset && (typeof offset !== 'number' || offset < 0)) { throw new Error('Offset must be a non-negative number') } // Build the baloosearch command let command = `baloosearch` // Add options command += ` --limit ${limit}` command += ` --offset ${offset}` if (directory) { command += ` --directory "${directory}"` } if (type) { command += ` --type "${type}"` } // Add the query command += ` "${query}"` try { // Execute the command const { stdout, stderr } = await execPromise(command) // Parse the output const lines = stdout.trim().split('\n').filter(line => line.length > 0) // Filter out the "Elapsed" line that baloosearch adds at the end const filePaths = lines.filter(line => !line.startsWith('Elapsed:')) const results = [] for (const filePath of filePaths) { // Each line represents a search result results.push({ path: filePath, query: query }) } return results } catch (error) { throw new Error(`Failed to execute baloosearch: ${error.message}`) } }