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

npm install

Running with npx

You can run this MCP server directly using npx without installing it globally:

npx baloosearch-mcp

This will start the MCP server that can be used with any MCP-compatible AI assistant.

Usage

Starting the Server

npm start

The server will start and listen for MCP requests via stdio.

Testing the Baloosearch Tool

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

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/server/mcp-server.js

Search for Files

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

# 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:

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "baloosearch": {
      "command": "node",
      "args": ["/path/to/baloosearch-mcp/src/server/mcp-server.js"],
      "env": {}
    }
  }
}

Restart Claude Desktop
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

# 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:

Create an account at npmjs.com if you don't have one
Log in to npm:
npm login
Publish the package:
npm publish

After publishing, users will be able to run your MCP server using:

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:

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:

balooctl monitor

License

This project is licensed under the MIT License.

Baloosearch MCP Server