AI导哈

模型上下文协议客户端-服务器部署

该项目部署了一个MCP（模型上下文协议）客户端-服务器架构，客户端通过REST API提供远程交互，服务器提供访问战略规划数据的工具。

  • by OmarQuda
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 OmarQuda/mcp_

使用说明

MCP 客户端-服务器部署

该项目采用MCP（模型上下文协议）的客户端-服务器架构，其中：

  • 该 客户 生成/产生 服务器 作为使用stdio通信的子进程
  • 客户端提供了一个REST API用于远程交互
  • 服务器提供了访问战略规划数据的工具

建筑

┌─────────────────────────────────────────┐
│  Render Web Service                     │
│  ├─ app.py (FastAPI - Client)           │
│  │   ├─ REST API endpoints              │
│  │   ├─ Talks to Groq/LLM               │
│  │   └─ Calls MCP server via stdio      │
│  │                                       │
│  └─ db.py (MCP Server - subprocess)     │
│      └─ Provides MCP tools:             │
│         - get_institute_about           │
│         - list_strategic_plans          │
│         - get_strategic_map             │
└─────────────────────────────────────────┘

本地开发

先决条件

  • Python 3.13
  • uv 包管理器

设置

  1. 安装依赖项：
# Using uv (recommended)
cd db_chat && uv sync
cd ../mcp-client && uv sync

# Or using pip
pip install -r requirements.txt
  1. 创造 .env 在根目录中放入文件：
# Groq API Configuration
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

# API Configuration
GENERAL_BASE_URL=your_general_base_url_here
STRATEGIC_BASE_URL=your_strategic_base_url_here
API_USERNAME=your_username_here
API_PASSWORD=your_password_here

# Optional
MAX_TURNS=10

本地运行

选项1：交互式客户端（终端）

cd mcp-client
uv run python client.py ../db_chat/db.py

选项2：Web API（REST）

python app.py

然后访问于 http://localhost:8000

API 端点

健康检查

GET /
GET /health

列出可用工具

GET /tools

回答：

{
  "tools": [
    {
      "name": "get_institute_about",
      "description": "Return the Arabic 'about institute' text",
      "input_schema": {}
    },
    ...
  ]
}

查询系统

POST /query
Content-Type: application/json

{
  "query": "What is the institute about?"
}

回答：

{
  "response": "The institute is...",
  "error": null
}

部署到渲染服务

使用 render.yaml（推荐）

  1. 将代码推送到GitHub
  2. 将你的GitHub仓库连接到Render
  3. Render 将自动检测 render.yaml
  4. 在Render仪表板中设置环境变量：
    • GROQ_API_KEY
    • GENERAL_BASE_URL
    • STRATEGIC_BASE_URL
    • API_USERNAME
    • API_PASSWORD
  5. 部署！

手动部署

  1. 在Render上创建一个新的Web服务
  2. 连接您的存储库
  3. 配置：
    • 环境python
    • 构建命令： pip install -r requirements.txt
    • 开始命令： python app.py
    • Python 版本3.13.0
  4. 添加环境变量（见上文）
  5. 部署

测试已部署的API

使用 curl

# Health check
curl https://your-app.onrender.com/health

# List tools
curl https://your-app.onrender.com/tools

# Query
curl -X POST https://your-app.onrender.com/query \
  -H "Content-Type: application/json" \
  -d '{"query": "List the latest 5 strategic plans"}'

使用Python

import requests

url = "https://your-app.onrender.com/query"
response = requests.post(url, json={"query": "What is the institute about?"})
print(response.json()["response"])

项目结构

.
├── app.py                          # FastAPI web service (entry point)
├── requirements.txt                # Python dependencies
├── render.yaml                     # Render deployment config
├── runtime.txt                     # Python version
├── db_chat/                        # MCP Server
│   ├── db.py                       # MCP server implementation
│   ├── external_api_service.py     # API client
│   └── pyproject.toml              # Server dependencies
├── mcp-client/                     # MCP Client
│   ├── client.py                   # MCP client implementation
│   ├── llm_service.py              # LLM integration
│   └── pyproject.toml              # Client dependencies
└── README.md                       # This file

环境变量

变量 描述 必需
GROQ_API_KEY 根据提供的信息，以下是原文内容的翻译：
GROQ_MODEL Groq模型名称 否（默认：llama-3.3-70b-versatile）
GENERAL_BASE_URL 通用API基础URL 是
STRATEGIC_BASE_URL 战略API基础URL 是
API_USERNAME API用户名 是
API_PASSWORD API密码 是
MAX_TURNS 最大对话轮次 否（默认：10）
PORT 服务器端口 否（默认：8000）

它是如何工作的

  1. 初创企业当 app.py 开始，它：

    • 创建一个 MCPClient 例子
    • 生成（生物/物体等） db.py 作为子过程
    • 在它们之间建立stdio通信

  2. 查询处理当你发送查询时：

    • FastAPI接收HTTP请求
    • 将其传递给MCP客户端
    • 客户端将其发送给Groq的大型语言模型（LLM）
    • 大型语言模型（LLM）决定是否需要工具
    • 如果是，则通过标准输入输出（stdio）调用MCP服务器
    • 服务器从外部API获取数据
    • 响应流程如下：服务器 → 客户端 → 大语言模型 → API 响应

  3. 关机当服务停止时：

    • MCP客户端优雅地关闭了连接
    • 服务器子进程终止
    • 资源已清理

故障排除

“MCP 客户端未初始化”

  • 检查所有环境变量是否已设置
  • 检查启动错误的日志记录

“没有名为 'mcp' 的模块”

  • 确保 requirements.txt 包含所有依赖项
  • 在 Render 上重建服务

大型语言模型（LLM）未调用工具

  • 验证 GROQ_API_KEY 是有效的
  • 检查该查询是否确实需要使用工具

许可证

麻省理工学院（MIT）

相关 MCP