@hotmeshio/long-tail 0.1.0

package/build/services/mcp/client/tools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Call a tool on a connected server.
+ * Resolves the server by ID or name, auto-connecting built-in servers.
+ */
+export declare function callServerTool(serverId: string, toolName: string, args: Record<string, any>, authContext?: {
+    userId?: string;
+    delegationToken?: string;
+}): Promise<any>;
+/**
+ * Return a map of tool functions suitable for proxyActivities().
+ *
+ * Each tool is wrapped as:
+ *   `mcp_{serverName}_{toolName}(args) => Promise<any>`
+ *
+ * Usage in a workflow:
+ * ```typescript
+ * const tools = await mcpClient.toolActivities(serverId);
+ * const proxied = Durable.workflow.proxyActivities({ activities: tools });
+ * const result = await proxied.mcp_myserver_search({ query: 'hello' });
+ * ```
+ */
+export declare function toolActivities(serverId: string): Promise<Record<string, (args: Record<string, any>) => Promise<any>>>;

package/build/services/mcp/client/tools.js

@@ -0,0 +1,118 @@
+"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.callServerTool = callServerTool;
+exports.toolActivities = toolActivities;
+const logger_1 = require("../../logger");
+const defaults_1 = require("../../../modules/defaults");
+const context_1 = require("../../iam/context");
+const mcpDbService = __importStar(require("../db"));
+const connection_1 = require("./connection");
+/**
+ * Derive auth context from the ambient ToolContext (AsyncLocalStorage).
+ * Returns undefined when no ToolContext is active (e.g., direct CLI calls).
+ */
+function deriveAuthFromToolContext() {
+    const ctx = (0, context_1.getToolContext)();
+    if (!ctx?.principal.id)
+        return undefined;
+    return {
+        userId: ctx.principal.id,
+        delegationToken: ctx.credentials.delegationToken,
+    };
+}
+/**
+ * Call a tool on a connected server.
+ * Resolves the server by ID or name, auto-connecting built-in servers.
+ */
+async function callServerTool(serverId, toolName, args, authContext) {
+    const client = await (0, connection_1.resolveClient)(serverId);
+    if (!client) {
+        throw new Error(`MCP server ${serverId} is not connected`);
+    }
+    // Resolve auth: explicit authContext > ambient ToolContext > none
+    const resolvedAuth = authContext ?? deriveAuthFromToolContext();
+    // Inject auth context as a hidden _auth argument when available
+    const toolArgs = resolvedAuth?.userId || resolvedAuth?.delegationToken
+        ? { ...args, _auth: { userId: resolvedAuth.userId, token: resolvedAuth.delegationToken } }
+        : args;
+    // Audit: log tool invocation with principal identity
+    const ctx = (0, context_1.getToolContext)();
+    if (ctx?.principal.id) {
+        logger_1.loggerRegistry.debug(`[lt-mcp:audit] ${toolName} on ${serverId} by ${ctx.principal.type}:${ctx.principal.id}`);
+    }
+    const result = await client.callTool({ name: toolName, arguments: toolArgs }, undefined, { timeout: defaults_1.MCP_TOOL_TIMEOUT_MS });
+    // Extract text content from MCP response
+    if (Array.isArray(result.content)) {
+        const textContent = result.content.find((c) => c.type === 'text');
+        if (textContent && 'text' in textContent) {
+            try {
+                return JSON.parse(textContent.text);
+            }
+            catch {
+                return textContent.text;
+            }
+        }
+    }
+    return result.content;
+}
+/**
+ * Return a map of tool functions suitable for proxyActivities().
+ *
+ * Each tool is wrapped as:
+ *   `mcp_{serverName}_{toolName}(args) => Promise<any>`
+ *
+ * Usage in a workflow:
+ * ```typescript
+ * const tools = await mcpClient.toolActivities(serverId);
+ * const proxied = Durable.workflow.proxyActivities({ activities: tools });
+ * const result = await proxied.mcp_myserver_search({ query: 'hello' });
+ * ```
+ */
+async function toolActivities(serverId) {
+    const server = await mcpDbService.getMcpServer(serverId);
+    if (!server)
+        throw new Error(`MCP server ${serverId} not found`);
+    const tools = server.tool_manifest || await (0, connection_1.listServerTools)(serverId);
+    const activities = {};
+    const safeName = server.name.replace(/[^a-zA-Z0-9]/g, '_');
+    for (const tool of tools) {
+        const activityName = `mcp_${safeName}_${tool.name.replace(/[^a-zA-Z0-9]/g, '_')}`;
+        activities[activityName] = async (args) => {
+            return callServerTool(serverId, tool.name, args);
+        };
+    }
+    return activities;
+}

package/build/services/mcp/db-server/index.d.ts

@@ -0,0 +1,25 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Create the Long Tail DB Query MCP server.
+ *
+ * Provides read-only query tools against the lt_* tables:
+ * - find_tasks -- search tasks by status, workflow type, or origin
+ * - find_escalations -- search escalations by status, role, type
+ * - get_process_summary -- aggregate process view grouped by origin_id
+ * - get_escalation_stats -- real-time escalation statistics
+ * - get_workflow_types -- list registered workflow configurations
+ * - get_system_health -- overall system health snapshot
+ */
+export declare function createDbServer(options?: {
+    name?: string;
+    /** When true, skip the singleton cache and create a dedicated instance. */
+    fresh?: boolean;
+}): Promise<McpServer>;
+/**
+ * Get the current DB MCP server instance.
+ */
+export declare function getDbServer(): McpServer | null;
+/**
+ * Stop the DB MCP server and release resources.
+ */
+export declare function stopDbServer(): Promise<void>;

package/build/services/mcp/db-server/index.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDbServer = createDbServer;
+exports.getDbServer = getDbServer;
+exports.stopDbServer = stopDbServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const logger_1 = require("../../logger");
+const tools_1 = require("./tools");
+let server = null;
+/**
+ * Create the Long Tail DB Query MCP server.
+ *
+ * Provides read-only query tools against the lt_* tables:
+ * - find_tasks -- search tasks by status, workflow type, or origin
+ * - find_escalations -- search escalations by status, role, type
+ * - get_process_summary -- aggregate process view grouped by origin_id
+ * - get_escalation_stats -- real-time escalation statistics
+ * - get_workflow_types -- list registered workflow configurations
+ * - get_system_health -- overall system health snapshot
+ */
+async function createDbServer(options) {
+    if (server && !options?.fresh)
+        return server;
+    const name = options?.name || 'long-tail-db-query';
+    const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    // Only cache as the singleton when not a fresh (dedicated) instance
+    if (!options?.fresh) {
+        server = instance;
+    }
+    (0, tools_1.registerDbTools)(instance);
+    logger_1.loggerRegistry.info(`[lt-mcp:db-server] ${name} ready (6 tools registered)`);
+    return instance;
+}
+/**
+ * Get the current DB MCP server instance.
+ */
+function getDbServer() {
+    return server;
+}
+/**
+ * Stop the DB MCP server and release resources.
+ */
+async function stopDbServer() {
+    if (server) {
+        await server.close();
+        server = null;
+        logger_1.loggerRegistry.info('[lt-mcp:db-server] stopped');
+    }
+}

package/build/services/mcp/db-server/schemas.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export declare const findTasksSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<["pending", "in_progress", "needs_intervention", "completed", "failed"]>>;
+    workflow_type: z.ZodOptional<z.ZodString>;
+    workflow_id: z.ZodOptional<z.ZodString>;
+    origin_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    status?: "pending" | "in_progress" | "completed" | "needs_intervention" | "failed" | undefined;
+    workflow_type?: string | undefined;
+    workflow_id?: string | undefined;
+    origin_id?: string | undefined;
+}, {
+    status?: "pending" | "in_progress" | "completed" | "needs_intervention" | "failed" | undefined;
+    workflow_type?: string | undefined;
+    limit?: number | undefined;
+    workflow_id?: string | undefined;
+    origin_id?: string | undefined;
+}>;
+export declare const findEscalationsSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<["pending", "resolved"]>>;
+    role: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    role?: string | undefined;
+    status?: "pending" | "resolved" | undefined;
+    type?: string | undefined;
+    priority?: number | undefined;
+}, {
+    role?: string | undefined;
+    status?: "pending" | "resolved" | undefined;
+    type?: string | undefined;
+    priority?: number | undefined;
+    limit?: number | undefined;
+}>;
+export declare const getProcessSummarySchema: z.ZodObject<{
+    workflow_type: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    workflow_type?: string | undefined;
+}, {
+    workflow_type?: string | undefined;
+    limit?: number | undefined;
+}>;
+export declare const getEscalationStatsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getWorkflowTypesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getSystemHealthSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;

package/build/services/mcp/db-server/schemas.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSystemHealthSchema = exports.getWorkflowTypesSchema = exports.getEscalationStatsSchema = exports.getProcessSummarySchema = exports.findEscalationsSchema = exports.findTasksSchema = void 0;
+const zod_1 = require("zod");
+const defaults_1 = require("../../../modules/defaults");
+// Schemas extracted to break TS2589 deep-instantiation in registerTool generics
+exports.findTasksSchema = zod_1.z.object({
+    status: zod_1.z.enum(['pending', 'in_progress', 'needs_intervention', 'completed', 'failed'])
+        .optional().describe('Filter by task status'),
+    workflow_type: zod_1.z.string().optional().describe('Filter by workflow type (e.g. "reviewContent")'),
+    workflow_id: zod_1.z.string().optional().describe('Filter by workflow execution ID'),
+    origin_id: zod_1.z.string().optional().describe('Filter by origin/process ID to see all tasks in a process'),
+    limit: zod_1.z.number().int().min(1).max(defaults_1.QUERY_LIMIT_MAX).optional().default(defaults_1.QUERY_LIMIT_DEFAULT)
+        .describe('Maximum number of results'),
+});
+exports.findEscalationsSchema = zod_1.z.object({
+    status: zod_1.z.enum(['pending', 'resolved']).optional()
+        .describe('Filter by escalation status'),
+    role: zod_1.z.string().optional().describe('Filter by assigned role (e.g. "reviewer", "engineer")'),
+    type: zod_1.z.string().optional().describe('Filter by escalation type'),
+    priority: zod_1.z.number().int().min(1).max(4).optional()
+        .describe('Filter by priority (1=critical, 4=low)'),
+    limit: zod_1.z.number().int().min(1).max(defaults_1.QUERY_LIMIT_MAX).optional().default(defaults_1.QUERY_LIMIT_DEFAULT)
+        .describe('Maximum number of results'),
+});
+exports.getProcessSummarySchema = zod_1.z.object({
+    workflow_type: zod_1.z.string().optional()
+        .describe('Filter processes to those containing this workflow type'),
+    limit: zod_1.z.number().int().min(1).max(defaults_1.QUERY_LIMIT_MAX).optional().default(defaults_1.QUERY_LIMIT_DEFAULT)
+        .describe('Maximum number of processes'),
+});
+exports.getEscalationStatsSchema = zod_1.z.object({});
+exports.getWorkflowTypesSchema = zod_1.z.object({});
+exports.getSystemHealthSchema = zod_1.z.object({});

package/build/services/mcp/db-server/tools.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register all DB query tools on the given MCP server instance.
+ */
+export declare function registerDbTools(instance: McpServer): void;

package/build/services/mcp/db-server/tools.js

@@ -0,0 +1,224 @@
+"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.registerDbTools = registerDbTools;
+const db_1 = require("../../db");
+const taskService = __importStar(require("../../task"));
+const escalationService = __importStar(require("../../escalation"));
+const configService = __importStar(require("../../config"));
+const sql_1 = require("../sql");
+const schemas_1 = require("./schemas");
+/**
+ * Register all DB query tools on the given MCP server instance.
+ */
+function registerDbTools(instance) {
+    // find_tasks
+    instance.registerTool('find_tasks', {
+        title: 'Find Tasks',
+        description: 'Search tasks with optional filters. Returns task records with workflow_id, status, ' +
+            'workflow_type, milestones, created/completed timestamps, and metadata.',
+        inputSchema: schemas_1.findTasksSchema,
+    }, async (args) => {
+        const { tasks, total } = await taskService.listTasks({
+            status: args.status,
+            workflow_type: args.workflow_type,
+            workflow_id: args.workflow_id,
+            origin_id: args.origin_id,
+            limit: args.limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        total,
+                        count: tasks.length,
+                        tasks: tasks.map((t) => ({
+                            id: t.id,
+                            workflow_id: t.workflow_id,
+                            workflow_type: t.workflow_type,
+                            status: t.status,
+                            priority: t.priority,
+                            origin_id: t.origin_id,
+                            created_at: t.created_at,
+                            completed_at: t.completed_at,
+                            error: t.error,
+                            trace_id: t.trace_id,
+                            span_id: t.span_id,
+                        })),
+                    }),
+                }],
+        };
+    });
+    // find_escalations
+    instance.registerTool('find_escalations', {
+        title: 'Find Escalations',
+        description: 'Search escalations with optional filters. Returns escalation records with type, ' +
+            'role, priority, status, description, and assignment info.',
+        inputSchema: schemas_1.findEscalationsSchema,
+    }, async (args) => {
+        const { escalations, total } = await escalationService.listEscalations({
+            status: args.status,
+            role: args.role,
+            type: args.type,
+            priority: args.priority,
+            limit: args.limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        total,
+                        count: escalations.length,
+                        escalations: escalations.map((e) => ({
+                            id: e.id,
+                            type: e.type,
+                            subtype: e.subtype,
+                            role: e.role,
+                            priority: e.priority,
+                            status: e.status,
+                            description: e.description,
+                            workflow_type: e.workflow_type,
+                            assigned_to: e.assigned_to,
+                            created_at: e.created_at,
+                        })),
+                    }),
+                }],
+        };
+    });
+    // get_process_summary
+    instance.registerTool('get_process_summary', {
+        title: 'Get Process Summary',
+        description: 'List business processes grouped by origin_id. Each process shows task count, ' +
+            'completed/escalated counts, workflow types involved, and time range.',
+        inputSchema: schemas_1.getProcessSummarySchema,
+    }, async (args) => {
+        const { processes, total } = await taskService.listProcesses({
+            workflow_type: args.workflow_type,
+            limit: args.limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        total,
+                        count: processes.length,
+                        processes: processes.map((p) => ({
+                            origin_id: p.origin_id,
+                            task_count: p.task_count,
+                            completed: p.completed,
+                            escalated: p.escalated,
+                            workflow_types: p.workflow_types,
+                            started_at: p.started_at,
+                            last_activity: p.last_activity,
+                        })),
+                    }),
+                }],
+        };
+    });
+    // get_escalation_stats
+    instance.registerTool('get_escalation_stats', {
+        title: 'Get Escalation Stats',
+        description: 'Real-time escalation statistics: pending/claimed counts, created/resolved in last ' +
+            '1h and 24h, breakdown by role.',
+        inputSchema: schemas_1.getEscalationStatsSchema,
+    }, async (_args) => {
+        const stats = await escalationService.getEscalationStats();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(stats),
+                }],
+        };
+    });
+    // get_workflow_types
+    instance.registerTool('get_workflow_types', {
+        title: 'Get Workflow Types',
+        description: 'List all registered workflow configurations. Shows workflow type, whether it is ' +
+            'an LT workflow or container, its task queue, roles, and description.',
+        inputSchema: schemas_1.getWorkflowTypesSchema,
+    }, async (_args) => {
+        const configs = await configService.listWorkflowConfigs();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        count: configs.length,
+                        workflows: configs.map((c) => ({
+                            workflow_type: c.workflow_type,
+                            invocable: c.invocable,
+                            task_queue: c.task_queue,
+                            default_role: c.default_role,
+                            description: c.description,
+                            roles: c.roles,
+                        })),
+                    }),
+                }],
+        };
+    });
+    // get_system_health
+    instance.registerTool('get_system_health', {
+        title: 'Get System Health',
+        description: 'Overall system health snapshot: task counts by status, escalation counts by status, ' +
+            'active workflow types, and recent activity window.',
+        inputSchema: schemas_1.getSystemHealthSchema,
+    }, async (_args) => {
+        const pool = (0, db_1.getPool)();
+        const [taskCounts, escalationCounts, activeTypes, recentActivity] = await Promise.all([
+            pool.query(sql_1.HEALTH_TASK_COUNTS),
+            pool.query(sql_1.HEALTH_ESCALATION_COUNTS),
+            pool.query(sql_1.HEALTH_ACTIVE_WORKFLOW_TYPES),
+            pool.query(sql_1.HEALTH_RECENT_ACTIVITY),
+        ]);
+        const tasksByStatus = {};
+        for (const row of taskCounts.rows) {
+            tasksByStatus[row.status] = row.count;
+        }
+        const escalationsByStatus = {};
+        for (const row of escalationCounts.rows) {
+            escalationsByStatus[row.status] = row.count;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        tasks: tasksByStatus,
+                        escalations: escalationsByStatus,
+                        active_workflow_types: activeTypes.rows.map((r) => r.workflow_type),
+                        recent_activity: recentActivity.rows[0],
+                    }),
+                }],
+        };
+    });
+}

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

@@ -0,0 +1,26 @@
+import type { LTMcpServerRecord, LTMcpServerStatus, LTMcpToolManifest } from '../../types';
+import type { CreateMcpServerInput } from './types';
+export declare function createMcpServer(input: CreateMcpServerInput): Promise<LTMcpServerRecord>;
+export declare function getMcpServer(id: string): Promise<LTMcpServerRecord | null>;
+export declare function getMcpServerByName(name: string): Promise<LTMcpServerRecord | null>;
+export declare function updateMcpServer(id: string, updates: Partial<Pick<CreateMcpServerInput, 'name' | 'description' | 'transport_type' | 'transport_config' | 'auto_connect' | 'metadata' | 'tags'>>): Promise<LTMcpServerRecord | null>;
+export declare function deleteMcpServer(id: string): Promise<boolean>;
+export declare function updateMcpServerStatus(id: string, status: LTMcpServerStatus, toolManifest?: LTMcpToolManifest[]): Promise<void>;
+export declare function listMcpServers(filters: {
+    status?: LTMcpServerStatus;
+    auto_connect?: boolean;
+    search?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    servers: LTMcpServerRecord[];
+    total: number;
+}>;
+export declare function getAutoConnectServers(): Promise<LTMcpServerRecord[]>;
+/**
+ * Find MCP servers by tags.
+ * @param tags - Tags to filter by
+ * @param match - 'any' (OR — server has at least one tag) or 'all' (AND — server has all tags)
+ */
+export declare function findServersByTags(tags: string[], match?: 'any' | 'all'): Promise<LTMcpServerRecord[]>;