Implementare l'API del Gioco e il server MCP dell'Inventario

Task 1: Implementare la Game API

Implementeremo le seguenti API in questa sezione:

1. saveGame - crea o aggiorna un gioco.
2. queryGames - restituisce una lista paginata di giochi salvati precedentemente.
3. queryInventory - restituisce una lista paginata degli oggetti nell’inventario di un giocatore.
4. queryActions - restituisce la cronologia delle conversazioni per un dato gioco.

Dove risiede ogni pezzo di stato

• games e inventory sono in DynamoDB (tramite ElectroDB) — le lambda della Game API e il server MCP dell’Inventario li leggono/scrivono.
• actions (trascrizione della chat) è in S3 — l’S3SessionManager dello Story Agent scrive un blob JSON per turno, e queryActions nella Game API li legge in modo che l’UI possa riprodurre la cronologia al ricaricamento della pagina. Non esiste una procedura saveAction; l’agente è l’unico scrittore.

Schema dell’API

Per definire gli input e gli output della nostra API, creiamo il nostro schema utilizzando Zod nel file packages/game-api/src/schema/index.ts come segue:

+

import { z } from 'zod';

export const QueryInputSchema = z.object({
  cursor: z.string().optional(),
  limit: z.number().optional().default(100),
});
export type IQueryInput = z.TypeOf<typeof QueryInputSchema>;

export const ActionSchema = z.object({
  role: z.enum(['user', 'assistant']),
  content: z.string(),
  messageId: z.number(),
});
export type IAction = z.TypeOf<typeof ActionSchema>;

export const GameSchema = z.object({
  playerName: z.string(),
  genre: z.enum(['zombie', 'superhero', 'medieval']),
  lastUpdated: z.iso.datetime(),
});
export type IGame = z.TypeOf<typeof GameSchema>;

export const ItemSchema = z.object({
  playerName: z.string(),
  itemName: z.string(),
  emoji: z.string().optional(),
  lastUpdated: z.iso.datetime(),
  quantity: z.number(),
});
export type IItem = z.TypeOf<typeof ItemSchema>;

export const createPaginatedQueryOutput = <ItemType extends z.ZodTypeAny>(
  itemSchema: ItemType,
) => {
  return z.object({
    items: z.array(itemSchema),
    cursor: z.string().nullable(),
  });
};

+-

export * from './echo.js'
import { z } from 'zod';

export const QueryInputSchema = z.object({
  cursor: z.string().optional(),
  limit: z.number().optional().default(100),
});
export type IQueryInput = z.TypeOf<typeof QueryInputSchema>;

export const ActionSchema = z.object({
  role: z.enum(['user', 'assistant']),
  content: z.string(),
  messageId: z.number(),
});
export type IAction = z.TypeOf<typeof ActionSchema>;

export const GameSchema = z.object({
  playerName: z.string(),
  genre: z.enum(['zombie', 'superhero', 'medieval']),
  lastUpdated: z.iso.datetime(),
});
export type IGame = z.TypeOf<typeof GameSchema>;

export const ItemSchema = z.object({
  playerName: z.string(),
  itemName: z.string(),
  emoji: z.string().optional(),
  lastUpdated: z.iso.datetime(),
  quantity: z.number(),
});
export type IItem = z.TypeOf<typeof ItemSchema>;

export const createPaginatedQueryOutput = <ItemType extends z.ZodTypeAny>(
  itemSchema: ItemType,
) => {
  return z.object({
    items: z.array(itemSchema),
    cursor: z.string().nullable(),
  });
};

Elimina il file packages/game-api/src/schema/echo.ts poiché non lo utilizzeremo in questo progetto.

Inferenza automatica dei tipi

Per ognuno degli schemi che definiamo in Zod, esportiamo anche un’interfaccia utilizzando la sintassi z.TypeOf. Questo converte la nostra definizione Zod in un’interfaccia TypeScript senza duplicare gli sforzi.

Modellazione delle entità

Questo è il diagramma ER per la nostra applicazione.

Implementeremo il nostro database in DynamoDB e utilizzeremo la libreria client ElectroDB per semplificare le operazioni. Il queryActions della Game API necessita anche del client S3 per leggere i turni di conversazione che l’agente ha scritto. Installali tutti con:

pnpm

pnpm add -w electrodb@3.7.5 @aws-sdk/client-dynamodb@3.1053.0 @aws-sdk/client-s3@3.1053.0

yarn

yarn add electrodb@3.7.5 @aws-sdk/client-dynamodb@3.1053.0 @aws-sdk/client-s3@3.1053.0

npm

npm install --legacy-peer-deps electrodb@3.7.5 @aws-sdk/client-dynamodb@3.1053.0 @aws-sdk/client-s3@3.1053.0

bun

bun install electrodb@3.7.5 @aws-sdk/client-dynamodb@3.1053.0 @aws-sdk/client-s3@3.1053.0

Dipendenze root

Tutte le dipendenze vengono aggiunte al file package.json principale poiché @aws/nx-plugin segue il principio della single version policy. Per maggiori informazioni, consulta la guida ts#project.

Per definire le entità ElectroDB dal diagramma ER, creiamo il file packages/game-api/src/entities/index.ts:

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

/**
 * Resolves the DynamoDB table name from runtime config (AppConfig).
 */
const resolveTableName = async (): Promise<string> => {
  const tablesConfig = await getAppConfig('tables', {
    application: process.env.RUNTIME_CONFIG_APP_ID!,
    environment: 'default',
    transform: 'json',
  });

  const tableName = (tablesConfig as Record<string, any>).ElectroDbTable?.tableName;
  if (!tableName) {
    throw new Error(
      'Could not resolve table name from runtime config',
    );
  }
  return tableName;
};

export const createGameEntity = async (client: DynamoDBClient = new DynamoDBClient()) =>
  new Entity(
    {
      model: {
        entity: 'Game',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        genre: { type: 'string', required: true, readOnly: true },
        lastUpdated: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
        },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: {
            field: 'sk',
            composite: [],
          },
        },
      },
    },
    { client, table: await resolveTableName() },
  );

export const createInventoryEntity = async (client: DynamoDBClient = new DynamoDBClient()) =>
  new Entity(
    {
      model: {
        entity: 'Inventory',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        lastUpdated: {
          type: 'string',
          required: true,
          default: () => new Date().toISOString(),
        },
        itemName: {
          type: 'string',
          required: true,
        },
        emoji: {
          type: 'string',
          required: false,
        },
        quantity: {
          type: 'number',
          required: true,
        },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: { field: 'sk', composite: ['itemName'] },
        },
      },
    },
    { client, table: await resolveTableName() },
  );

ElectroDB ci permette non solo di definire i nostri tipi, ma può anche fornire valori predefiniti per certi campi come i timestamp. Inoltre, ElectroDB segue il single-table design, che è la best practice quando si utilizza DynamoDB.

Collezioni ElectroDB

Sebbene ElectroDB supporti le collections, in questo tutorial abbiamo scelto di non utilizzarle per semplicità.

Per preparare il server MCP a interagire con l’inventario, assicuriamoci di esportare l’entità dell’inventario in packages/game-api/src/index.ts:

packages/game-api/src/index.ts

export type { AppRouter } from './router.js';
export { appRouter } from './router.js';
export type { Context } from './init.js';
export * from './client/index.js';
export * from './schema/index.js';
export * from './entities/index.js';

Struttura del pacchetto

La struttura del pacchetto sarebbe migliore se rifattorizzassimo le entità in un progetto condiviso separato, in modo che il server MCP non debba dipendere dall’API.

Definizione delle procedure

Per implementare i metodi dell’API, apporta le seguenti modifiche in packages/game-api/src/procedures:

games.ts

import { createGameEntity } from '../entities/index.js';
import {
  GameSchema,
  IGame,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from '../schema/index.js';
import { publicProcedure } from '../init.js';

export const queryGames = publicProcedure
  .input(QueryInputSchema)
  .output(createPaginatedQueryOutput(GameSchema))
  .query(async ({ input }) => {
    const gameEntity = await createGameEntity();
    const result = await gameEntity.scan.go({
      cursor: input.cursor,
      count: input.limit,
    });

    return {
      items: result.data as IGame[],
      cursor: result.cursor,
    };
  });

export const saveGame = publicProcedure
  .input(GameSchema.omit({ lastUpdated: true }))
  .output(GameSchema)
  .mutation(async ({ input }) => {
    const gameEntity = await createGameEntity();

    const result = await gameEntity.put(input).go();
    return result.data as IGame;
  });

inventory.ts

import {
  ItemSchema,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from '../schema/index.js';
import { publicProcedure } from '../init.js';
import { z } from 'zod';
import { createInventoryEntity } from '../entities/index.js';

export const queryInventory = publicProcedure
  .input(QueryInputSchema.extend({ playerName: z.string() }))
  .output(createPaginatedQueryOutput(ItemSchema))
  .query(async ({ input }) => {
    const inventoryEntity = await createInventoryEntity();
    const result = await inventoryEntity.query
      .primary({ playerName: input.playerName })
      .go({ cursor: input.cursor, count: input.limit });

    return {
      items: result.data,
      cursor: result.cursor,
    };
  });

actions.ts

import { publicProcedure } from '../init.js';
import { ActionSchema, IAction } from '../schema/index.js';
import { z } from 'zod';
import {
  S3Client,
  ListObjectsV2Command,
  GetObjectCommand,
} from '@aws-sdk/client-s3';
import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
import { readFile, readdir } from 'node:fs/promises';
import { join, resolve } from 'node:path';

const resolveSessionsBucket = async (): Promise<string> => {
  const buckets = await getAppConfig('buckets', {
    application: process.env.RUNTIME_CONFIG_APP_ID!,
    environment: 'default',
    transform: 'json',
  });
  const bucket = (buckets as Record<string, any>).StorySessions?.bucketName;
  if (!bucket)
    throw new Error('StorySessions bucket not found in runtime config');
  return bucket;
};

const s3 = new S3Client();
const LOCAL_SESSION_STORAGE_DIR = '/tmp/strands-sessions';

// Matches ``session_<sessionId>/agents/agent_<agentId>/messages/message_<idx>.json``
// written by ``strands.session.S3SessionManager`` on the agent side. We only
// ever care about the default agent id ``default`` that Strands uses when
// none is set explicitly, so hard-code the path prefix the UI needs to list.
const messagesPrefix = (sessionId: string) =>
  `session_${sessionId}/agents/agent_default/messages/`;

const messageIndex = (pathOrKey: string): number => {
  const match = pathOrKey.match(/message_(\d+)\.json$/);
  return match ? Number(match[1]) : Number.MAX_SAFE_INTEGER;
};

const toAction = (body: any): IAction | undefined => {
  const message = body.redact_message ?? body.message;
  const role = message?.role;
  if (role !== 'user' && role !== 'assistant') return undefined;
  const text = Array.isArray(message.content)
    ? message.content
        .filter((b: any) => typeof b?.text === 'string')
        .map((b: any) => b.text)
        .join('')
    : String(message.content ?? '');
  if (!text) return undefined;
  return { role, content: text, messageId: body.message_id };
};

const readLocalActions = async (sessionId: string): Promise<IAction[]> => {
  const baseDir = resolve(LOCAL_SESSION_STORAGE_DIR);
  const messagesDir = resolve(baseDir, messagesPrefix(sessionId));
  if (!messagesDir.startsWith(`${baseDir}/`)) {
    throw new Error('Invalid session id');
  }

  let files: string[];
  try {
    files = await readdir(messagesDir);
  } catch (error: any) {
    if (error?.code === 'ENOENT') return [];
    throw error;
  }

  const actions: IAction[] = [];
  for (const file of files
    .filter((f) => f.endsWith('.json'))
    .sort((a, b) => messageIndex(a) - messageIndex(b))) {
    const body = JSON.parse(await readFile(join(messagesDir, file), 'utf8'));
    const action = toAction(body);
    if (action) actions.push(action);
  }
  return actions;
};

const readS3Actions = async (sessionId: string): Promise<IAction[]> => {
  const bucket = await resolveSessionsBucket();
  const list = await s3.send(
    new ListObjectsV2Command({
      Bucket: bucket,
      Prefix: messagesPrefix(sessionId),
    }),
  );
  const keys = (list.Contents ?? [])
    .map((o) => o.Key!)
    .filter((k) => k.endsWith('.json'))
    .sort((a, b) => messageIndex(a) - messageIndex(b));

  const actions: IAction[] = [];
  for (const key of keys) {
    const obj = await s3.send(
      new GetObjectCommand({ Bucket: bucket, Key: key }),
    );
    const body = JSON.parse(await obj.Body!.transformToString());
    const action = toAction(body);
    if (action) actions.push(action);
  }
  return actions;
};

export const queryActions = publicProcedure
  .input(z.object({ sessionId: z.string() }))
  .output(z.object({ items: z.array(ActionSchema) }))
  .query(async ({ input }) => {
    const actions =
      process.env.SERVE_LOCAL === 'true'
        ? await readLocalActions(input.sessionId)
        : await readS3Actions(input.sessionId);
    return { items: actions };
  });

Elimina il file echo.ts (da packages/game-api/src/procedures) poiché non lo utilizzeremo in questo progetto.

Configurazione del router

Dopo aver definito le nostre procedure, per collegarle alla nostra API, aggiorna il seguente file:

packages/game-api/src/router.ts

+

import { t } from './init.js';
import { queryActions } from './procedures/actions.js';
import { queryGames, saveGame } from './procedures/games.js';
import { queryInventory } from './procedures/inventory.js';

export const router = t.router;

export const appRouter = router({
  actions: router({
    query: queryActions,
  }),
  games: router({
    query: queryGames,
    save: saveGame,
  }),
  inventory: router({
    query: queryInventory,
  }),
});

export type AppRouter = typeof appRouter;

+-

import { echo } from './procedures/echo.js';
import { t } from './init.js';
import { queryActions } from './procedures/actions.js';
import { queryGames, saveGame } from './procedures/games.js';
import { queryInventory } from './procedures/inventory.js';

export const router = t.router;

export const appRouter = router({
  echo,
  actions: router({
    query: queryActions,
  }),
  games: router({
    query: queryGames,
    save: saveGame,
  }),
  inventory: router({
    query: queryInventory,
  }),
});

export type AppRouter = typeof appRouter;

Task 2: Creare un server MCP per l’inventario

Creiamo un server MCP che permetterà al nostro agente di gestire gli oggetti nell’inventario di un giocatore.

Definiremo i seguenti strumenti per il nostro agente:

• list-inventory-items per recuperare gli oggetti correnti nell’inventario del giocatore
• add-to-inventory per aggiungere oggetti all’inventario del giocatore
• remove-from-inventory per rimuovere oggetti dall’inventario del giocatore

Per risparmiare tempo, definiremo tutti gli strumenti inline:

packages/inventory/src/mcp-server/server.ts

+

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import z from 'zod';
import { createInventoryEntity } from ':dungeon-adventure/game-api';

/**
 * Create the MCP Server
 */
export const createServer = async () => {
  const server = new McpServer({
    name: 'inventory-mcp-server',
    version: '1.0.0',
  });

  server.registerTool(
    'list-inventory-items',
    {
      description: "List items in the player's inventory. Leave cursor blank unless you are requesting subsequent pages",
      inputSchema: {
        playerName: z.string(),
        cursor: z.string().optional(),
      },
    },
    async ({ playerName }) => {
      const inventory = await createInventoryEntity();
      const results = await inventory.query
        .primary({
          playerName,
        })
        .go();

      return {
        content: [{ type: 'text' as const, text: JSON.stringify(results) }],
      };
    },
  );

  server.registerTool(
    'add-to-inventory',
    {
      description: "Add an item to the player's inventory. Quantity defaults to 1 if omitted.",
      inputSchema: {
        playerName: z.string(),
        itemName: z.string(),
        emoji: z.string(),
        quantity: z.number().optional().default(1),
      },
    },
    async ({ playerName, itemName, emoji, quantity = 1 }) => {
      const inventory = await createInventoryEntity();
      await inventory
        .put({
          playerName,
          itemName,
          quantity,
          emoji,
        })
        .go();

      return {
        content: [
          {
            type: 'text' as const,
            text: `Added ${itemName} (x${quantity}) to inventory`,
          },
        ],
      };
    },
  );

  server.registerTool(
    'remove-from-inventory',
    {
      description: "Remove an item from the player's inventory. If quantity is omitted, all items are removed.",
      inputSchema: {
        playerName: z.string(),
        itemName: z.string(),
        quantity: z.number().optional(),
      },
    },
    async ({ playerName, itemName, quantity }) => {
      const inventory = await createInventoryEntity();

      // If quantity is omitted, remove the entire item
      if (quantity === undefined) {
        try {
          await inventory.delete({ playerName, itemName }).go();
          return {
            content: [
              { type: 'text' as const, text: `${itemName} removed from inventory.` },
            ],
          };
        } catch {
          return {
            content: [
              { type: 'text' as const, text: `${itemName} not found in inventory` },
            ],
          };
        }
      }

      // If quantity is specified, fetch current quantity and update
      const item = await inventory.get({ playerName, itemName }).go();

      if (!item.data) {
        return {
          content: [
            { type: 'text' as const, text: `${itemName} not found in inventory` },
          ],
        };
      }

      const newQuantity = item.data.quantity - quantity;

      if (newQuantity <= 0) {
        await inventory.delete({ playerName, itemName }).go();
        return {
          content: [
            { type: 'text' as const, text: `${itemName} removed from inventory.` },
          ],
        };
      }

      await inventory
        .put({
          playerName,
          itemName,
          quantity: newQuantity,
          emoji: item.data.emoji,
        })
        .go();

      return {
        content: [
          {
            type: 'text' as const,
            text: `Removed ${itemName} (x${quantity}) from inventory. ${newQuantity} remaining.`,
          },
        ],
      };
    },
  );

  return server;
};

+-

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerDivideTool } from './tools/divide.js';
import { registerSampleGuidanceResource } from './resources/sample-guidance.js';
import z from 'zod';
import { createInventoryEntity } from ':dungeon-adventure/game-api';

/**
 * Create the MCP Server
 */
export const createServer = async () => {
  const server = new McpServer({
    name: 'inventory-mcp-server',
    version: '1.0.0',
  });

  registerDivideTool(server);
  registerSampleGuidanceResource(server);
  server.registerTool(
    'list-inventory-items',
    {
      description: "List items in the player's inventory. Leave cursor blank unless you are requesting subsequent pages",
      inputSchema: {
        playerName: z.string(),
        cursor: z.string().optional(),
      },
    },
    async ({ playerName }) => {
      const inventory = await createInventoryEntity();
      const results = await inventory.query
        .primary({
          playerName,
        })
        .go();

      return {
        content: [{ type: 'text' as const, text: JSON.stringify(results) }],
      };
    },
  );

  server.registerTool(
    'add-to-inventory',
    {
      description: "Add an item to the player's inventory. Quantity defaults to 1 if omitted.",
      inputSchema: {
        playerName: z.string(),
        itemName: z.string(),
        emoji: z.string(),
        quantity: z.number().optional().default(1),
      },
    },
    async ({ playerName, itemName, emoji, quantity = 1 }) => {
      const inventory = await createInventoryEntity();
      await inventory
        .put({
          playerName,
          itemName,
          quantity,
          emoji,
        })
        .go();

      return {
        content: [
          {
            type: 'text' as const,
            text: `Added ${itemName} (x${quantity}) to inventory`,
          },
        ],
      };
    },
  );

  server.registerTool(
    'remove-from-inventory',
    {
      description: "Remove an item from the player's inventory. If quantity is omitted, all items are removed.",
      inputSchema: {
        playerName: z.string(),
        itemName: z.string(),
        quantity: z.number().optional(),
      },
    },
    async ({ playerName, itemName, quantity }) => {
      const inventory = await createInventoryEntity();

      // If quantity is omitted, remove the entire item
      if (quantity === undefined) {
        try {
          await inventory.delete({ playerName, itemName }).go();
          return {
            content: [
              { type: 'text' as const, text: `${itemName} removed from inventory.` },
            ],
          };
        } catch {
          return {
            content: [
              { type: 'text' as const, text: `${itemName} not found in inventory` },
            ],
          };
        }
      }

      // If quantity is specified, fetch current quantity and update
      const item = await inventory.get({ playerName, itemName }).go();

      if (!item.data) {
        return {
          content: [
            { type: 'text' as const, text: `${itemName} not found in inventory` },
          ],
        };
      }

      const newQuantity = item.data.quantity - quantity;

      if (newQuantity <= 0) {
        await inventory.delete({ playerName, itemName }).go();
        return {
          content: [
            { type: 'text' as const, text: `${itemName} removed from inventory.` },
          ],
        };
      }

      await inventory
        .put({
          playerName,
          itemName,
          quantity: newQuantity,
          emoji: item.data.emoji,
        })
        .go();

      return {
        content: [
          {
            type: 'text' as const,
            text: `Removed ${itemName} (x${quantity}) from inventory. ${newQuantity} remaining.`,
          },
        ],
      };
    },
  );

  return server;
};

Man mano che il numero di strumenti cresce, puoi eventualmente rifattorizzarli in file separati.

Elimina le directory tools e resources in packages/inventory/src/mcp-server poiché non verranno utilizzate.

Task 3: Aggiornare l’infrastruttura

Il passo finale è aggiornare la nostra infrastruttura per creare la tabella DynamoDB e concedere i permessi per eseguire operazioni dalla Game API. Per farlo, aggiorna packages/infra/src come segue:

constructs/electrodb-table.ts

import { CfnOutput } from 'aws-cdk-lib';
import {
  AttributeType,
  BillingMode,
  ProjectionType,
  Table,
  TableProps,
} from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
import { suppressRules } from ':dungeon-adventure/common-constructs';

export type ElectrodbDynamoTableProps = Omit<
  TableProps,
  'partitionKey' | 'sortKey' | 'billingMode'
>;

export class ElectrodbDynamoTable extends Table {
  constructor(scope: Construct, id: string, props?: ElectrodbDynamoTableProps) {
    super(scope, id, {
      partitionKey: {
        name: 'pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'sk',
        type: AttributeType.STRING,
      },
      billingMode: BillingMode.PAY_PER_REQUEST,
      ...props,
    });

    this.addGlobalSecondaryIndex({
      indexName: 'gsi1pk-gsi1sk-index',
      partitionKey: {
        name: 'gsi1pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'gsi1sk',
        type: AttributeType.STRING,
      },
      projectionType: ProjectionType.ALL,
    });

    // Suppress checkov rules that expect a KMS customer managed key and backup to be enabled
    suppressRules(this, ['CKV_AWS_119', 'CKV_AWS_28'], 'No need for custom encryption or backup');

    new CfnOutput(this, 'TableName', { value: this.tableName });
  }
}

stacks/application-stack.ts

+

import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  RuntimeConfig,
  StoryAgent,
  UserIdentity,
  suppressRules,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import {
  BlockPublicAccess,
  Bucket,
  BucketEncryption,
} from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
import { ElectrodbDynamoTable } from '../constructs/electrodb-table.js';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const rc = RuntimeConfig.ensure(this);

    const userIdentity = new UserIdentity(this, 'UserIdentity');

    const electroDbTable = new ElectrodbDynamoTable(this, 'ElectroDbTable');

    // Register the table name in runtime config 'tables' namespace
    rc.set('tables', 'ElectroDbTable', {
      tableName: electroDbTable.tableName,
    });

    // S3 bucket for Strands conversation history. The Story Agent writes each
    // turn via ``S3SessionManager``; the Game API reads them back for replay.
    const storySessions = new Bucket(this, 'StorySessions', {
      encryption: BucketEncryption.S3_MANAGED,
      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
      enforceSSL: true,
      removalPolicy: RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });
    suppressRules(
      storySessions,
      ['CKV_AWS_18', 'CKV_AWS_21'],
      'Access logging and object versioning are unnecessary for ephemeral chat transcripts',
    );
    rc.set('buckets', 'StorySessions', {
      bucketName: storySessions.bucketName,
    });

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
    });

    electroDbTable.grantReadData(gameApi.integrations['games.query'].handler);
    electroDbTable.grantReadData(
      gameApi.integrations['inventory.query'].handler,
    );
    electroDbTable.grantReadWriteData(
      gameApi.integrations['games.save'].handler,
    );
    storySessions.grantRead(gameApi.integrations['actions.query'].handler);

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');
    electroDbTable.grantReadWriteData(mcpServer.agentCoreRuntime);

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      identity: userIdentity,
    });
    storySessions.grantReadWrite(storyAgent);

    new CfnOutput(this, 'StoryAgentArn', {
      value: storyAgent.agentCoreRuntime.agentRuntimeArn,
    });
    new CfnOutput(this, 'InventoryMcpArn', {
      value: mcpServer.agentCoreRuntime.agentRuntimeArn,
    });

    // Grant the agent permissions to invoke our mcp server
    mcpServer.grantInvokeAccess(storyAgent);

    // Grant the authenticated role access to invoke the api
    gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);

    new GameUI(this, 'GameUI');
  }
}

+-

import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  RuntimeConfig,
  StoryAgent,
  UserIdentity,
  suppressRules,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import {
  BlockPublicAccess,
  Bucket,
  BucketEncryption,
} from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
import { ElectrodbDynamoTable } from '../constructs/electrodb-table.js';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const rc = RuntimeConfig.ensure(this);

    const userIdentity = new UserIdentity(this, 'UserIdentity');

    const electroDbTable = new ElectrodbDynamoTable(this, 'ElectroDbTable');

    // Register the table name in runtime config 'tables' namespace
    rc.set('tables', 'ElectroDbTable', {
      tableName: electroDbTable.tableName,
    });

    // S3 bucket for Strands conversation history. The Story Agent writes each
    // turn via ``S3SessionManager``; the Game API reads them back for replay.
    const storySessions = new Bucket(this, 'StorySessions', {
      encryption: BucketEncryption.S3_MANAGED,
      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
      enforceSSL: true,
      removalPolicy: RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });
    suppressRules(
      storySessions,
      ['CKV_AWS_18', 'CKV_AWS_21'],
      'Access logging and object versioning are unnecessary for ephemeral chat transcripts',
    );
    rc.set('buckets', 'StorySessions', {
      bucketName: storySessions.bucketName,
    });

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
    });

    electroDbTable.grantReadData(gameApi.integrations['games.query'].handler);
    electroDbTable.grantReadData(
      gameApi.integrations['inventory.query'].handler,
    );
    electroDbTable.grantReadWriteData(
      gameApi.integrations['games.save'].handler,
    );
    storySessions.grantRead(gameApi.integrations['actions.query'].handler);

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');
    electroDbTable.grantReadWriteData(mcpServer.agentCoreRuntime);

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      identity: userIdentity,
    });
    storySessions.grantReadWrite(storyAgent);

    new CfnOutput(this, 'StoryAgentArn', {
      value: storyAgent.agentCoreRuntime.agentRuntimeArn,
    });
    new CfnOutput(this, 'InventoryMcpArn', {
      value: mcpServer.agentCoreRuntime.agentRuntimeArn,
    });

    // Grant the agent permissions to invoke our mcp server
    mcpServer.grantInvokeAccess(storyAgent);

    // Grant the authenticated role access to invoke the api
    gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);

    new GameUI(this, 'GameUI');
  }
}

Procedure isolate

Nota qui che poiché ogni procedura è gestita da una singola funzione lambda, possiamo seguire il principio del minimo privilegio e assegnare solo i permessi di lettura/scrittura necessari in base all’implementazione della procedura.

Configurazione Runtime

Il nome della tabella DynamoDB è registrato nella Configurazione Runtime sotto il namespace tables, memorizzato in AWS AppConfig. Le funzioni Lambda e il server MCP lo recuperano a runtime utilizzando Lambda Powertools, invece di doverlo passare come variabile d’ambiente. Un vantaggio di questo approccio è che man mano che il numero di tabelle o altri identificatori di infrastruttura cresce, hai bisogno solo di una singola variabile d’ambiente RUNTIME_CONFIG_APP_ID quando esegui localmente.

Task 4: Deployment e testing

Prima, correggi eventuali problemi di linting:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Poi compila la codebase:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Deployare l’applicazione

Per deployare la tua applicazione, esegui il seguente comando:

pnpm

pnpm nx deploy infra "dungeon-adventure-infra-sandbox/*"

yarn

yarn nx deploy infra "dungeon-adventure-infra-sandbox/*"

npm

npx nx deploy infra "dungeon-adventure-infra-sandbox/*"

bun

bunx nx deploy infra "dungeon-adventure-infra-sandbox/*"

Bootstrap richiesto

Per eseguire il bootstrap del tuo account AWS prima, esegui:

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Il primo deployment richiederà circa 8 minuti. I deployment successivi richiederanno circa 2 minuti.

Iterazione rapida

Se stai modificando il codice delle funzioni Lambda, puoi eseguire il deploy con il flag --hotswap dopo aver compilato la codebase per un tempo di deployment molto più breve (2-3 secondi).

pnpm

pnpm nx deploy infra "dungeon-adventure-infra-sandbox/*" --hotswap

yarn

yarn nx deploy infra "dungeon-adventure-infra-sandbox/*" --hotswap

npm

npx nx deploy infra "dungeon-adventure-infra-sandbox/*" --hotswap

bun

bunx nx deploy infra "dungeon-adventure-infra-sandbox/*" --hotswap

Una volta completato il deployment, vedrai output simili ai seguenti (alcuni valori sono stati oscurati):

dungeon-adventure-infra-sandbox-Application
dungeon-adventure-infra-sandbox-Application: deploying... [2/2]

 ✅  dungeon-adventure-infra-sandbox-Application

✨  Deployment time: 354s

Outputs:
dungeon-adventure-infra-sandbox-Application.ElectroDbTableTableNameXXX = dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY
dungeon-adventure-infra-sandbox-Application.GameApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-infra-sandbox-Application.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
dungeon-adventure-infra-sandbox-Application.InventoryMcpArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY
dungeon-adventure-infra-sandbox-Application.RuntimeConfigApplicationId = xxxx
dungeon-adventure-infra-sandbox-Application.StoryAgentArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventurecationStoryAgentXXXX-YYYY
dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolClientIdXXX = xxxxxxxxxx
dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXXX = region_xxx

Testare l’API

Puoi testare l’API in due modi:

• Avviando un’istanza locale del backend tRPC e invocando le API con curl.
• Chiamare l'API deployata utilizzando curl con sigv4 abilitato

Locale

Per avviare il server locale game-api, esegui il seguente comando:

pnpm

RUNTIME_CONFIG_APP_ID=xxxx pnpm nx serve game-api

yarn

RUNTIME_CONFIG_APP_ID=xxxx yarn nx serve game-api

npm

RUNTIME_CONFIG_APP_ID=xxxx npx nx serve game-api

bun

RUNTIME_CONFIG_APP_ID=xxxx bunx nx serve game-api

Usa i valori di output CDK

Utilizza il valore dungeon-adventure-infra-sandbox-Application.RuntimeConfigApplicationId dall’output del deploy CDK per sostituire il segnaposto evidenziato.

Una volta avviato il server, puoi chiamarlo eseguendo il seguente comando:

curl -X GET 'http://localhost:2022/games.query?input=%7B%7D'

Deployato

acurl ap-southeast-2 execute-api -X GET 'https://xxx.execute-api.ap-southeast-2.amazonaws.com/prod/games.query?input=%7B%7D'

Usa i valori di output CDK

Utilizza il valore dungeon-adventure-infra-sandbox-Application.GameApiGameApiEndpointXXX dall’output del deploy CDK per sostituire il segnaposto evidenziato e imposta la regione di conseguenza.

Codifica URL

Il %7B%7D che passiamo per testare l’API è un oggetto JSON vuoto ({}) codificato in URI.

Se il comando viene eseguito con successo, vedrai una risposta come:

{"result":{"data":{"items":[],"cursor":null}}}

Complimenti, hai costruito e deployato la tua prima API utilizzando tRPC! 🎉🎉🎉