Python MCP 服务器

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

什么是MCP？

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

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

使用方式

生成MCP服务器

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

VSCode
CLI

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

pnpm nx g @aws/nx-plugin:py#mcp-server

yarn nx g @aws/nx-plugin:py#mcp-server

npx nx g @aws/nx-plugin:py#mcp-server

bunx nx g @aws/nx-plugin:py#mcp-server

您还可以执行试运行以查看哪些文件会被更改

pnpm nx g @aws/nx-plugin:py#mcp-server --dry-run

yarn nx g @aws/nx-plugin:py#mcp-server --dry-run

npx nx g @aws/nx-plugin:py#mcp-server --dry-run

bunx nx g @aws/nx-plugin:py#mcp-server --dry-run

选项参数

参数	类型	默认值	描述
project 必需	string	-	要添加 MCP 服务器的项目
name	string	-	MCP 服务器的名称（默认：mcp-server）
auth	iam \| cognito	iam	用于对 MCP 服务器进行身份验证的方法。仅在设置了 infra 时适用（当 infra 为 none 时忽略）。
iac	inherit \| cdk \| terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
infra	agentcore \| none	agentcore	托管 MCP 服务器的基础设施类型。选择 none 表示不托管。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

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

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

基础设施

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

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

CDK
Terraform

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

文件夹packages/common/terraform
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的 Terraform 模块
    …
  - 文件夹core/ 被 app 目录模块重用的通用模块
    …
- project.json 项目构建目标与配置

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

CDK
Terraform

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

如果您选择了None作为infra，则不会生成CDK构造或Terraform模块——MCP服务器仅配置为本地STDIO / HTTP使用。在此模式下，auth选项会被忽略，因为没有需要进行身份验证的托管端点。

当部署到 Bedrock AgentCore Runtime 时，MCP 服务器会被构建为容器镜像，推送到 Amazon ECR，并在 AgentCore Runtime 中运行。AI 助手调用 AgentCore Runtime 数据平面端点，该端点通过可流式 HTTP 传输将 tools/* 和 resources/* 调用转发到您的服务器。

使用 infra: None 时，不会生成任何 AWS 基础设施。MCP 服务器仅配置为本地 STDIO 和 HTTP 传输，并由运行在同一台机器上的 AI 助手使用。

使用MCP服务器

添加工具

工具是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模式生成
错误处理和响应格式化

添加资源

资源为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助手

配置文件

大多数支持 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"
      }
    }
  }
}

特定助手配置

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

运行MCP服务器

本地开发

要在本地运行您的MCP服务器（以及与其连接的所有内容，如本地数据库），请使用项目的dev目标：

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

如果您在项目中添加了多个组件（MCP服务器、代理等），这将启动所有组件。要仅运行此MCP服务器，请使用其<your-server-name>-dev目标：

pnpm nx your-server-name-dev your-project

yarn nx your-server-name-dev your-project

npx nx your-server-name-dev your-project

bunx nx your-server-name-dev your-project

检查器

生成器配置了名为<your-server-name>-inspect的目标，该目标会在本地启动您的MCP服务器（通过<your-server-name>-dev目标，包括任何连接的依赖项，如本地数据库），并启动预配置的MCP检查器，通过可流式HTTP传输连接到服务器。

pnpm nx your-server-name-inspect your-project

yarn nx your-server-name-inspect your-project

npx nx your-server-name-inspect your-project

bunx nx your-server-name-inspect your-project

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

STDIO模式

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

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

pnpm nx your-server-name-serve-stdio your-project

yarn nx your-server-name-serve-stdio your-project

npx nx your-server-name-serve-stdio your-project

bunx nx your-server-name-serve-stdio your-project

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

可流式HTTP

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

pnpm nx your-server-name-serve your-project

yarn nx your-server-name-serve your-project

npx nx your-server-name-serve your-project

bunx nx your-server-name-serve your-project

该命令使用uv run uvicorn --reload通过HTTP传输运行MCP服务器（默认在8000端口），并在文件更改时自动重启。

部署到Bedrock AgentCore运行时

基础设施即代码

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

CDK
Terraform

系统会为您的 MCP 服务器生成一个 CDK 构造，其名称基于生成器运行时指定的 name（默认为 <ProjectName>McpServer）。

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

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

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

系统会基于生成器运行时指定的 name（默认为 <ProjectName>-mcp-server）生成一个 Terraform 模块。

将共享的 runtime_config_appconfig 模块的输出传递给 MCP 服务器模块：

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

认证

生成器提供了 auth 选项来为您的 MCP 服务器配置认证。在生成 MCP 服务器时，您可以在 IAM（默认）或 Cognito 认证之间进行选择。

IAM 认证

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

CDK
Terraform

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

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

您可以使用 grantInvokeAccess 方法授予调用 Bedrock AgentCore Runtime 上 MCP 服务器的权限。例如，您可能希望允许通过 py#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.grantInvokeAccess(agent);
  }
}

# MCP 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

要授予调用 MCP 服务器的权限，您需要添加如下策略，并引用 module.my_project_mcp_server.agent_core_runtime_arn 输出值：

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_mcp_server.agent_core_runtime_arn,
    "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
  ]
}

Cognito 认证

当您选择 Cognito 认证时，生成器会配置 MCP 服务器使用 Cognito 进行认证。

CDK
Terraform

生成的构造接受一个 identity 属性来配置 Cognito 认证：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      identity,
    });
  }
}

UserIdentity 构造可以使用 ts#website#auth 生成器生成，或者您可以创建自己的 CDK UserPool 和 UserPoolClient。

生成的模块接受 user_pool_id 和 user_pool_client_ids 变量用于 Cognito 认证：

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

打包和Docker目标

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

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

同时添加了特定于MCP服务器的docker目标，该目标将Dockerfile和打包构建产物复制到docker上下文目录中。这样可以将Dockerfile与构建输出共存，使CDK能够直接使用AgentRuntimeArtifact.fromAsset构建Docker镜像。

镜像扫描

为此项目构建的 Docker 镜像会在构建过程中使用 Trivy 进行漏洞扫描，运行来自 ECR 托管的 Trivy 镜像。

会向您的项目添加一个 trivy 目标，它会扫描构建的镜像，如果发现任何 HIGH 或 CRITICAL 严重级别漏洞，将导致构建失败。生成的 Dockerfile 使用在生成时没有已知可修复的这些严重级别漏洞的基础镜像，并升级捆绑的工具（如 npm）以保持这种状态。

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。由于扫描仅在镜像更改时重新运行，未更改的镜像不会被重新扫描。

抑制 Trivy 发现

在某些情况下，您可能希望抑制特定的漏洞，例如当尚无可用修复且您已评估风险为可接受时。

将漏洞 ID（每行一个）添加到项目根目录中的 .trivyignore 文件（即 project.json 旁边）：

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

有关过滤发现的更多详细信息，请参阅 Trivy 过滤文档。

可观测性

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

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

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

连接

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

TypeScript Agent to MCP将 TypeScript Agent 连接到 MCP 服务器

Python Agent to MCP将 Python Agent 连接到 MCP 服务器

Python MCP Server to Python DynamoDB将 Python MCP Server 连接到 DynamoDB 表

AgentCore Gateway to MCP Server在 AgentCore Gateway 后聚合 MCP 服务器