@hotmeshio/long-tail 0.1.0

package/build/services/mcp/server.d.ts

@@ -0,0 +1,26 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create the Long Tail Human Queue MCP server.
+ *
+ * Registers five tools that expose the escalation API:
+ * - escalate_to_human — create a new escalation (fire-and-forget)
+ * - check_resolution — check escalation status
+ * - get_available_work — list available escalations by role
+ * - claim_and_resolve — claim + resolve in one step
+ * - escalate_and_wait — create escalation and return signal for durable wait
+ *
+ * The server is created with tools registered but no transport
+ * auto-connected. Callers connect a transport programmatically
+ * or via the Streamable HTTP endpoint.
+ */
+export declare function createHumanQueueServer(options?: {
+    name?: string;
+}): Promise<McpServer>;
+/**
+ * Get the current MCP server instance.
+ */
+export declare function getServer(): McpServer | null;
+/**
+ * Stop the MCP server and release resources.
+ */
+export declare function stopServer(): Promise<void>;

package/build/services/mcp/server.js

@@ -0,0 +1,286 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHumanQueueServer = createHumanQueueServer;
+exports.getServer = getServer;
+exports.stopServer = stopServer;
+const crypto = __importStar(require("crypto"));
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const logger_1 = require("../logger");
+const escalationService = __importStar(require("../escalation"));
+let server = null;
+// ── Schemas (extracted to break TS2589 deep-instantiation in registerTool generics) ──
+const escalateSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
+    message: zod_1.z.string().describe('Description of what needs human review'),
+    data: zod_1.z.record(zod_1.z.any()).optional().describe('Contextual data for the reviewer'),
+    type: zod_1.z.string().optional().default('mcp').describe('Escalation type classification'),
+    subtype: zod_1.z.string().optional().default('tool_call').describe('Escalation subtype'),
+    priority: zod_1.z.number().min(1).max(4).optional().default(2)
+        .describe('Priority: 1 (highest) to 4 (lowest)'),
+});
+const checkResolutionSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation ID to check'),
+});
+const getAvailableWorkSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Role to filter by'),
+    limit: zod_1.z.number().optional().default(10).describe('Max results to return'),
+});
+const claimAndResolveSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation ID to claim and resolve'),
+    resolver_id: zod_1.z.string().describe('Identifier for who/what is resolving'),
+    payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
+});
+const escalateAndWaitSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
+    message: zod_1.z.string().describe('Description of what input is needed from the human'),
+    form_schema: zod_1.z.record(zod_1.z.any()).optional()
+        .describe('JSON Schema for the resolver form. Use format:"password" for sensitive fields.'),
+    data: zod_1.z.record(zod_1.z.any()).optional().describe('Contextual data for the reviewer'),
+    assigned_to: zod_1.z.string().optional().describe('Auto-assign to a specific user'),
+    type: zod_1.z.string().optional().default('mcp').describe('Escalation type classification'),
+    subtype: zod_1.z.string().optional().default('wait_for_human').describe('Escalation subtype'),
+    priority: zod_1.z.number().min(1).max(4).optional().default(1)
+        .describe('Priority: 1 (highest) to 4 (lowest)'),
+}).passthrough();
+/**
+ * Create the Long Tail Human Queue MCP server.
+ *
+ * Registers five tools that expose the escalation API:
+ * - escalate_to_human — create a new escalation (fire-and-forget)
+ * - check_resolution — check escalation status
+ * - get_available_work — list available escalations by role
+ * - claim_and_resolve — claim + resolve in one step
+ * - escalate_and_wait — create escalation and return signal for durable wait
+ *
+ * The server is created with tools registered but no transport
+ * auto-connected. Callers connect a transport programmatically
+ * or via the Streamable HTTP endpoint.
+ */
+async function createHumanQueueServer(options) {
+    if (server)
+        return server;
+    const name = options?.name || 'long-tail-human-queue';
+    server = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    // ── escalate_to_human ───────────────────────────────────────────────
+    server.registerTool('escalate_to_human', {
+        title: 'Escalate to Human',
+        description: 'Create a new escalation for human review. Returns the escalation ID.',
+        inputSchema: escalateSchema,
+    }, async (args) => {
+        const escalation = await escalationService.createEscalation({
+            type: args.type || 'mcp',
+            subtype: args.subtype || 'tool_call',
+            description: args.message,
+            priority: args.priority,
+            role: args.role,
+            envelope: JSON.stringify(args.data || {}),
+            metadata: { source: 'mcp_server' },
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        escalation_id: escalation.id,
+                        status: escalation.status,
+                        role: escalation.role,
+                        created_at: escalation.created_at,
+                    }),
+                }],
+        };
+    });
+    // ── check_resolution ────────────────────────────────────────────────
+    server.registerTool('check_resolution', {
+        title: 'Check Escalation Resolution',
+        description: 'Check the status of an escalation. Returns status and resolver payload if resolved.',
+        inputSchema: checkResolutionSchema,
+    }, async (args) => {
+        const escalation = await escalationService.getEscalation(args.escalation_id);
+        if (!escalation) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Escalation not found' }),
+                    }],
+                isError: true,
+            };
+        }
+        const result = {
+            escalation_id: escalation.id,
+            status: escalation.status,
+        };
+        if (escalation.status === 'resolved' && escalation.resolver_payload) {
+            try {
+                result.resolver_payload = JSON.parse(escalation.resolver_payload);
+            }
+            catch {
+                result.resolver_payload = escalation.resolver_payload;
+            }
+            result.resolved_at = escalation.resolved_at;
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    // ── get_available_work ──────────────────────────────────────────────
+    server.registerTool('get_available_work', {
+        title: 'Get Available Work',
+        description: 'List available escalations for a role. Returns pending, unassigned escalations.',
+        inputSchema: getAvailableWorkSchema,
+    }, async (args) => {
+        const { escalations } = await escalationService.listAvailableEscalations({
+            role: args.role,
+            limit: args.limit,
+        });
+        const items = escalations.map((e) => ({
+            escalation_id: e.id,
+            type: e.type,
+            subtype: e.subtype,
+            description: e.description,
+            priority: e.priority,
+            role: e.role,
+            created_at: e.created_at,
+        }));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ count: items.length, escalations: items }),
+                }],
+        };
+    });
+    // ── claim_and_resolve ───────────────────────────────────────────────
+    server.registerTool('claim_and_resolve', {
+        title: 'Claim and Resolve',
+        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation.',
+        inputSchema: claimAndResolveSchema,
+    }, async (args) => {
+        const claimed = await escalationService.claimEscalation(args.escalation_id, args.resolver_id, 5);
+        if (!claimed) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Escalation not available for claim' }),
+                    }],
+                isError: true,
+            };
+        }
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        if (!resolved) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Failed to resolve escalation' }),
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        escalation_id: resolved.id,
+                        status: resolved.status,
+                        resolved_at: resolved.resolved_at,
+                    }),
+                }],
+        };
+    });
+    // ── escalate_and_wait ──────────────────────────────────────────────
+    server.registerTool('escalate_and_wait', {
+        title: 'Escalate and Wait',
+        description: 'Create an escalation and pause the workflow until a human responds. ' +
+            'Returns a signal ID that the workflow uses to wait. ' +
+            'Preferred over escalate_to_human + check_resolution polling.',
+        inputSchema: escalateAndWaitSchema,
+    }, async (args) => {
+        const signalId = `wait-for-human-${crypto.randomUUID()}`;
+        // YAML workflows inject _yaml_signal_routing to override Durable's signalId-based routing
+        const yamlRouting = args._yaml_signal_routing;
+        const signalRouting = yamlRouting
+            ? { ...yamlRouting, signalId }
+            : { signalId };
+        const metadata = {
+            source: 'mcp_server',
+            signal_routing: signalRouting,
+        };
+        if (args.form_schema) {
+            metadata.form_schema = args.form_schema;
+        }
+        const escalation = await escalationService.createEscalation({
+            type: args.type || 'mcp',
+            subtype: args.subtype || 'wait_for_human',
+            description: args.message,
+            priority: args.priority,
+            role: args.role,
+            envelope: JSON.stringify(args.data || {}),
+            metadata,
+            workflow_type: yamlRouting?.workflowType,
+            workflow_id: yamlRouting?.workflowId,
+            task_queue: yamlRouting?.taskQueue,
+        });
+        if (args.assigned_to) {
+            await escalationService.claimEscalation(escalation.id, args.assigned_to, 240);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        type: 'waitFor',
+                        signalId,
+                        escalationId: escalation.id,
+                    }),
+                }],
+        };
+    });
+    logger_1.loggerRegistry.info(`[lt-mcp:server] ${name} ready (5 tools registered)`);
+    return server;
+}
+/**
+ * Get the current MCP server instance.
+ */
+function getServer() {
+    return server;
+}
+/**
+ * Stop the MCP server and release resources.
+ */
+async function stopServer() {
+    if (server) {
+        await server.close();
+        server = null;
+        logger_1.loggerRegistry.info('[lt-mcp:server] stopped');
+    }
+}

package/build/services/mcp/sql.d.ts

@@ -0,0 +1,12 @@
+export declare const CREATE_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, metadata, tags)\n  VALUES ($1, $2, $3, $4, $5, $6, $7)\n  RETURNING *";
+export declare const GET_MCP_SERVER = "\n  SELECT * FROM lt_mcp_servers WHERE id = $1";
+export declare const GET_MCP_SERVER_BY_NAME = "\n  SELECT * FROM lt_mcp_servers WHERE name = $1";
+export declare const DELETE_MCP_SERVER = "\n  DELETE FROM lt_mcp_servers WHERE id = $1";
+export declare const UPDATE_STATUS_CONNECTED = "\n  UPDATE lt_mcp_servers\n  SET status = $2, last_connected_at = NOW(), tool_manifest = $3\n  WHERE id = $1";
+export declare const UPDATE_STATUS = "\n  UPDATE lt_mcp_servers SET status = $2 WHERE id = $1";
+export declare const GET_AUTO_CONNECT_SERVERS = "\n  SELECT * FROM lt_mcp_servers\n  WHERE auto_connect = true\n  ORDER BY name";
+export declare const HEALTH_TASK_COUNTS = "\n  SELECT status, COUNT(*)::int AS count\n  FROM lt_tasks GROUP BY status ORDER BY status";
+export declare const HEALTH_ESCALATION_COUNTS = "\n  SELECT status, COUNT(*)::int AS count\n  FROM lt_escalations GROUP BY status ORDER BY status";
+export declare const HEALTH_ACTIVE_WORKFLOW_TYPES = "\n  SELECT DISTINCT workflow_type FROM lt_tasks\n  WHERE status IN ('pending', 'in_progress')\n  ORDER BY workflow_type";
+export declare const HEALTH_RECENT_ACTIVITY = "\n  SELECT\n    COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '1 hour')::int AS tasks_created_1h,\n    COUNT(*) FILTER (WHERE completed_at > NOW() - INTERVAL '1 hour')::int AS tasks_completed_1h,\n    COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '24 hours')::int AS tasks_created_24h,\n    COUNT(*) FILTER (WHERE completed_at > NOW() - INTERVAL '24 hours')::int AS tasks_completed_24h\n  FROM lt_tasks";
+export declare const SEED_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())\n  ON CONFLICT (name) DO UPDATE SET\n    tool_manifest = EXCLUDED.tool_manifest,\n    metadata = EXCLUDED.metadata,\n    description = EXCLUDED.description,\n    tags = EXCLUDED.tags,\n    compile_hints = EXCLUDED.compile_hints,\n    credential_providers = EXCLUDED.credential_providers,\n    status = 'connected',\n    last_connected_at = NOW()";

package/build/services/mcp/sql.js

@@ -0,0 +1,59 @@
+"use strict";
+// ─── MCP server CRUD ────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEED_MCP_SERVER = exports.HEALTH_RECENT_ACTIVITY = exports.HEALTH_ACTIVE_WORKFLOW_TYPES = exports.HEALTH_ESCALATION_COUNTS = exports.HEALTH_TASK_COUNTS = exports.GET_AUTO_CONNECT_SERVERS = exports.UPDATE_STATUS = exports.UPDATE_STATUS_CONNECTED = exports.DELETE_MCP_SERVER = exports.GET_MCP_SERVER_BY_NAME = exports.GET_MCP_SERVER = exports.CREATE_MCP_SERVER = void 0;
+exports.CREATE_MCP_SERVER = `
+  INSERT INTO lt_mcp_servers
+    (name, description, transport_type, transport_config, auto_connect, metadata, tags)
+  VALUES ($1, $2, $3, $4, $5, $6, $7)
+  RETURNING *`;
+exports.GET_MCP_SERVER = `
+  SELECT * FROM lt_mcp_servers WHERE id = $1`;
+exports.GET_MCP_SERVER_BY_NAME = `
+  SELECT * FROM lt_mcp_servers WHERE name = $1`;
+exports.DELETE_MCP_SERVER = `
+  DELETE FROM lt_mcp_servers WHERE id = $1`;
+// ─── Status updates ─────────────────────────────────────────────────────────
+exports.UPDATE_STATUS_CONNECTED = `
+  UPDATE lt_mcp_servers
+  SET status = $2, last_connected_at = NOW(), tool_manifest = $3
+  WHERE id = $1`;
+exports.UPDATE_STATUS = `
+  UPDATE lt_mcp_servers SET status = $2 WHERE id = $1`;
+// ─── Discovery ──────────────────────────────────────────────────────────────
+exports.GET_AUTO_CONNECT_SERVERS = `
+  SELECT * FROM lt_mcp_servers
+  WHERE auto_connect = true
+  ORDER BY name`;
+// ─── System health (used by db-server.ts) ───────────────────────────────────
+exports.HEALTH_TASK_COUNTS = `
+  SELECT status, COUNT(*)::int AS count
+  FROM lt_tasks GROUP BY status ORDER BY status`;
+exports.HEALTH_ESCALATION_COUNTS = `
+  SELECT status, COUNT(*)::int AS count
+  FROM lt_escalations GROUP BY status ORDER BY status`;
+exports.HEALTH_ACTIVE_WORKFLOW_TYPES = `
+  SELECT DISTINCT workflow_type FROM lt_tasks
+  WHERE status IN ('pending', 'in_progress')
+  ORDER BY workflow_type`;
+exports.HEALTH_RECENT_ACTIVITY = `
+  SELECT
+    COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '1 hour')::int AS tasks_created_1h,
+    COUNT(*) FILTER (WHERE completed_at > NOW() - INTERVAL '1 hour')::int AS tasks_completed_1h,
+    COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '24 hours')::int AS tasks_created_24h,
+    COUNT(*) FILTER (WHERE completed_at > NOW() - INTERVAL '24 hours')::int AS tasks_completed_24h
+  FROM lt_tasks`;
+// ─── Seed (used by system/seed.ts) ──────────────────────────────────────────
+exports.SEED_MCP_SERVER = `
+  INSERT INTO lt_mcp_servers
+    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)
+  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())
+  ON CONFLICT (name) DO UPDATE SET
+    tool_manifest = EXCLUDED.tool_manifest,
+    metadata = EXCLUDED.metadata,
+    description = EXCLUDED.description,
+    tags = EXCLUDED.tags,
+    compile_hints = EXCLUDED.compile_hints,
+    credential_providers = EXCLUDED.credential_providers,
+    status = 'connected',
+    last_connected_at = NOW()`;

package/build/services/mcp/types.d.ts

@@ -0,0 +1,17 @@
+/** Type definitions for the MCP (Model Context Protocol) service. */
+export interface CreateMcpServerInput {
+    name: string;
+    description?: string;
+    transport_type: 'stdio' | 'sse';
+    transport_config: Record<string, any>;
+    auto_connect?: boolean;
+    metadata?: Record<string, any>;
+    tags?: string[];
+}
+export interface BuiltInMcpAdapterOptions {
+    server?: {
+        enabled?: boolean;
+        name?: string;
+    };
+    autoConnect?: string[];
+}

package/build/services/mcp/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the MCP (Model Context Protocol) service. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/services/mcp/vision-server.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create the Document Vision MCP server.
+ *
+ * Returns a fresh McpServer instance each time. The MCP SDK only allows
+ * one transport per server, so each consumer (triage activities, pipeline
+ * workers, tests) needs its own instance to avoid "already connected" errors.
+ */
+export declare function createVisionServer(options?: {
+    name?: string;
+}): Promise<McpServer>;
+/**
+ * Stop a Vision MCP server instance and release resources.
+ */
+export declare function stopVisionServer(): Promise<void>;

package/build/services/mcp/vision-server.js

@@ -0,0 +1,214 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVisionServer = createVisionServer;
+exports.stopVisionServer = stopVisionServer;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const sharp_1 = __importDefault(require("sharp"));
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const llm_1 = require("../llm");
+const defaults_1 = require("../../modules/defaults");
+const logger_1 = require("../logger");
+const prompts_1 = require("../../system/mcp-servers/prompts");
+// ── Resolve fixtures directory ──────────────────────────────────────────────
+function fixturesDir() {
+    // Works from both ts-node (root) and compiled (build/) contexts
+    const candidates = [
+        path.join(__dirname, '..', '..', 'tests', 'fixtures'),
+        path.join(__dirname, '..', '..', '..', 'tests', 'fixtures'),
+    ];
+    for (const dir of candidates) {
+        if (fs.existsSync(dir))
+            return dir;
+    }
+    return candidates[0];
+}
+// ── Schemas (extracted to break TS2589 deep-instantiation in registerTool generics) ──
+const listDocumentPagesSchema = zod_1.z.object({});
+const rotatePageSchema = zod_1.z.object({
+    image_ref: zod_1.z.string().describe('Storage reference to the image to rotate'),
+    degrees: zod_1.z.number().int().describe('Rotation degrees (90, 180, 270)'),
+});
+const translateContentSchema = zod_1.z.object({
+    content: zod_1.z.string().describe('The content text to translate'),
+    target_language: zod_1.z.string().describe('Target language code (e.g. "en", "es")'),
+});
+/**
+ * List available document page images from storage.
+ */
+async function listDocumentPages() {
+    const dir = fixturesDir();
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter(f => f.endsWith('.png') || f.endsWith('.jpg'));
+}
+/**
+ * Register all three vision tools on an McpServer instance.
+ */
+function registerTools(srv) {
+    // ── list_document_pages ─────────────────────────────────────────
+    srv.registerTool('list_document_pages', {
+        title: 'List Document Pages',
+        description: 'List available document page images from storage. Returns an array of image references.',
+        inputSchema: listDocumentPagesSchema,
+    }, async (_args) => {
+        const pages = await listDocumentPages();
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ pages }) }],
+        };
+    });
+    // ── rotate_page ───────────────────────────────────────────────
+    srv.registerTool('rotate_page', {
+        title: 'Rotate Page',
+        description: 'Rotate a document page image by the given degrees using sharp. Writes the corrected image to storage and returns the new image reference.',
+        inputSchema: rotatePageSchema,
+    }, async (args) => {
+        const dir = fixturesDir();
+        const srcPath = path.join(dir, args.image_ref);
+        if (!fs.existsSync(srcPath)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Image not found: ${args.image_ref}` }),
+                    }],
+            };
+        }
+        // Build output filename: page1_upside_down.png → page1_upside_down_rotated.png
+        const ext = path.extname(args.image_ref);
+        const base = path.basename(args.image_ref, ext);
+        const rotatedName = `${base}_rotated${ext}`;
+        const destPath = path.join(dir, rotatedName);
+        await (0, sharp_1.default)(srcPath)
+            .rotate(args.degrees)
+            .toFile(destPath);
+        logger_1.loggerRegistry.info(`[lt-mcp:vision-server] rotated ${args.image_ref} by ${args.degrees}° → ${rotatedName}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        rotated_ref: rotatedName,
+                        degrees: args.degrees,
+                        source_ref: args.image_ref,
+                    }),
+                }],
+        };
+    });
+    // ── translate_content ──────────────────────────────────────────
+    srv.registerTool('translate_content', {
+        title: 'Translate Content',
+        description: 'Translate content text to the target language using OpenAI. Returns the translated content and detected source language.',
+        inputSchema: translateContentSchema,
+    }, async (args) => {
+        const { hasLLMApiKey } = await Promise.resolve().then(() => __importStar(require('../llm')));
+        if (!hasLLMApiKey(defaults_1.LLM_MODEL_SECONDARY)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            translated_content: args.content,
+                            source_language: 'unknown',
+                            target_language: args.target_language,
+                            note: 'LLM API key not configured — returned content unchanged',
+                        }),
+                    }],
+            };
+        }
+        const response = await (0, llm_1.callLLM)({
+            model: defaults_1.LLM_MODEL_SECONDARY,
+            messages: [
+                {
+                    role: 'system',
+                    content: (0, prompts_1.TRANSLATE_SYSTEM_PROMPT)(args.target_language),
+                },
+                { role: 'user', content: args.content },
+            ],
+            max_tokens: defaults_1.LLM_MAX_TOKENS_VISION,
+        });
+        const raw = response.content || '';
+        try {
+            const cleaned = raw.replace(/^```json\n?|\n?```$/g, '').trim();
+            const parsed = JSON.parse(cleaned);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            translated_content: parsed.translated_content || args.content,
+                            source_language: parsed.source_language || 'unknown',
+                            target_language: args.target_language,
+                        }),
+                    }],
+            };
+        }
+        catch {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            translated_content: raw,
+                            source_language: 'unknown',
+                            target_language: args.target_language,
+                        }),
+                    }],
+            };
+        }
+    });
+}
+/**
+ * Create the Document Vision MCP server.
+ *
+ * Returns a fresh McpServer instance each time. The MCP SDK only allows
+ * one transport per server, so each consumer (triage activities, pipeline
+ * workers, tests) needs its own instance to avoid "already connected" errors.
+ */
+async function createVisionServer(options) {
+    const name = options?.name || 'long-tail-document-vision';
+    const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    registerTools(instance);
+    logger_1.loggerRegistry.info(`[lt-mcp:vision-server] ${name} ready (3 tools registered)`);
+    return instance;
+}
+/**
+ * Stop a Vision MCP server instance and release resources.
+ */
+async function stopVisionServer() {
+    // No-op — instances are now independent and cleaned up by their callers
+    logger_1.loggerRegistry.info('[lt-mcp:vision-server] stopped');
+}

package/build/services/mcp/workflow-compiler-server.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create the Workflow Compiler MCP server.
+ *
+ * Provides tools for converting MCP tool call sequences into
+ * deterministic HotMesh YAML workflows:
+ * - convert_execution_to_yaml — analyze execution and generate YAML
+ * - deploy_yaml_workflow — deploy and optionally activate
+ * - list_yaml_workflows — list stored YAML workflows
+ */
+export declare function createWorkflowCompilerServer(options?: {
+    name?: string;
+}): Promise<McpServer>;
+export declare function getWorkflowCompilerServer(): McpServer | null;
+export declare function stopWorkflowCompilerServer(): Promise<void>;