liu10250510/mcp-file-search-server

MCP File Search Server

A Model Context Protocol (MCP) server that provides intelligent file search capabilities for local directories. This server can search by file type, filename patterns, and file content using natural language queries.

Features

• 🔍 Natural Language Search: Use plain English to describe what files you're looking for
• 📁 Multi-Type Search: Search by file extension, filename keywords, and file content
• 🤖 AI-Powered Parsing: Uses OpenAI GPT to intelligently parse search requests
• 📄 Multiple File Formats: Supports PDF, Word docs, Excel, JSON, CSV, and text files
• ⚡ Fast Search: Efficient file system traversal with smart filtering
• 🎯 Relevance Scoring: Results ranked by relevance to your query

Installation

1. Install dependencies:

   uv sync
   

2. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your OpenAI API key
   

3. Run the setup script:

   python setup_mcp_server.py
   

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "file-search": {
      "command": "python",
      "args": ["/path/to/mcp_file_search_server.py"],
      "env": {}
    }
  }
}

Available Tools

search_files

Search for files in a local directory using natural language.

Parameters:

• folder_path (required): Absolute path to search directory
• search_prompt (required): Natural language search description
• max_results (optional): Maximum results to return (default: 10)

Examples:

{
  "folder_path": "/Users/john/Documents",
  "search_prompt": "pdf files about machine learning",
  "max_results": 5
}

{
  "folder_path": "/Users/john/Projects",
  "search_prompt": "python scripts with neural network code",
  "max_results": 10
}

Standalone Usage

You can also use the search functionality directly:

from fastmcp_file_search import search_files
from models import SearchRequest

request = SearchRequest(
    folder_path="/path/to/search",
    search_prompt="find all PDF files about AI",
    max_results=10
)

results = search_files(request)
for result in results:
    print(f"Found: {result['file_name']}")

Web UI

Run the Streamlit web interface:

streamlit run file_search_ui.py

Supported File Types

• Documents: PDF, Word (.docx, .doc), Excel (.xlsx, .xls)
• Data: JSON, CSV
• Code: Python (.py), JavaScript (.js), HTML, CSS, XML
• Text: Plain text, Markdown (.md), YAML (.yml), etc.

Search Examples

• "pdf files about machine learning"
• "python scripts with neural network code"
• "excel spreadsheets containing budget data"
• "json configuration files"
• "word documents from last month"
• "text files with API documentation"

Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required)
• OPENAI_ORG_ID: Your OpenAI organization ID (optional)

Search Behavior

• Uses AND logic by default (files must match all criteria)
• Searches file extensions, filenames, and content
• Excludes system directories (.git, .venv, pycache, etc.)
• Limits content search to first 50KB of each file

Architecture

mcp_file_search_server.py  # MCP server implementation
├── fastmcp_file_search.py # Main search orchestration
├── models.py              # Data models
├── utils.py               # LLM parsing and utilities
├── search_functions.py    # Individual search functions
└── file_search_ui.py      # Web interface

Troubleshooting

1. "Import mcp could not be resolved"

   • Install the MCP package: pip install mcp

2. "LLM parsing failed"

   • Check your OpenAI API key in .env
   • Verify internet connection

3. "No files found"

   • Check folder path exists and is readable
   • Try broader search terms
   • Verify file types exist in target directory

Project Structure

├── mcp_file_search_server.py    # Main MCP server implementation
├── models.py                    # Pydantic data models
├── utils.py                     # LLM integration and utilities
├── search_functions.py          # Individual search operations
├── fastmcp_file_search.py      # Main search orchestration
├── file_search_ui.py           # Streamlit web interface
├── test_official_client.py     # Official MCP client test
├── test_mcp_client.py          # JSON-RPC test client
├── mcp_config.json             # MCP server configuration
├── pyproject.toml              # Project dependencies
├── README.md                   # This file
└── USAGE_GUIDE.md              # Detailed usage instructions

Development

To extend the server:

1. Add new search functions in search_functions.py
2. Update the search orchestration in fastmcp_file_search.py
3. Add new tools to mcp_file_search_server.py

License

MIT License - see LICENSE file for details.