MCP SOP Server

MCP SOP 服务

一个用于访问和搜索标准操作规程（SOP）的模型上下文协议（MCP）服务，支持意大利语。

概述

此 MCP 服务为 AI Agent 提供以下能力：

• 使用语义搜索查找公司 SOP 文档
• 根据具体情境检索相关流程
• 按类别浏览 SOP
• 获取特定场景下的操作指导

此服务使用：

• ChromaDB 进行向量存储和语义搜索
• Sentence Transformers 多语言模型，支持意大利语
• FastMCP 实现 MCP 服务
• RAG（检索增强生成） 实现智能文档检索

功能

• 🇮🇹 意大利语支持：使用针对意大利语文本优化的多语言嵌入
• 📄 多格式支持：处理 PDF 和 DOCX 文档
• 🔍 语义搜索：根据含义而非仅根据关键词查找相关 SOP
• 📁 类别筛选：在指定的 SOP 类别中搜索
• 🤖 适用于 AI：提供适合大模型使用的结构化响应
• ⚡ 快速检索：使用 ChromaDB 高效进行基于向量的搜索
• 🚀 延迟初始化：服务快速启动，并在首次请求时为文档建立索引

安装

1. 克隆代码库：

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

2. 创建并激活虚拟环境：

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 添加 SOP 文档： 创建 sop_documents/ 目录，并按类别文件夹整理 SOP 文件。

配置

MCP 客户端设置

如需将此服务与 Claude Desktop 或其他 MCP 客户端配合使用，请将其添加到 MCP 客户端配置中：

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"
    }
  }
}

注意：请确保使用虚拟环境中 Python 可执行文件的完整路径，并根据系统调整路径。

目录结构

服务要求按如下方式整理 SOP 文档：

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

使用方法

启动服务

通常由 MCP 客户端（例如 Claude Desktop）自动启动服务。如需手动运行：

python main.py

服务将会：

1. 快速启动并等待连接
2. 在首次调用工具时，扫描 sop_documents/ 目录中的所有 SOP 文档
3. 处理并提取 PDF 和 DOCX 文件中的文本
4. 使用多语言模型生成嵌入
5. 将所有内容存储在 ChromaDB 中，以便快速检索

可用工具

此服务提供以下 MCP 工具：

1. search_sop_documents

使用自然语言查询搜索相关 SOP 内容。

参数：

• query（字符串）：意大利语或英语搜索查询
• max_results（整数，可选）：返回结果的上限（默认值：5）
• category（字符串，可选）：按 SOP 类别筛选

示例：

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

2. get_sop_guidance

根据 SOP 文档获取特定情境的指导。

参数：

• situation（字符串）：情境描述
• category（字符串，可选）：将搜索范围限定在指定类别

示例：

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

3. list_sop_categories

获取所有可用的 SOP 类别和集合统计信息。

4. get_sop_by_category

检索指定类别中的所有 SOP。

参数：

• category（字符串）：SOP 类别名称

5. refresh_sop_database

刷新文档数据库（在 SOP 更新时使用）。

6. get_server_status

获取当前服务状态和统计信息。

技术配置

嵌入模型

服务默认使用 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 支持意大利语。你可以在 src/mcp_sop_server/document_searcher.py 中更改此设置：

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

分块大小

可以在 src/mcp_sop_server/document_processor.py 中调整文本分块：

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

数据库位置

ChromaDB 存储位置自动设为项目根目录下的 chroma_db/。

示例查询

以下是一些可以使用的示例查询：

意大利语：

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

英语：

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

故障排查

常见问题

1. 未找到文档：确保 SOP 文档位于正确的目录结构中
2. 嵌入模型下载：首次运行时，下载多语言模型可能需要一些时间
3. 内存用量：大型文档集合可能需要更多 RAM 来生成嵌入
4. 路径问题：请确保在 MCP 客户端配置中使用绝对路径

日志

服务会提供详细日志，并使用表情符号提升可读性：

• 🚀 服务启动和初始化
• 📄 文档处理状态
• 📊 处理统计信息
• ✅ 成功消息
• ❌ 错误消息

请查看控制台输出或 MCP 客户端日志，了解详细信息。

开发

项目结构

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

添加新文档类型

要支持其他文件格式，请扩展 DocumentProcessor 类：

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

自定义搜索逻辑

修改 DocumentSearcher 类，以实现自定义搜索算法或筛选条件。

其他工具

在 mcp_server.py 中使用 @mcp.tool() 装饰器定义新的 MCP 工具。

许可证

本项目供公司内部使用，用于访问 SOP 文档。

支持

如果对 SOP MCP 服务有问题或疑问，请在 GitHub 仓库中创建议题。