关键词

LLM后端上下文服务AI工具平台Python应用OpenShift部署

项目简介

FastMCP 服务器模板是一个基于 Python 和 FastMCP 框架构建的后端应用，旨在以标准化方式为大型语言模型 (LLM) 客户端提供上下文信息和功能。它支持动态注册和管理各种功能模块，包括工具（Tools）、资源（Resources）、Prompt 模板（Prompts）和中间件（Middleware），并通过 JSON-RPC 协议与 LLM 客户端进行通信。该模板设计为生产就绪，具有热重载、身份认证和 OpenShift 一键部署等特性。

主要功能点

  • 动态功能加载: 自动发现并加载通过 Python 装饰器定义的工具、资源、Prompt 和中间件，无需手动注册。
  • 工具 (Tools): 允许 LLM 客户端调用外部功能。支持参数类型安全验证、错误处理和结构化输出。
  • 资源 (Resources): 提供数据访问能力，LLM 客户端可按 URI 请求数据。支持资源分类组织和动态参数化。
  • Prompt 模板 (Prompts): 支持可定制的 LLM 交互模式。Prompt 定义在 Python 中，支持类型注解、上下文访问和多种返回类型。
  • 中间件 (Middleware): 提供请求处理的钩子，用于实现日志、身份认证、限流等横切关注点。
  • 安全认证: 可选的 JWT 身份认证和基于作用域的授权机制。
  • 多种传输协议: 支持本地开发时的 STDIO（标准输入输出）和生产部署时的 HTTP 传输。
  • 生产就绪: 提供 OpenShift 一键部署脚本、热重载功能和完善的测试套件。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/rdwj/mcp-server-template.git
cd mcp-server-template
  2. 安装依赖: 
    make install
    这会创建 Python 虚拟环境并安装所有必要的 Python 库。
  3. 安装 'cmcp' 客户端工具 (可选，用于本地测试): 
    pip install cmcp
    或者在虚拟环境激活后运行： 
    .venv/bin/pip install cmcp

服务器配置

MCP 客户端需要知道如何启动 MCP 服务器进程才能与之通信。以下是 MCP 客户端配置该服务器的 JSON 示例及其参数说明：

{
  "name": "fastmcp-unified",
  "command": ".venv/bin/python",
  "args": ["-m", "src.main"],
  "environment": {
    "MCP_TRANSPORT": "stdio",
    "MCP_HOT_RELOAD": "1",
    "MCP_LOG_LEVEL": "INFO",
    "MCP_SERVER_NAME": "my-mcp-server-instance"
    // 可以根据需要添加其他环境变量，如 MCP_AUTH_JWT_SECRET 等
  },
  "description": "本地开发环境的 FastMCP 服务器",
  "capabilities": {
    // 根据服务器实际提供的功能进行声明，建议从服务器获取实际能力
    "tools": true,
    "resources": true,
    "prompts": true,
    "streaming": true,
    "json_rpc_version": "2.0"
  }
}

参数注释:

  • 'name': 服务器的名称，会显示在 MCP 客户端中。
  • 'command': 启动 MCP 服务器的 Python 可执行文件路径。在本地开发时，通常指向项目虚拟环境中的 Python 解释器。
  • 'args': 传递给 Python 可执行文件的参数。'-m src.main' 表示运行 'src' 目录下的 'main.py' 模块作为服务器入口。
  • 'environment': 环境变量配置。
    • 'MCP_TRANSPORT': 指定传输协议，'"stdio"' 用于本地开发，'"http"' 用于 OpenShift 部署。
    • 'MCP_HOT_RELOAD': 设置为 '"1"' 启用热重载，方便开发调试。
    • 'MCP_LOG_LEVEL': 日志级别，如 '"INFO"'、'"DEBUG"'。
    • 'MCP_SERVER_NAME': 自定义服务器名称。
    • 'MCP_AUTH_JWT_SECRET': （可选）JWT 签名密钥，用于身份认证。
    • 'MCP_AUTH_JWT_PUBLIC_KEY': （可选）JWT 公钥，用于非对称签名验证。
    • 'MCP_REQUIRED_SCOPES': （可选）请求所需的逗号分隔的作用域。
    • 部署到 OpenShift 时，'MCP_TRANSPORT' 自动设置为 '"http"'，并可通过 'MCP_HTTP_HOST'、'MCP_HTTP_PORT'、'MCP_HTTP_PATH' 配置 HTTP 服务参数。
  • 'description': 服务器的简要描述。
  • 'capabilities': 服务器能力声明，告知客户端服务器支持哪些功能。

基本使用方法

  1. 启动本地服务器: 
    make run-local
    这会在当前终端启动 MCP 服务器，监听 STDIO。
  2. 通过 'cmcp' 客户端测试 (在另一个终端): 
    cmcp ".venv/bin/python -m src.main" tools/list
    这个命令会连接到本地运行的服务器，并请求列出所有可用的工具。你可以尝试其他命令，例如调用一个工具： 
    cmcp ".venv/bin/python -m src.main" tools/call echo '{"message": "Hello from cmcp!"}'
  3. 添加自定义功能: 根据 README.md 中的指引，在 'src/tools/'、'src/resources/'、'src/prompts/' 或 'src/middleware/' 目录中创建 Python 文件，并使用 '@mcp.tool'、'@mcp.resource'、'@mcp.prompt' 或 '@mcp.middleware' 装饰器定义你的功能。服务器在热重载模式下会自动发现并加载这些新功能。
  4. 部署到 OpenShift: 如果你需要将服务器部署到 OpenShift 环境，确保你已登录 'oc' CLI，然后运行： 
    make deploy
# 或者部署到指定项目
make deploy PROJECT=my-mcp-project
    这会构建容器镜像并部署到你的 OpenShift 集群。

信息

分类

AI与计算

访问项目