@thehammer/schema-mcp-server 1.0.0 → 1.0.2

package/dist/index.js

@@ -14,14 +14,109 @@
  *   SCHEMA_API_TOKEN - Bearer token for SchemaMcpAuthMiddleware
  *   SCHEMA_DEFINITION_ID - ID of the schema being built
  */
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as api from "./api-client.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
 const server = new McpServer({
     name: "schema-mcp-server",
-    version: "1.0.0",
+    version: pkg.version,
 });
+/**
+ * Role-based tool registration.
+ *
+ * SCHEMA_ROLE controls which tools this MCP server instance registers.
+ * Each agent (orchestrator + sub-agents) gets its own MCP server instance
+ * with only the tools relevant to its role.
+ *
+ * Roles:
+ *   orchestrator     — Read-only + annotations + context + progress (no mutations)
+ *   schema-builder   — Schema mutations + reads (no directives/templates/annotations)
+ *   behavior-builder — Directive mutations + reads (no schema/templates/annotations)
+ *   template-builder — Template mutations + reads + styles (no schema/directives/annotations)
+ *   full (default)   — All tools (backwards compatible, used by reviewer agents)
+ */
+const SCHEMA_ROLE = process.env.SCHEMA_ROLE || "full";
+// Tools shared by all roles (read-only schema + template inspection)
+const COMMON_TOOLS = [
+    "schema_get",
+    "annotation_list",
+    "directive_list",
+    "template_list",
+    "template_get",
+    "template_get_example_pages",
+    "template_get_sample_data",
+    "template_preview",
+    "template_preview_html",
+    "quality_gate_list",
+];
+const ROLE_TOOLS = {
+    orchestrator: new Set([
+        ...COMMON_TOOLS,
+        "post_progress",
+        "annotation_create",
+        "annotation_update",
+        "annotation_resolve",
+        "annotation_convert_to_rule",
+        "annotation_delete",
+        "blueprint_list",
+        "context_workflow_inputs",
+        "context_workflow_input_pages",
+        "context_chat_history",
+    ]),
+    "schema-builder": new Set([
+        ...COMMON_TOOLS,
+        "post_progress",
+        "schema_update_model",
+        "schema_remove_model",
+        "schema_update_root",
+        "quality_gate_submit_review",
+    ]),
+    "behavior-builder": new Set([
+        ...COMMON_TOOLS,
+        "post_progress",
+        "directive_create",
+        "directive_update",
+        "directive_delete",
+        "quality_gate_submit_review",
+    ]),
+    "template-builder": new Set([
+        ...COMMON_TOOLS,
+        "post_progress",
+        "template_create",
+        "template_update",
+        "template_patch",
+        "template_set_sample_data",
+        "quality_gate_submit_review",
+        "style_list",
+    ]),
+    reviewer: new Set([
+        ...COMMON_TOOLS,
+        "blueprint_list",
+        "style_list",
+        "context_workflow_inputs",
+        "context_workflow_input_pages",
+    ]),
+};
+/**
+ * Check if a tool should be registered for the current SCHEMA_ROLE.
+ *
+ * Unknown roles default to NO tools (fail-closed) to prevent accidental
+ * full access from typos or misconfiguration.
+ */
+function shouldRegister(toolName) {
+    if (SCHEMA_ROLE === "full")
+        return true;
+    const allowed = ROLE_TOOLS[SCHEMA_ROLE];
+    if (!allowed) {
+        console.error(`Unknown SCHEMA_ROLE "${SCHEMA_ROLE}" — no tools will be registered. Valid roles: full, ${Object.keys(ROLE_TOOLS).join(", ")}`);
+        return false;
+    }
+    return allowed.has(toolName);
+}
 /** Wrap API response data into MCP tool result format. */
 function jsonResult(data) {
     return {
@@ -114,459 +209,497 @@ const messageParam = z
 // ============================================================================
 // Progress Tool
 // ============================================================================
-server.tool("post_progress", "Post a progress update to share your current thinking, plans, and discoveries with the user. Call this before making changes to explain your plan, after making changes to explain what you did, and whenever you discover something that affects your approach.", {
-    message: z
-        .string()
-        .describe("Your progress update message for the user"),
-    phase: z
-        .string()
-        .optional()
-        .describe("Current phase (e.g., planning, implementing, reviewing)"),
-}, async ({ message, phase }) => {
-    const result = await api.postProgress(message, phase);
-    return jsonResult(result);
-});
+if (shouldRegister("post_progress"))
+    server.tool("post_progress", "Post a progress update to share your current thinking, plans, and discoveries with the user. Call this before making changes to explain your plan, after making changes to explain what you did, and whenever you discover something that affects your approach.", {
+        message: z
+            .string()
+            .describe("Your progress update message for the user"),
+        phase: z
+            .string()
+            .optional()
+            .describe("Current phase (e.g., planning, implementing, reviewing)"),
+    }, async ({ message, phase }) => {
+        const result = await api.postProgress(message, phase);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Schema Tools
 // ============================================================================
-server.tool("schema_get", "Get the full context for the current schema: schema JSON, annotations, directives, templates, and workflow inputs", {}, async () => {
-    const result = await api.getFullContext();
-    return jsonResult(result);
-});
-server.tool("schema_update_model", "Create or update a model and its fields. Two modes:\n" +
-    "**Model mode** (title provided): Creates model if it doesn't exist, then applies all fields. " +
-    "Pass fields as {field_name: {type, description, ...}} to set multiple fields in one call.\n" +
-    "**Field mode** (field_name provided): Updates a single field's properties via partial merge.\n" +
-    "Use dot-path notation for nested models (e.g., 'client' for fields under client).", {
-    path: z
-        .string()
-        .nullable()
-        .describe("Dot-path to the parent model (null for root level)"),
-    // Model mode params
-    title: z
-        .string()
-        .optional()
-        .describe("Human-readable title for the model (e.g., 'Medical Providers'). " +
-        "The slug name is auto-derived. Required for model mode."),
-    type: z
-        .enum(["object", "array"])
-        .optional()
-        .describe("Type of model to create (required when creating a new model, ignored for existing models)"),
-    fields: z
-        .record(z.string(), z.record(z.string(), z.unknown()))
-        .optional()
-        .describe("Fields to create/update on the model. Keys are field names, values are property objects " +
-        "(e.g., {type: 'string', description: '...', 'x-identity': true}). Each field is merged with existing properties."),
-    // Field mode params
-    field_name: z
-        .string()
-        .optional()
-        .describe("Name of a single field to update (field mode). Cannot be combined with title."),
-    properties: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Properties to merge into the single field (field mode only)"),
-    message: messageParam,
-}, async ({ path, title, type, fields, field_name, properties, message }) => {
-    const data = { path };
-    if (title !== undefined) {
-        data.title = title;
-        if (type !== undefined)
-            data.type = type;
-        if (fields !== undefined)
-            data.fields = fields;
-    }
-    else if (field_name !== undefined) {
-        data.field_name = field_name;
-        if (properties !== undefined)
-            data.properties = properties;
-    }
-    const result = await api.updateModel(data, message);
-    return jsonResult(result);
-});
-server.tool("schema_remove_model", "Remove a model at a path in the schema. Provide the human-readable title — the slug name is auto-derived.", {
-    path: z
-        .string()
-        .nullable()
-        .describe("Dot-path to the parent model (null for root level)"),
-    title: z
-        .string()
-        .describe("Human-readable title of the model to remove (e.g., 'Medical Providers'). The slug name is auto-derived."),
-    message: messageParam,
-}, async ({ path, title, message }) => {
-    const result = await api.removeModel(path, title, message);
-    return jsonResult(result);
-});
-server.tool("schema_update_root", "Update root-level schema metadata (title, description, type). WARNING: This modifies the schema root object itself, NOT the fields inside it. To add fields to the root model, use schema_update_model with path=null in field mode. Only use this tool to change the root's title or description.", {
-    properties: z
-        .record(z.string(), z.unknown())
-        .describe("Properties to merge into the root schema definition"),
-    message: messageParam,
-}, async ({ properties, message }) => {
-    const result = await api.updateRoot(properties, message);
-    return jsonResult(result);
-});
+if (shouldRegister("schema_get"))
+    server.tool("schema_get", "Get the full context for the current schema: schema JSON, annotations, directives, templates, and workflow inputs", {}, async () => {
+        const result = await api.getFullContext();
+        return jsonResult(result);
+    });
+if (shouldRegister("schema_update_model"))
+    server.tool("schema_update_model", "Create or update a model and its fields. Two modes:\n" +
+        "**Model mode** (title provided): Creates model if it doesn't exist, then applies all fields. " +
+        "Pass fields as {field_name: {type, description, ...}} to set multiple fields in one call.\n" +
+        "**Field mode** (field_name provided): Updates a single field's properties via partial merge.\n" +
+        "Use dot-path notation for nested models (e.g., 'client' for fields under client).", {
+        path: z
+            .string()
+            .nullable()
+            .describe("Dot-path to the parent model (null for root level)"),
+        // Model mode params
+        title: z
+            .string()
+            .optional()
+            .describe("Human-readable title for the model (e.g., 'Medical Providers'). " +
+            "The slug name is auto-derived. Required for model mode."),
+        type: z
+            .enum(["object", "array"])
+            .optional()
+            .describe("Type of model to create (required when creating a new model, ignored for existing models)"),
+        fields: z
+            .record(z.string(), z.record(z.string(), z.unknown()))
+            .optional()
+            .describe("Fields to create/update on the model. Keys are field names, values are property objects " +
+            "(e.g., {type: 'string', description: '...', 'x-identity': true}). Each field is merged with existing properties."),
+        // Field mode params
+        field_name: z
+            .string()
+            .optional()
+            .describe("Name of a single field to update (field mode). Cannot be combined with title."),
+        properties: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Properties to merge into the single field (field mode only)"),
+        message: messageParam,
+    }, async ({ path, title, type, fields, field_name, properties, message, }) => {
+        const data = { path };
+        if (title !== undefined) {
+            data.title = title;
+            if (type !== undefined)
+                data.type = type;
+            if (fields !== undefined)
+                data.fields = fields;
+        }
+        else if (field_name !== undefined) {
+            data.field_name = field_name;
+            if (properties !== undefined)
+                data.properties = properties;
+        }
+        const result = await api.updateModel(data, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("schema_remove_model"))
+    server.tool("schema_remove_model", "Remove a model at a path in the schema. Provide the human-readable title — the slug name is auto-derived.", {
+        path: z
+            .string()
+            .nullable()
+            .describe("Dot-path to the parent model (null for root level)"),
+        title: z
+            .string()
+            .describe("Human-readable title of the model to remove (e.g., 'Medical Providers'). The slug name is auto-derived."),
+        message: messageParam,
+    }, async ({ path, title, message }) => {
+        const result = await api.removeModel(path, title, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("schema_update_root"))
+    server.tool("schema_update_root", "Update root-level schema metadata (title, description, type). WARNING: This modifies the schema root object itself, NOT the fields inside it. To add fields to the root model, use schema_update_model with path=null in field mode. Only use this tool to change the root's title or description.", {
+        properties: z
+            .record(z.string(), z.unknown())
+            .describe("Properties to merge into the root schema definition"),
+        message: messageParam,
+    }, async ({ properties, message }) => {
+        const result = await api.updateRoot(properties, message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Annotation Tools
 // ============================================================================
-server.tool("annotation_list", "List all annotations for the current schema", {}, async () => {
-    const result = await api.listAnnotations();
-    return jsonResult(result);
-});
-server.tool("annotation_create", "Create a new annotation on the schema (note, rule, question, or research)", {
-    category: z
-        .enum(["note", "rule", "question", "research"])
-        .describe("Annotation category"),
-    title: z.string().describe("Short title for the annotation"),
-    content: z.string().describe("Markdown content of the annotation"),
-    target_fragment_selector: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Fragment selector targeting a specific schema node"),
-    message: messageParam,
-}, async ({ category, title, content, target_fragment_selector, message }) => {
-    const result = await api.applyAnnotationAction(null, "create", {
-        category,
-        title,
-        content,
-        target_fragment_selector,
-    }, message);
-    return jsonResult(result);
-});
-server.tool("annotation_update", "Update an existing annotation", {
-    annotation_id: z.number().describe("ID of the annotation to update"),
-    title: z.string().optional().describe("New title"),
-    content: z.string().optional().describe("New content"),
-    category: z
-        .enum(["note", "rule", "question", "research"])
-        .optional()
-        .describe("New category"),
-    message: messageParam,
-}, async ({ annotation_id, message, ...data }) => {
-    const updateData = definedOnly(data);
-    const result = await api.applyAnnotationAction(annotation_id, "update", updateData, message);
-    return jsonResult(result);
-});
-server.tool("annotation_resolve", "Resolve a question annotation by providing an answer", {
-    annotation_id: z
-        .number()
-        .describe("ID of the question annotation to resolve"),
-    resolved_content: z.string().describe("The answer to the question"),
-    message: messageParam,
-}, async ({ annotation_id, resolved_content, message }) => {
-    const result = await api.applyAnnotationAction(annotation_id, "resolve", { resolved_content }, message);
-    return jsonResult(result);
-});
-server.tool("annotation_convert_to_rule", "Convert a question or note annotation to a rule", {
-    annotation_id: z.number().describe("ID of the annotation to convert"),
-    message: messageParam,
-}, async ({ annotation_id, message }) => {
-    const result = await api.applyAnnotationAction(annotation_id, "convert-to-rule", undefined, message);
-    return jsonResult(result);
-});
-server.tool("annotation_delete", "Soft-delete an annotation", {
-    annotation_id: z.number().describe("ID of the annotation to delete"),
-    message: messageParam,
-}, async ({ annotation_id, message }) => {
-    const result = await api.applyAnnotationAction(annotation_id, "delete", undefined, message);
-    return jsonResult(result);
-});
+if (shouldRegister("annotation_list"))
+    server.tool("annotation_list", "List all annotations for the current schema", {}, async () => {
+        const result = await api.listAnnotations();
+        return jsonResult(result);
+    });
+if (shouldRegister("annotation_create"))
+    server.tool("annotation_create", "Create a new annotation on the schema (note, rule, question, or research)", {
+        category: z
+            .enum(["note", "rule", "question", "research"])
+            .describe("Annotation category"),
+        title: z.string().describe("Short title for the annotation"),
+        content: z.string().describe("Markdown content of the annotation"),
+        target_fragment_selector: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Fragment selector targeting a specific schema node"),
+        message: messageParam,
+    }, async ({ category, title, content, target_fragment_selector, message, }) => {
+        const result = await api.applyAnnotationAction(null, "create", {
+            category,
+            title,
+            content,
+            target_fragment_selector,
+        }, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("annotation_update"))
+    server.tool("annotation_update", "Update an existing annotation", {
+        annotation_id: z
+            .number()
+            .describe("ID of the annotation to update"),
+        title: z.string().optional().describe("New title"),
+        content: z.string().optional().describe("New content"),
+        category: z
+            .enum(["note", "rule", "question", "research"])
+            .optional()
+            .describe("New category"),
+        message: messageParam,
+    }, async ({ annotation_id, message, ...data }) => {
+        const updateData = definedOnly(data);
+        const result = await api.applyAnnotationAction(annotation_id, "update", updateData, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("annotation_resolve"))
+    server.tool("annotation_resolve", "Resolve a question annotation by providing an answer", {
+        annotation_id: z
+            .number()
+            .describe("ID of the question annotation to resolve"),
+        resolved_content: z.string().describe("The answer to the question"),
+        message: messageParam,
+    }, async ({ annotation_id, resolved_content, message }) => {
+        const result = await api.applyAnnotationAction(annotation_id, "resolve", { resolved_content }, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("annotation_convert_to_rule"))
+    server.tool("annotation_convert_to_rule", "Convert a question or note annotation to a rule", {
+        annotation_id: z
+            .number()
+            .describe("ID of the annotation to convert"),
+        message: messageParam,
+    }, async ({ annotation_id, message }) => {
+        const result = await api.applyAnnotationAction(annotation_id, "convert-to-rule", undefined, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("annotation_delete"))
+    server.tool("annotation_delete", "Soft-delete an annotation", {
+        annotation_id: z
+            .number()
+            .describe("ID of the annotation to delete"),
+        message: messageParam,
+    }, async ({ annotation_id, message }) => {
+        const result = await api.applyAnnotationAction(annotation_id, "delete", undefined, message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Blueprint Tools
 // ============================================================================
-server.tool("blueprint_list", "List all blueprints for the current schema. A blueprint groups behavior directives into an extraction pipeline. One is auto-created when you create your first directive.", {}, async () => {
-    const result = await api.listBlueprints();
-    return jsonResult(result);
-});
+if (shouldRegister("blueprint_list"))
+    server.tool("blueprint_list", "List all blueprints for the current schema. A blueprint groups behavior directives into an extraction pipeline. One is auto-created when you create your first directive.", {}, async () => {
+        const result = await api.listBlueprints();
+        return jsonResult(result);
+    });
 // ============================================================================
 // Directive Tools
 // ============================================================================
-server.tool("directive_list", "List all behavior directives for the current schema", {}, async () => {
-    const result = await api.listDirectives();
-    return jsonResult(result);
-});
-server.tool("directive_create", "Create a new behavior directive. IMPORTANT: The 'type' parameter MUST be one of exactly these three shortcut strings: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'. Do NOT use full class names (e.g., do NOT use 'ArtifactGenerationSchemaBehaviorDirective'). The blueprint is auto-resolved.", {
-    type: z
-        .string()
-        .describe("Behavior type: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'."),
-    name: z.string().describe("Unique name for the directive"),
-    label: z.string().describe("Display label"),
-    target_fragment_selector: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Fragment selector targeting a schema node. Determines which model in the hierarchy this directive operates on. Null = root level."),
-    data_fragment_selector: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Fragment selector for which fields to extract (DataExtraction only). Auto-generated if omitted."),
-    prompt: z
-        .string()
-        .optional()
-        .describe("Prompt text for the directive. Required for ArtifactGeneration (LLM instruction for generating text) and InputOrganization (guidance for page grouping). Optional for DataExtraction (additional extraction guidance)."),
-    settings: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Directive settings object. EXACT key names required: " +
-        "For DataExtraction: {'extraction_mode': 'skim'} or {'extraction_mode': 'exhaustive'} — key MUST be 'extraction_mode', NOT 'mode'. " +
-        "For IO/Artifact: {'agent_effort': 'high'} or 'very_high' or 'extreme'. " +
-        "For Artifact: optionally include 'editable': true, 'deletable': true for user-editable artifacts."),
-    message: messageParam,
-}, async ({ type, name, label, target_fragment_selector, data_fragment_selector, prompt, settings, message, }) => {
-    // Map type names to FQCNs — accepts shortcuts and common variations
-    const typeMap = {
-        // Canonical shortcuts
-        DataExtraction: "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
-        InputOrganization: "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
-        ArtifactGeneration: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
-        // Common variations agents try
-        Artifact: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
-        ArtifactGen: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
-        IO: "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
-        Extraction: "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
-        // Accept FQCNs directly (agents sometimes pass full class names)
-        "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective": "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
-        "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective": "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
-        "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective": "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
-        // Common wrong FQCN the agent guesses
-        "App\\Models\\Schema\\ArtifactGenerationSchemaBehaviorDirective": "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
-    };
-    const resolvedType = typeMap[type] || type;
-    if (!Object.values(typeMap).includes(resolvedType) &&
-        !resolvedType.startsWith("App\\")) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: `Unknown directive type '${type}'. Use one of: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'.`,
-                    }),
-                },
-            ],
+if (shouldRegister("directive_list"))
+    server.tool("directive_list", "List all behavior directives for the current schema", {}, async () => {
+        const result = await api.listDirectives();
+        return jsonResult(result);
+    });
+if (shouldRegister("directive_create"))
+    server.tool("directive_create", "Create a new behavior directive. IMPORTANT: The 'type' parameter MUST be one of exactly these three shortcut strings: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'. Do NOT use full class names (e.g., do NOT use 'ArtifactGenerationSchemaBehaviorDirective'). The blueprint is auto-resolved.", {
+        type: z
+            .string()
+            .describe("Behavior type: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'."),
+        name: z.string().describe("Unique name for the directive"),
+        label: z.string().describe("Display label"),
+        target_fragment_selector: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Fragment selector targeting a schema node. Determines which model in the hierarchy this directive operates on. Null = root level."),
+        data_fragment_selector: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Fragment selector for which fields to extract (DataExtraction only). Auto-generated if omitted."),
+        prompt: z
+            .string()
+            .optional()
+            .describe("Prompt text for the directive. Required for ArtifactGeneration (LLM instruction for generating text) and InputOrganization (guidance for page grouping). Optional for DataExtraction (additional extraction guidance)."),
+        settings: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Directive settings object. EXACT key names required: " +
+            "For DataExtraction: {'extraction_mode': 'skim'} or {'extraction_mode': 'exhaustive'} — key MUST be 'extraction_mode', NOT 'mode'. " +
+            "For IO/Artifact: {'agent_effort': 'high'} or 'very_high' or 'extreme'. " +
+            "For Artifact: optionally include 'editable': true, 'deletable': true for user-editable artifacts."),
+        message: messageParam,
+    }, async ({ type, name, label, target_fragment_selector, data_fragment_selector, prompt, settings, message, }) => {
+        // Map type names to FQCNs — accepts shortcuts and common variations
+        const typeMap = {
+            // Canonical shortcuts
+            DataExtraction: "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
+            InputOrganization: "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
+            ArtifactGeneration: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
+            // Common variations agents try
+            Artifact: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
+            ArtifactGen: "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
+            IO: "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
+            Extraction: "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
+            // Accept FQCNs directly (agents sometimes pass full class names)
+            "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective": "App\\Models\\Schema\\DataExtractionSchemaBehaviorDirective",
+            "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective": "App\\Models\\Schema\\InputOrganizationSchemaBehaviorDirective",
+            "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective": "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
+            // Common wrong FQCN the agent guesses
+            "App\\Models\\Schema\\ArtifactGenerationSchemaBehaviorDirective": "App\\Models\\Schema\\ArtifactSchemaBehaviorDirective",
         };
-    }
-    const result = await api.applyDirectiveAction(null, "create", {
-        type: resolvedType,
-        name,
-        label,
-        target_fragment_selector,
-        data_fragment_selector,
-        prompt,
-        settings,
-    }, message);
-    return jsonResult(result);
-});
-server.tool("directive_update", "Update an existing behavior directive", {
-    directive_id: z.number().describe("ID of the directive to update"),
-    name: z.string().optional().describe("New name"),
-    label: z.string().optional().describe("New label"),
-    target_fragment_selector: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Updated fragment selector targeting a schema node"),
-    data_fragment_selector: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Updated data fragment selector (DataExtraction only)"),
-    settings: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Updated settings"),
-    message: messageParam,
-}, async ({ directive_id, message, ...data }) => {
-    const updateData = definedOnly(data);
-    const result = await api.applyDirectiveAction(directive_id, "update", updateData, message);
-    return jsonResult(result);
-});
-server.tool("directive_delete", "Delete a behavior directive", {
-    directive_id: z.number().describe("ID of the directive to delete"),
-    message: messageParam,
-}, async ({ directive_id, message }) => {
-    const result = await api.applyDirectiveAction(directive_id, "delete", undefined, message);
-    return jsonResult(result);
-});
+        const resolvedType = typeMap[type] || type;
+        if (!Object.values(typeMap).includes(resolvedType) &&
+            !resolvedType.startsWith("App\\")) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Unknown directive type '${type}'. Use one of: 'DataExtraction', 'InputOrganization', or 'ArtifactGeneration'.`,
+                        }),
+                    },
+                ],
+            };
+        }
+        const result = await api.applyDirectiveAction(null, "create", {
+            type: resolvedType,
+            name,
+            label,
+            target_fragment_selector,
+            data_fragment_selector,
+            prompt,
+            settings,
+        }, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("directive_update"))
+    server.tool("directive_update", "Update an existing behavior directive", {
+        directive_id: z.number().describe("ID of the directive to update"),
+        name: z.string().optional().describe("New name"),
+        label: z.string().optional().describe("New label"),
+        target_fragment_selector: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Updated fragment selector targeting a schema node"),
+        data_fragment_selector: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Updated data fragment selector (DataExtraction only)"),
+        settings: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Updated settings"),
+        message: messageParam,
+    }, async ({ directive_id, message, ...data }) => {
+        const updateData = definedOnly(data);
+        const result = await api.applyDirectiveAction(directive_id, "update", updateData, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("directive_delete"))
+    server.tool("directive_delete", "Delete a behavior directive", {
+        directive_id: z.number().describe("ID of the directive to delete"),
+        message: messageParam,
+    }, async ({ directive_id, message }) => {
+        const result = await api.applyDirectiveAction(directive_id, "delete", undefined, message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Template Tools
 // ============================================================================
-server.tool("template_create", "Create a new template definition for the current schema", {
-    name: z
-        .string()
-        .optional()
-        .describe("Template name (auto-generated if omitted, must be unique per team)"),
-    type: z
-        .enum(["document", "table"])
-        .optional()
-        .describe("Template type (default: document)"),
-    description: z
-        .string()
-        .optional()
-        .describe("Human-readable description of the template's purpose"),
-    template_json: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Full template JSON structure with type, meta, styles, and document keys"),
-    message: messageParam,
-}, async ({ message, ...data }) => {
-    const createData = definedOnly(data);
-    const result = await api.createTemplate(createData, message);
-    return jsonResult(result);
-});
-server.tool("template_list", "List all template definitions for the current schema", {}, async () => {
-    const result = await api.listTemplates();
-    return jsonResult(result);
-});
-server.tool("template_get", "Get full details of a template definition including template_json", {
-    template_id: z.number().describe("ID of the template to fetch"),
-}, async ({ template_id }) => {
-    const result = await api.getTemplateDetails(template_id);
-    return jsonResult(result);
-});
-server.tool("template_update", "Update a template definition (e.g., template_json content)", {
-    template_id: z.number().describe("ID of the template to update"),
-    template_json: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("Updated template JSON structure"),
-    name: z.string().optional().describe("Updated template name"),
-    message: messageParam,
-}, async ({ template_id, message, ...data }) => {
-    const updateData = definedOnly(data);
-    const result = await api.applyTemplateAction(template_id, "update", updateData, message);
-    return jsonResult(result);
-});
-server.tool("template_patch", "Apply targeted path/value edits to a template's JSON. Preferred over template_update for iterative changes — " +
-    "only specify the paths that need to change instead of rewriting the entire template_json. " +
-    "Read data-template-path attributes in template_preview HTML to find the correct paths.", {
-    template_id: z.number().describe("ID of the template to patch"),
-    edits: z
-        .array(z.object({
-        path: z
+if (shouldRegister("template_create"))
+    server.tool("template_create", "Create a new template definition for the current schema", {
+        name: z
             .string()
-            .describe("Dot-notation path into template_json (e.g. 'document.body.2.content')"),
-        value: z
-            .unknown()
             .optional()
-            .describe("New value (scalar, element object, or null to delete)"),
-        value_array: z
-            .array(z.unknown())
+            .describe("Template name (auto-generated if omitted, must be unique per team)"),
+        type: z
+            .enum(["document", "table"])
             .optional()
-            .describe("Replace path with this array (for replacing children, body sections, etc.)"),
-    }))
-        .describe("Array of path/value edits to apply"),
-    message: messageParam,
-}, async ({ template_id, edits, message }) => {
-    const result = await api.patchTemplate(template_id, edits, message);
-    return jsonResult(result);
-});
-server.tool("template_get_example_pages", "Get example output documents attached to a template. Returns transcribed text content AND image URLs for each file so you can see both the text and visual layout of what the template output should look like.", {
-    template_id: z
-        .number()
-        .describe("ID of the template to get example pages for"),
-}, async ({ template_id }) => {
-    const result = await api.getTemplateExamplePages(template_id);
-    return multiPageImageResult(result);
-});
-server.tool("template_get_sample_data", "Get the sample data stored on a template. Sample data is used for rendering template previews when no real team object is available.", {
-    template_id: z
-        .number()
-        .describe("ID of the template to get sample data for"),
-}, async ({ template_id }) => {
-    const result = await api.getTemplateSampleData(template_id);
-    return jsonResult(result);
-});
-server.tool("template_set_sample_data", "Set sample data on a template for preview rendering. Store representative extraction data that matches the schema structure so the template can render a realistic preview. This data is used by template_preview when no team_object_id is provided.", {
-    template_id: z
-        .number()
-        .describe("ID of the template to set sample data on"),
-    sample_data: z
-        .record(z.string(), z.unknown())
-        .describe("Sample data object matching the schema structure. Should contain realistic values " +
-        "for all template variables so the preview renders meaningful content."),
-    message: messageParam,
-}, async ({ template_id, sample_data, message }) => {
-    const result = await api.setTemplateSampleData(template_id, sample_data, message);
-    return jsonResult(result);
-});
-server.tool("template_preview", "Capture a screenshot of the rendered template. Returns image URL(s) of the template as it would appear in a document. " +
-    "Use this to visually compare your template against the example output from template_get_example_pages. " +
-    "If no team_object_id is provided, uses the template's sample_data (set via template_set_sample_data) or auto-generated placeholders.", {
-    template_id: z.number().describe("ID of the template to preview"),
-    team_object_id: z
-        .number()
-        .optional()
-        .describe("Optional team object ID to render with real extraction data instead of sample data"),
-    message: messageParam,
-}, async ({ template_id, team_object_id, message }) => {
-    const result = await api.getTemplatePreview(template_id, team_object_id, message);
-    return imageResult(result);
-});
-server.tool("template_preview_html", "Get the rendered template HTML for fast structural verification. " +
-    "Returns the full HTML of the rendered template as text (~1s, much faster than template_preview). " +
-    "Use this during iterative building to verify structure, field references, and layout. " +
-    "Use template_preview (screenshot) only once at the end for final visual verification.", {
-    template_id: z.number().describe("ID of the template to preview"),
-    team_object_id: z
-        .number()
-        .optional()
-        .describe("Optional team object ID to render with real extraction data instead of sample data"),
-    message: messageParam,
-}, async ({ template_id, team_object_id, message }) => {
-    const result = await api.getTemplatePreviewHtml(template_id, team_object_id, message);
-    return jsonResult(result);
-});
+            .describe("Template type (default: document)"),
+        description: z
+            .string()
+            .optional()
+            .describe("Human-readable description of the template's purpose"),
+        template_json: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Full template JSON structure with type, meta, styles, and document keys"),
+        message: messageParam,
+    }, async ({ message, ...data }) => {
+        const createData = definedOnly(data);
+        const result = await api.createTemplate(createData, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_list"))
+    server.tool("template_list", "List all template definitions for the current schema", {}, async () => {
+        const result = await api.listTemplates();
+        return jsonResult(result);
+    });
+if (shouldRegister("template_get"))
+    server.tool("template_get", "Get full details of a template definition including template_json", {
+        template_id: z.number().describe("ID of the template to fetch"),
+    }, async ({ template_id }) => {
+        const result = await api.getTemplateDetails(template_id);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_update"))
+    server.tool("template_update", "Update a template definition (e.g., template_json content)", {
+        template_id: z.number().describe("ID of the template to update"),
+        template_json: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Updated template JSON structure"),
+        name: z.string().optional().describe("Updated template name"),
+        message: messageParam,
+    }, async ({ template_id, message, ...data }) => {
+        const updateData = definedOnly(data);
+        const result = await api.applyTemplateAction(template_id, "update", updateData, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_patch"))
+    server.tool("template_patch", "Apply targeted path/value edits to a template's JSON. Preferred over template_update for iterative changes — " +
+        "only specify the paths that need to change instead of rewriting the entire template_json. " +
+        "Read data-template-path attributes in template_preview HTML to find the correct paths.", {
+        template_id: z.number().describe("ID of the template to patch"),
+        edits: z
+            .array(z.object({
+            path: z
+                .string()
+                .describe("Dot-notation path into template_json (e.g. 'document.body.2.content')"),
+            value: z
+                .unknown()
+                .optional()
+                .describe("New value (scalar, element object, or null to delete)"),
+            value_array: z
+                .array(z.unknown())
+                .optional()
+                .describe("Replace path with this array (for replacing children, body sections, etc.)"),
+        }))
+            .describe("Array of path/value edits to apply"),
+        message: messageParam,
+    }, async ({ template_id, edits, message }) => {
+        const result = await api.patchTemplate(template_id, edits, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_get_example_pages"))
+    server.tool("template_get_example_pages", "Get example output documents attached to a template. Returns transcribed text content AND image URLs for each file so you can see both the text and visual layout of what the template output should look like.", {
+        template_id: z
+            .number()
+            .describe("ID of the template to get example pages for"),
+    }, async ({ template_id }) => {
+        const result = await api.getTemplateExamplePages(template_id);
+        return multiPageImageResult(result);
+    });
+if (shouldRegister("template_get_sample_data"))
+    server.tool("template_get_sample_data", "Get the sample data stored on a template. Sample data is used for rendering template previews when no real team object is available.", {
+        template_id: z
+            .number()
+            .describe("ID of the template to get sample data for"),
+    }, async ({ template_id }) => {
+        const result = await api.getTemplateSampleData(template_id);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_set_sample_data"))
+    server.tool("template_set_sample_data", "Set sample data on a template for preview rendering. Store representative extraction data that matches the schema structure so the template can render a realistic preview. This data is used by template_preview when no team_object_id is provided.", {
+        template_id: z
+            .number()
+            .describe("ID of the template to set sample data on"),
+        sample_data: z
+            .record(z.string(), z.unknown())
+            .describe("Sample data object matching the schema structure. Should contain realistic values " +
+            "for all template variables so the preview renders meaningful content."),
+        message: messageParam,
+    }, async ({ template_id, sample_data, message }) => {
+        const result = await api.setTemplateSampleData(template_id, sample_data, message);
+        return jsonResult(result);
+    });
+if (shouldRegister("template_preview"))
+    server.tool("template_preview", "Capture a screenshot of the rendered template. Returns image URL(s) of the template as it would appear in a document. " +
+        "Use this to visually compare your template against the example output from template_get_example_pages. " +
+        "If no team_object_id is provided, uses the template's sample_data (set via template_set_sample_data) or auto-generated placeholders.", {
+        template_id: z.number().describe("ID of the template to preview"),
+        team_object_id: z
+            .number()
+            .optional()
+            .describe("Optional team object ID to render with real extraction data instead of sample data"),
+        message: messageParam,
+    }, async ({ template_id, team_object_id, message }) => {
+        const result = await api.getTemplatePreview(template_id, team_object_id, message);
+        return imageResult(result);
+    });
+if (shouldRegister("template_preview_html"))
+    server.tool("template_preview_html", "Get the rendered template HTML for fast structural verification. " +
+        "Returns the full HTML of the rendered template as text (~1s, much faster than template_preview). " +
+        "Use this during iterative building to verify structure, field references, and layout. " +
+        "Use template_preview (screenshot) only once at the end for final visual verification.", {
+        template_id: z.number().describe("ID of the template to preview"),
+        team_object_id: z
+            .number()
+            .optional()
+            .describe("Optional team object ID to render with real extraction data instead of sample data"),
+        message: messageParam,
+    }, async ({ template_id, team_object_id, message }) => {
+        const result = await api.getTemplatePreviewHtml(template_id, team_object_id, message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Quality Gate Tools
 // ============================================================================
-server.tool("quality_gate_list", "List all quality gate items for the current schema. Shows each item's key, category, label, description, status, and reviewer analysis. Use this to see which items are pending review.", {}, async () => {
-    const result = await api.listQualityGateItems();
-    return jsonResult(result);
-});
-server.tool("quality_gate_submit_review", "Submit a review for a quality gate item. Set status to 'passed' or 'failed' with detailed analysis explaining your reasoning and evidence.", {
-    quality_gate_item_id: z
-        .number()
-        .describe("ID of the quality gate item to review"),
-    status: z
-        .enum(["passed", "failed"])
-        .describe("Review result: 'passed' if the item meets criteria, 'failed' if not"),
-    analysis: z
-        .string()
-        .describe("Detailed review analysis with evidence. Explain what you checked, " +
-        "what you found, and why you passed or failed the item."),
-    message: messageParam,
-}, async ({ quality_gate_item_id, status, analysis, message }) => {
-    const result = await api.submitQualityGateReview(quality_gate_item_id, status, analysis, message);
-    return jsonResult(result);
-});
+if (shouldRegister("quality_gate_list"))
+    server.tool("quality_gate_list", "List all quality gate items for the current schema. Shows each item's key, category, label, description, status, and reviewer analysis. Use this to see which items are pending review.", {}, async () => {
+        const result = await api.listQualityGateItems();
+        return jsonResult(result);
+    });
+if (shouldRegister("quality_gate_submit_review"))
+    server.tool("quality_gate_submit_review", "Submit a review for a quality gate item. Set status to 'passed' or 'failed' with detailed analysis explaining your reasoning and evidence.", {
+        quality_gate_item_id: z
+            .number()
+            .describe("ID of the quality gate item to review"),
+        status: z
+            .enum(["passed", "failed"])
+            .describe("Review result: 'passed' if the item meets criteria, 'failed' if not"),
+        analysis: z
+            .string()
+            .describe("Detailed review analysis with evidence. Explain what you checked, " +
+            "what you found, and why you passed or failed the item."),
+        message: messageParam,
+    }, async ({ quality_gate_item_id, status, analysis, message }) => {
+        const result = await api.submitQualityGateReview(quality_gate_item_id, status, analysis, message);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Style Library Tools (read-only)
 // ============================================================================
-server.tool("style_list", "List all available style variants organized by element type. Each variant includes a description and structural properties. Call this before building or modifying templates to discover what variants are available. Colors are controlled by the theme, not by variants.", {}, async () => {
-    const result = await api.getStyleList();
-    return jsonResult(result);
-});
+if (shouldRegister("style_list"))
+    server.tool("style_list", "List all available style variants organized by element type. Each variant includes a description and structural properties. Call this before building or modifying templates to discover what variants are available. Colors are controlled by the theme, not by variants.", {}, async () => {
+        const result = await api.getStyleList();
+        return jsonResult(result);
+    });
 // ============================================================================
 // Context Tools (read-only)
 // ============================================================================
-server.tool("context_workflow_inputs", "List all workflow inputs associated with this schema, including file metadata", {}, async () => {
-    const result = await api.getWorkflowInputs();
-    return jsonResult(result);
-});
-server.tool("context_workflow_input_pages", "Get transcribed page content for a specific workflow input (text from document OCR/LLM transcription)", {
-    workflow_input_id: z
-        .number()
-        .describe("ID of the workflow input to get pages for"),
-}, async ({ workflow_input_id }) => {
-    const result = await api.getWorkflowInputPages(workflow_input_id);
-    return jsonResult(result);
-});
-server.tool("context_chat_history", "Get recent chat messages from the schema's collaboration thread", {
-    limit: z
-        .number()
-        .optional()
-        .describe("Maximum number of messages to return (default 50, max 100)"),
-}, async ({ limit }) => {
-    const result = await api.getChatHistory(limit);
-    return jsonResult(result);
-});
+if (shouldRegister("context_workflow_inputs"))
+    server.tool("context_workflow_inputs", "List all workflow inputs associated with this schema, including file metadata", {}, async () => {
+        const result = await api.getWorkflowInputs();
+        return jsonResult(result);
+    });
+if (shouldRegister("context_workflow_input_pages"))
+    server.tool("context_workflow_input_pages", "Get transcribed page content for a specific workflow input (text from document OCR/LLM transcription)", {
+        workflow_input_id: z
+            .number()
+            .describe("ID of the workflow input to get pages for"),
+    }, async ({ workflow_input_id }) => {
+        const result = await api.getWorkflowInputPages(workflow_input_id);
+        return jsonResult(result);
+    });
+if (shouldRegister("context_chat_history"))
+    server.tool("context_chat_history", "Get recent chat messages from the schema's collaboration thread", {
+        limit: z
+            .number()
+            .optional()
+            .describe("Maximum number of messages to return (default 50, max 100)"),
+    }, async ({ limit }) => {
+        const result = await api.getChatHistory(limit);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Start Server
 // ============================================================================
@@ -574,6 +707,7 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Schema MCP Server running on stdio");
+    console.error(`  Role: ${SCHEMA_ROLE}`);
     console.error(`  API URL: ${process.env.SCHEMA_API_URL || "http://localhost:80"}`);
     console.error(`  Schema ID: ${api.SCHEMA_ID}`);
 }

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@thehammer/schema-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newms87/gpt-manager.git",
+    "directory": "mcp-server"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,13 +17,17 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "tsx": "^4.0.0",