跳转到内容
@aws/nx-plugin
Blog

Python MCP 服务器

生成一个Python 模型上下文协议（MCP）服务器，用于为大型语言模型（LLMs）提供上下文，并可选择部署到Amazon Bedrock AgentCore。

什么是MCP？

Section titled “什么是MCP？”

模型上下文协议（MCP）是一个开放标准，允许AI助手与外部工具和资源交互。它为LLMs提供了一致的方式来：

  • 执行执行操作或检索信息的工具（函数）
  • 访问提供上下文或数据的资源

使用方式

Section titled “使用方式”

生成MCP服务器

Section titled “生成MCP服务器”

您可以通过两种方式生成Python MCP服务器：

  1. 安装 Nx Console VSCode Plugin 如果您尚未安装
  2. 在VSCode中打开Nx控制台
  3. 点击 Generate (UI) 在"Common Nx Commands"部分
  4. 搜索 @aws/nx-plugin - py#mcp-server
  5. 填写必需参数
    • 点击 Generate

    选项参数

    Section titled “选项参数”
    参数 类型 默认值 描述
    project 必需 string - The project to add an MCP server to
    computeType string BedrockAgentCoreRuntime The type of compute to host your MCP server. Select None for no hosting.
    name string - The name of your MCP server (default: mcp-server)
    iacProvider string CDK The preferred IaC provider

    生成器输出

    Section titled “生成器输出”

    生成器将在现有Python项目中添加以下文件：

    • 文件夹your-project/
      • 文件夹your_module/
        • 文件夹mcp_server/ （或指定的自定义名称）
          • __init__.py Python包初始化文件
          • server.py 主服务器定义，包含示例工具和资源
          • stdio.py STDIO传输入口点，适用于简单本地MCP服务器
          • http.py 可流式HTTP传输入口点，适用于托管MCP服务器
          • Dockerfile MCP服务器托管入口点（当computeType设为None时排除）
      • pyproject.toml 更新了MCP依赖项
      • project.json 更新了MCP服务器服务目标

    基础设施

    Section titled “基础设施”

    由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

    通用的基础设施即代码项目结构如下：

    • 文件夹packages/common/constructs
      • 文件夹src
        • 文件夹app/ 针对特定项目/生成器的基础设施构造体
          • …
        • 文件夹core/ 被 app 目录构造体重用的通用构造体
          • …
        • index.ts 导出 app 目录构造体的入口文件
      • project.json 项目构建目标与配置

    部署 MCP 服务器时将会生成以下文件：

    • 文件夹packages/common/constructs/src
      • 文件夹app
        • 文件夹mcp-servers
          • 文件夹<project-name>
            • <project-name>.ts 用于部署 MCP 服务器的 CDK 构造
            • Dockerfile CDK 构造使用的直通式 docker 文件
      • 文件夹core
        • 文件夹agent-core
          • runtime.ts 用于部署到 Bedrock AgentCore Runtime 的通用 CDK 构造

    使用MCP服务器

    Section titled “使用MCP服务器”

    添加工具

    Section titled “添加工具”

    工具是AI助手可以调用的执行操作的函数。Python MCP服务器使用MCP Python SDK (FastMCP)库，该库提供了基于装饰器的工具定义方式。

    在server.py文件中添加新工具：

    @mcp.tool(description="工具描述")
    def your_tool_name(param1: str, param2: int) -> str:
        """带类型提示的工具实现"""
        # 工具逻辑
        return f"结果：{param1} 与 {param2}"

    FastMCP库自动处理：

    • 基于函数类型提示的类型验证
    • MCP协议的JSON模式生成
    • 错误处理和响应格式化

    添加资源

    Section titled “添加资源”

    资源为AI助手提供上下文。使用@mcp.resource装饰器添加资源：

    @mcp.resource("example://static-resource", description="静态资源示例")
    def static_resource() -> str:
        """返回静态内容"""
        return "这是为AI提供上下文的静态内容"
    

    @mcp.resource("dynamic://resource/{item_id}", description="动态资源示例")
    def dynamic_resource(item_id: str) -> str:
        """根据参数返回动态内容"""
        # 根据item_id获取数据
        data = fetch_data_for_item(item_id)
        return f"{item_id}的动态内容：{data}"

    配置AI助手

    Section titled “配置AI助手”

    配置文件

    Section titled “配置文件”

    大多数支持 MCP 的 AI 助手都采用相似的配置方式。您需要创建或更新包含 MCP 服务器详细信息的配置文件：

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "-m",
            "my_module.mcp_server.stdio"
          ],
          "env": {
            "VIRTUAL_ENV": "/path/to/your/project/.venv"
          }
        }
      }
    }

    特定助手配置

    Section titled “特定助手配置”

    请参考以下文档配置特定 AI 助手的 MCP 设置：

    运行MCP服务器

    Section titled “运行MCP服务器”

    检查器

    Section titled “检查器”

    生成器配置了名为<your-server-name>-inspect的目标，用于启动MCP检查器并通过STDIO传输连接到MCP服务器。

    Terminal window
    pnpm nx run your-project:your-server-name-inspect

    检查器将运行在http://localhost:6274。点击”Connect”按钮开始使用。

    STDIO模式

    Section titled “STDIO模式”

    测试和使用MCP服务器最简单的方式是使用检查器或按上述方式配置AI助手。

    您也可以通过<your-server-name>-serve-stdio目标直接使用STDIO传输运行服务器：

    Terminal window
    pnpm nx run your-project:your-server-name-serve-stdio

    该命令使用uv run通过STDIO传输执行MCP服务器。

    可流式HTTP

    Section titled “可流式HTTP”

    如需使用可流式HTTP传输在本地运行MCP服务器，可使用<your-server-name>-serve-http目标：

    Terminal window
    pnpm nx run your-project:your-server-name-serve-http

    该命令使用uv run通过HTTP传输执行MCP服务器，默认运行在8000端口。

    部署到Bedrock AgentCore运行时

    Section titled “部署到Bedrock AgentCore运行时”

    基础设施即代码

    Section titled “基础设施即代码”

    如果为computeType选择了BedrockAgentCoreRuntime，系统会生成相关的CDK或Terraform基础设施代码，您可以用其将MCP服务器部署到Amazon Bedrock AgentCore Runtime。

    系统会基于生成器运行时指定的name自动生成CDK构造（默认使用<ProjectName>McpServer命名）。

    您可以在CDK应用中使用该构造：

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        // 将MCP服务器添加到堆栈
        new MyProjectMcpServer(this, 'MyProjectMcpServer');
      }
    }

    认证机制

    Section titled “认证机制”

    IAM认证

    Section titled “IAM认证”

    默认情况下，MCP服务器使用IAM认证进行安全防护，直接部署时无需额外参数：

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        new MyProjectMcpServer(this, 'MyProjectMcpServer');
      }
    }

    您可以通过grantInvoke方法授予调用权限。例如，允许使用py#strands-agent生成器创建的代理调用MCP服务器：

    import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        const agent = new MyProjectAgent(this, 'MyProjectAgent');
        const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');
    

        mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
      }
    }

    Cognito JWT认证

    Section titled “Cognito JWT认证”

    以下演示如何为代理配置Cognito认证。

    配置JWT认证时，可通过authorizerConfiguration属性传递参数。以下示例展示了如何配置Cognito用户池和客户端来保护MCP服务器：

    import { MyProjectMcpServer } from ':my-scope/common-constructs';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        const userPool = new UserPool(this, 'UserPool');
        const client = userPool.addClient('Client', {
          authFlows: {
            userPassword: true,
          },
        });
    

        new MyProjectMcpServer(this, 'MyProjectMcpServer', {
          authorizerConfiguration: {
            customJWTAuthorizer: {
              discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
              allowedClients: [client.userPoolClientId],
            },
          },
        });
      }
    }

    打包和Docker目标

    Section titled “打包和Docker目标”

    要为Bedrock AgentCore Runtime构建MCP服务器，项目中添加了bundle目标，该目标：

    • 使用uv export将Python依赖导出到requirements.txt文件
    • 使用uv pip install为目标平台（aarch64-manylinux2014）安装依赖

    同时添加了特定于MCP服务器的docker目标，该目标：

    • 从Dockerfile构建docker镜像，根据MCP协议约定在8000端口运行MCP服务器

    可观测性

    Section titled “可观测性”

    您的MCP服务器通过配置Dockerfile中的自动检测功能，使用AWS Distro for Open Telemetry (ADOT) 实现了开箱即用的可观测性。

    您可以在CloudWatch AWS控制台的菜单中选择”GenAI Observability”查看追踪数据。注意：要使追踪数据正常显示，需先启用Transaction Search功能。

    更多详细信息，请参考AgentCore可观测性配置文档。