Baloosearch MCP Server

# Baloosearch MCP Server A Model Context Protocol (MCP) server that provides file search functionality using KDE's baloosearch tool. ## Description This MCP server exposes a tool that allows AI assistants to search for terms in files using the KDE baloosearch utility. It enables semantic search across your file system to find relevant documents and content. The server implements the Model Context Protocol specification and can be used with any MCP-compatible client, such as Claude Desktop or other AI assistants that support the protocol. ## Features - Search for terms in files using KDE baloosearch - Configurable search parameters (limit, offset, directory, file type) - Advanced query syntax support (AND, OR, NOT, phrases, wildcards) - Property-based searches (Artist, Author, etc.) - File type filtering (Audio, Document, Image, etc.) - JSON output of search results - Full MCP compliance for integration with AI assistants ## Prerequisites - Node.js (v18 or higher) - KDE baloosearch tool (typically installed with KDE desktop environment) ## Installation ```bash npm install ``` ## Running with npx You can run this MCP server directly using npx without installing it globally: ```bash npx baloosearch-mcp ``` This will start the MCP server that can be used with any MCP-compatible AI assistant. ## Usage ### Starting the Server ```bash npm start ``` The server will start and listen for MCP requests via stdio. ### Testing the Baloosearch Tool ```bash npm run test-tool ``` This runs a direct test of the baloosearch functionality. ## Tools ### 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\")"` - 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` **Parameters:** - `query` (string, required): The search query terms. Supports advanced search syntax: - `AND`: Requires both terms (e.g., `"budget AND marketing"`) - `OR`: Requires either term (e.g., `"report OR presentation"`) - `NOT` or `-`: Excludes terms (e.g., `"financial -tax"` or `"financial NOT tax"`) - Phrase search: Use quotes for exact phrases (e.g., `"\"project plan\""`) - Wildcards: Use `*` for partial matching (e.g., `"report*"`) - Property searches: `"Artist:\"Coldplay\""` or `"Author:\"Smith\""` - File type filters: `"type:Audio"`, `"type:Document"`, `"type:Image"`, etc. - Property comparisons: `"rating>3"`, `"modified>2024-01-01"` - Grouping: Use parentheses to group terms (e.g., `"(budget OR finance) AND 2024"`) - `limit` (number, optional): Maximum number of results to return (default: 10) - `offset` (number, optional): Offset from which to start the search (default: 0) - `directory` (string, optional): Limit search to specified directory (absolute path) - `type` (string, optional): 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. **Returns:** - JSON array of objects containing file paths that match the search criteria ## Testing with Command Line You can test the server directly from the command line using echo and pipes: ### List Available Tools ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/server/mcp-server.js ``` ### Search for Files ```bash echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"test","limit":3}}}' | node src/server/mcp-server.js ``` ### Advanced Search Examples ```bash # Search for files with both "budget" and "marketing" echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"budget AND marketing","limit":5}}}' | node src/server/mcp-server.js # Search for audio files by a specific artist echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Audio AND Artist:\"ArtistName\"","limit":5}}}' | node src/server/mcp-server.js # Search for documents with high ratings echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Document AND rating>3","limit":5}}}' | node src/server/mcp-server.js # Search for recent documents echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Document AND modified>2024-01-01","limit":5}}}' | node src/server/mcp-server.js # Search for images with specific properties echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"search_files","arguments":{"query":"type:Image AND PhotoFNumber<2.8","limit":5}}}' | node src/server/mcp-server.js ``` ## Integration with Claude Desktop To use this server with Claude Desktop: 1. Add the following to your `claude_desktop_config.json`: ```json { "mcpServers": { "baloosearch": { "command": "node", "args": ["/path/to/baloosearch-mcp/src/server/mcp-server.js"], "env": {} } } } ``` 2. Restart Claude Desktop 3. The baloosearch tool will be available in the tools list ## Project Structure ``` baloosearch-mcp/ ├── src/ │ ├── server/ │ │ └── mcp-server.js # Main MCP server implementation │ ├── tools/ │ │ └── baloosearch-tool.js # Baloosearch tool implementation │ ├── test-tool.js # Test script for the tool │ └── test-server.js # Test script for the server ├── test/ │ ├── integration.js # Integration test script │ └── server-test.sh # Server test script ├── package.json # Project configuration └── README.md # This file ``` ## Development ### Running Tests ```bash # Test the baloosearch tool directly npm run test-tool # Test the MCP server startup npm run test-server ``` ### Publishing to npm To publish this package to npm: 1. Create an account at [npmjs.com](https://www.npmjs.com/signup) if you don't have one 2. Log in to npm: ```bash npm login ``` 3. Publish the package: ```bash npm publish ``` After publishing, users will be able to run your MCP server using: ```bash npx baloosearch-mcp ``` ### Modifying the Server The main server implementation is in `src/server/mcp-server.js`. You can add additional tools or modify existing ones by following the same pattern as the `search_files` tool. ### Modifying the Baloosearch Tool The baloosearch tool implementation is in `src/tools/baloosearch-tool.js`. You can modify the search parameters or add additional functionality as needed. ## Troubleshooting ### "baloosearch: command not found" Make sure you have KDE desktop environment installed with baloosearch available. You can test this by running: ```bash which baloosearch ``` ### Server exits immediately This is normal behavior for MCP servers using stdio transport. The server waits for JSON-RPC messages via stdin/stdout. ### No search results Make sure your baloosearch index is up to date. You can update it by running: ```bash balooctl monitor ``` ## License This project is licensed under the MIT License.