@contextual-io/cli 0.6.0 → 0.8.0

package/dist/models/mcp.js

@@ -0,0 +1,137 @@
+/*
+ * WARNING: This is a shared, external API contract.
+ */
+import { z } from "zod";
+export const McpSessionId = z.string();
+export const McpDetachReason = z.enum([
+    "target-disconnected",
+    "mcp-disconnected",
+    "manual-detach",
+]);
+export const McpBindFailureCode = z.enum([
+    "MCP_DISABLED",
+    "NO_ACTIVE_BROWSER",
+    "BIND_DENIED",
+    "INTERNAL_ERROR",
+]);
+export const McpToolErrorCode = z.enum([
+    "NOT_ATTACHED",
+    "UNKNOWN_TOOL",
+    "COMMAND_IN_FLIGHT",
+    "TIMEOUT",
+    "UNAUTHORIZED",
+    "INTERNAL_ERROR",
+]);
+export const JsonSchema = z.record(z.string(), z.unknown());
+export const McpToolDefinition = z.object({
+    annotations: z.record(z.string(), z.unknown()).optional(),
+    description: z.string(),
+    inputSchema: JsonSchema,
+    name: z.string(),
+    outputSchema: JsonSchema.optional(),
+    title: z.string().optional(),
+});
+export const McpClientPackageInfo = z.object({
+    name: z.string().optional(),
+    version: z.string().optional(),
+});
+export const McpManifestRequest = z.object({
+    interfaceType: z.string(),
+});
+export const McpManifestResponse = z.object({
+    definitions: z.array(McpToolDefinition),
+    interfaceType: z.string(),
+    resolvedAt: z.number().int(),
+    tools: z.array(z.string()),
+});
+export const McpFlowSession = z.object({
+    flowId: z.string(),
+    flowName: z.string(),
+});
+export const McpListSessionsRequest = z.object({
+    flowId: z.string().optional(),
+    interfaceType: z.string(),
+});
+export const McpListSessionsResponse = z.object({
+    sessions: z.array(McpFlowSession),
+});
+export const McpBindSessionRequest = z.object({
+    flowId: z.string(),
+});
+export const McpBindSessionResponse = z.object({
+    boundAt: z.number().int(),
+    flowId: z.string(),
+    flowName: z.string(),
+});
+export const McpBindSessionFailure = z.object({
+    code: McpBindFailureCode,
+    message: z.string(),
+    sessions: z.array(McpFlowSession).optional(),
+});
+export const McpSessionControlRequest = z.object({
+    mcpSessionId: McpSessionId,
+});
+export const McpSessionDisconnectAck = z.object({
+    detachedAt: z.number().int().optional(),
+});
+export const McpToolRegistrySync = z.object({
+    action: z.enum(["register", "clear"]),
+    clientPackage: McpClientPackageInfo.optional(),
+    definitions: z.array(McpToolDefinition),
+    expertId: z.string().optional(),
+    expertName: z.string().optional(),
+    mcpSessionId: McpSessionId,
+    replace: z.boolean().optional(),
+    tools: z.array(z.string()),
+    updatedAt: z.number().int(),
+});
+export const McpToolCall = z.object({
+    args: z.record(z.string(), z.unknown()),
+    name: z.string(),
+    timeoutMs: z.number().int().optional(),
+    type: z.literal("mcp-tool"),
+});
+export const McpToolProgress = z.object({
+    data: z.unknown().optional(),
+    message: z.string().optional(),
+    percent: z.number().optional(),
+});
+export const McpToolResult = z.object({
+    commandId: z.string(),
+    result: z.unknown(),
+});
+export const McpToolError = z.object({
+    code: McpToolErrorCode.optional(),
+    data: z.unknown().optional(),
+    message: z.string(),
+});
+export const McpCommandStatusType = z.enum([
+    "accepted",
+    "dispatched",
+    "progress",
+    "completed",
+    "failed",
+    "timeout",
+]);
+export const McpCommandStatus = z.object({
+    commandId: z.string(),
+    error: McpToolError.optional(),
+    mcpSessionId: McpSessionId,
+    progress: McpToolProgress.optional(),
+    status: McpCommandStatusType,
+    timestamp: z.number().int(),
+    toolName: z.string(),
+});
+export const McpCommandHistoryEntry = z.object({
+    commandId: z.string(),
+    completedAt: z.number().int().optional(),
+    createdAt: z.number().int(),
+    error: McpToolError.optional(),
+    mcpSessionId: McpSessionId,
+    progress: McpToolProgress.optional(),
+    result: z.unknown().optional(),
+    status: McpCommandStatusType,
+    toolCall: McpToolCall.optional(),
+    toolName: z.string(),
+    updatedAt: z.number().int(),
+});

package/dist/utils/endpoints.d.ts

@@ -2,3 +2,4 @@ import { Silo } from "../models/silo.js";
 export declare const getNativeObjectApiEndpoint: (tenantId: string, silo: Silo) => string;
 export declare const getRegistryApiEndpoint: (tenantId: string, silo: Silo) => string;
 export declare const getAuthApiEndpoint: (tenantId: string, silo: Silo) => string;
+export declare const getSolutionAiApiEndpoint: (tenantId: string, silo: Silo) => string;

package/dist/utils/endpoints.js

@@ -1,3 +1,4 @@
 export const getNativeObjectApiEndpoint = (tenantId, silo) => `https://native-object.${tenantId}.my${silo === "prod" ? "" : `.${silo}`}.contextual.io`;
 export const getRegistryApiEndpoint = (tenantId, silo) => `https://native-object-registry.${tenantId}.my${silo === "prod" ? "" : `.${silo}`}.contextual.io`;
 export const getAuthApiEndpoint = (tenantId, silo) => `https://auth.${tenantId}.my${silo === "prod" ? "" : `.${silo}`}.contextual.io`;
+export const getSolutionAiApiEndpoint = (tenantId, silo) => `https://solution-ai.${tenantId}.my${silo === "prod" ? "" : `.${silo}`}.contextual.io`;

package/dist/utils/message.d.ts

@@ -0,0 +1,14 @@
+type BoxOptions = {
+    borderColorFn?: (text: string) => string;
+    bottomLeftBorderChar?: string;
+    bottomRightBorderChar?: string;
+    textColorFn?: (text: string) => string;
+    topLeftBorderChar?: string;
+    topRightBorderChar?: string;
+    xBorderChar?: string;
+    xPadding?: number;
+    yBorderChar?: string;
+    yPadding?: number;
+};
+export declare const boxMessage: (message: string, { borderColorFn, textColorFn, xPadding, yPadding, }?: BoxOptions) => string;
+export {};

package/dist/utils/message.js

@@ -0,0 +1,31 @@
+import chalk from "chalk";
+import { stripVTControlCharacters } from "node:util";
+const BoxTL = "╭";
+const BoxTR = "╮";
+const BoxBL = "╰";
+const BoxBR = "╯";
+const BoxX = "─";
+const BoxY = "│";
+const getVisibleLength = (value) => stripVTControlCharacters(value).length;
+export const boxMessage = (message, { borderColorFn = (text) => chalk.yellow(text), textColorFn = (text) => chalk.white(text), xPadding = 2, yPadding = 0, } = {}) => {
+    xPadding = Math.max(0, xPadding);
+    yPadding = Math.max(0, yPadding);
+    const lines = message.split("\n");
+    const maxLength = Math.max(...lines.map(line => getVisibleLength(line)));
+    const totalInnerWidth = maxLength + xPadding * 2;
+    const leftPadding = " ".repeat(xPadding);
+    const topBorder = borderColorFn(`${BoxTL}${BoxX.repeat(totalInnerWidth)}${BoxTR}`);
+    const bottomBorder = borderColorFn(`${BoxBL}${BoxX.repeat(totalInnerWidth)}${BoxBR}`);
+    const yPaddingLines = Array.from({ length: yPadding }, () => `${textColorFn(BoxY)}${" ".repeat(totalInnerWidth)}${textColorFn(BoxY)}`);
+    const contentLines = lines.map(line => {
+        const rightPadding = " ".repeat(maxLength - getVisibleLength(line) + xPadding);
+        return `${borderColorFn(BoxY)}${leftPadding}${textColorFn(line)}${rightPadding}${borderColorFn(BoxY)}`;
+    });
+    return [
+        topBorder,
+        ...yPaddingLines,
+        ...contentLines,
+        ...yPaddingLines,
+        bottomBorder,
+    ].join("\n");
+};

package/dist/utils/update-check.d.ts

@@ -0,0 +1,23 @@
+export type UpdateCheckResult = {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+};
+export declare const compareVersions: (left: string, right: string) => -1 | 0 | 1;
+export declare const checkForUpdate: ({ currentVersion, packageName, timeoutMs, }: {
+    currentVersion: string;
+    packageName: string;
+    timeoutMs?: number;
+}) => Promise<undefined | UpdateCheckResult>;
+export declare const shouldRunPeriodicCheck: ({ cacheDir, frequencyMs, }: {
+    cacheDir: string;
+    frequencyMs: number;
+}) => boolean;
+export declare const markChecked: ({ cacheDir, notifiedVersion, }: {
+    cacheDir: string;
+    notifiedVersion?: string;
+}) => void;
+export declare const hasNotifiedVersion: ({ cacheDir, latestVersion, }: {
+    cacheDir: string;
+    latestVersion: string;
+}) => boolean;

package/dist/utils/update-check.js

@@ -0,0 +1,101 @@
+import fetch from "cross-fetch";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+const NpmLatestVersionResponse = z.object({
+    version: z.string(),
+});
+const updateCheckFileName = "update-check.json";
+const parseVersionPart = (value) => {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+};
+const splitVersion = (version) => {
+    const trimmed = version.startsWith("v") ? version.slice(1) : version;
+    const [corePart, prerelease] = trimmed.split("-", 2);
+    const core = corePart.split(".").map((part) => parseVersionPart(part));
+    return { core, prerelease };
+};
+export const compareVersions = (left, right) => {
+    const leftVersion = splitVersion(left);
+    const rightVersion = splitVersion(right);
+    const maxLength = Math.max(leftVersion.core.length, rightVersion.core.length);
+    for (let i = 0; i < maxLength; i += 1) {
+        const leftPart = leftVersion.core[i] ?? 0;
+        const rightPart = rightVersion.core[i] ?? 0;
+        if (leftPart > rightPart)
+            return 1;
+        if (leftPart < rightPart)
+            return -1;
+    }
+    if (!leftVersion.prerelease && rightVersion.prerelease)
+        return 1;
+    if (leftVersion.prerelease && !rightVersion.prerelease)
+        return -1;
+    return 0;
+};
+const readState = (cacheDir) => {
+    const statePath = path.join(cacheDir, updateCheckFileName);
+    if (!fs.existsSync(statePath))
+        return {};
+    try {
+        const rawState = fs.readFileSync(statePath, "utf8");
+        return JSON.parse(rawState);
+    }
+    catch {
+        return {};
+    }
+};
+const writeState = (cacheDir, state) => {
+    if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+    }
+    const statePath = path.join(cacheDir, updateCheckFileName);
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2), "utf8");
+};
+const fetchLatestVersion = async (packageName, timeoutMs) => {
+    try {
+        const encodedPackageName = encodeURIComponent(packageName);
+        const response = await fetch(`https://registry.npmjs.org/${encodedPackageName}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return undefined;
+        const { version } = NpmLatestVersionResponse.parse(await response.json());
+        return version;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const checkForUpdate = async ({ currentVersion, packageName, timeoutMs = 1500, }) => {
+    const latestVersion = await fetchLatestVersion(packageName, timeoutMs);
+    if (!latestVersion)
+        return undefined;
+    return {
+        currentVersion,
+        latestVersion,
+        updateAvailable: compareVersions(latestVersion, currentVersion) > 0,
+    };
+};
+export const shouldRunPeriodicCheck = ({ cacheDir, frequencyMs, }) => {
+    const state = readState(cacheDir);
+    if (!state.lastCheckedAt)
+        return true;
+    const lastCheckedAt = new Date(state.lastCheckedAt).getTime();
+    if (Number.isNaN(lastCheckedAt))
+        return true;
+    return Date.now() - lastCheckedAt >= frequencyMs;
+};
+export const markChecked = ({ cacheDir, notifiedVersion, }) => {
+    const state = readState(cacheDir);
+    writeState(cacheDir, {
+        ...state,
+        lastCheckedAt: new Date().toISOString(),
+        lastNotifiedVersion: notifiedVersion ?? state.lastNotifiedVersion,
+    });
+};
+export const hasNotifiedVersion = ({ cacheDir, latestVersion, }) => {
+    const state = readState(cacheDir);
+    return state.lastNotifiedVersion === latestVersion;
+};

package/oclif.manifest.json

@@ -265,6 +265,114 @@
         "use.js"
       ]
     },
+    "mcp": {
+      "aliases": [],
+      "args": {},
+      "description": "Manage local MCP server commands. Start with 'ctxl mcp serve' to run the local MCP bridge.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> flow-editor --flow my-flow-id"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "mcp",
+      "pluginAlias": "@contextual-io/cli",
+      "pluginName": "@contextual-io/cli",
+      "pluginType": "core",
+      "strict": true,
+      "usage": [
+        "<%= command.id %> <COMMAND>"
+      ],
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "mcp",
+        "index.js"
+      ]
+    },
+    "mcp:serve": {
+      "aliases": [],
+      "args": {
+        "interface": {
+          "default": "flow-editor",
+          "description": "Interface type to scope tools for. Available interfaces depend on your platform version.",
+          "name": "interface",
+          "required": false
+        }
+      },
+      "description": "Start a local MCP HTTP server that connects to SolutionAI for a given interface type. By default it binds to http://localhost:5051/. The server fetches the full tool manifest from SolutionAI and serves all tools immediately. Pass a flowId with each tool call to target a specific flow, or use list_sessions to discover available flows.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> flow-editor --flow my-flow-id"
+      ],
+      "flags": {
+        "config-id": {
+          "char": "C",
+          "helpGroup": "GLOBAL",
+          "name": "config-id",
+          "summary": "Specify config id to use for call.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "flow": {
+          "char": "f",
+          "description": "pre-filter session listing to a specific flow ID",
+          "name": "flow",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "port": {
+          "char": "p",
+          "description": "local HTTP port (default: 5051)",
+          "name": "port",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "tool-prefix": {
+          "char": "t",
+          "description": "prefix all MCP tool names with ctxl_",
+          "name": "tool-prefix",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "url": {
+          "description": "override MCP route URL (http/https)",
+          "hidden": true,
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "char": "V",
+          "description": "emit verbose MCP runtime diagnostics",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "mcp:serve",
+      "pluginAlias": "@contextual-io/cli",
+      "pluginName": "@contextual-io/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "mcp",
+        "serve.js"
+      ]
+    },
     "records:add": {
       "aliases": [
         "records:create",
@@ -1259,5 +1367,5 @@
       ]
     }
   },
-  "version": "0.6.0"
+  "version": "0.8.0"
 }

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@contextual-io/cli",
   "description": "Contextual CLI",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "author": "Nasser Oloumi",
   "bin": {
     "ctxl": "./bin/run.js"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@oclif/core": "^4",
     "@oclif/plugin-autocomplete": "^3.2.39",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-not-found": "^3.2.73",
-    "@oclif/table": "^0.5.1",
+    "@oclif/table": "^0.5.2",
     "chalk": "^5.6.2",
     "cross-fetch": "^4.1.0",
+    "express": "^5.2.1",
     "open": "^11.0.0",
+    "socket.io-client": "^4.8.3",
     "stream-json": "^1.9.1",
     "zod": "4.1.12"
   },
@@ -24,6 +27,7 @@
     "@oclif/test": "^4",
     "@stylistic/eslint-plugin": "^5.6.1",
     "@types/chai": "^4",
+    "@types/express": "^5.0.5",
     "@types/mocha": "^10",
     "@types/node": "^18",
     "@types/stream-json": "^1.7.8",
@@ -33,7 +37,7 @@
     "eslint-config-prettier": "^10",
     "eslint-plugin-unused-imports": "^4.3.0",
     "mocha": "^10",
-    "oclif": "^4",
+    "oclif": "^4.22.81",
     "shx": "^0.3.3",
     "ts-node": "^10",
     "typescript": "^5"
@@ -57,6 +61,9 @@
     "bin": "ctxl",
     "dirname": "ctxl",
     "commands": "./dist/commands",
+    "hooks": {
+      "init": "./dist/hooks/init/index.js"
+    },
     "plugins": [
       "@oclif/plugin-help",
       "@oclif/plugin-not-found",