MCP与ACP配置系统

一个全面的模型上下文协议（MCP）协调器，集成了Azure OpenAI，用于智能工具选择和查询处理。该系统通过直观的Streamlit界面，提供了一个灵活的框架，用于连接多个数据源（如Azure SQL、Azure AI搜索、Google搜索）和AI服务。

概述

这个项目实施了一个 模型上下文协议（MCP） 作为以下两者之间桥梁的服务器：

数据来源Azure SQL 数据库，Azure AI 搜索（图像相似度），通过 SerpAPI 使用 Google 搜索
人工智能服务Azure OpenAI用于智能查询路由和自然语言处理
用户界面Streamlit网页用户界面，命令行界面

该系统利用Azure OpenAI，根据用户查询智能决定调用哪些工具/服务，使其成为一个能够处理从SQL查询到图像相似度搜索等多种请求的智能协调器。

特点/功能

核心功能

MCP服务器基于FastMCP的服务器，支持动态工具注册
Azure与OpenAI的集成GPT-4o用于智能决策和查询路由
多源支持：

- 支持自然语言查询生成的Azure SQL数据库 - 基于向量的图像相似度的Azure AI搜索 - 通过SerpAPI进行谷歌搜索以实现网页图片搜索

异步操作对并发操作提供完整的异步/await支持
Streamlit 用户界面美观的仿射主题配置和聊天界面
错误处理强大的错误处理，带有详细日志记录

MCP 服务编排器功能

智能工具选择Azure OpenAI 根据查询上下文决定使用哪个工具
响应合成结构化工具输出的自然语言响应
上下文管理保持对话上下文和工具元数据
标准I/O通信用于工具通信的标准MCP协议

建筑学

┌─────────────────────────────────────────────────────────────┐
│                       User Interface                         │
│  (Streamlit UI / CLI / Interactive Mode)                    │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  MCP Orchestrator (main2.py)                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │          Azure OpenAI Decision Engine                │  │
│  │  • Analyzes user query                               │  │
│  │  • Selects appropriate tool                          │  │
│  │  • Synthesizes natural language response             │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │            MCP Client (stdio)                        │  │
│  │  • Communicates with MCP server                      │  │
│  │  • Manages tool calls                                │  │
│  │  • Handles streaming responses                       │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  MCP Server (server.py)                     │
│  • Dynamic tool registration based on credentials.json      │
│  • Environment variable management                          │
│  • Tool routing and execution                               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Tool Layer                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐ │
│  │  Azure SQL   │  │  Azure AI    │  │  Google Search   │ │
│  │   (SQL DB)   │  │   Search     │  │   (SerpAPI)      │ │
│  │              │  │  (Images)    │  │                  │ │
│  └──────────────┘  └──────────────┘  └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘

先决条件

所需服务

Azure OpenAI（注：此处“Azure OpenAI”通常指的是微软Azure云平台与OpenAI合作提供的服务或接口，但直接翻译为“Azure OpenAI”在中文中并不常见，若需更自然的表达，可根据上下文具体翻译为“微软Azure与OpenAI的合作服务/接口”等，但在此保持原样以体现原文）GPT-4o的部署用于协调（或编排）
Azure SQL 数据库 （可选）：用于SQL查询处理
Azure AI 搜索 （可选）：用于图像相似度搜索
Azure AI Vision（Azure AI视觉） （可选）：用于图像矢量化
SerpAPI （可选）：用于谷歌网页搜索

软件需求

Python 3.13+
适用于 SQL Server 的 ODBC 驱动程序 18（如果使用 Azure SQL）
虚拟环境（推荐）

安装

1. 克隆仓库

cd /path/to/your/workspace
# Assuming the project is already at /Users/kavyanegi/Downloads/MCP
cd MCP

2. 创建虚拟环境

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

3. 安装依赖项

pip install -r requirements.txt

4. 安装MCP的附加要求

pip install fastmcp mcp streamlit

配置

1. 环境变量

创建一个 .env 项目根目录中的文件：

# Azure OpenAI (REQUIRED)
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-12-01-preview
AZURE_DEPLOYMENT=gpt-4o-08-06

# Azure AI Vision (Required for image search)
AZURE_AI_VISION_API_KEY=your_vision_api_key_here
AZURE_AI_VISION_REGION=eastus
AZURE_AI_VISION_ENDPOINT=https://your-vision-resource.cognitiveservices.azure.com/

# Optional: Will be set via UI or credentials.json
SERVICE_ENDPOINT=https://your-search-service.search.windows.net
INDEX_NAME=your-index-name
SEARCH_ADMIN_KEY=your_search_admin_key
IMAGES_DIR=/path/to/images

# SQL Database (Optional: Will be set via UI)
SQL_SERVER=your-server.database.windows.net
SQL_DATABASE=your-database
SQL_USERNAME=your-username
SQL_PASSWORD=your-password
SQL_DRIVER={ODBC Driver 18 for SQL Server}

# Google Search (Optional: Will be set via UI)
SERP_API_KEY=your_serpapi_key

2. 凭证配置

创建 credentials.json 配置数据源：

[
  {
    "form_type": "sql_database",
    "sql_server": "server.database.windows.net",
    "sql_database": "MyDatabase",
    "sql_username": "admin",
    "sql_password": "password",
    "sql_driver": "{ODBC Driver 18 for SQL Server}",
    "tool_description": "Processes queries on Azure SQL Database containing HR data"
  },
  {
    "form_type": "azure_ai_search",
    "service_endpoint": "https://search-service.search.windows.net",
    "search_admin_key": "your_key",
    "index_name": "images-index",
    "ai_vision_key": "your_vision_key",
    "ai_vision_region": "eastus",
    "ai_vision_endpoint": "https://vision-resource.cognitiveservices.azure.com/",
    "default_images_dir": "/path/to/images",
    "tool_description": "Searches for similar images using vector embeddings"
  },
  {
    "form_type": "google_database",
    "serp_api_key": "your_serpapi_key",
    "tool_description": "Searches the web for similar images using Google Lens"
  }
]

⚠️ 重要永远不要承诺 credentials.json 或者 .env 将文件纳入版本控制。将它们添加到 .gitignore。

用法

1. Streamlit 用户界面（推荐）

Streamlit 界面提供了一种可视化的方式来配置服务并与 MCP 编排器进行交互。

streamlit run st5.py

特点：

配置 Azure SQL、Azure AI 搜索和 Google 搜索
查看MCP连接状态
与协调者聊天
上传图片以进行相似度搜索
查看可用工具及其描述

2. MCP 交响乐指挥（命令行）

交互模式

python main2.py

这将启动一个交互式聊天会话，在其中您可以：

询问有关您的SQL数据库的问题
搜索相似图片
获取由Azure OpenAI合成的智能回复

示例查询：

💬 You: What are the differences between sabbatical, sick, and paid leave?
💬 You: Find images similar to /path/to/image.jpg
💬 You: How many employees are in the database?

单查询模式

python main2.py --query "What are the top 5 products by sales?"

3. 直接使用服务器

直接启动MCP服务器：

python server.py

服务器将：

从（指定位置）加载凭据 credentials.json
设置环境变量
动态注册工具
在标准输入输出（stdio）上启动FastMCP服务器

项目结构

MCP/
├── main2.py                      # MCP Orchestrator with Azure OpenAI
├── server.py                     # FastMCP Server with dynamic tool registration
├── st5.py                        # Streamlit UI for configuration and chat
├── requirements.txt              # Python dependencies
├── .env                          # Environment variables (NOT in git)
├── credentials.json              # Data source credentials (NOT in git)
├── .gitignore                    # Git ignore rules
│
├── app_tools/                    # Tool implementations
│   ├── __init__.py
│   ├── azure/
│   │   ├── azure_sql.py         # Azure SQL Database integration
│   │   └── azure_aisearch.py    # Azure AI Search + Vision integration
│   └── web_db.py                # Google Search via SerpAPI
│
├── images/                       # Image storage for similarity search
├── results/                      # Search results storage
└── unused/                       # Archived/experimental code

关键文件

`main2.py`

MCP Studio Client管理与MCP服务器的stdio通信
AzureOpenAIOrchestrator（可译为“Azure OpenAI 任务协调器”或根据具体上下文简化为“Azure OpenAI 协调器”）使用GPT-4o进行工具选择和响应合成
MCPOrchestrator 可以翻译为“MCPOrchestra（MCPOrchestra）调度器”或“MCPOrchestra（MCPOrchestra）协调器”，具体取决于上下文和该术语在特定领域中的常用表达。在这里，我将其翻译为“MCPOrchestra（MCPOrchestra）调度器”，以保持术语的一致性和易理解性主要协调器，负责协调客户端和大型语言模型（LLM）

`server.py`

负载（或负荷） credentials.json 并设置环境变量
根据配置动态注册工具
将表单类型映射到工具实现
运行FastMCP服务器

`st5.py`

带有Affine主题的Streamlit用户界面
每个服务的配置面板
MCP聊天界面
图片上传和搜索功能

`app_tools/azure/azure_sql.py`

连接到 Azure SQL 数据库
使用GPT-4o从自然语言生成SQL
执行查询并返回结果
用自然语言总结结果

`app_tools/azure/azure_aisearch.py`

使用Azure AI Vision生成图像向量
在Azure AI Search中执行向量相似性搜索
返回带有元数据的相似图像

`app_tools/web_db.py`

使用SerpAPI的Google Lens引擎
在网络上搜索视觉相似的图片
返回带有标题和URL的最相关匹配项

可用工具

1. `process_user_query` (Azure SQL)

描述在Azure SQL数据库上处理自然语言查询

输入：

{
  "user_query": "What are the differences between sabbatical and sick leave?"
}

输出：

{
  "success": true,
  "content": ["Natural language answer based on SQL results"]
}

2. `search_similar` (Azure AI 搜索)

描述使用向量嵌入查找相似图像

输入:

{
  "query_image_path": "/path/to/image.jpg",
  "k": 5
}

输出：

{
  "success": true,
  "content": [
    {
      "description": "Image description",
      "decoded_path": "/path/to/similar/image.jpg",
      "exists": true,
      "score": 0.95
    }
  ]
}

3. `image_search` （谷歌搜索）

描述使用Google Lens在网页上搜索视觉相似的图片

输入：

{
  "image_url": "https://example.com/image.jpg",
  "num": 5
}

输出：

{
  "success": true,
  "content": [
    {
      "title": "Similar image title",
      "thumbnail": "https://...",
      "url": "https://...",
      "source": "example.com"
    }
  ]
}

安全考量

⚠️ 严重安全问题

永远不要 在源代码中硬编码凭证。当前的代码库中包含一些必须移除的硬编码凭证：

将所有凭据移动到环境变量中：

   # Bad (hardcoded in code)
   SQL_PASSWORD = "intern@12345"

   # Good (from environment)
   SQL_PASSWORD = os.getenv("SQL_PASSWORD")

立即更换被泄露的凭据：

- 任何已提交到 git 的凭据都应进行轮换 - 更改Azure门户中的所有API密钥和密码

使用 .gitignore:

   .env
   credentials.json
   *.log
   __pycache__/
   venv/

使用 Azure 密钥保管库 （推荐）：

   from azure.identity import DefaultAzureCredential
   from azure.keyvault.secrets import SecretClient

   credential = DefaultAzureCredential()
   client = SecretClient(vault_url="https://your-vault.vault.azure.net/", credential=credential)
   secret = client.get_secret("sql-password")

最佳实践

环境变量始终使用 .env 用于存储秘密的文件或环境变量
凭证轮换定期更换凭据
最小特权原则使用具有最小必要权限的服务账户
审计日志记录在Azure SQL和其他服务上启用审核日志记录
网络安全尽可能使用私有终结点和虚拟网络（VNets）

故障排除

问题：MCP连接失败

错误： RuntimeError: Attempted to exit cancel scope in a different task

解决方案这是一个来自MCP SDK的无害清理警告。连接仍然有效。在最新版本中，该错误已被抑制 main2.py.

问题：Azure OpenAI API 错误

错误: 401 Unauthorized 或者 API key invalid

解决方案:

验证您的API密钥 .env
检查您的 Azure OpenAI 端点是否正确
确保您的部署名称匹配 AZURE_DEPLOYMENT
验证API版本是否受支持

问题：SQL 连接失败

错误： Login failed for user 或者 Server not found

解决方案：

验证您的SQL Server防火墙是否允许您的IP地址
检查用户名/密码 credentials.json 或者 .env
确保已安装ODBC驱动程序18
使用 Azure Data Studio 测试连接

问题：图片搜索未返回结果

错误未找到相似图片

解决方案：

验证 Azure AI Vision 凭据
检查您的索引是否包含向量嵌入
确保图像路径有效且可读
验证 Azure AI Search 索引名称是否正确

问题：导入错误

错误: ModuleNotFoundError: No module named 'mcp'

解决方案:

pip install fastmcp mcp
pip install -r requirements.txt

贡献

开发环境设置

为仓库创建分支（或“克隆仓库”）
创建一个特性分支： git checkout -b feature/your-feature
进行你的更改
进行彻底测试
提交时附带明确信息
推送并创建拉取请求

代码风格

遵循PEP 8规范
在可能的情况下使用类型提示
为所有函数添加文档字符串
保持函数的专注性和简洁性
为新功能编写单元测试

测试

# Test individual components
python app_tools/azure/azure_sql.py
python app_tools/azure/azure_aisearch.py
python app_tools/web_db.py

# Test MCP server
python server.py

# Test orchestrator
python main2.py --query "test query"

许可证

支持

对于问题和疑问：

检查故障排除部分；章节
查看登录日志 search_index.log
启用DEBUG日志记录： logging.basicConfig(level=logging.DEBUG)
联系开发团队

______________________________________________________________________

版本1.0.0 最后更新时间2024年10月 python3.13+ 状态生产

Unified MCP

快速接入

详细介绍