manage_inventory

Instructions

Implementation Reference

• src/registry.ts:1078-1095 (registration)

  Tool registration entry for 'manage_inventory'. Specifies name, description, converts manageInventorySchema to JSON schema, and provides wrapper handler that calls the actual manageInventory function from data.ts with error handling.

  manage_inventory: {
    name: 'manage_inventory',
    description: 'Manage character inventory. Operations: give (add items), take (remove items), equip (equip to slot), unequip (remove from slot), move (change container), list (show inventory), transfer (move between characters).',
    inputSchema: toJsonSchema(manageInventorySchema),
    handler: async (args) => {
      try {
        const result = await manageInventory(args);
        return result;
      } catch (err) {
        if (err instanceof z.ZodError) {
          const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
          return error(`Validation failed: ${messages}`);
        }
        const message = err instanceof Error ? err.message : String(err);
        return error(message);
      }
    },
  },

• src/modules/data.ts:1643-1744 (schema)

  Zod schema definition for manage_inventory tool. Supports single operations (give, take, equip, unequip, move, list, transfer) via discriminated union and batch operations. Includes detailed item schema with type, quantity, weight, etc., and equipment slots.

  /** Item schema for give operation */
  const itemSchema = z.object({
    name: z.string().min(1),
    type: ItemTypeSchema,
    quantity: z.number().int().min(1),
    weight: z.number().optional(),
    value: z.number().optional(),
    description: z.string().optional(),
    properties: z.array(z.string()).optional(),
    damage: z.string().optional(),
    damageType: z.string().optional(),
    ac: z.number().optional(),
    container: z.string().optional(),
  });
  
  /** Give operation schema */
  const giveOperationSchema = z.object({
    operation: z.literal('give'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    item: itemSchema,
  });
  
  /** Take operation schema */
  const takeOperationSchema = z.object({
    operation: z.literal('take'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    itemName: z.string(),
    quantity: z.number().int().min(1).optional().default(1),
  });
  
  /** Equip operation schema */
  const equipOperationSchema = z.object({
    operation: z.literal('equip'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    itemName: z.string(),
    slot: EquipmentSlotSchema,
  });
  
  /** Unequip operation schema */
  const unequipOperationSchema = z.object({
    operation: z.literal('unequip'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    itemName: z.string().optional(),
    slot: EquipmentSlotSchema.optional(),
  });
  
  /** Move operation schema */
  const moveItemOperationSchema = z.object({
    operation: z.literal('move'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    itemName: z.string(),
    fromContainer: z.string().optional(),
    toContainer: z.string(),
    quantity: z.number().int().min(1).optional(),
  });
  
  /** List operation schema */
  const listInventoryOperationSchema = z.object({
    operation: z.literal('list'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    filterType: ItemTypeSchema.optional(),
  });
  
  /** Transfer operation schema */
  const transferOperationSchema = z.object({
    operation: z.literal('transfer'),
    characterId: z.string().optional(),
    characterName: z.string().optional(),
    toCharacterId: z.string().optional(),
    toCharacterName: z.string().optional(),
    itemName: z.string(),
    quantity: z.number().int().min(1).optional().default(1),
  });
  
  /** Single inventory operation schema */
  const singleInventoryOperationSchema = z.discriminatedUnion('operation', [
    giveOperationSchema,
    takeOperationSchema,
    equipOperationSchema,
    unequipOperationSchema,
    moveItemOperationSchema,
    listInventoryOperationSchema,
    transferOperationSchema,
  ]);
  
  /** Batch operation schema */
  const batchInventoryOperationSchema = z.object({
    batch: z.array(singleInventoryOperationSchema).max(20),
  });
  
  /** Combined schema for manage_inventory */
  export const manageInventorySchema = z.union([
    singleInventoryOperationSchema,
    batchInventoryOperationSchema,
  ]);

• src/modules/data.ts:2230-2280 (handler)

  Core handler implementation. Parses input using manageInventorySchema, handles single operations by dispatching to specific handlers (handleInventoryGive, etc.) or processes batch up to 20 operations. Returns formatted ASCII box output in MCP content format.

  export async function manageInventory(input: unknown): Promise<{ content: { type: 'text'; text: string }[] }> {
    try {
      const parsed = manageInventorySchema.parse(input);
  
      // Check if batch operation
      if ('batch' in parsed) {
        const results: { success: boolean; result: string }[] = [];
        
        for (const op of parsed.batch) {
          try {
            const result = processSingleOperation(op);
            const isError = result.includes('ERROR');
            results.push({ success: !isError, result });
          } catch (err) {
            results.push({ 
              success: false, 
              result: createBox('ERROR', [err instanceof Error ? err.message : 'Unknown error'], DISPLAY_WIDTH) 
            });
          }
        }
  
        const successCount = results.filter(r => r.success).length;
        const failCount = results.filter(r => !r.success).length;
  
        const lines: string[] = [];
        lines.push(`Operations: ${parsed.batch.length}`);
        lines.push(`Successful: ${successCount}`);
        lines.push(`Failed: ${failCount}`);
  
        return { content: [{ type: 'text' as const, text: createBox('BATCH COMPLETE', lines, DISPLAY_WIDTH) }] };
      }
  
      // Single operation
      const result = processSingleOperation(parsed);
      return { content: [{ type: 'text' as const, text: result }] };
    } catch (error) {
      const lines: string[] = [];
  
      if (error instanceof z.ZodError) {
        for (const issue of error.issues) {
          lines.push(`${issue.path.join('.')}: ${issue.message}`);
        }
      } else if (error instanceof Error) {
        lines.push(error.message);
      } else {
        lines.push('An unknown error occurred');
      }
  
      return { content: [{ type: 'text' as const, text: createBox('ERROR', lines, DISPLAY_WIDTH) }] };
    }
  }