# MCP Server

A Model Context Protocol (MCP) server implementation that provides various tools for AI agents and LLMs, including search capabilities powered by SearXNG and file system operations.

## Features

- **Web Search**: Perform web searches with customizable parameters using SearXNG
- **File System Operations**: Read, write, and manage files with security controls
- **Extensible Architecture**: Add custom tools following the MCP protocol
- **Docker Support**: Easy deployment with Docker and docker-compose
- **Command-line Interface**: Simple management through CLI
- **Resources and Prompts**: Full MCP specification support for resources and prompts

## Requirements

- **Python 3.13** (required)
- MCP SDK ≥ 1.6.0
- UV package manager for dependency management
- Docker (optional, for containerized deployment)

## Implementation Approaches

This project demonstrates two approaches to implementing MCP servers:

### 1. FastMCP Decorator Approach (Recommended)

The simplified approach using FastMCP decorators in `mcp_server/server.py`:

```python
from mcp.server.fastmcp import FastMCP

# Create server
mcp = FastMCP("MCP Server")

# Add a tool using decorator
@mcp.tool()
def search(query: str, num_results: int = 5) -> dict:
    """Search the web"""
    # Implementation...
    return results

# Add a resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a greeting"""
    return f"Hello, {name}!"

# Add a prompt
@mcp.prompt()
def search_prompt(query: str) -> str:
    """Create a search prompt"""
    return f"Please search for: {query}"
```

### 2. Original Architecture (Advanced)

The original architecture in `mcp_server/core/` provides a more complex implementation with:

- `ToolRegistry` for managing tool registration
- `MCPTool` abstract base class for tool implementation
- Singleton `MCPServer` for server management

This approach offers more flexibility for complex applications but requires more boilerplate code.

## Tools

### search

Execute web searches through SearXNG with customizable filtering.

Inputs:
- `query` (string): Search terms
- `num_results` (number, optional): Number of results to return (default: 5, max: 20)
- `language` (string, optional): Language code for results (e.g., "en", "fr")
- `time_range` (string, optional): Time range for results (day, week, month, year)
- `search_category` (string, optional): Category to search in (general, images, news, videos)

### filesystem

Read, write, and manage files with secure access controls.

Operations:
- **Read File**
  - `path` (string): Path to the file to read
  - `encoding` (string, optional): Encoding to use (default: "utf-8")
  - `binary` (boolean, optional): Whether to read in binary mode (default: false)

- **Write File**
  - `path` (string): Path to write the file
  - `content` (string): Content to write
  - `encoding` (string, optional): Encoding to use (default: "utf-8")
  - `binary` (boolean, optional): Whether to write in binary mode (default: false)
  - `append` (boolean, optional): Whether to append to file (default: false)

- **List Files**
  - `path` (string, optional): Directory to list (default: current directory)
  - `recursive` (boolean, optional): Whether to list recursively (default: false)
  - `pattern` (string, optional): Pattern to match filenames

## Configuration

### Environment Variables

Configure your MCP server using environment variables:

```bash
# Server settings
MCP_SERVER__HOST=0.0.0.0
MCP_SERVER__PORT=8000

# SearXNG settings
MCP_SEARXNG__INSTANCE_URL=http://localhost:8080
MCP_SEARXNG__TIMEOUT=5

# Logging settings
MCP_LOG__LEVEL=INFO

# Data directory
MCP_DATA_DIR=./data
```

### Usage with Claude Desktop

#### Option 1: Install Simple Example Server

```bash
# Install the simple example server directly
mcp install examples/server.py

# Or test with the MCP Inspector
mcp dev examples/server.py
```

#### Option 2: Docker Configuration

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e",
        "MCP_SEARXNG__INSTANCE_URL=http://host.docker.internal:8080",
        "mcp-server"
      ]
    }
  }
}
```

You'll need to run a SearXNG instance separately:

```json
{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8080:8080",
        "-e", 
        "BASE_URL=http://localhost:8080/",
        "searxng/searxng"
      ]
    }
  }
}
```

## Installation

### Docker (Recommended)

```bash
# Build the Docker image
docker build -t mcp-server .

# Run the server and SearXNG
docker-compose up
```

### Direct Installation

```bash
# Ensure you have Python 3.13 installed
python --version  # Should show Python 3.13.x

# Install uv if you don't have it
pip install uv

# Create a virtual environment and install dependencies
uv venv --python=python3.13
uv install

# Run the server
python -m mcp_server start
```

## Client Examples

See the `examples/` directory for client examples:

- `examples/client.py`: Modern client using `ClientSession` API
- `examples/simple_client.py`: Simple client using direct API calls

## Extending with Custom Tools

### Using the FastMCP Approach

```python
from mcp_server.server import mcp

@mcp.tool()
def my_custom_tool(param1: str, param2: int = 10) -> dict:
    """My custom tool description"""
    # Implement tool functionality
    return {"result": f"Processed {param1} with {param2}"}
```

### Using the Original Architecture

See the [Developer Guide](docs/developer-guide.md) for instructions on adding custom tools with the original architecture.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgements

- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification
- [SearXNG](https://github.com/searxng/searxng) for the search engine functionality



## Command to run the project
python -m mcp_server start --config config.env