run-dmcp 0.3.0 → 0.5.0

package/README.md

@@ -59,14 +59,28 @@ schema comes up, where the database lives, and whether anything listens.
 
 **The package root is the core, and the tabletop surface is a layer above it.** Dice, combat,
 abilities, status effects, random tables and quests are genuinely game-shaped — an optional
-dependency, not part of the engine (see [docs/DESIGN.md](docs/DESIGN.md) §8). A consumer that only
-needs entities, facts, events and the timeline imports `run-dmcp` and calls `createCoreMcpServer`. A
-consumer that wants the full tabletop surface imports `run-dmcp/rpg` and calls `createMcpServer` —
-same name, same options, the whole assembly this package has always served:
+dependency, not part of the engine (see [docs/DESIGN.md](docs/DESIGN.md) §8).
+
+**Mechanism and assembly are separate entries, and importing one never loads the other** (since
+0.4.0). Four specifiers, two layers by two kinds:
+
+| | mechanism — functions, constants, types | assembly — builds a server |
+|---|---|---|
+| **core** | `run-dmcp` | `run-dmcp/server` → `createCoreMcpServer` |
+| **+ tabletop** | `run-dmcp/rpg` | `run-dmcp/rpg/server` → `createMcpServer` |
+
+Assembling a server means loading the MCP SDK, twenty-one register modules and (for the full
+assembly) the web UI. Wanting `createGame` or `LIMITS` does not, and until 0.4.0 both entries
+charged for it anyway: the core entry cost 97.4ms per process cold and costs 47.0ms now, which is
+below the MCP SDK's own 55.0ms, because without the assembly it no longer loads the SDK at all.
+
+A consumer that *does* build a server loads the SDK regardless, so it saves less than that
+difference suggests — measured with the SDK warm, importing both entries, 67.4ms → 38.0ms, about
+29ms per process. The functions did not change; their specifiers did.
 
 ```ts
 import { initializeSchema, type SchemaMigration } from "run-dmcp";
-import { createMcpServer } from "run-dmcp/rpg";
+import { createMcpServer } from "run-dmcp/rpg/server";
 
 const migrations: SchemaMigration[] = [
   {

package/dist/bin/run-dmcp.js

@@ -18,7 +18,7 @@ import { startHttpServer } from "../http/server.js";
 // (design §8, issue #17). The application always served the full surface,
 // so it reaches for it here rather than the core-only `createCoreMcpServer`
 // in ../mcp-server.js.
-import { createMcpServer } from "../rpg/index.js";
+import { createMcpServer } from "../rpg/server.js";
 import { httpPortFromEnv, setHttpPort, webUiEnabled } from "../utils/webui.js";
 import { createLogger } from "../utils/logger.js";
 const log = createLogger("bin");

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export { createCoreMcpServer, SERVER_NAME, SERVER_VERSION } from "./mcp-server.js";
 export { getDatabase, closeDatabase, withTransaction, getDatabasePath, getDataDir, resolveDataPathFrom, } from "./db/connection.js";
 export type { DataPathInputs } from "./db/connection.js";
 export { initializeSchema } from "./db/schema.js";

package/dist/index.js

@@ -26,7 +26,13 @@
 // depending up into it. `src/__tests__/layerBoundary.test.ts` walks the
 // static import graph from this file and fails if anything under `src/rpg/`
 // is reachable from it.
-export { createCoreMcpServer, SERVER_NAME, SERVER_VERSION } from "./mcp-server.js";
+// The assembled core server is NOT here. It moved to "run-dmcp/server"
+// (src/server.ts) so that importing mechanism stops loading it: building a
+// server costs the MCP SDK and twenty-one register modules, and a consumer
+// reaching for `LIMITS` or `createGame` was paying for both -- 97.4ms per
+// process against 46.8ms without it, cold, at 0.3.0. Enforced by
+// src/__tests__/assemblyBoundary.test.ts, which walks this file's runtime
+// import graph and fails if the assembly is reachable from it again.
 // The database, and where it lives. The path resolves against the consuming
 // application (DMCP_DB_PATH, else an existing XDG data directory, else the
 // working directory) and never against this package's install location.

package/dist/mcp-server.d.ts

@@ -2,7 +2,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Mechanic } from "./timeline/resolve.js";
 import { type RenderVocabulary } from "./timeline/render.js";
 export declare const SERVER_NAME = "dmcp";
-export declare const SERVER_VERSION = "0.3.0";
+/** What the server tells a client it is, in the MCP handshake. Kept equal to
+ *  the published package version by src/__tests__/serverVersion.test.ts --
+ *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
+ *  package.json and nothing was watching this. */
+export declare const SERVER_VERSION = "0.5.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/mcp-server.js

@@ -41,7 +41,11 @@ import { registerRenderTools } from "./register/render.js";
 import { createResolver } from "./timeline/resolve.js";
 import { createStateRenderer } from "./timeline/render.js";
 export const SERVER_NAME = "dmcp";
-export const SERVER_VERSION = "0.3.0";
+/** What the server tells a client it is, in the MCP handshake. Kept equal to
+ *  the published package version by src/__tests__/serverVersion.test.ts --
+ *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
+ *  package.json and nothing was watching this. */
+export const SERVER_VERSION = "0.5.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/register/batch.js

@@ -3,7 +3,7 @@ import * as characterTools from "../tools/character.js";
 import * as worldTools from "../tools/world.js";
 import * as inventoryTools from "../tools/inventory.js";
 import * as narrativeTools from "../tools/narrative.js";
-import { LIMITS } from "../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 import { imageGenSchema, voiceSchema } from "../schemas/index.js";
 // Multi-entity workflow tools over entity/property concepts -- characters,
@@ -18,7 +18,7 @@ export function registerBatchTools(server) {
     server.registerTool("batch_create_npcs", {
         description: "Create multiple NPCs at once. Use this when populating a location with several characters. Returns all created characters.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
             npcs: z
                 .array(z.object({
                 name: z.string().min(1).max(LIMITS.NAME_MAX).describe("NPC name"),
@@ -28,10 +28,10 @@ export function registerBatchTools(server) {
                     .object({
                     health: z.number().optional(),
                     maxHealth: z.number().optional(),
-                    conditions: z.array(z.string()).optional(),
+                    conditions: validatedSchemas.stringArray.optional(),
                 })
                     .optional(),
-                locationId: z.string().optional().describe("Starting location"),
+                locationId: validatedSchemas.id.optional().describe("Starting location"),
                 notes: z.string().max(LIMITS.CONTENT_MAX).optional(),
                 voice: voiceSchema.optional(),
                 imageGen: imageGenSchema.optional(),
@@ -105,12 +105,13 @@ export function registerBatchTools(server) {
     server.registerTool("scene_transition", {
         description: "Complete scene transition in one call: moves specified characters to a new location and logs a narrative event. Perfect for moving between scenes.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
             characterIds: z
-                .array(z.string())
+                .array(validatedSchemas.id)
                 .min(1)
+                .max(LIMITS.ARRAY_MAX)
                 .describe("Characters to move to the new scene"),
-            destinationId: z.string().describe("Destination location ID"),
+            destinationId: validatedSchemas.id.describe("Destination location ID"),
             narrativeDescription: z
                 .string()
                 .max(LIMITS.DESCRIPTION_MAX)
@@ -165,7 +166,7 @@ export function registerBatchTools(server) {
     server.registerTool("get_character_context", {
         description: "Get comprehensive character context in one call: character details, inventory, and current location info. Reduces multiple tool calls to one.",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
+            characterId: validatedSchemas.id.describe("The character ID"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ characterId }) => {
@@ -219,8 +220,8 @@ export function registerBatchTools(server) {
     server.registerTool("get_location_context", {
         description: "Get comprehensive location context in one call: location details, present characters, and items here. Reduces multiple tool calls to one.",
         inputSchema: {
-            locationId: z.string().describe("The location ID"),
-            gameId: z.string().describe("The game ID (needed for character lookup)"),
+            locationId: validatedSchemas.id.describe("The location ID"),
+            gameId: validatedSchemas.id.describe("The game ID (needed for character lookup)"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ locationId, gameId }) => {

package/dist/register/character.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import * as characterTools from "../tools/character.js";
 import { imageGenSchema, voiceSchema } from "../schemas/index.js";
-import { LIMITS } from "../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 import { characterOutputSchema, characterStatusSchema, conditionModifyOutputSchema, } from "../utils/output-schemas.js";
 import { verbositySchema, applyVerbosity } from "../utils/verbosity.js";
@@ -44,7 +44,7 @@ export function registerCharacterTools(server) {
     server.registerTool("get_character", {
         description: "Get character details",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
+            characterId: validatedSchemas.id.describe("The character ID"),
         },
         outputSchema: characterOutputSchema,
         annotations: ANNOTATIONS.READ_ONLY,
@@ -67,13 +67,13 @@ export function registerCharacterTools(server) {
     server.registerTool("update_character", {
         description: "Update character attributes, skills, status, or voice",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
-            name: z.string().optional().describe("New name"),
+            characterId: validatedSchemas.id.describe("The character ID"),
+            name: validatedSchemas.token.optional().describe("New name"),
             attributes: z.record(z.string(), z.number()).optional().describe("Attribute updates"),
             skills: z.record(z.string(), z.number()).optional().describe("Skill updates"),
             status: z.record(z.string(), z.unknown()).optional().describe("Status updates"),
-            locationId: z.string().optional().describe("New location"),
-            notes: z.string().optional().describe("Notes update"),
+            locationId: validatedSchemas.id.optional().describe("New location"),
+            notes: validatedSchemas.content.optional().describe("Notes update"),
             voice: voiceSchema.nullable().optional().describe("Voice characteristics (null to remove)"),
             imageGen: imageGenSchema.nullable().optional().describe("Image generation metadata (null to remove)"),
         },
@@ -98,9 +98,9 @@ export function registerCharacterTools(server) {
     server.registerTool("list_characters", {
         description: "List characters in a game. Use verbosity to control response size: 'minimal' for quick lookups (id/name only), 'standard' for common fields, 'full' for all details.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
             isPlayer: z.boolean().optional().describe("Filter by player/NPC"),
-            locationId: z.string().optional().describe("Filter by location"),
+            locationId: validatedSchemas.id.optional().describe("Filter by location"),
             verbosity: verbositySchema,
         },
         outputSchema: {
@@ -128,8 +128,8 @@ export function registerCharacterTools(server) {
     server.registerTool("move_character", {
         description: "Move a character to a different location",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
-            locationId: z.string().describe("The destination location ID"),
+            characterId: validatedSchemas.id.describe("The character ID"),
+            locationId: validatedSchemas.id.describe("The destination location ID"),
         },
         outputSchema: {
             success: z.boolean(),
@@ -163,7 +163,7 @@ export function registerCharacterTools(server) {
     server.registerTool("modify_health", {
         description: "Modify a character's health. Use mode 'damage' to reduce health, or 'heal' to restore health.",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
+            characterId: validatedSchemas.id.describe("The character ID"),
             mode: z.enum(["damage", "heal"]).describe("'damage' to reduce health, 'heal' to restore health"),
             amount: z.number().describe("Amount of damage or healing"),
         },
@@ -201,7 +201,7 @@ export function registerCharacterTools(server) {
     server.registerTool("modify_conditions", {
         description: "Add and/or remove conditions from a character in a single call. More efficient than separate add/remove calls.",
         inputSchema: {
-            characterId: z.string().describe("The character ID"),
+            characterId: validatedSchemas.id.describe("The character ID"),
             add: z.array(z.string().max(100)).max(LIMITS.ARRAY_MAX).optional().describe("Conditions to add"),
             remove: z.array(z.string().max(100)).max(LIMITS.ARRAY_MAX).optional().describe("Conditions to remove"),
         },
@@ -244,8 +244,8 @@ export function registerCharacterTools(server) {
     server.registerTool("get_character_by_name", {
         description: "Look up a character 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("Character name to search for (case-insensitive)"),
+            gameId: validatedSchemas.id.describe("The game ID to search within"),
+            name: validatedSchemas.token.describe("Character name to search for (case-insensitive)"),
         },
         outputSchema: characterOutputSchema,
         annotations: ANNOTATIONS.READ_ONLY,
@@ -268,7 +268,7 @@ export function registerCharacterTools(server) {
     server.registerTool("list_character_summaries", {
         description: "List characters with quick-identification summaries. Use this to help identify characters by appearance before looking up their full details. More efficient than loading full character data when you just need to identify who's who.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
         },
         outputSchema: {
             summaries: z.array(z.object({
@@ -297,7 +297,7 @@ export function registerCharacterTools(server) {
     server.registerTool("delete_character", {
         description: "Delete a character permanently. This is IRREVERSIBLE and will remove the character and all associated data.",
         inputSchema: {
-            characterId: z.string().describe("The character ID to delete"),
+            characterId: validatedSchemas.id.describe("The character ID to delete"),
         },
         outputSchema: {
             success: z.boolean(),