run-dmcp 0.4.0 → 0.5.0

package/dist/register/world.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import * as worldTools from "../tools/world.js";
 import { imageGenSchema } from "../schemas/index.js";
-import { LIMITS } from "../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 export function registerWorldTools(server) {
     server.registerTool("create_location", {
@@ -26,7 +26,7 @@ export function registerWorldTools(server) {
     server.registerTool("get_location", {
         description: "Get location details",
         inputSchema: {
-            locationId: z.string().describe("The location ID"),
+            locationId: validatedSchemas.id.describe("The location ID"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ locationId }) => {
@@ -44,9 +44,9 @@ export function registerWorldTools(server) {
     server.registerTool("update_location", {
         description: "Update a location",
         inputSchema: {
-            locationId: z.string().describe("The location ID"),
-            name: z.string().optional().describe("New name"),
-            description: z.string().optional().describe("New description"),
+            locationId: validatedSchemas.id.describe("The location ID"),
+            name: validatedSchemas.token.optional().describe("New name"),
+            description: validatedSchemas.description.optional().describe("New description"),
             properties: z.record(z.string(), z.unknown()).optional().describe("Property updates"),
             imageGen: imageGenSchema.nullable().optional().describe("Image generation metadata (null to remove)"),
         },
@@ -66,7 +66,7 @@ export function registerWorldTools(server) {
     server.registerTool("list_locations", {
         description: "List all locations in a game",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ gameId }) => {
@@ -78,11 +78,11 @@ export function registerWorldTools(server) {
     server.registerTool("connect_locations", {
         description: "Create exits/paths between two locations. Call this whenever you describe how locations connect to each other - the player should be able to navigate based on database connections.",
         inputSchema: {
-            fromLocationId: z.string().describe("First location ID"),
-            toLocationId: z.string().describe("Second location ID"),
-            fromDirection: z.string().describe("Direction from first location (e.g., 'north', 'up', 'through the door')"),
-            toDirection: z.string().describe("Direction from second location back (e.g., 'south', 'down')"),
-            description: z.string().optional().describe("Description of the path"),
+            fromLocationId: validatedSchemas.id.describe("First location ID"),
+            toLocationId: validatedSchemas.id.describe("Second location ID"),
+            fromDirection: validatedSchemas.token.describe("Direction from first location (e.g., 'north', 'up', 'through the door')"),
+            toDirection: validatedSchemas.token.describe("Direction from second location back (e.g., 'south', 'down')"),
+            description: validatedSchemas.description.optional().describe("Description of the path"),
             bidirectional: z.boolean().optional().describe("Create exit in both directions (default: true)"),
         },
         annotations: ANNOTATIONS.CREATE,
@@ -108,8 +108,8 @@ export function registerWorldTools(server) {
     server.registerTool("get_location_by_name", {
         description: "Look up a location by name within a game. Supports exact, partial, and fuzzy matching. Returns the best match or an error if no reasonable match found.",
         inputSchema: {
-            gameId: z.string().describe("The game ID to search within"),
-            name: z.string().describe("Location name to search for (case-insensitive)"),
+            gameId: validatedSchemas.id.describe("The game ID to search within"),
+            name: validatedSchemas.token.describe("Location name to search for (case-insensitive)"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ gameId, name }) => {

package/dist/rpg/register/batch.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import * as characterTools from "../../tools/character.js";
 import * as narrativeTools from "../../tools/narrative.js";
 import * as combatTools from "../tools/combat.js";
-import { LIMITS } from "../../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../../utils/validation.js";
 import { ANNOTATIONS } from "../../utils/tool-annotations.js";
 // The one multi-entity workflow tool that reaches into combat, split out of
 // src/register/batch.ts (design §8, issue #17): everything else there --
@@ -17,8 +17,8 @@ export function registerRpgBatchTools(server) {
     server.registerTool("setup_combat_encounter", {
         description: "Complete combat setup in one call: creates enemy NPCs and starts combat with all participants (enemies + players at location). Returns the ready-to-play combat state.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
-            locationId: z.string().describe("Location where combat takes place"),
+            gameId: validatedSchemas.id.describe("The game ID"),
+            locationId: validatedSchemas.id.describe("Location where combat takes place"),
             enemies: z
                 .array(z.object({
                 name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Enemy name"),

package/dist/schemas/index.js

@@ -1,121 +1,140 @@
+// Reusable Zod schemas, shared by the register modules.
+//
+// EVERY string here is bounded, and this file is where most of the engine's
+// bounds actually live: `imageGenSchema` alone is accepted by seven tools, so
+// one unbounded leaf in it was seven unbounded declarations in the published
+// contract (issue #29 -- 698 of them, against 348 hand-written `.max()` calls
+// spread across the register modules). Bounds belong in the shared schema, not
+// at each call site, for the same reason the schema itself is shared.
+//
+// The tiers come from `validatedSchemas` (../utils/validation.ts) and nowhere
+// else: `.token` for a short descriptor, `.description` for free text a model
+// writes prose into, `.embeddedData` for inline base64. Reach for one of those
+// rather than hand-rolling `z.string().max(...)` -- inlining the bound at each
+// site is exactly how 698 of them came to be forgotten. Each access hands back
+// a FRESH schema instance, deliberately; that file's comment says why, and it
+// is the difference between publishing a declaration and publishing a `$ref`.
 import { z } from "zod";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 // Reusable Zod schemas for image generation
 export const subjectDescriptionSchema = z.object({
     type: z.enum(["character", "location", "item", "scene"]),
-    primaryDescription: z.string(),
+    primaryDescription: validatedSchemas.description,
     physicalTraits: z.object({
-        age: z.string().optional(),
-        gender: z.string().optional(),
-        bodyType: z.string().optional(),
-        height: z.string().optional(),
-        skinTone: z.string().optional(),
-        hairColor: z.string().optional(),
-        hairStyle: z.string().optional(),
-        eyeColor: z.string().optional(),
-        facialFeatures: z.string().optional(),
-        distinguishingMarks: z.array(z.string()).optional(),
+        age: validatedSchemas.token.optional(),
+        gender: validatedSchemas.token.optional(),
+        bodyType: validatedSchemas.token.optional(),
+        height: validatedSchemas.token.optional(),
+        skinTone: validatedSchemas.token.optional(),
+        hairColor: validatedSchemas.token.optional(),
+        hairStyle: validatedSchemas.token.optional(),
+        eyeColor: validatedSchemas.token.optional(),
+        facialFeatures: validatedSchemas.description.optional(),
+        distinguishingMarks: validatedSchemas.stringArray.optional(),
     }).optional(),
     attire: z.object({
-        description: z.string(),
-        colors: z.array(z.string()).optional(),
-        materials: z.array(z.string()).optional(),
-        accessories: z.array(z.string()).optional(),
+        description: validatedSchemas.description,
+        colors: validatedSchemas.stringArray.optional(),
+        materials: validatedSchemas.stringArray.optional(),
+        accessories: validatedSchemas.stringArray.optional(),
     }).optional(),
     environment: z.object({
-        setting: z.string(),
-        timeOfDay: z.string().optional(),
-        weather: z.string().optional(),
-        lighting: z.string().optional(),
-        architecture: z.string().optional(),
-        vegetation: z.string().optional(),
-        notableFeatures: z.array(z.string()).optional(),
+        setting: validatedSchemas.description,
+        timeOfDay: validatedSchemas.token.optional(),
+        weather: validatedSchemas.token.optional(),
+        lighting: validatedSchemas.token.optional(),
+        architecture: validatedSchemas.token.optional(),
+        vegetation: validatedSchemas.token.optional(),
+        notableFeatures: validatedSchemas.stringArray.optional(),
     }).optional(),
     objectDetails: z.object({
-        material: z.string().optional(),
-        size: z.string().optional(),
-        condition: z.string().optional(),
-        glowOrEffects: z.string().optional(),
+        material: validatedSchemas.token.optional(),
+        size: validatedSchemas.token.optional(),
+        condition: validatedSchemas.token.optional(),
+        glowOrEffects: validatedSchemas.description.optional(),
     }).optional(),
-    pose: z.string().optional(),
-    expression: z.string().optional(),
-    action: z.string().optional(),
+    pose: validatedSchemas.description.optional(),
+    expression: validatedSchemas.description.optional(),
+    action: validatedSchemas.description.optional(),
 });
 export const styleDescriptionSchema = z.object({
-    artisticStyle: z.string(),
-    genre: z.string(),
-    mood: z.string(),
-    colorScheme: z.string().optional(),
-    influences: z.array(z.string()).optional(),
-    qualityTags: z.array(z.string()).optional(),
-    negativeElements: z.array(z.string()).optional(),
+    artisticStyle: validatedSchemas.description,
+    genre: validatedSchemas.token,
+    mood: validatedSchemas.token,
+    colorScheme: validatedSchemas.token.optional(),
+    influences: validatedSchemas.stringArray.optional(),
+    qualityTags: validatedSchemas.stringArray.optional(),
+    negativeElements: validatedSchemas.stringArray.optional(),
 });
 export const compositionDescriptionSchema = z.object({
-    framing: z.string(),
-    cameraAngle: z.string().optional(),
-    aspectRatio: z.string().optional(),
-    focusPoint: z.string().optional(),
-    background: z.string().optional(),
-    depth: z.string().optional(),
+    framing: validatedSchemas.description,
+    cameraAngle: validatedSchemas.token.optional(),
+    aspectRatio: validatedSchemas.token.optional(),
+    focusPoint: validatedSchemas.description.optional(),
+    background: validatedSchemas.description.optional(),
+    depth: validatedSchemas.token.optional(),
 });
 export const comfyUIPromptSchema = z.object({
-    positive: z.string(),
-    negative: z.string(),
-    checkpoint: z.string().optional(),
+    positive: validatedSchemas.description,
+    negative: validatedSchemas.description,
+    checkpoint: validatedSchemas.token.optional(),
     loras: z.array(z.object({
-        name: z.string(),
+        name: validatedSchemas.name,
         weight: z.number(),
-    })).optional(),
+    })).max(LIMITS.ARRAY_MAX).optional(),
     samplerSettings: z.object({
-        sampler: z.string().optional(),
-        scheduler: z.string().optional(),
+        sampler: validatedSchemas.token.optional(),
+        scheduler: validatedSchemas.token.optional(),
         steps: z.number().optional(),
         cfg: z.number().optional(),
     }).optional(),
 });
 export const generatedImageSchema = z.object({
-    id: z.string(),
-    tool: z.string(),
-    prompt: z.string(),
-    url: z.string().optional(),
-    base64: z.string().optional(),
+    id: validatedSchemas.id,
+    tool: validatedSchemas.token,
+    prompt: validatedSchemas.description,
+    // A URL, including a `data:` one. Over DESCRIPTION_MAX it is not an address,
+    // it is a payload, and `base64` below is the field for those.
+    url: validatedSchemas.description.optional(),
+    base64: validatedSchemas.embeddedData.optional(),
     seed: z.number().optional(),
-    timestamp: z.string(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
+    timestamp: validatedSchemas.token,
+    metadata: z.record(validatedSchemas.token, z.unknown()).optional(),
 });
 export const imageGenSchema = z.object({
     subject: subjectDescriptionSchema,
     style: styleDescriptionSchema,
     composition: compositionDescriptionSchema,
     prompts: z.object({
-        generic: z.string().optional(),
-        sdxl: z.string().optional(),
-        dalle: z.string().optional(),
-        midjourney: z.string().optional(),
-        flux: z.string().optional(),
+        generic: validatedSchemas.description.optional(),
+        sdxl: validatedSchemas.description.optional(),
+        dalle: validatedSchemas.description.optional(),
+        midjourney: validatedSchemas.description.optional(),
+        flux: validatedSchemas.description.optional(),
         comfyui: comfyUIPromptSchema.optional(),
     }).optional(),
-    generations: z.array(generatedImageSchema).optional(),
+    generations: z.array(generatedImageSchema).max(LIMITS.ARRAY_MAX).optional(),
     consistency: z.object({
-        characterRef: z.string().optional(),
-        seedImage: z.string().optional(),
-        colorPalette: z.array(z.string()).optional(),
-        styleRef: z.string().optional(),
+        characterRef: validatedSchemas.description.optional(),
+        seedImage: validatedSchemas.description.optional(),
+        colorPalette: validatedSchemas.stringArray.optional(),
+        styleRef: validatedSchemas.description.optional(),
     }).optional(),
 }).describe("Image generation metadata for visual representation");
 // Voice schema for characters
 export const voiceSchema = z.object({
     pitch: z.enum(["very_low", "low", "medium", "high", "very_high"]).describe("Voice pitch"),
     speed: z.enum(["very_slow", "slow", "medium", "fast", "very_fast"]).describe("Speaking speed"),
-    tone: z.string().describe("Voice tone (e.g., 'gravelly', 'melodic', 'nasal', 'breathy')"),
-    accent: z.string().optional().describe("Accent (e.g., 'Scottish', 'French', 'Brooklyn')"),
-    quirks: z.array(z.string()).optional().describe("Speech quirks (e.g., 'stutters when nervous')"),
-    description: z.string().optional().describe("Free-form voice description for more nuance"),
+    tone: validatedSchemas.token.describe("Voice tone (e.g., 'gravelly', 'melodic', 'nasal', 'breathy')"),
+    accent: validatedSchemas.token.optional().describe("Accent (e.g., 'Scottish', 'French', 'Brooklyn')"),
+    quirks: validatedSchemas.stringArray.optional().describe("Speech quirks (e.g., 'stutters when nervous')"),
+    description: validatedSchemas.description.optional().describe("Free-form voice description for more nuance"),
 });
 // Random table entry schema
 export const tableEntrySchema = z.object({
     minRoll: z.number().optional().describe("Minimum roll to get this result (for ranged tables)"),
     maxRoll: z.number().optional().describe("Maximum roll for this result"),
     weight: z.number().optional().describe("Weight for weighted random selection"),
-    result: z.string().describe("The result text"),
-    effects: z.record(z.unknown()).optional().describe("Optional structured effects"),
+    result: validatedSchemas.description.describe("The result text"),
+    effects: z.record(validatedSchemas.token, z.unknown()).optional().describe("Optional structured effects"),
 });

package/dist/utils/validation.d.ts

@@ -1,24 +1,53 @@
 import { z } from "zod";
 /**
  * Common input length limits for security and performance.
- * These prevent DoS attacks via extremely large inputs.
+ *
+ * These prevent DoS attacks via extremely large inputs -- and they are also
+ * the engine's PUBLISHED CONTRACT. A `.max()` here lands in the tool's
+ * `input_schema` and `tools/list` hands it to every client before the first
+ * call, so a consumer can read what a field takes instead of hard-coding a
+ * copy of these numbers. One does. Leaving a string parameter unbounded is
+ * therefore not a missing safety net but an active statement that the field
+ * takes anything; `src/__tests__/schemaBounds.test.ts` fails on any that is
+ * (issue #29).
  */
 export declare const LIMITS: {
     readonly NAME_MAX: 200;
     readonly DESCRIPTION_MAX: 5000;
     readonly CONTENT_MAX: 50000;
     readonly NARRATIVE_MAX: 200000;
+    readonly EMBEDDED_DATA_MAX: 2000000;
     readonly ARRAY_MAX: 100;
     readonly MAX_DEPTH: 10;
 };
 /**
- * Pre-built Zod schemas with length limits
+ * Pre-built Zod schemas with length limits.
+ *
+ * EVERY PROPERTY HERE IS A GETTER, AND HANDS BACK A FRESH INSTANCE.
+ *
+ * That is not a style: `zod-to-json-schema` (which the MCP SDK runs over
+ * every `inputSchema` on its way to `tools/list`) de-duplicates by object
+ * IDENTITY. Reuse one instance twice inside a single tool and the second
+ * occurrence is published as
+ *
+ *     { "$ref": "#/properties/imageGen/properties/subject/properties/..." }
+ *
+ * -- a pointer into a sibling property, in place of the declaration a
+ * consumer came to read. Sharing these as plain constants put 648 of those
+ * into the contract, where there had been none; a fresh instance per access
+ * puts the declaration back at every site. `src/__tests__/schemaBounds.test.ts`
+ * fails on any `$ref` in a published schema, which is what caught it.
+ *
+ * The cost is a schema object built per access. They are read at server
+ * construction, not per call.
  */
 export declare const validatedSchemas: {
     readonly name: z.ZodString;
+    readonly token: z.ZodString;
     readonly description: z.ZodString;
     readonly content: z.ZodString;
     readonly narrative: z.ZodString;
+    readonly embeddedData: z.ZodString;
     readonly id: z.ZodString;
     readonly tag: z.ZodString;
     readonly stringArray: z.ZodArray<z.ZodString, "many">;

package/dist/utils/validation.js

@@ -1,7 +1,15 @@
 import { z } from "zod";
 /**
  * Common input length limits for security and performance.
- * These prevent DoS attacks via extremely large inputs.
+ *
+ * These prevent DoS attacks via extremely large inputs -- and they are also
+ * the engine's PUBLISHED CONTRACT. A `.max()` here lands in the tool's
+ * `input_schema` and `tools/list` hands it to every client before the first
+ * call, so a consumer can read what a field takes instead of hard-coding a
+ * copy of these numbers. One does. Leaving a string parameter unbounded is
+ * therefore not a missing safety net but an active statement that the field
+ * takes anything; `src/__tests__/schemaBounds.test.ts` fails on any that is
+ * (issue #29).
  */
 export const LIMITS = {
     // Short text fields (names, titles)
@@ -12,31 +20,80 @@ export const LIMITS = {
     CONTENT_MAX: 50000,
     // Very long text fields (story exports, narrative)
     NARRATIVE_MAX: 200000,
+    // Inline binary carried as a data URI or bare base64 -- an image, not prose.
+    // Deliberately generous rather than a prose tier: the fields that take one
+    // (`imageGen.generations[].base64`) accepted anything before they were
+    // bounded, and a real inline PNG is hundreds of kilobytes.
+    EMBEDDED_DATA_MAX: 2000000,
     // Array limits
     ARRAY_MAX: 100,
     // JSON object depth limit (for nested structures)
     MAX_DEPTH: 10,
 };
 /**
- * Pre-built Zod schemas with length limits
+ * Pre-built Zod schemas with length limits.
+ *
+ * EVERY PROPERTY HERE IS A GETTER, AND HANDS BACK A FRESH INSTANCE.
+ *
+ * That is not a style: `zod-to-json-schema` (which the MCP SDK runs over
+ * every `inputSchema` on its way to `tools/list`) de-duplicates by object
+ * IDENTITY. Reuse one instance twice inside a single tool and the second
+ * occurrence is published as
+ *
+ *     { "$ref": "#/properties/imageGen/properties/subject/properties/..." }
+ *
+ * -- a pointer into a sibling property, in place of the declaration a
+ * consumer came to read. Sharing these as plain constants put 648 of those
+ * into the contract, where there had been none; a fresh instance per access
+ * puts the declaration back at every site. `src/__tests__/schemaBounds.test.ts`
+ * fails on any `$ref` in a published schema, which is what caught it.
+ *
+ * The cost is a schema object built per access. They are read at server
+ * construction, not per call.
  */
 export const validatedSchemas = {
     // Name fields (character names, location names, etc.)
-    name: z.string().min(1).max(LIMITS.NAME_MAX),
+    get name() {
+        return z.string().min(1).max(LIMITS.NAME_MAX);
+    },
+    // Short free text with a ceiling and NO floor -- a colour, a direction, an
+    // aspect ratio, a sampler. Same length as `name`, without `.min(1)`: bounding
+    // a field that accepts "" today must not also start rejecting it.
+    get token() {
+        return z.string().max(LIMITS.NAME_MAX);
+    },
     // Description fields
-    description: z.string().max(LIMITS.DESCRIPTION_MAX),
+    get description() {
+        return z.string().max(LIMITS.DESCRIPTION_MAX);
+    },
     // Content fields (notes, large text)
-    content: z.string().max(LIMITS.CONTENT_MAX),
+    get content() {
+        return z.string().max(LIMITS.CONTENT_MAX);
+    },
     // Narrative content (very large text allowed)
-    narrative: z.string().max(LIMITS.NARRATIVE_MAX),
+    get narrative() {
+        return z.string().max(LIMITS.NARRATIVE_MAX);
+    },
+    // Inline binary carried as base64 or a data URI -- an image, not prose.
+    get embeddedData() {
+        return z.string().max(LIMITS.EMBEDDED_DATA_MAX);
+    },
     // ID fields (UUIDs are 36 characters)
-    id: z.string().max(100),
+    get id() {
+        return z.string().max(100);
+    },
     // Tag/category strings
-    tag: z.string().min(1).max(100),
+    get tag() {
+        return z.string().min(1).max(100);
+    },
     // Array of strings with limits
-    stringArray: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX),
+    get stringArray() {
+        return z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX);
+    },
     // Array of tags
-    tagArray: z.array(z.string().min(1).max(100)).max(LIMITS.ARRAY_MAX),
+    get tagArray() {
+        return z.array(z.string().min(1).max(100)).max(LIMITS.ARRAY_MAX);
+    },
 };
 /**
  * Helper to create a bounded string schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An MCP server for LLM-run interactive fiction where the server owns what is true - including when it was true. A continuation of DMCP.",
   "license": "MIT",
   "author": "Derek Ferguson",