AWS AgentCore — MCP 运行时 (Neo4j SDK)

简介

此示例演示了如何部署 AWS AgentCore 运行时，并使用基于 FastMCP 和 Neo4j Python 驱动程序构建的自定义 MCP 服务器。该 MCP 服务器并非使用预构建的 Docker 镜像，而是编写为 Python 脚本，通过 CDK 将其与依赖项打包并上传至 S3，最后部署为基于代码的 AgentCore 运行时。

核心功能

  • 基于代码的部署：通过 S3 直接从源代码部署 Python MCP 服务器 — 无需 Docker 镜像

  • FastMCP 框架：使用 FastMCP 构建的轻量级 MCP 服务器，支持流式 HTTP 传输

  • Pydantic 模型：为组织、行业类别和文章提供类型化的响应模型

  • Neo4j Python 驱动程序：使用官方 Python 驱动程序实现与 Neo4j 的直接连接

  • Secrets Manager 集成：Neo4j 凭据安全存储在 AWS Secrets Manager 中

  • IAM 身份验证：使用 AWS IAM 权限实现安全、公共的运行时访问

  • CDK 基础设施：完整的“基础设施即代码”部署 — 无需手动配置 CLI

应用场景

  • 自定义 MCP 工具开发，完全掌控服务器逻辑

  • 为 AI Agent 提供对 Neo4j 知识图谱的安全访问

  • 基于 Python 的 MCP 服务器快速原型开发

  • 企业级数据库凭据密钥管理

架构设计

Architecture Diagram

组件

  1. AWS AgentCore 运行时

    • 托管代理执行环境

    • 从 S3 进行基于代码的部署

    • Python 3.13 运行时

    • 与框架无关的编排

  2. 自定义 MCP 服务器 (mcp_app/mcp_server.py)

    • 使用 FastMCP 构建

    • 流式 HTTP 传输（无状态）

    • 用于类型化工具响应的 Pydantic 模型（Organization、IndustryCategory、Article）

    • 用于数据库访问的 Neo4j Python 驱动程序

    • 在启动时从 Secrets Manager 加载凭据

  3. AWS Secrets Manager

    • 存储 Neo4j 连接凭据 (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE)

    • 通过环境变量将 Secret ARN 传递给运行时

    • 在服务器启动时获取凭据

  4. S3 代码资产

    • CDK 使用 uv 在 Docker 构建步骤中将 mcp_app/ 及其依赖项打包

    • 所得包上传至 S3

    • AgentCore 运行时在部署时从 S3 加载代码

  5. IAM 角色

    • 用于代码检索的 S3 访问权限

    • 用于凭据检索的 Secrets Manager 访问权限

    • 用于可观测性的 CloudWatch Logs 和 X-Ray

    • AgentCore 的工作负载身份

  6. Neo4j 数据库

    • 演示实例：neo4j+s://demo.neo4jlabs.com:7687

    • 包含组织、人物、位置的公司数据库

深度分析

基于代码的部署机制

该示例使用 mcp_app/mcp_server.py 中的 Python MCP 服务器，它与依赖项打包并通过 CDK 部署到 S3

工作原理

  1. CDK 使用带有 uv 的 Docker 构建步骤将 mcp_app/ 打包，为 linux/aarch64 安装依赖项 (fastmcp, boto3, neo4j, pydantic)

  2. 打包后的文件作为 CDK 资产上传到 S3

  3. CfnRuntime 资源引用该 S3 位置，使用 PYTHON_3_13 运行时并将 mcp_server.py 作为入口点

  4. 启动时，MCP 服务器使用 SECRET_ARN 环境变量从 Secrets Manager 加载 Neo4j 凭据

  5. FastMCP 服务器运行在流式 HTTP 传输之上

优势

  • 完全控制 MCP 服务器逻辑和工具

  • 无需管理 Docker 镜像 — 纯 Python 部署

  • 通过 uv 在构建时解析依赖项

  • 通过 Secrets Manager 安全管理凭据

身份验证流程

User/Agent Request
    ↓
[AWS IAM Authentication]
    ↓
AgentCore Runtime (Public)
    ↓
MCP Server (mcp_server.py)
    ↓
[Load credentials from Secrets Manager via SECRET_ARN]
    ↓
Neo4j Database

安全层

  1. IAM 身份验证：控制谁可以调用运行时

  2. 公共运行时：可通过 IAM 访问，无需 VPC

  3. Secrets Manager：安全地存储和检索 Neo4j 凭据

  4. TLS 加密：到 Neo4j 的安全连接 (neo4j+s://)

可用的 MCP 工具

自定义 MCP 服务器公开了以下工具

  • `get_organizations(limit: int) — 从 Neo4j 数据库返回最多 `limit` 个组织。每个组织包含 name（名称）、summary（摘要）、revenue（收入）、nbrEmployees（员工数）、isPublic（是否上市）、isDissolved（是否解散）和 motto（座右铭）等属性。

  • `get_industry_categories(limit: int) — 从 Neo4j 数据库返回最多 `limit` 个行业类别名称。

  • `get_articles_by_organization(name: str) — 返回提及特定组织的文章。每篇文章包含 `title`（标题）、author（作者）、date（日期）、sentiment（情感）、siteName（站点名称）和 summary（摘要）等属性。

您可以通过添加更多用 @mcp.tool() 修饰的函数来扩展 mcp_app/mcp_server.py 以增加更多工具。

CDK 栈组件

CDK 部署 (neo4j_sdk_runtime/neo4j_sdk_runtime_stack.py) 创建了

  • S3 代码资产 — mcp_app/ 与依赖项通过 uv 打包并上传至 S3

  • Secrets Manager 密钥 — 存储 Neo4j 连接凭据，值来源于 CDK 上下文 (cdk.json 或 -c 覆盖)

  • IAM 角色 — 提供 S3 代码访问、Secrets Manager、CloudWatch Logs、X-Ray、CloudWatch 指标和工作负载身份的权限

  • AgentCore `CfnRuntime` — 带有 MCP 协议、公共网络模式和 IAM 认证的基于代码的部署

环境变量

AgentCore 运行时配置如下

  • SECRET_ARN — 包含 Neo4j 凭据的 Secrets Manager 密钥的 ARN

  • AWS_DEFAULT_REGION — AWS 区域（显式设置为 AgentCore 兼容性）

Secrets Manager 密钥包含

  • NEO4J_URI — 数据库连接 URI（必填）

  • NEO4J_USERNAME — Neo4j 用户名（必填）

  • NEO4J_PASSWORD — Neo4j 密码（必填）

  • NEO4J_DATABASE — 数据库名称（可选，默认为 neo4j）

如何使用此示例

先决条件

  • 具备 Bedrock 和 AgentCore 访问权限的 AWS 账户

  • 配置了适当凭据的 AWS CLI

  • 已安装 AWS CDK (npm install -g aws-cdk)

  • Python 3.9+

第 1 步：克隆仓库

git clone https://github.com/neo4j-labs/neo4j-agent-integrations.git
cd neo4j-agent-integrations/aws-agentcore/samples/3-mcp-runtime-neo4j-sdk

第 2 步：安装依赖项

pip install -r requirements.txt

第 3 步：配置 Neo4j 凭据

Neo4j 连接凭据通过 CDK 上下文提供。默认值在 cdk.json 中提供

{
  "context": {
    "neo4j_uri": "neo4j+s://demo.neo4jlabs.com:7687",
     "neo4j_database": "companies",
     "neo4j_username": "companies",
     "neo4j_password": "companies"
  }
}

该示例默认使用公共公司演示数据库。要使用您自己的 Neo4j 实例，请编辑 cdk.json 中的值或在部署时覆盖它们

cdk deploy Neo4jSdkRuntimeStack \
  -c neo4j_uri=neo4j+s://your-instance:7687 \
  -c neo4j_database=neo4j \
  -c neo4j_username=neo4j \
  -c neo4j_password=your-password

第 4 步：部署基础设施

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy the stack
cdk deploy Neo4jSdkRuntimeStack

# Confirm the deployment when prompted

预期输出： 部署将输出

  • McpAppS3Bucket — 包含 MCP 应用程序部署包的 S3 存储桶

  • McpAppS3Key — 部署包的 S3 对象键

  • Neo4jSdkRuntimeArn — 已部署的 AgentCore 运行时的 ARN

  • AgentRuntimeRoleArn — 运行时的 IAM 角色 ARN

  • Neo4jSecretArn — Secrets Manager 密钥的 ARN

CDK 栈会自动

  • 将 mcp_app/ 与依赖项打包并上传到 S3

  • 使用 Neo4j 凭据创建 Secrets Manager 密钥

  • 创建具有必要权限的 IAM 角色

  • 创建并配置带有 MCP 协议、公共访问和 IAM 认证的 CfnRuntime

第 5 步：测试运行时

打开 demo.ipynb 并将 arn 变量设置为 CDK 输出中的 Neo4jSdkRuntimeArn，然后运行笔记本。它使用 mcp_proxy_for_aws 和 strands 通过 IAM 签名请求进行连接。

arn = "<Neo4jSdkRuntimeArn from CDK output>"

第 6 步：清理

# Destroy the CDK stack (removes the Runtime, IAM role, secret, and S3 assets)
cdk destroy Neo4jSdkRuntimeStack

参考资料

AWS 文档

Neo4j 资源

© . This site is unofficial and not affiliated with Neo4j, Inc.