带有PII屏蔽的代理OpenSearch MCP服务器
该项目实现了 模型上下文协议（MCP）代理服务器 它位于LLM客户端和OpenSearch集群之间。其主要目的是拦截搜索结果并自动屏蔽 个人身份信息（PII） 在敏感数据到达大型语言模型之前。
🏗 系统架构
应用程序作为中间件层运行：
- 前端/客户端：用户通过CLI、Web UI或兼容MCP的IDE（如Cursor或Claude Desktop）进行交互。
- 代理服务器 (
proxy_mcp/server.py)：接收工具调用（例如。，search_index_masked). - 内部客户 (
proxy_mcp/mcp_client.py)：生成并与实际的OpenSearch MCP Server子流程通信。 - 遮蔽发动机 (
proxy_mcp/masking.py)：拦截OpenSearch的原始JSON响应，并使用Presidio和SpaCy清理敏感字段。 - LLM：接收经过净化的最终数据以生成响应。
✨ 主要特点
- 透明代理：无缝地将请求转发到官方OpenSearch MCP服务器。
- 智能口罩：使用NLP（SpaCy）和Regex模式来检测和编辑敏感数据。
- 多个接口:
- 流媒体Web应用程序：一个与您的数据交互的现代聊天界面。 - 交互式CLI：一个基于终端的聊天客户端，集成了OpenAI。 - 标准MCP：可以用作其他MCP客户端的服务器。
- 工具支持:
- search_index_masked：执行搜索并屏蔽输出。 - list_indices：列出可用的OpenSearch索引。 - get_index_mapping：检索索引架构。
🛡️ 屏蔽逻辑
掩蔽引擎(proxy_mcp/masking.py)配置了以下规则：
| 实体类型 | 动作 | 替换/掩码 |
|---|---|---|
| PDS_WORD （正则表达式） | 替换 | `` |
| 统一资源定位符 | 更换 | `` |
| IP地址 | 更换 | `` |
| 人 | 口罩 | ******* |
| 电子邮件 | 口罩 | ******* |
| 电话号码 | 口罩 | ******* |
备注：为了保留上下文，日期、组织和美国护照等实体目前被排除在屏蔽之外。
🚀 安装
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，显示工具调用和响应。
- 启动后端API：
python web_server.py
# Runs on http://localhost:8000- 启动前端：
打开一个新终端并运行：
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的聊天逻辑。