Salta ai contenuti

Python MCP Server

Genera un server Python Model Context Protocol (MCP) per fornire contesto ai Large Language Model (LLM), e opzionalmente distribuiscilo su Amazon Bedrock AgentCore.

Il Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti AI di interagire con strumenti e risorse esterne. Fornisce un modo coerente per gli LLM di:

  • Eseguire strumenti (funzioni) che eseguono azioni o recuperano informazioni
  • Accedere a risorse che forniscono contesto o dati

Puoi generare un server MCP Python in due modi:

Esegui questo generatore@aws/nx-plugin:py#mcp-server

pnpm nx g @aws/nx-plugin:py#mcp-server
Componi il tuo comando6

Obbligatorio

infra = agentcore | agentcore-ecr

Opzioni del generatore6 opzioni
projectObbligatoriostring

Il progetto a cui aggiungere un server MCP

authenuminfra = agentcore | agentcore-ecrPredefinito: iam

Il metodo utilizzato per autenticare con il tuo server MCP. Applicabile solo quando infra è impostato (ignorato quando infra è none).

iamcognito
iacenumPredefinito: inherit

Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

inheritcdkterraform
infraenumPredefinito: agentcore

Il tipo di infrastruttura per ospitare il tuo server MCP. agentcore distribuisce il tuo codice come zip in un runtime gestito da AgentCore per il ciclo di build e deploy più veloce. agentcore-ecr costruisce e ospita un'immagine container invece, per il controllo a livello di sistema operativo o una pipeline container consolidata. Seleziona none per nessun hosting.

agentcoreagentcore-ecrnone
namestring

Il nome del tuo server MCP (predefinito: mcp-server)

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Il generatore aggiungerà i seguenti file al tuo progetto Python esistente:

  • Directoryyour-project/
    • Directoryyour_module/
      • Directorymcp_server/ (o nome personalizzato se specificato)
        • __init__.py Inizializzazione del pacchetto Python
        • server.py Definizione principale del server con strumenti e risorse di esempio
        • stdio.py Punto di ingresso per il trasporto STDIO, utile per server MCP locali semplici
        • http.py Punto di ingresso per il trasporto HTTP Streamable, utile per l’hosting del tuo server MCP
        • Dockerfile Definizione dell’immagine del container (solo quando infra è agentcore-ecr)
    • pyproject.toml Aggiornato con le dipendenze MCP
    • project.json Aggiornato con i target di serve del server MCP

L’opzione infra seleziona come il tuo codice viene impacchettato e ospitato su Amazon Bedrock AgentCore Runtime:

  • agentcore (predefinito) utilizza il deployment diretto del codice: il tuo codice compilato viene impacchettato come un file .zip, caricato su S3 ed eseguito su un runtime del linguaggio gestito da AgentCore. Non c’è alcuna immagine container da costruire, nessun repository ECR da gestire e nessuna immagine da inviare, il che rende il ciclo di build e deploy sostanzialmente più veloce.
  • agentcore-ecr costruisce un’immagine container arm64 da un Dockerfile fornito e la ospita dal registro condiviso core/asset-ecr, insieme a tutti gli altri container nel workspace. Scegli questa opzione quando hai bisogno di controllare l’immagine del sistema operativo — ad esempio per installare librerie di sistema native — o quando hai una pipeline di container consolidata. Questa opzione fornisce inoltre un target di scansione immagini Trivy (vedi Image Scanning di seguito).
  • none non genera alcuna infrastruttura, quindi il progetto può essere eseguito solo localmente.
infra = agentcore | agentcore-ecr

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

  • Directorypackages/common/constructs
    • Directorysrc
      • Directoryapp/ Constructs for infrastructure specific to a project/generator
      • Directorycore/ Generic constructs which are reused by constructs in app
      • index.ts Entry point exporting constructs from app
    • project.json Project build targets and configuration

Per il deployment del tuo MCP Server, vengono generati i seguenti file:

  • Directorypackages/common/constructs/src
    • Directoryapp
      • Directorymcp-servers
        • Directory<mcp-server-name>
          • <mcp-server-name>.ts CDK construct for deploying your MCP Server
infra = none

Se hai selezionato none per infra, non vengono generati costrutti CDK o moduli Terraform — il server MCP è configurato solo per l’uso locale STDIO / HTTP. L’opzione auth viene ignorata in questa modalità poiché non esiste un endpoint ospitato da autenticare.

Quando viene distribuito su Bedrock AgentCore Runtime, il codice del tuo server viene impacchettato come zip ed eseguito nel runtime gestito di AgentCore. Gli assistenti AI invocano l’endpoint del data plane di AgentCore Runtime, che inoltra le chiamate tools/* e resources/* al tuo server tramite il trasporto HTTP streamable.

Loading the diagram…

Gli strumenti sono funzioni che l’assistente AI può chiamare per eseguire azioni. Il server MCP Python utilizza la libreria MCP Python SDK (FastMCP), che fornisce un approccio semplice basato su decoratori per definire gli strumenti.

Puoi aggiungere nuovi strumenti nel file server.py:

@mcp.tool(description="Your tool description")
def your_tool_name(param1: str, param2: int) -> str:
"""Tool implementation with type hints"""
# Your tool logic here
return f"Result: {param1} with {param2}"

La libreria FastMCP gestisce automaticamente:

  • Validazione dei tipi basata sui type hint della tua funzione
  • Generazione dello schema JSON per il protocollo MCP
  • Gestione degli errori e formattazione delle risposte

Le risorse forniscono contesto all’assistente AI. Puoi aggiungere risorse utilizzando il decoratore @mcp.resource:

@mcp.resource("example://static-resource", description="Static resource example")
def static_resource() -> str:
"""Return static content"""
return "This is static content that provides context to the AI"
@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
def dynamic_resource(item_id: str) -> str:
"""Return dynamic content based on parameters"""
# Fetch data based on item_id
data = fetch_data_for_item(item_id)
return f"Dynamic content for {item_id}: {data}"

La maggior parte degli assistenti AI che supportano MCP utilizza un approccio di configurazione simile. Dovrai creare o aggiornare un file di configurazione con i dettagli del tuo server MCP:

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

Consulta la seguente documentazione per configurare MCP con specifici Assistenti AI:

Per eseguire il tuo server MCP (e tutto ciò che è connesso ad esso, come un database locale) localmente, utilizza il target dev del progetto:

Terminal window
pnpm nx dev your-project

Se hai aggiunto più componenti al tuo progetto (server MCP, agenti, ecc.), questo li avvia tutti. Per eseguire solo questo server MCP, utilizza il suo target <your-server-name>-dev:

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

Il generatore configura un target denominato <your-server-name>-inspect, che avvia il tuo server MCP localmente (tramite il target <your-server-name>-dev, incluse eventuali dipendenze connesse come un database locale) e lancia l’MCP Inspector preconfigurato per connettersi ad esso tramite trasporto HTTP Streamable.

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

Questo avvierà l’inspector su http://localhost:6274. Inizia cliccando sul pulsante “Connect”.

Il modo più semplice per testare e utilizzare un server MCP è utilizzare l’inspector o configurarlo con un assistente AI (come sopra).

Puoi tuttavia eseguire il tuo server con trasporto STDIO direttamente utilizzando il target <your-server-name>-serve-stdio.

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

Questo comando utilizza uv run per eseguire il tuo server MCP con trasporto STDIO.

Se desideri eseguire il tuo server MCP localmente utilizzando trasporto HTTP Streamable, puoi utilizzare il target <your-server-name>-serve.

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

Questo comando utilizza uv run uvicorn --reload per eseguire il tuo server MCP con trasporto HTTP, e si riavvia automaticamente quando i file cambiano.

Ogni server MCP viene assegnato alla propria porta, a partire da 8000, in modo che diversi server possano essere eseguiti fianco a fianco nello stesso workspace. Leggi la porta su cui il tuo server è in ascolto dal suo target <your-server-name>-serve in project.json.

infra = agentcore | agentcore-ecr

Distribuire il Tuo Server MCP su Bedrock AgentCore Runtime

Sezione intitolata “Distribuire il Tuo Server MCP su Bedrock AgentCore Runtime”

Se hai selezionato agentcore o agentcore-ecr per infra, viene generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo server MCP su Amazon Bedrock AgentCore Runtime.

Viene generato un costrutto CDK per il tuo server MCP, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>McpServer per impostazione predefinita.

Puoi utilizzare questo costrutto CDK in un’applicazione CDK:

import { MyProjectMcpServer } from '@my-scope/common-constructs';
export class ExampleStack extends Stack {
constructor(scope: Construct, id: string) {
// Add the MCP server to your stack
new MyProjectMcpServer(this, 'MyProjectMcpServer');
}
}

Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo server MCP. Puoi scegliere tra autenticazione IAM (predefinita) o Cognito durante la generazione del tuo server MCP.

Per impostazione predefinita, il tuo server MCP sarà protetto utilizzando l’autenticazione IAM, semplicemente distribuiscilo senza alcun argomento:

import { MyProjectMcpServer } from '@my-scope/common-constructs';
export class ExampleStack extends Stack {
constructor(scope: Construct, id: string) {
new MyProjectMcpServer(this, 'MyProjectMcpServer');
}
}

Puoi concedere l’accesso per invocare il tuo server MCP su Bedrock AgentCore Runtime utilizzando il metodo grantInvokeAccess. Ad esempio, potresti desiderare che un agente generato con il generatore py#agent chiami il tuo server 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);
}
}

Quando selezioni l’autenticazione Cognito, il generatore configura il server MCP per utilizzare Cognito per l’autenticazione.

Il costrutto generato accetta una prop identity che configura l’autenticazione 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,
});
}
}

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

Per costruire il tuo server MCP per Bedrock AgentCore Runtime, viene aggiunto un target bundle al tuo progetto, che:

  • Esporta le tue dipendenze Python in un file requirements.txt utilizzando uv export
  • Installa le dipendenze per la piattaforma di destinazione (aarch64-manylinux_2_28) utilizzando uv pip install
infra = agentcore

Viene anche aggiunto un target <your-server-name>-package, che assembla il pacchetto di codice distribuibile: il bundle di dipendenze aarch64, l’albero del modulo Python e un punto di ingresso main.py radice. L’infrastruttura generata carica questa directory come .zip — tramite AgentRuntimeArtifact.fromCodeAsset sotto CDK, o archiviata nel bucket di asset condiviso sotto Terraform.

infra = agentcore-ecr

Viene anche aggiunto un target docker specifico per il tuo server MCP, che copia il Dockerfile e gli artefatti raggruppati in una directory di contesto docker. Questo co-localizza il Dockerfile con l’output costruito, consentendo a CDK di costruire l’immagine Docker direttamente utilizzando AgentRuntimeArtifact.fromAsset.

L’immagine Docker costruita per questo progetto può essere scansionata per vulnerabilità utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.

Un target trivy viene aggiunto al tuo progetto che scansiona l’immagine costruita ed esce con codice diverso da zero se viene trovata qualsiasi vulnerabilità di gravità HIGH o CRITICAL. Il Dockerfile generato utilizza un’immagine base senza vulnerabilità risolvibili note di queste gravità al momento della generazione, e aggiorna gli strumenti inclusi (come npm) per mantenerla tale.

La scansione utilizza lo stesso motore container della tua build dell’immagine (docker o finch), quindi non sono richiesti strumenti aggiuntivi. La scansione non è memorizzata in cache, poiché l’immagine che legge risiede nel motore container anziché su disco — quindi scansiona sempre l’immagine reale e fallisce in modo evidente anziché riportare un successo memorizzato in cache per un’immagine che non è più presente. Ogni esecuzione richiede quindi decine di secondi per immagine e aggiorna il database delle vulnerabilità di Trivy, quindi necessita di accesso alla rete. Lo script root trivy fornito scansiona ogni immagine nel workspace:

Terminal window
pnpm trivy

Potrebbero esserci casi in cui desideri sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e hai valutato il rischio come accettabile.

Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella root del tuo progetto (cioè accanto al tuo project.json):

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

Per maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.

Il tuo server MCP è configurato automaticamente con l’osservabilità utilizzando AWS Distro for Open Telemetry (ADOT), configurando l’auto-strumentazione nel tuo Dockerfile.

Puoi trovare le tracce nella Console AWS CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.

Per maggiori dettagli, consulta la documentazione AgentCore sull’osservabilità.

Utilizza il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsPythonModel Context Protocol
Python Agent to MCPConnect a Python Agent to an MCP server
Model Context ProtocolPythonAmazon DynamoDBPython
Python MCP Server to Python DynamoDBConnect a Python MCP Server to a DynamoDB table
Amazon Bedrock AgentCore GatewayModel Context Protocol
AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway