Template Base

模块化MCP服务器模板

这个仓库提供了一个开箱即用的起点，用于构建模型上下文协议（MCP）服务，其中包含了所有必要的组件 FastMCP它自带一个生产级别的服务器、自动模块发现功能、一个具有预设意见的配置系统，以及一个用于端到端测试整个堆栈的示例客户端。

______________________________________________________________________

亮点

• FastMCP HTTP服务器 由Starlette和Uvicorn提供支持。
• 自动发现 内部的工具、资源和提示 server 包（通过（与...切换） AUTO_DISCOVER）。
• 环境驱动的配置 由……支持/赞助 server/config/settings.yaml 具有合理的默认设置。
• 优雅地关闭 以及可选的JSON日志记录功能，便于容器化部署。
• Oracle性能调优示例提示 以及展示结构化提示构建的资源。
• 客户端示例 (client/check_query.py该程序会调用服务器，获取资源，触发提示，并通过Groq流式传输结果。
• Docker 已就绪compose 命令通过单个指令启动服务器和演示客户端。

______________________________________________________________________

项目布局

.
|-- client/
|   |-- check_query.py          # Example FastMCP client + Groq workflow
|   |-- requirements.txt        # Client dependencies
|   |-- Dockerfile              # Client container
|   `-- query_reports/          # Generated analysis artifacts
|-- server/
|   |-- server.py               # Entrypoint, HTTP app, auto-discovery
|   |-- mcp_app.py              # Shared FastMCP instance
|   |-- config.py               # Settings loader (env + YAML)
|   |-- config/settings.yaml    # Default configuration template
|   |-- tools/                  # Example tools (hello, math, remote bridge)
|   |-- resources/              # Example resources (server info, documents)
|   |-- prompts/                # Example prompts (Oracle tuning)
|   |-- requirements.txt        # Server dependencies
|   `-- Dockerfile              # Server container
|-- docker-compose.yml          # Local orchestration for server + client
|-- .env                        # Runtime configuration (not committed)
`-- .gitignore

______________________________________________________________________

先决条件

• Docker 和 Docker Compose（用于快速入门）
• 如果你计划在你的机器上直接运行服务器或客户端，建议使用 Python 3.11+
• Groq API访问权限（仅演示客户端需要）

______________________________________________________________________

开始使用 Docker

1. 复制 .env.example 到；朝 .env （或创建 .env并填写相关数值，尤其是 GROQ_API_KEY 如果你计划运行示例客户端。
2. 构建并启动堆栈：

   docker-compose up --build

1. 一旦两个服务都运行正常，就探索服务器：

   curl http://localhost:9002/healthz
   curl http://localhost:9002/_info

1. 在另一个终端中，执行其容器内的演示客户端：

   docker-compose exec client python check_query.py

客户端从MCP服务器获取调优规则，生成提示，调用Groq进行分析，并将摘要写入（到某个位置或文件中，原文此处略去具体位置） client/query_summary.csv 更详细的Markdown报告 client/query_reports/。

停止堆栈使用 docker-compose down 当你完成后。

______________________________________________________________________

本地运行（可选）

如果您更倾向于在不使用 Docker 的情况下运行组件：

# Server
cd server
python -m venv .venv && .venv\Scripts\activate  # adjust for your shell
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 9002

# Client (new terminal)
cd client
python -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt
python check_query.py

确保 .env 文件在这两个目录中均可找到，因此脚本可以读取匹配的配置。

______________________________________________________________________

配置

服务器从环境变量中读取其设置（可选地通过扩展获取） server/config/settings.yaml）。 关键价值观包括：

更新 .env 在运行堆栈之前，请（或使用您的部署密钥管理器）。如果YAML文件缺失，配置加载器将回退到使用环境变量。

______________________________________________________________________

添加新的MCP组件

1. 工具 – 添加一个新函数 server/tools/ 并用……装饰它 @mcp.tool()当 AUTO_DISCOVER 一旦启用，模块将在重启时自动加载。

   # server/tools/hello_tool.py
   from mcp_app import mcp

   @mcp.tool()
   def hello(name: str) -> str:
       return f"Hello, {name}!"

1. 资源 – 定义只读数据源，使用 @mcp.resource("protocol://path") 里面 server/resources/。

1. 提示 – 返回格式化的字符串（或消息结构），使用 @mcp.prompt() 在 server/prompts/随附的Oracle调优提示是进行结构化大型语言模型（LLM）交互的良好起点。

重启服务器（或让Uvicorn重新加载），连接的客户端将立即能够使用新的组件。

______________________________________________________________________

演示客户端工作流

client/check_query.py 说明了如何：

• 使用（以下方式）连接到服务器 fastmcp.Client 通过HTTP。
• 检索服务器资源（oracle://tuning/rules）。
• 请求提示（oracle_query_tuning_prompt并将它们转发给Groq。
• 解析模型输出，总结关键发现，并撰写报告。

在将服务器连接到您自己的应用程序或代理框架时，请将其作为参考。

______________________________________________________________________

扩展模板

• 用您自己的领域知识替换示例提示/资源逻辑。
• 通过启用远程服务器块来挂载或代理额外的MCP服务 settings.yaml。
• 添加身份验证中间件到 server/server.py 在生产环境中保护终端节点。
• 根据您的部署环境，按需使用仪器日志记录/指标导出器。

______________________________________________________________________

许可证

根据MIT许可证发布。详见 LICENSE （如需更多细节，请添加一条）。