MCP SOP Server

Um servidor MCP para acessar e pesquisar Procedimentos Operacionais Padrão (POPs) com suporte ao idioma italiano.

GitHubExperimente este MCPPatrocinado

Documentação

MCP SOP Server

Um servidor Model Context Protocol (MCP) para acessar e pesquisar Procedimentos Operacionais Padrão (SOPs) com suporte ao idioma italiano.

Visão Geral

Este servidor MCP fornece aos agentes de IA a capacidade de:

  • Pesquisar na documentação de SOPs da sua empresa usando busca semântica
  • Recuperar procedimentos relevantes com base em situações específicas
  • Navegar por SOPs por categoria
  • Obter orientação sobre o que fazer em cenários específicos

O servidor utiliza:

  • ChromaDB para armazenamento vetorial e busca semântica
  • Sentence Transformers com modelos multilíngues para suporte ao idioma italiano
  • FastMCP para a implementação do servidor MCP
  • RAG (Retrieval Augmented Generation) para recuperação inteligente de documentos

Recursos

  • 🇮🇹 Suporte ao Idioma Italiano: Utiliza embeddings multilíngues otimizados para texto em italiano
  • 📄 Suporte a Múltiplos Formatos: Processa documentos PDF e DOCX
  • 🔍 Busca Semântica: Encontre SOPs relevantes com base no significado, não apenas em palavras-chave
  • 📁 Filtro por Categoria: Pesquise dentro de categorias específicas de SOPs
  • 🤖 Pronto para IA: Fornece respostas estruturadas perfeitas para consumo por LLMs
  • ⚡ Recuperação Rápida: Busca vetorial eficiente com ChromaDB
  • 🚀 Inicialização Preguiçosa: O servidor inicia rapidamente, os documentos são indexados na primeira solicitação

Instalação

  1. Clone o repositório:

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

  2. Crie e ative o ambiente virtual:

    python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

  3. Instale as dependências:

    pip install -r requirements.txt

  4. Adicione seus documentos SOP: Crie um diretório sop_documents/ e organize seus arquivos SOP por pastas de categoria.

Configuração

Configuração do Cliente MCP

Para usar este servidor com o Claude Desktop ou outros clientes MCP, adicione-o à configuração do seu cliente MCP:

Para Claude Desktop (mcp-client-config.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"
    }
  }
}

Nota: Certifique-se de usar o caminho completo para o executável Python do seu ambiente virtual e ajuste os caminhos de acordo com o seu sistema.

Estrutura de Diretórios

O servidor espera que os documentos SOP estejam organizados da seguinte forma:

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

Uso

Iniciando o Servidor

O servidor normalmente é iniciado automaticamente pelo seu cliente MCP (como o Claude Desktop). Se for executar manualmente:

python main.py

O servidor irá:

  1. Iniciar rapidamente e aguardar conexões
  2. Na primeira chamada de ferramenta: escanear todos os documentos SOP no diretório sop_documents/
  3. Processar e extrair texto de arquivos PDF e DOCX
  4. Gerar embeddings usando o modelo multilíngue
  5. Armazenar tudo no ChromaDB para recuperação rápida

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas MCP:

1. search_sop_documents

Pesquise conteúdo relevante de SOPs usando consultas em linguagem natural.

Parâmetros:

  • query (string): Consulta de busca em italiano ou inglês
  • max_results (int, opcional): Número máximo de resultados a retornar (padrão: 5)
  • category (string, opcional): Filtrar por categoria de SOP

Exemplo:

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

2. get_sop_guidance

Obtenha orientação específica para uma situação com base nos documentos SOP.

Parâmetros:

  • situation (string): Descrição da situação
  • category (string, opcional): Focar a busca em uma categoria específica

Exemplo:

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

3. list_sop_categories

Obtenha todas as categorias de SOP disponíveis e estatísticas da coleção.

4. get_sop_by_category

Recupere todos os SOPs dentro de uma categoria específica.

Parâmetros:

  • category (string): Nome da categoria de SOP

5. refresh_sop_database

Atualize o banco de dados de documentos (use quando os SOPs forem atualizados).

6. get_server_status

Obtenha o status atual do servidor e estatísticas.

Configuração Técnica

Modelo de Embedding

O servidor usa sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 por padrão para suporte ao idioma italiano. Você pode alterar isso em src/mcp_sop_server/document_searcher.py:

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

Tamanho do Chunk

O particionamento de texto pode ser ajustado em src/mcp_sop_server/document_processor.py:

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

Localização do Banco de Dados

O local de armazenamento do ChromaDB é definido automaticamente para chroma_db/ na raiz do projeto.

Exemplos de Consultas

Aqui estão alguns exemplos de consultas que você pode usar:

Italiano:

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

Inglês:

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

Solução de Problemas

Problemas Comuns

  1. Nenhum documento encontrado: Certifique-se de que os documentos SOP estejam na estrutura de diretórios correta
  2. Download do modelo de embedding: A primeira execução pode levar tempo para baixar o modelo multilíngue
  3. Uso de memória: Coleções grandes de documentos podem exigir mais RAM para geração de embeddings
  4. Problemas de caminho: Certifique-se de usar caminhos absolutos na configuração do seu cliente MCP

Logs

O servidor fornece logs detalhados com emojis para melhor legibilidade:

  • 🚀 Inicialização e inicialização do servidor
  • 📄 Status do processamento de documentos
  • 📊 Estatísticas de processamento
  • ✅ Mensagens de sucesso
  • ❌ Mensagens de erro

Verifique a saída do console ou os logs do seu cliente MCP para informações detalhadas.

Desenvolvimento

Estrutura do Projeto

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

Adicionando Novos Tipos de Documentos

Para suportar formatos de arquivo adicionais, estenda a classe DocumentProcessor:

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

Lógica de Busca Personalizada

Modifique a classe DocumentSearcher para implementar algoritmos ou filtros de busca personalizados.

Ferramentas Adicionais

Adicione novas ferramentas MCP definindo-as com o decorador @mcp.tool() em mcp_server.py.

Licença

Este projeto é destinado ao uso interno da empresa para acessar a documentação de SOPs.

Suporte

Para problemas ou perguntas sobre o servidor MCP SOP, crie uma issue no repositório do GitHub.