Gioco di Dungeon con IA Agentiva

Modulo 2: Implementazione dell’API del gioco e del server MCP per l’inventario

Inizieremo implementando la nostra Game API. Per farlo, dobbiamo creare 5 API in totale:

1. saveGame - crea o aggiorna un gioco.
2. queryGames - restituisce una lista paginata di giochi salvati precedentemente.
3. saveAction - salva un’azione per un determinato gioco.
4. queryActions - restituisce una lista paginata di tutte le azioni relative a un gioco.
5. queryInventory - restituisce una lista paginata degli oggetti nell’inventario di un giocatore.

Schema dell’API

Per definire gli input e gli output della nostra API, creiamo il nostro schema utilizzando Zod nella directory packages/game-api/src/schema come segue:

action.ts

import { z } from 'zod';

export const ActionSchema = z.object({
  playerName: z.string(),
  timestamp: z.iso.datetime(),
  role: z.enum(['assistant', 'user']),
  content: z.string(),
});

export type IAction = z.TypeOf<typeof ActionSchema>;

common.ts

import { z } from 'zod';

export const QueryInputSchema = z.object({
  cursor: z.string().optional(),
  limit: z.number().optional().default(100),
});

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

export type IQueryInput = z.TypeOf<typeof QueryInputSchema>;

game.ts

import { z } from 'zod';

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>;

inventory.ts

import { z } from 'zod';

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>;

index.ts

+

export * from './action.js';
export * from './common.js';
export * from './game.js';
export * from './inventory.js';

+-

export * from './echo.js'
export * from './action.js';
export * from './common.js';
export * from './game.js';
export * from './inventory.js';

Puoi anche eliminare il file packages/game-api/src/schema/echo.ts dato che non lo utilizzeremo in questo progetto.

Consiglio

Come puoi vedere sopra, 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à

Il diagramma ER per la nostra applicazione è il seguente:

Implementeremo il nostro database in DynamoDB e utilizzeremo la libreria client ElectroDB per semplificare le operazioni. Per iniziare, dobbiamo prima installare electrodb e il DynamoDB Client eseguendo il seguente comando:

pnpm

pnpm add -w electrodb@3.5.0 @aws-sdk/client-dynamodb@3.913.0

yarn

yarn add electrodb@3.5.0 @aws-sdk/client-dynamodb@3.913.0

npm

npm install --legacy-peer-deps electrodb@3.5.0 @aws-sdk/client-dynamodb@3.913.0

bun

bun install electrodb@3.5.0 @aws-sdk/client-dynamodb@3.913.0

Nota

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.

Ora creiamo i seguenti file nella nostra cartella packages/game-api/src/entities per definire le entità ElectroDB secondo il diagramma ER sopra:

action.ts

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

export const createActionEntity = (client?: DynamoDBClient) =>
  new Entity(
    {
      model: {
        entity: 'Action',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        timestamp: {
          type: 'string',
          required: true,
          readOnly: true,
          set: () => new Date().toISOString(),
          default: () => new Date().toISOString(),
        },
        role: { type: 'string', required: true, readOnly: true },
        content: { type: 'string', required: true, readOnly: true },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: { field: 'sk', composite: ['timestamp'] },
        },
      },
    },
    { client, table: process.env.TABLE_NAME },
  );

game.ts

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

export const createGameEntity = (client?: 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: process.env.TABLE_NAME },
  );

inventory.ts

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

export const createInventoryEntity = (client?: 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: process.env.TABLE_NAME },
  );

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

Nota

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/inventory.js';

Nota

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.

Aggiunta del client DynamoDB al contesto tRPC

Dato che abbiamo bisogno di accedere al client DynamoDB in ognuna delle nostre procedure, vogliamo creare un’unica istanza del client che possiamo passare tramite il contesto. Per farlo, apporta le seguenti modifiche in packages/game-api/src:

middleware/dynamodb.ts

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { initTRPC } from '@trpc/server';

export interface IDynamoDBContext {
  dynamoDb?: DynamoDBClient;
}

export const createDynamoDBPlugin = () => {
  const t = initTRPC.context<IDynamoDBContext>().create();
  return t.procedure.use(async (opts) => {
    const dynamoDb = new DynamoDBClient();

    const response = await opts.next({
      ctx: {
        ...opts.ctx,
        dynamoDb,
      },
    });

    return response;
  });
};

Questo è un plugin che strumentiamo per creare il DynamoDBClient e iniettarlo nel contesto.

middleware/index.ts

import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { APIGatewayProxyEvent } from 'aws-lambda';
import { ILoggerContext } from './logger.js';
import { IMetricsContext } from './metrics.js';
import { ITracerContext } from './tracer.js';
import { IDynamoDBContext } from './dynamodb.js';

export * from './dynamodb.js';
export * from './logger.js';
export * from './metrics.js';
export * from './tracer.js';
export * from './error.js';

export type IMiddlewareContext =
  CreateAWSLambdaContextOptions<APIGatewayProxyEvent> &
    IDynamoDBContext &
    ILoggerContext &
    IMetricsContext &
    ITracerContext;

Estendiamo il nostro IMiddlewareContext per aggiungere IDynamoDBContext.

init.ts

import { initTRPC } from '@trpc/server';
import {
  createDynamoDBPlugin,
  createErrorPlugin,
  createLoggerPlugin,
  createMetricsPlugin,
  createTracerPlugin,
  IMiddlewareContext,
} from './middleware/index.js';

process.env.POWERTOOLS_SERVICE_NAME = 'GameApi';
process.env.POWERTOOLS_METRICS_NAMESPACE = 'GameApi';

export type Context = IMiddlewareContext;

export const t = initTRPC.context<Context>().create();

export const publicProcedure = t.procedure
  .concat(createDynamoDBPlugin())
  .concat(createLoggerPlugin())
  .concat(createTracerPlugin())
  .concat(createMetricsPlugin())
  .concat(createErrorPlugin());

Il plugin DynamoDB viene strumentato.

Nota

L’API concat associa il nostro middleware alle procedure che definiamo. Per maggiori dettagli, consulta la guida concat.

Definizione delle procedure

Ora è il momento di implementare i metodi dell’API. Per farlo, apporta le seguenti modifiche in packages/game-api/src/procedures:

Query

query-actions.ts

import { createActionEntity } from '../entities/action.js';
import {
  ActionSchema,
  IAction,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from '../schema/index.js';
import { publicProcedure } from '../init.js';
import { z } from 'zod';

export const queryActions = publicProcedure
  .input(QueryInputSchema.extend({ playerName: z.string() }))
  .output(createPaginatedQueryOutput(ActionSchema))
  .query(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const result = await actionEntity.query
      .primary({ playerName: input.playerName })
      .go({ cursor: input.cursor, count: input.limit });

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

query-games.ts

import { createGameEntity } from '../entities/game.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, ctx }) => {
    const gameEntity = createGameEntity(ctx.dynamoDb);
    const result = await gameEntity.scan.go({
      cursor: input.cursor,
      count: input.limit,
    });

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

query-inventory.ts

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

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

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

Mutazioni

save-action.ts

import { ActionSchema, IAction } from '../schema/index.js';
import { publicProcedure } from '../init.js';
import { createActionEntity } from '../entities/action.js';
import { createGameEntity } from '../entities/game.js';

export const saveAction = publicProcedure
  .input(ActionSchema.omit({ timestamp: true }))
  .output(ActionSchema)
  .mutation(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const gameEntity = createGameEntity(ctx.dynamoDb);

    const action = await actionEntity.put(input).go();
    await gameEntity
      .update({ playerName: input.playerName })
      .set({ lastUpdated: action.data.timestamp })
      .go();
    return action.data as IAction;
  });

save-game.ts

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

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

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

Puoi anche eliminare il file echo.ts (da packages/game-api/src/procedures) dato che non lo utilizzeremo in questo progetto.

Configurazione del router

Ora che abbiamo definito le nostre procedure, colleghiamole alla nostra API. Per farlo, aggiorna il seguente file:

packages/game-api/src/router.ts

+

import {
  awsLambdaRequestHandler,
  CreateAWSLambdaContextOptions,
} from '@trpc/server/adapters/aws-lambda';
import { t } from './init.js';
import { APIGatewayProxyEvent } from 'aws-lambda';
import { queryActions } from './procedures/query-actions.js';
import { saveAction } from './procedures/save-action.js';
import { queryGames } from './procedures/query-games.js';
import { saveGame } from './procedures/save-game.js';
import { queryInventory } from './procedures/query-inventory.js';

export const router = t.router;

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

export const handler = awsLambdaRequestHandler({
  router: appRouter,
  createContext: (
    ctx: CreateAWSLambdaContextOptions<APIGatewayProxyEvent>,
  ) => ctx,
  responseMeta: () => ({
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': '*',
    },
  }),
});

export type AppRouter = typeof appRouter;

+-

import {
  awsLambdaRequestHandler,
  CreateAWSLambdaContextOptions,
} from '@trpc/server/adapters/aws-lambda';
import { echo } from './procedures/echo.js';
import { t } from './init.js';
import { APIGatewayProxyEvent } from 'aws-lambda';
import { queryActions } from './procedures/query-actions.js';
import { saveAction } from './procedures/save-action.js';
import { queryGames } from './procedures/query-games.js';
import { saveGame } from './procedures/save-game.js';
import { queryInventory } from './procedures/query-inventory.js';

export const router = t.router;

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

export const handler = awsLambdaRequestHandler({
  router: appRouter,
  createContext: (
    ctx: CreateAWSLambdaContextOptions<APIGatewayProxyEvent>,
  ) => ctx,
  responseMeta: () => ({
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': '*',
    },
  }),
});

export type AppRouter = typeof appRouter;

Server MCP per l’inventario

Ora 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 { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import z from 'zod-v3';
import { createInventoryEntity } from ':dungeon-adventure/game-api';

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

  const dynamoDb = new DynamoDBClient();
  const inventory = createInventoryEntity(dynamoDb);

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

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

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

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

  server.tool(
    'remove-from-inventory',
    "Remove an item from the player's inventory. If quantity is omitted, all items are removed.",
    {
      playerName: z.string(),
      itemName: z.string(),
      quantity: z.number().optional(),
    },
    async ({ playerName, itemName, quantity }) => {
      // If quantity is omitted, remove the entire item
      if (quantity === undefined) {
        try {
          await inventory.delete({ playerName, itemName }).go();
          return {
            content: [
              { type: 'text', text: `${itemName} removed from inventory.` },
            ],
          } as const;
        } catch {
          return {
            content: [
              { type: 'text', text: `${itemName} not found in inventory` },
            ],
          } as const;
        }
      }

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

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

      const newQuantity = item.data.quantity - quantity;

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

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

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

  return server;
};

+-

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAddTool } from './tools/add.js';
import { registerSampleGuidanceResource } from './resources/sample-guidance.js';
import z from 'zod-v3';
import { createInventoryEntity } from ':dungeon-adventure/game-api';

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

  registerAddTool(server);
  registerSampleGuidanceResource(server);
  const dynamoDb = new DynamoDBClient();
  const inventory = createInventoryEntity(dynamoDb);

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

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

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

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

  server.tool(
    'remove-from-inventory',
    "Remove an item from the player's inventory. If quantity is omitted, all items are removed.",
    {
      playerName: z.string(),
      itemName: z.string(),
      quantity: z.number().optional(),
    },
    async ({ playerName, itemName, quantity }) => {
      // If quantity is omitted, remove the entire item
      if (quantity === undefined) {
        try {
          await inventory.delete({ playerName, itemName }).go();
          return {
            content: [
              { type: 'text', text: `${itemName} removed from inventory.` },
            ],
          } as const;
        } catch {
          return {
            content: [
              { type: 'text', text: `${itemName} not found in inventory` },
            ],
          } as const;
        }
      }

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

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

      const newQuantity = item.data.quantity - quantity;

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

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

      return {
        content: [
          {
            type: 'text',
            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.

Ora puoi eliminare le directory tools e resources in packages/inventory/src/mcp-server poiché non sono utilizzate.

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,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
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 userIdentity = new UserIdentity(this, 'UserIdentity');

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

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this)
        .withDefaultOptions({
          environment: {
            TABLE_NAME: electroDbTable.tableName,
          },
        })
        .build(),
    });

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

    const { userPool, userPoolClient } = userIdentity;

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer', {
      environment: {
        TABLE_NAME: electroDbTable.tableName,
      },
    });
    electroDbTable.grantReadWriteData(mcpServer.agentCoreRuntime);

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedAudience: [userPoolClient.userPoolClientId],
        },
      },
      environment: {
        INVENTORY_MCP_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });
    // Add the Story Agent ARN to runtime-config.json so it can be referenced by the website
    RuntimeConfig.ensure(this).config.agentArn =
      storyAgent.agentCoreRuntime.arn;

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

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

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

    // Ensure this is instantiated last so our runtime-config.json can be automatically configured
    new GameUI(this, 'GameUI');
  }
}

+-

import {
  GameApi,
  GameUI,
  InventoryMcpServer,
  RuntimeConfig,
  StoryAgent,
  UserIdentity,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
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 userIdentity = new UserIdentity(this, 'UserIdentity');

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

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
      integrations: GameApi.defaultIntegrations(this)
        .withDefaultOptions({
          environment: {
            TABLE_NAME: electroDbTable.tableName,
          },
        })
        .build(),
    });

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

    const { userPool, userPoolClient } = userIdentity;

    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');
    const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer', {
      environment: {
        TABLE_NAME: electroDbTable.tableName,
      },
    });
    electroDbTable.grantReadWriteData(mcpServer.agentCoreRuntime);

    // Use Cognito for user authentication with the agent
    const storyAgent = new StoryAgent(this, 'StoryAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedAudience: [userPoolClient.userPoolClientId],
        },
      },
      environment: {
        INVENTORY_MCP_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });
    // Add the Story Agent ARN to runtime-config.json so it can be referenced by the website
    RuntimeConfig.ensure(this).config.agentArn =
      storyAgent.agentCoreRuntime.arn;

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

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

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

    // Ensure this is instantiated last so our runtime-config.json can be automatically configured
    new GameUI(this, 'GameUI');
  }
}

Nota

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.

Deployment e testing

Prima di tutto, compiliamo la codebase:

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Consiglio

Se incontri errori di linting, puoi eseguire il seguente comando per correggerli automaticamente.

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

La tua applicazione può ora essere deployata eseguendo 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/*

Attenzione

Potresti dover eseguire il bootstrap del tuo account AWS prima, con:

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.

Consiglio

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 run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

yarn

yarn nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

npm

npx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

bun

bunx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

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

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

 ✅  dungeon-adventure-sandbox-Application

✨  Deployment time: 354s

Outputs:
dungeon-adventure-sandbox-Application.ElectroDbTableTableNameXXX = dungeon-adventure-sandbox-Application-ElectroDbTableXXX-YYY
dungeon-adventure-sandbox-Application.GameApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-sandbox-Application.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
dungeon-adventure-sandbox-Application.StoryApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-sandbox-Application.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
dungeon-adventure-sandbox-Application.UserIdentityUserIdentityUserPoolIdXXX = region_xxx

Possiamo testare la nostra 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

Locale

Avvia il server locale game-api eseguendo:

pnpm

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY pnpm nx run @dungeon-adventure/game-api:serve

yarn

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY yarn nx run @dungeon-adventure/game-api:serve

npm

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY npx nx run @dungeon-adventure/game-api:serve

bun

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY bunx nx run @dungeon-adventure/game-api:serve

Attenzione

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

Una volta avviato il server, puoi chiamarlo con:

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'

Attenzione

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

Nota

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

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

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

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