@thehammer/schema-mcp-server 1.0.0

package/dist/api-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * HTTP client for communicating with the gpt-manager Laravel API.
+ *
+ * All requests include the Bearer token for SchemaMcpAuthMiddleware
+ * and target the schema-scoped MCP endpoints.
+ */
+declare const SCHEMA_ID: string;
+interface ApiResponse {
+    data?: unknown;
+    schema?: unknown;
+    error?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+export declare function mcpPath(endpoint: string): string;
+export declare function getFullContext(): Promise<ApiResponse>;
+export declare function updateModel(data: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function removeModel(path: string | null, title: string, message?: string): Promise<ApiResponse>;
+export declare function updateRoot(properties: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function getWorkflowInputs(): Promise<ApiResponse>;
+export declare function getWorkflowInputPages(workflowInputId: number): Promise<ApiResponse>;
+export declare function getChatHistory(limit?: number): Promise<ApiResponse>;
+export declare function listAnnotations(): Promise<ApiResponse>;
+export declare function applyAnnotationAction(id: number | null, action: string, data?: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function listBlueprints(): Promise<ApiResponse>;
+export declare function listDirectives(): Promise<ApiResponse>;
+export declare function applyDirectiveAction(id: number | null, action: string, data?: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function listTemplates(): Promise<ApiResponse>;
+export declare function getTemplateDetails(id: number): Promise<ApiResponse>;
+export declare function createTemplate(data: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function applyTemplateAction(id: number, action: string, data?: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function patchTemplate(id: number, edits: Array<Record<string, unknown>>, message?: string): Promise<ApiResponse>;
+export declare function getTemplateExamplePages(templateId: number): Promise<ApiResponse>;
+export declare function getTemplateSampleData(templateId: number): Promise<ApiResponse>;
+export declare function setTemplateSampleData(templateId: number, sampleData: Record<string, unknown>, message?: string): Promise<ApiResponse>;
+export declare function getTemplatePreview(templateId: number, teamObjectId?: number, message?: string): Promise<ApiResponse>;
+export declare function getTemplatePreviewHtml(templateId: number, teamObjectId?: number, message?: string): Promise<ApiResponse>;
+export declare function getStyleList(): Promise<ApiResponse>;
+export declare function listQualityGateItems(): Promise<ApiResponse>;
+export declare function submitQualityGateReview(itemId: number, status: string, analysis: string, message?: string): Promise<ApiResponse>;
+export declare function postProgress(progressMessage: string, phase?: string): Promise<ApiResponse>;
+export { SCHEMA_ID };

package/dist/api-client.js

@@ -0,0 +1,168 @@
+/**
+ * HTTP client for communicating with the gpt-manager Laravel API.
+ *
+ * All requests include the Bearer token for SchemaMcpAuthMiddleware
+ * and target the schema-scoped MCP endpoints.
+ */
+const API_URL = process.env.SCHEMA_API_URL || "http://localhost:80";
+const API_TOKEN = process.env.SCHEMA_API_TOKEN || "";
+const SCHEMA_ID = process.env.SCHEMA_DEFINITION_ID || "";
+if (!API_TOKEN) {
+    console.error("SCHEMA_API_TOKEN is required");
+    process.exit(1);
+}
+if (!SCHEMA_ID) {
+    console.error("SCHEMA_DEFINITION_ID is required");
+    process.exit(1);
+}
+async function apiRequest(method, path, body) {
+    const url = `${API_URL}/api/${path}`;
+    const options = {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_TOKEN}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+    };
+    if (body && method !== "GET") {
+        options.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, options);
+    const json = (await response.json());
+    if (!response.ok) {
+        const errorMessage = json.message || json.error || `HTTP ${response.status}`;
+        throw new Error(`API Error: ${errorMessage}`);
+    }
+    return json;
+}
+// --- Schema MCP Endpoints ---
+export function mcpPath(endpoint) {
+    return `schemas/mcp/${SCHEMA_ID}/${endpoint}`;
+}
+export async function getFullContext() {
+    return apiRequest("GET", mcpPath("full-context"));
+}
+export async function updateModel(data, message) {
+    return apiRequest("POST", mcpPath("update-model"), {
+        ...data,
+        message,
+    });
+}
+export async function removeModel(path, title, message) {
+    return apiRequest("POST", mcpPath("remove-model"), {
+        path,
+        title,
+        message,
+    });
+}
+export async function updateRoot(properties, message) {
+    return apiRequest("POST", mcpPath("update-root"), { properties, message });
+}
+export async function getWorkflowInputs() {
+    return apiRequest("GET", mcpPath("workflow-inputs"));
+}
+export async function getWorkflowInputPages(workflowInputId) {
+    return apiRequest("GET", mcpPath(`workflow-input-pages/${workflowInputId}`));
+}
+export async function getChatHistory(limit) {
+    const query = limit ? `?limit=${limit}` : "";
+    return apiRequest("GET", mcpPath(`chat-history${query}`));
+}
+// --- MCP-Scoped Annotation, Directive, Template Endpoints ---
+export async function listAnnotations() {
+    return apiRequest("GET", mcpPath("annotations"));
+}
+export async function applyAnnotationAction(id, action, data, message) {
+    return apiRequest("POST", mcpPath("annotations/action"), {
+        action,
+        annotation_id: id,
+        ...data,
+        message,
+    });
+}
+export async function listBlueprints() {
+    return apiRequest("GET", mcpPath("blueprints"));
+}
+export async function listDirectives() {
+    return apiRequest("GET", mcpPath("directives"));
+}
+export async function applyDirectiveAction(id, action, data, message) {
+    return apiRequest("POST", mcpPath("directives/action"), {
+        action,
+        directive_id: id,
+        ...data,
+        message,
+    });
+}
+export async function listTemplates() {
+    return apiRequest("GET", mcpPath("templates"));
+}
+export async function getTemplateDetails(id) {
+    return apiRequest("GET", mcpPath(`templates/${id}`));
+}
+export async function createTemplate(data, message) {
+    return apiRequest("POST", mcpPath("templates/action"), {
+        ...data,
+        message,
+    });
+}
+export async function applyTemplateAction(id, action, data, message) {
+    return apiRequest("POST", mcpPath(`templates/${id}/action`), {
+        action,
+        ...data,
+        message,
+    });
+}
+export async function patchTemplate(id, edits, message) {
+    return apiRequest("POST", mcpPath(`templates/${id}/patch`), {
+        edits,
+        message,
+    });
+}
+export async function getTemplateExamplePages(templateId) {
+    return apiRequest("GET", mcpPath(`templates/${templateId}/example-pages`));
+}
+export async function getTemplateSampleData(templateId) {
+    return apiRequest("GET", mcpPath(`templates/${templateId}/sample-data`));
+}
+export async function setTemplateSampleData(templateId, sampleData, message) {
+    return apiRequest("POST", mcpPath(`templates/${templateId}/sample-data`), {
+        sample_data: sampleData,
+        message,
+    });
+}
+export async function getTemplatePreview(templateId, teamObjectId, message) {
+    return apiRequest("POST", mcpPath(`templates/${templateId}/preview`), {
+        ...(teamObjectId ? { team_object_id: teamObjectId } : {}),
+        ...(message ? { message } : {}),
+    });
+}
+export async function getTemplatePreviewHtml(templateId, teamObjectId, message) {
+    return apiRequest("POST", mcpPath(`templates/${templateId}/preview-html`), {
+        ...(teamObjectId ? { team_object_id: teamObjectId } : {}),
+        ...(message ? { message } : {}),
+    });
+}
+// --- Style Library Endpoints ---
+export async function getStyleList() {
+    return apiRequest("GET", mcpPath("style-list"));
+}
+// --- Quality Gate Endpoints ---
+export async function listQualityGateItems() {
+    return apiRequest("GET", mcpPath("quality-gate-items"));
+}
+export async function submitQualityGateReview(itemId, status, analysis, message) {
+    return apiRequest("POST", mcpPath(`quality-gate-items/${itemId}/review`), {
+        status,
+        analysis,
+        message,
+    });
+}
+export async function postProgress(progressMessage, phase) {
+    return apiRequest("POST", mcpPath("progress"), {
+        message: progressMessage,
+        phase,
+    });
+}
+export { SCHEMA_ID };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Schema MCP Server
+ *
+ * Lightweight stdio MCP server that translates Claude Code tool calls
+ * into HTTP requests to the gpt-manager Laravel API.
+ *
+ * Every mutation tool includes an optional `message` parameter — a human-readable
+ * description of what you're doing. This message is logged as an AgentDispatchEvent
+ * and shown in the user's real-time activity feed.
+ *
+ * Environment variables:
+ *   SCHEMA_API_URL - Laravel API base URL (default: http://localhost:80)
+ *   SCHEMA_API_TOKEN - Bearer token for SchemaMcpAuthMiddleware
+ *   SCHEMA_DEFINITION_ID - ID of the schema being built
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,583 @@
+#!/usr/bin/env node
+/**
+ * Schema MCP Server
+ *
+ * Lightweight stdio MCP server that translates Claude Code tool calls
+ * into HTTP requests to the gpt-manager Laravel API.
+ *
+ * Every mutation tool includes an optional `message` parameter — a human-readable
+ * description of what you're doing. This message is logged as an AgentDispatchEvent
+ * and shown in the user's real-time activity feed.
+ *
+ * Environment variables:
+ *   SCHEMA_API_URL - Laravel API base URL (default: http://localhost:80)
+ *   SCHEMA_API_TOKEN - Bearer token for SchemaMcpAuthMiddleware
+ *   SCHEMA_DEFINITION_ID - ID of the schema being built
+ */
+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 server = new McpServer({
+    name: "schema-mcp-server",
+    version: "1.0.0",
+});
+/** Wrap API response data into MCP tool result format. */
+function jsonResult(data) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(data, null, 2) },
+        ],
+    };
+}
+/**
+ * Wrap API response data into MCP tool result format with embedded images.
+ *
+ * Extracts base64-encoded images from the API response and includes them as
+ * MCP image content blocks so the agent can actually see the images (URLs alone
+ * are just text strings to the model). Strips the base64 data from the JSON
+ * text to avoid duplication.
+ */
+function imageResult(data, base64Key = "images_base64") {
+    const content = [];
+    // Extract base64 images from top-level or nested data
+    // Each entry is {data: string, mime_type: string} from the Laravel API
+    const responseData = (data?.data ?? data);
+    const base64Images = responseData?.[base64Key] ?? [];
+    // Add each image as an MCP image content block
+    for (const img of base64Images) {
+        content.push({
+            type: "image",
+            data: img.data,
+            mimeType: img.mime_type || "image/jpeg",
+        });
+    }
+    // Strip base64 data from JSON to avoid bloating the text output
+    const cleanData = JSON.parse(JSON.stringify(data));
+    if (cleanData?.data?.[base64Key]) {
+        delete cleanData.data[base64Key];
+    }
+    content.push({
+        type: "text",
+        text: JSON.stringify(cleanData, null, 2),
+    });
+    return { content };
+}
+/**
+ * Wrap an array of pages (each potentially with images) into MCP image+text result.
+ *
+ * Used for multi-page responses like template_get_example_pages where each page
+ * entry may have its own images_base64 array.
+ */
+function multiPageImageResult(data) {
+    const content = [];
+    const pages = (data?.data ?? []);
+    const cleanPages = [];
+    for (const page of pages) {
+        // Each entry is {data: string, mime_type: string} from the Laravel API
+        const base64Images = page?.images_base64 ?? [];
+        // Add page label before its images
+        if (base64Images.length > 0 && page.filename) {
+            content.push({
+                type: "text",
+                text: `--- ${page.filename} ---`,
+            });
+        }
+        for (const img of base64Images) {
+            content.push({
+                type: "image",
+                data: img.data,
+                mimeType: img.mime_type || "image/jpeg",
+            });
+        }
+        // Strip base64 from the clean copy
+        const cleanPage = { ...page };
+        delete cleanPage.images_base64;
+        cleanPages.push(cleanPage);
+    }
+    // Add text summary at the end
+    content.push({
+        type: "text",
+        text: JSON.stringify({ data: cleanPages }, null, 2),
+    });
+    return { content };
+}
+/** Filter out undefined values from an object (for optional update params). */
+function definedOnly(data) {
+    return Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined));
+}
+/** Common message param for all mutation tools. */
+const messageParam = z
+    .string()
+    .optional()
+    .describe("Human-readable description of what you're doing (shown in the user's activity feed)");
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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'.`,
+                    }),
+                },
+            ],
+        };
+    }
+    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);
+});
+// ============================================================================
+// 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
+            .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);
+});
+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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// 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);
+});
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Schema MCP Server running on stdio");
+    console.error(`  API URL: ${process.env.SCHEMA_API_URL || "http://localhost:80"}`);
+    console.error(`  Schema ID: ${api.SCHEMA_ID}`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@thehammer/schema-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "schema-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}