# MCP SOP Server

A Model Context Protocol (MCP) server for accessing and searching Standard Operating Procedures (SOPs) with Italian language support.

## Overview

This MCP server provides AI agents with the ability to:

- Search through your company's SOP documentation using semantic search
- Retrieve relevant procedures based on specific situations
- Browse SOPs by category
- Get guidance on what to do in specific scenarios

The server uses:

- **ChromaDB** for vector storage and semantic search
- **Sentence Transformers** with multilingual models for Italian language support
- **FastMCP** for the MCP server implementation
- **RAG (Retrieval Augmented Generation)** for intelligent document retrieval

## Features

- 🇮🇹 **Italian Language Support**: Uses multilingual embeddings optimized for Italian text
- 📄 **Multi-format Support**: Processes PDF and DOCX documents
- 🔍 **Semantic Search**: Find relevant SOPs based on meaning, not just keywords
- 📁 **Category Filtering**: Search within specific SOP categories
- 🤖 **AI-Ready**: Provides structured responses perfect for LLM consumption
- ⚡ **Fast Retrieval**: Efficient vector-based search with ChromaDB
- 🚀 **Lazy Initialization**: Server starts quickly, documents are indexed on first request

## Installation

1. **Clone the repository**:

   ```bash
   git clone https://github.com/dadapera/mcp-sop-server.git
   cd mcp-sop-server
   ```

2. **Create and activate virtual environment**:

   ```bash
   python -m venv venv

   # On Windows
   venv\Scripts\activate

   # On macOS/Linux
   source venv/bin/activate
   ```

3. **Install Dependencies**:

   ```bash
   pip install -r requirements.txt
   ```

4. **Add your SOP documents**:
   Create a `sop_documents/` directory and organize your SOP files by category folders.

## Configuration

### MCP Client Setup

To use this server with Claude Desktop or other MCP clients, add it to your MCP client configuration:

**For Claude Desktop** (`mcp-client-config.json`):

```json
{
  "mcpServers": {
    "sop-server": {
      "command": "/path/to/your/venv/Scripts/python.exe",
      "args": ["/path/to/your/mcp-sop-server/main.py"],
      "cwd": "/path/to/your/mcp-sop-server"
    }
  }
}
```

> **Note**: Make sure to use the full path to your virtual environment's Python executable and adjust paths according to your system.

### Directory Structure

The server expects SOP documents to be organized as follows:

```
sop_documents/
├── SOP01 Quality System Documentation Management/
│   ├── document1.pdf
│   └── document2.docx
├── SOP02 HR management/
│   └── hr_procedures.pdf
├── SOP03 Design/
│   └── design_process.docx
└── ...
```

## Usage

### Starting the Server

The server is typically started automatically by your MCP client (like Claude Desktop). If running manually:

```bash
python main.py
```

The server will:

1. Start quickly and wait for connections
2. On first tool call: scan all SOP documents in the `sop_documents/` directory
3. Process and extract text from PDF and DOCX files
4. Generate embeddings using the multilingual model
5. Store everything in ChromaDB for fast retrieval

### Available Tools

The server provides the following MCP tools:

#### 1. `search_sop_documents`

Search for relevant SOP content using natural language queries.

**Parameters:**

- `query` (string): Search query in Italian or English
- `max_results` (int, optional): Maximum results to return (default: 5)
- `category` (string, optional): Filter by SOP category

**Example:**

```json
{
  "query": "Come gestire una non conformità nel processo di produzione",
  "max_results": 3,
  "category": "SOP05 Non Conformity"
}
```

#### 2. `get_sop_guidance`

Get specific guidance for a situation based on SOP documents.

**Parameters:**

- `situation` (string): Description of the situation
- `category` (string, optional): Focus search on specific category

**Example:**

```json
{
  "situation": "Un cliente ha segnalato un difetto nel prodotto consegnato",
  "category": "SOP05 Non Conformity"
}
```

#### 3. `list_sop_categories`

Get all available SOP categories and collection statistics.

#### 4. `get_sop_by_category`

Retrieve all SOPs within a specific category.

**Parameters:**

- `category` (string): SOP category name

#### 5. `refresh_sop_database`

Refresh the document database (use when SOPs are updated).

#### 6. `get_server_status`

Get current server status and statistics.

## Technical Configuration

### Embedding Model

The server uses `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` by default for Italian language support. You can change this in `src/mcp_sop_server/document_searcher.py`:

```python
model_name = "sentence-transformers/your-preferred-model"
```

### Chunk Size

Text chunking can be adjusted in `src/mcp_sop_server/document_processor.py`:

```python
def chunk_text(self, text: str, chunk_size: int = 1000, overlap: int = 200):
```

### Database Location

ChromaDB storage location is automatically set to `chroma_db/` in the project root.

## Example Queries

Here are some example queries you can use:

**Italian:**

- "Come gestire una non conformità?"
- "Procedura per la manutenzione dell'infrastruttura"
- "Cosa fare in caso di audit interno?"
- "Gestione del magazzino e inventario"

**English:**

- "How to handle quality issues?"
- "Software development lifecycle procedures"
- "Risk management protocols"
- "Employee training requirements"

## Troubleshooting

### Common Issues

1. **No documents found**: Ensure SOP documents are in the correct directory structure
2. **Embedding model download**: First run may take time to download the multilingual model
3. **Memory usage**: Large document collections may require more RAM for embedding generation
4. **Path issues**: Make sure to use absolute paths in your MCP client configuration

### Logs

The server provides detailed logging with emojis for better readability:

- 🚀 Server startup and initialization
- 📄 Document processing status
- 📊 Processing statistics
- ✅ Success messages
- ❌ Error messages

Check the console output or your MCP client logs for detailed information.

## Development

### Project Structure

```
mcp-sop-server/
├── src/mcp_sop_server/          # Main package
│   ├── __init__.py              # Package initialization
│   ├── mcp_server.py            # FastMCP server and tools
│   ├── document_processor.py    # Document text extraction
│   └── document_searcher.py     # Vector search with ChromaDB
├── main.py                      # Entry point
├── requirements.txt             # Dependencies
├── test_server.py              # Server testing
├── mcp-client-config.json      # Example client configuration
└── README.md                   # This file
```

### Adding New Document Types

To support additional file formats, extend the `DocumentProcessor` class:

```python
def extract_text_from_new_format(self, file_path: Path) -> str:
    # Implementation for new format
    pass
```

### Custom Search Logic

Modify the `DocumentSearcher` class to implement custom search algorithms or filters.

### Additional Tools

Add new MCP tools by defining them with the `@mcp.tool()` decorator in `mcp_server.py`.

## License

This project is intended for internal company use for accessing SOP documentation.

## Support

For issues or questions about the SOP MCP server, create an issue on the GitHub repository.