快速mcp服务器
PRD:FastMCP生产就绪服务器
1.目的
构建一个结构化、可配置、可测试的生产就绪FastMCP服务器，并为本地、容器化和Azure部署做好准备。将Neo4j连接作为工具，并提供CI/CD脚手架。
2.目标
- 将项目组织成基于包的结构。
- 提供环境驱动的配置（HOST/PORT、应用程序名称、Neo4j证书）。
- 添加结构化日志（JSON）。
- 添加Neo4j工具：健康检查和查询工具。
- 提供测试、Docker、Docker Compose和Azure部署模板。
- 为测试和可选部署提供CI工作流。
3.非目标
- 全面强化生产安全（秘密管理、网络策略）。
- 特定于域的Neo4j模式或复杂查询库。
- 全监控/可观察性堆栈。
4.目标环境
- Python 3.10.19
- FastMCP 2.14.5
- Neo4j 5.25.0
- macOS上的本地开发，Azure上的生产（容器应用或应用服务）
5.功能要求
5.1服务器
- 必须使用环境中的名称启动FastMCP服务器。
- 必须从环境绑定到HOST和PORT。
- MCP端点位于/MCP。
5.2工具
- greet（name:str）->str返回“你好，{name}！”。
- neo4j_health（）->带异常字符串的“ok”或“error”。
- neo4j_query（密码：str，参数：dict |无=无，限制：int=50）->列表\[字典\]
- 上限为1..1000。 - 失败时返回记录字典列表或〔｛“error”：“…”｝〕。
5.3配置
- 读取这些变量：
- APP_NAME - 主机 - 端口 - LOG_LEVEL - NEO4J_URI - NEO4J_USER - NEO4J_密码
- 提供.env.example.模板。
5.4日志记录
- 将JSON日志发送到stdout。
- 包括时间（UTC ISO）、级别、记录器、消息和exc_info（如果存在）。
5.5测试
- 问候工具的基本单元测试。
- 使用pytest运行。
5.6 Docker与作曲
- 应用程序容器的Dockerfile。
- docker-compose.yml与应用程序和Neo4j服务。
- 应用程序通过以下方式使用Neo4j容器bolt://neo4j:7687.
5.7 Azure部署
- Azure容器应用模板（containerapp.yaml）。
- 部署容器应用程序的脚本。
- 应用服务启动脚本。
- 应用服务apps_template。
- 部署应用服务的脚本。
- 用于CI和可选部署的GitHub操作工作流。
5.8 GitHub秘密（部署）
CI部署作业需要：
- AZURE_CREDENTIALS（服务主体JSON）
- AZURE_RG
- AZURE_LOCATION
- ACR_LOGIN_SERVER
- ACR_用户名
- ACR_密码
仅限应用服务：
- APP_SERVICE_NAME
仅限容器应用程序：
- ACA_ENV
- ACA_APP_NAME
6.项目结构
. ├─ app/ │ ├─ __初始化__南美国家巴拉圭的缩写（Paraguay） │ ├─ config.py │ ├─ 日志.py │ ├─ main.py │ └─ 工具/ │ ├─ __初始化__南美国家巴拉圭的缩写（Paraguay） │ ├─ 问候.py │ └─ neo4j.py ├─ 测试/ │ └─ test_greetings.py ├─ 要求/ │ ├─ base.txt │ └─ dev.txt ├─ .env.example ├─ Dockerfile ├─ docker-compose.yml ├─ startup.sh ├─ 需求.txt ├─ 服务器.py ├─ 蔚蓝/ │ ├─ 应用程序参数 │ └─ containerapp.yaml ├─ 脚本/ │ ├─ deploy_aa.sh │ └─ 部署appservice.sh └─ .github/ └─ 工作流/ └─ ci-deploy.yml
6.1快速入门
当地：
- 从.env.example创建.env文件，并根据需要调整值。
- 安装deps:pip安装-r要求/dev.txt
- 运行测试：pytest
- 启动服务器：python-m app.main
- 打开：http://127.0.0.1:8000/mcp
Docker：
- 构建并运行：docker compose up--Build
- 打开：http://127.0.0.1:8000/mcp
- Neo4j浏览器：http://127.0.0.1:7474
Azure应用服务（手动）：
- 为ACR设置所需的环境变量和机密。
- 运行：bash脚本/deploy_appservice.sh
Neo4j环境变量（Neo4j工具需要）：
- NEO4J_URI
- NEO4J_USER
- NEO4J_密码
MCP客户端标头（无状态可流式传输http）：
- 接受：应用程序/json、文本/事件流
- 内容类型：应用程序/json
邮递员导入（无状态收集）：
{
"info": {
"name": "FastMCP Neo4j (Stateless)",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "neo4j_health",
"request": {
"method": "POST",
"header": [
{ "key": "Accept", "value": "application/json, text/event-stream" },
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": \"h1\",\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"neo4j_health\",\n \"arguments\": {}\n }\n}"
},
"url": {
"raw": "http://{{host}}:{{port}}/mcp",
"protocol": "http",
"host": ["{{host}}"],
"port": "{{port}}",
"path": ["mcp"]
}
}
},
{
"name": "neo4j_query",
"request": {
"method": "POST",
"header": [
{ "key": "Accept", "value": "application/json, text/event-stream" },
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": \"q1\",\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"neo4j_query\",\n \"arguments\": {\n \"cypher\": \"MATCH (n) RETURN n LIMIT 5\",\n \"parameters\": {}\n }\n }\n}"
},
"url": {
"raw": "http://{{host}}:{{port}}/mcp",
"protocol": "http",
"host": ["{{host}}"],
"port": "{{port}}",
"path": ["mcp"]
}
}
}
],
"variable": [
{ "key": "host", "value": "127.0.0.1" },
{ "key": "port", "value": "8000" }
]
}7.建筑
7.1组件图（ASCII）
流程图TB 应用程序\[“fastmcp应用程序 app/main.py 工具/\*.py config.py logging.py“\] Neo4j\[“Neo4j数据库 bolt://host:7687"\] MCP\[“/MCP端点”\]
应用程序\Neo4j 应用程序-->MCP
7.2运行时流（ASCII）
开始 ->负载设置 ->配置JSON日志记录 ->创建FastMCP ->注册工具 ->run（主机、端口）
7.3部署图（ASCII）
当地： 开发人员->Python->FastMCP->/mcp
Docker： 开发者->Docker->容器（FastMCP）->Neo4j容器
Azure容器应用程序： GitHub操作->ACA->容器（FastMCP）
Azure应用服务： GitHub操作->应用服务->startup.sh->FastMCP
8.详细实施要求
8.1应用程序/配置文件
- 具有env默认值的数据类设置。
- get_settings（）返回设置。
8.2应用程序/日志.py
- JsonFormatter，其中ensure_ascii=True。
- configure_logging（level）设置根处理程序和级别。
8.3 app/main.py
- create_app（设置）返回已注册工具的FastMCP。
- main（）加载设置并与主机/端口一起运行。
8.4应用程序/工具/neo4j.py
- 使用neo4j。带有缓存驱动程序的GraphDatabase.driver。
- 健康检查使用“正常返回1”。
- 查询返回字典列表，处理错误。
8.5服务器.py
- 调用app.main.main以获得兼容性。
9.安全和配置
- repo中没有存储任何秘密。
- .env.example.是安全默认值。
- 用于在生产中提供机密的Azure应用程序设置。
10.操作注意事项
- 日志记录是JSON，用于摄取到Azure日志记录中。
- Neo4j连接错误不应导致服务器在启动时崩溃。
- Neo4j查询工具是最小的，应该限制在生产环境中。
11.风险和缓解措施
- 无边界查询：强制限制上限。
- 凭据泄漏：避免提交.env，使用Azure设置。
- 可用性：允许通过Azure重新启动容器。
12.测试计划
- 问候工具的单元测试。
- 可选：在docker compose中添加Neo4j的集成测试。
13.验收标准
- 服务器使用env HOST/PORT运行。
- /mcp端点响应。
- 问候工具返回正确的字符串。
- 当数据库可访问时，neo4j_health返回“ok”。
- neo4j_query返回有效查询的行。
- docker compose带来了app+neo4j。
- CI运行pytest。
- Azure模板和脚本已存在。
14.里程碑
- 重构项目并添加配置/日志/工具。
- 添加测试并拆分要求。
- 添加Docker并编写。
- 添加Azure模板和脚本。
- 添加CI工作流。
15.开放式问题
- 最终的Neo4j模式和查询模式。
- Azure目标：容器应用与主要应用服务。
- 秘密管理策略（密钥库等）。