Proxy Opensearch MCP

带有PII屏蔽的代理OpenSearch MCP服务器

该项目实现了 模型上下文协议（MCP）代理服务器 它位于LLM客户端和OpenSearch集群之间。其主要目的是拦截搜索结果并自动屏蔽 个人身份信息（PII） 在敏感数据到达大型语言模型之前。

🏗 系统架构

应用程序作为中间件层运行：

1. 前端/客户端：用户通过CLI、Web UI或兼容MCP的IDE（如Cursor或Claude Desktop）进行交互。
2. 代理服务器 (proxy_mcp/server.py)：接收工具调用（例如。， search_index_masked).
3. 内部客户 (proxy_mcp/mcp_client.py)：生成并与实际的OpenSearch MCP Server子流程通信。
4. 遮蔽发动机 (proxy_mcp/masking.py)：拦截OpenSearch的原始JSON响应，并使用Presidio和SpaCy清理敏感字段。
5. LLM：接收经过净化的最终数据以生成响应。

✨ 主要特点

• 透明代理：无缝地将请求转发到官方OpenSearch MCP服务器。
• 智能口罩：使用NLP（SpaCy）和Regex模式来检测和编辑敏感数据。
• 多个接口:

- 流媒体Web应用程序：一个与您的数据交互的现代聊天界面。 - 交互式CLI：一个基于终端的聊天客户端，集成了OpenAI。 - 标准MCP：可以用作其他MCP客户端的服务器。

• 工具支持:

- search_index_masked：执行搜索并屏蔽输出。 - list_indices：列出可用的OpenSearch索引。 - get_index_mapping：检索索引架构。

🛡️ 屏蔽逻辑

掩蔽引擎(proxy_mcp/masking.py)配置了以下规则：

备注：为了保留上下文，日期、组织和美国护照等实体目前被排除在屏蔽之外。

🚀 安装

1.先决条件

• Python 3.10+
• OpenSearch集群（或访问凭据）
• 这 uv 包管理器（推荐）或 pip

2.设置

克隆存储库并安装依赖项：

# Using uv (Recommended)
uv sync

# OR using pip
pip install .

3.下载NLP模型

屏蔽引擎需要SpaCy的大型英文模型：

python -m spacy download en_core_web_lg

⚙️ 配置

创建一个 config.json 根目录中的文件（请参见 config.example.json):

{
    "openaiKey": "sk-your-openai-key",
    "mcpServers": {
        "proxy-opensearch": {
            "command": "python",
            "args": ["-m", "proxy_mcp.server"],
            "env": {
                "INNER_MCP_CMD": "uvx opensearch-mcp-server-py",
                "OPENSEARCH_URL": "https://your-opensearch-url",
                "OPENSEARCH_USERNAME": "your_username",
                "OPENSEARCH_PASSWORD": "your_password",
                "OPENSEARCH_VERIFY_CERTS": "false"
            }
        }
    }
}

• INNER_MCP_CMD：启动实际OpenSearch MCP服务器的命令。
• OPENSEARCH_*：传递给内部服务器的凭据。

🖥️ 用法

您可以在三种不同的模式下运行应用程序：

模式1：流媒体Web界面（推荐）

一个功能齐全的网络聊天UI，显示工具调用和响应。

1. 启动后端API：

   python web_server.py
   # Runs on http://localhost:8000

1. 启动前端：

打开一个新终端并运行：

   streamlit run streamlit_app.py
   # Opens browser at http://localhost:8501

模式2：交互式CLI客户端

一个基于终端的聊天客户端，可用于快速测试。

python interactive_client.py config.json

模式3：独立MCP服务器

要在Claude Desktop或Cursor等IDE中使用此代理，请配置IDE的MCP设置以运行：

python -m proxy_mcp.server

确保环境变量(OPENSEARCH_URL等）在IDE配置中设置。

📂 项目结构

• proxy_mcp/server.py：FastMCP服务器入口点。
• mcp_client.py：管理与内部OpenSearch服务器的子进程连接。
• masking.py：包含用于文本净化的Presidio和SpaCy逻辑。
• web_server.py：FastAPI后端将UI连接到MCP客户端。
• streamlit_app.py：前端聊天界面。
• interactive_client.py：基于CLI的聊天逻辑。