Document Search MCP Server

A local MCP server that provides read-only access to documents (Word, PDF, Excel, CSV, Visio, PNG, JPG, PowerPoint, Text, Markdown, EPUB) via the Model Context Protocol (MCP).

Features

• Read-only access: Enforced at the code level.

• Recursive scanning: Scans all subdirectories of configured directories.

• File type validation: Uses magic numbers to validate file types.

• Metadata extraction: Extracts metadata from all supported file types.

• Logging: Logs all actions to a file (configurable).

• Timeout for file operations: Configurable timeout (default: 180 seconds) to prevent hanging on large or corrupt files.

• Full MCP compliance: Supports initialize, resources/list, resources/read, and tools/call methods.

• YAML configuration: Supports both CLI arguments and YAML configuration files.

• Extensive file type support: PDF, Word, Excel, CSV, Visio, Images, PowerPoint, Text, Markdown, EPUB.

Related MCP server: Docalyze

Installation

1. Clone the repository:

   git clone https://github.com/bpweatherill/Document-Search-MCP-server.git
   cd Document-Search-MCP-server

2. Install dependencies:

   pip install -r requirements.txt

   For full file type support, install all optional dependencies:

   pip install PyPDF2 python-docx openpyxl Pillow textract xlrd PyYAML pdfplumber pypandoc python-pptx ebooklib

Usage

Start the Server

# Default: Scans ~/Documents
python -m src.main

# With custom directories and settings
python -m src.main --dir "C:\Users\Me\Documents" --dir "C:\Users\Me\Desktop" --max-file-size 50000000 --log-file "C:\logs\mcp.log" --log-level DEBUG --file-operation-timeout 180

# With a custom YAML config file
python -m src.main --config-file /path/to/custom_config.yaml

YAML Configuration

The server supports YAML configuration files in addition to CLI arguments. CLI arguments take precedence over YAML config.

Configuration file locations (checked in order):

1. mcp_server_config.yaml in the current directory

2. ~/.mcp_server/config.yaml in the user's home directory

3. /etc/mcp_server/config.yaml for system-wide config

4. Custom path specified with --config-file

Example YAML configuration:

# List of directories to scan (recursive)
allowed_dirs:
  - "~/Documents"
  - "/path/to/other/directory"

# Maximum file size in bytes (100MB default)
max_file_size: 104857600

# Path to the log file
log_file: "~/.mcp_server/log.txt"

# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
log_level: "INFO"

# Timeout for file operations in seconds
file_operation_timeout: 180

# Additional file extensions to allow
allowed_extensions:
  - ".txt"
  - ".md"
  - ".pptx"
  - ".ppt"
  - ".epub"

MCP Client Interaction

Send JSON-RPC requests over stdio. The server supports the following MCP methods:

1. Initialize

{
  "id": 1,
  "method": "initialize",
  "params": {}
}

Response:

{
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {
        "list": {"description": "List available document resources"},
        "read": {"description": "Read a document resource"}
      }
    },
    "serverInfo": {
      "name": "Document-Search-MCP-Server",
      "version": "1.0.0"
    }
  }
}

2. List Resources

{
  "id": 2,
  "method": "resources/list",
  "params": {}
}

3. Read Resource

{
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "file:///path/to/document.pdf"
  }
}

4. Call Tools

List Files

{
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {}
  }
}

Read File

{
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/path/to/file.pdf"
    }
  }
}

Get Metadata

{
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_metadata",
    "arguments": {
      "path": "/path/to/file.pdf"
    }
  }
}

5. Ping (Health Check)

{
  "id": 7,
  "method": "ping",
  "params": {}
}

Configuration

Security

• Read-only: All file operations are read-only.

• Path validation: Prevents directory traversal attacks.

• File type validation: Ensures files match their extensions.

• Race condition protection: Files are re-validated before each read operation.

• Timeout protection: File operations will not hang indefinitely.

MCP Compliance

This server fully implements the following MCP methods:

• initialize: Returns server capabilities and info.

• resources/list: Lists all available document resources.

• resources/read: Reads and returns the content of a resource.

• tools/call: Executes a tool (list_files, read_file, get_metadata).

• ping: Health check endpoint.

Testing

Run unit tests:

python -m unittest discover tests

Dependencies

Required

• PyPDF2: For PDF text extraction.

• python-docx: For Word document text extraction (.docx).

• openpyxl: For Excel file parsing (.xlsx).

• Pillow: For image metadata extraction (PNG, JPG, JPEG).

• PyYAML: For YAML configuration file support.

Optional (for extended file type support)

• pdfplumber: Better PDF text extraction (fallback to PyPDF2 if not available).

• textract: For binary Word document text extraction (.doc).

• xlrd: For binary Excel file parsing (.xls).

• pypandoc: For Markdown to HTML/plain text conversion.

• python-pptx: For PowerPoint file text extraction.

• ebooklib: For EPUB file text extraction.

• visio-python: For Visio file metadata extraction.

Supported File Types

Configuration File Example

Create a file named config.yaml (or use the provided example.yaml):

# Directories to scan
allowed_dirs:
  - "~/Documents"
  - "/path/to/other/directory"

# Maximum file size in bytes
max_file_size: 104857600

# Log file path
log_file: "~/.mcp_server/log.txt"

# Logging level
log_level: "INFO"

# File operation timeout in seconds
file_operation_timeout: 180

# Additional file extensions
allowed_extensions:
  - ".txt"
  - ".md"
  - ".pptx"
  - ".ppt"
  - ".epub"

Then start the server with:

python -m src.main

Or specify a custom config file:

python -m src.main --config-file /path/to/custom_config.yaml