@j0hanz/cortex-mcp 1.4.0 → 1.6.0

package/dist/lib/errors.js

@@ -4,7 +4,51 @@ const INSPECT_OPTIONS = {
     breakLength: 120,
 };
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
-function isRecord(value) {
+export class ReasoningError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ReasoningError';
+    }
+}
+export class SessionNotFoundError extends ReasoningError {
+    constructor(sessionId) {
+        super('E_SESSION_NOT_FOUND', `Session not found or expired: ${sessionId}`);
+        this.name = 'SessionNotFoundError';
+    }
+}
+export class InvalidThoughtCountError extends ReasoningError {
+    constructor(message) {
+        super('E_INVALID_THOUGHT_COUNT', message);
+        this.name = 'InvalidThoughtCountError';
+    }
+}
+export class InsufficientThoughtsError extends ReasoningError {
+    constructor(message) {
+        super('E_INSUFFICIENT_THOUGHTS', message);
+        this.name = 'InsufficientThoughtsError';
+    }
+}
+export class InvalidRunModeArgsError extends ReasoningError {
+    constructor(message) {
+        super('E_INVALID_RUN_MODE_ARGS', message);
+        this.name = 'InvalidRunModeArgsError';
+    }
+}
+export class ReasoningAbortedError extends ReasoningError {
+    constructor(message = 'Reasoning aborted') {
+        super('E_ABORTED', message);
+        this.name = 'ReasoningAbortedError';
+    }
+}
+export class ServerBusyError extends ReasoningError {
+    constructor(message = 'Server busy — too many concurrent reasoning tasks. Retry shortly.') {
+        super('E_SERVER_BUSY', message);
+        this.name = 'ServerBusyError';
+    }
+}
+export function isObjectRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 function stringifyUnknown(value) {
@@ -17,7 +61,7 @@ function stringifyUnknown(value) {
     return inspect(value, INSPECT_OPTIONS);
 }
 function getMessageFromErrorLike(value) {
-    if (!isRecord(value)) {
+    if (!isObjectRecord(value)) {
         return undefined;
     }
     return typeof value.message === 'string' ? value.message : undefined;
@@ -39,11 +83,9 @@ export function getErrorMessage(error) {
     return stringifyUnknown(error);
 }
 export function createErrorResponse(code, message) {
-    const structured = { ok: false, error: { code, message } };
-    const text = JSON.stringify(structured);
+    const text = JSON.stringify({ ok: false, error: { code, message } });
     return {
         content: [{ type: 'text', text }],
-        structuredContent: structured,
         isError: true,
     };
 }

package/dist/lib/formatting.d.ts

@@ -30,3 +30,16 @@ export declare function formatThoughtsToMarkdown(session: Readonly<Session>, ran
     start: number;
     end: number;
 }): string;
+/**
+ * Format a standardized progress message string.
+ *
+ * Rules:
+ * - Start/Mid: <tool>: <context> [metadata]
+ * - End: <tool>: <context> [metadata] • <outcome>
+ */
+export declare function formatProgressMessage(args: {
+    toolName: string;
+    context: string;
+    metadata?: string;
+    outcome?: string;
+}): string;

package/dist/lib/formatting.js

@@ -21,6 +21,9 @@ export function extractPinnedSections(thoughts) {
     const byTitle = new Map();
     for (const thought of thoughts) {
         const { content } = thought;
+        if (!content.includes(PIN_START)) {
+            continue;
+        }
         let searchFrom = 0;
         while (searchFrom < content.length) {
             const startIdx = content.indexOf(PIN_START, searchFrom);
@@ -120,3 +123,18 @@ export function formatThoughtsToMarkdown(session, range) {
     }
     return sections.join(TRACE_SEPARATOR);
 }
+/**
+ * Format a standardized progress message string.
+ *
+ * Rules:
+ * - Start/Mid: <tool>: <context> [metadata]
+ * - End: <tool>: <context> [metadata] • <outcome>
+ */
+export function formatProgressMessage(args) {
+    const { toolName, context, metadata, outcome } = args;
+    const metaPart = metadata ? ` ${metadata}` : '';
+    if (outcome) {
+        return `${toolName}: ${context}${metaPart} • ${outcome}`;
+    }
+    return `${toolName}: ${context}${metaPart}`;
+}

package/dist/lib/prompt-contracts.d.ts

@@ -1,14 +1,6 @@
-import { z } from 'zod';
-export interface PromptArg {
-    name: string;
-    type: z.ZodType;
-    description: string;
-    required: boolean;
-}
 export interface PromptContract {
     name: string;
     title: string;
     description: string;
-    args: PromptArg[];
 }
-export declare function getPromptContracts(): PromptContract[];
+export declare function getPromptContracts(): readonly PromptContract[];

package/dist/lib/prompt-contracts.js

@@ -1,124 +1,35 @@
-import { z } from 'zod';
+const PROMPT_CONTRACTS = [
+    {
+        name: 'get-help',
+        title: 'Get Help',
+        description: 'Return the server usage instructions.',
+    },
+    {
+        name: 'reasoning.basic',
+        title: 'Reasoning Basic',
+        description: 'Prepare a basic-depth reasoning request (3–5 thoughts).',
+    },
+    {
+        name: 'reasoning.normal',
+        title: 'Reasoning Normal',
+        description: 'Prepare a normal-depth reasoning request (6–10 thoughts).',
+    },
+    {
+        name: 'reasoning.high',
+        title: 'Reasoning High',
+        description: 'Prepare a high-depth reasoning request (15–25 thoughts).',
+    },
+    {
+        name: 'reasoning.continue',
+        title: 'Continue Reasoning',
+        description: 'Continue an existing reasoning session (follow-up query optional).',
+    },
+    {
+        name: 'reasoning.retry',
+        title: 'Retry Reasoning',
+        description: 'Retry a failed reasoning task with modified parameters.',
+    },
+];
 export function getPromptContracts() {
-    return [
-        {
-            name: 'get-help',
-            title: 'Get Help',
-            description: 'Return the server usage instructions.',
-            args: [],
-        },
-        {
-            name: 'reasoning.basic',
-            title: 'Reasoning Basic',
-            description: 'Prepare a basic-depth reasoning request (3–5 thoughts).',
-            args: [
-                {
-                    name: 'query',
-                    type: z.string().min(1).max(10000),
-                    description: 'The question or problem to reason about',
-                    required: true,
-                },
-                {
-                    name: 'targetThoughts',
-                    type: z.number().int().min(1).max(25),
-                    description: 'Optional exact step count within the selected level range (max 25)',
-                    required: false,
-                },
-            ],
-        },
-        {
-            name: 'reasoning.normal',
-            title: 'Reasoning Normal',
-            description: 'Prepare a normal-depth reasoning request (6–10 thoughts).',
-            args: [
-                {
-                    name: 'query',
-                    type: z.string().min(1).max(10000),
-                    description: 'The question or problem to reason about',
-                    required: true,
-                },
-                {
-                    name: 'targetThoughts',
-                    type: z.number().int().min(1).max(25),
-                    description: 'Optional exact step count within the selected level range (max 25)',
-                    required: false,
-                },
-            ],
-        },
-        {
-            name: 'reasoning.high',
-            title: 'Reasoning High',
-            description: 'Prepare a high-depth reasoning request (15–25 thoughts).',
-            args: [
-                {
-                    name: 'query',
-                    type: z.string().min(1).max(10000),
-                    description: 'The question or problem to reason about',
-                    required: true,
-                },
-                {
-                    name: 'targetThoughts',
-                    type: z.number().int().min(1).max(25),
-                    description: 'Optional exact step count within the selected level range (max 25)',
-                    required: false,
-                },
-            ],
-        },
-        {
-            name: 'reasoning.continue',
-            title: 'Continue Reasoning',
-            description: 'Continue an existing reasoning session (follow-up query optional).',
-            args: [
-                {
-                    name: 'sessionId',
-                    type: z.string().min(1).max(128),
-                    description: 'Existing session ID to continue',
-                    required: true,
-                },
-                {
-                    name: 'query',
-                    type: z.string().min(1).max(10000),
-                    description: 'Follow-up query for the existing session',
-                    required: false,
-                },
-                {
-                    name: 'level',
-                    type: z.enum(['basic', 'normal', 'high']),
-                    description: 'Optional in the tool; session level is used if provided',
-                    required: false,
-                },
-                {
-                    name: 'targetThoughts',
-                    type: z.number().int().min(1).max(25),
-                    description: 'Optional exact step count within the selected level range (max 25)',
-                    required: false,
-                },
-            ],
-        },
-        {
-            name: 'reasoning.retry',
-            title: 'Retry Reasoning',
-            description: 'Retry a failed reasoning task with modified parameters.',
-            args: [
-                {
-                    name: 'query',
-                    type: z.string().min(1).max(10000),
-                    description: 'The original or modified query',
-                    required: true,
-                },
-                {
-                    name: 'level',
-                    type: z.enum(['basic', 'normal', 'high']),
-                    description: 'The reasoning level to use',
-                    required: true,
-                },
-                {
-                    name: 'targetThoughts',
-                    type: z.number().int().min(1).max(25),
-                    description: 'Optional exact step count',
-                    required: false,
-                },
-            ],
-        },
-    ];
+    return PROMPT_CONTRACTS;
 }

package/dist/lib/tool-contracts.d.ts

@@ -12,4 +12,4 @@ export interface ToolContract {
     }[];
     outputShape: string;
 }
-export declare function getToolContracts(): ToolContract[];
+export declare function getToolContracts(): readonly ToolContract[];

package/dist/lib/tool-contracts.js

@@ -1,92 +1,87 @@
+const TOOL_CONTRACTS = [
+    {
+        name: 'reasoning_think',
+        purpose: 'Structured multi-step reasoning tool. Decomposes analysis into sequential thought steps stored in a persistent session trace.',
+        model: 'none (engine)',
+        timeoutMs: 0,
+        maxOutputTokens: 0,
+        params: [
+            {
+                name: 'query',
+                type: 'string',
+                required: false,
+                constraints: '1-10,000 chars',
+            },
+            {
+                name: 'level',
+                type: 'string',
+                required: false,
+                constraints: 'basic | normal | high',
+            },
+            {
+                name: 'runMode',
+                type: 'string',
+                required: false,
+                constraints: 'step | run_to_completion',
+            },
+            {
+                name: 'thought',
+                type: 'string | string[]',
+                required: false,
+                constraints: '1-100,000 chars',
+            },
+            {
+                name: 'targetThoughts',
+                type: 'number',
+                required: false,
+                constraints: '1-25',
+            },
+            {
+                name: 'sessionId',
+                type: 'string',
+                required: false,
+                constraints: '1-128 chars',
+            },
+            {
+                name: 'observation',
+                type: 'string',
+                required: false,
+                constraints: 'optional',
+            },
+            {
+                name: 'hypothesis',
+                type: 'string',
+                required: false,
+                constraints: 'optional',
+            },
+            {
+                name: 'evaluation',
+                type: 'string',
+                required: false,
+                constraints: 'optional',
+            },
+            {
+                name: 'step_summary',
+                type: 'string',
+                required: false,
+                constraints: 'optional',
+            },
+            {
+                name: 'is_conclusion',
+                type: 'boolean',
+                required: false,
+                constraints: 'optional',
+            },
+            {
+                name: 'rollback_to_step',
+                type: 'number',
+                required: false,
+                constraints: 'optional',
+            },
+        ],
+        outputShape: '{ok, result: {sessionId, level, status, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, remainingThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary}}',
+    },
+];
 export function getToolContracts() {
-    return [
-        {
-            name: 'reasoning_think',
-            purpose: 'Structured multi-step reasoning tool. Decomposes analysis into sequential thought steps stored in a persistent session trace.',
-            model: 'none (engine)',
-            timeoutMs: 0,
-            maxOutputTokens: 0,
-            params: [
-                {
-                    name: 'query',
-                    type: 'string',
-                    required: false,
-                    constraints: '1-10,000 chars',
-                },
-                {
-                    name: 'level',
-                    type: 'string',
-                    required: false,
-                    constraints: 'basic | normal | high',
-                },
-                {
-                    name: 'runMode',
-                    type: 'string',
-                    required: false,
-                    constraints: 'step | run_to_completion',
-                },
-                {
-                    name: 'thought',
-                    type: 'string | string[]',
-                    required: false,
-                    constraints: '1-100,000 chars',
-                },
-                {
-                    name: 'thoughts',
-                    type: 'string[]',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'targetThoughts',
-                    type: 'number',
-                    required: false,
-                    constraints: '1-25',
-                },
-                {
-                    name: 'sessionId',
-                    type: 'string',
-                    required: false,
-                    constraints: '1-128 chars',
-                },
-                {
-                    name: 'observation',
-                    type: 'string',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'hypothesis',
-                    type: 'string',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'evaluation',
-                    type: 'string',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'step_summary',
-                    type: 'string',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'is_conclusion',
-                    type: 'boolean',
-                    required: false,
-                    constraints: 'optional',
-                },
-                {
-                    name: 'rollback_to_step',
-                    type: 'number',
-                    required: false,
-                    constraints: 'optional',
-                },
-            ],
-            outputShape: '{ok, result: {sessionId, level, status, thoughts[], generatedThoughts, requestedThoughts, totalThoughts, remainingThoughts, tokenBudget, tokensUsed, ttlMs, expiresAt, createdAt, updatedAt, summary}}',
-        },
-    ];
+    return TOOL_CONTRACTS;
 }

package/dist/lib/tool-response.d.ts

@@ -1,4 +1,8 @@
 import type { ContentBlock, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+import type { IconMeta } from './types.js';
+export declare function withIconMeta(iconMeta?: IconMeta): {
+    icons: IconMeta[];
+} | undefined;
 export declare function createToolResponse<T extends object>(structured: T, embeddedResource?: TextResourceContents): {
     content: ContentBlock[];
     structuredContent: T;

package/dist/lib/tool-response.js

@@ -1,3 +1,6 @@
+export function withIconMeta(iconMeta) {
+    return iconMeta ? { icons: [iconMeta] } : undefined;
+}
 function createStructuredTextBlock(structured) {
     return { type: 'text', text: JSON.stringify(structured) };
 }

package/dist/lib/types.d.ts

@@ -1,6 +1,23 @@
 export type ReasoningLevel = 'basic' | 'normal' | 'high';
+export declare const REASONING_LEVELS: readonly ["basic", "normal", "high"];
+/** Shared level bounds — single source of truth for min/maxThoughts per level. */
+export declare const LEVEL_BOUNDS: {
+    readonly basic: {
+        readonly minThoughts: 3;
+        readonly maxThoughts: 5;
+    };
+    readonly normal: {
+        readonly minThoughts: 6;
+        readonly maxThoughts: 10;
+    };
+    readonly high: {
+        readonly minThoughts: 15;
+        readonly maxThoughts: 25;
+    };
+};
 export type ReasoningRunMode = 'step' | 'run_to_completion';
 export type SessionStatus = 'active' | 'completed' | 'cancelled';
+export declare const SESSION_STATUSES: readonly ["active", "completed", "cancelled"];
 interface Timestamped {
     readonly createdAt: number;
     readonly updatedAt: number;

package/dist/lib/types.js

@@ -1 +1,8 @@
-export {};
+export const REASONING_LEVELS = ['basic', 'normal', 'high'];
+/** Shared level bounds — single source of truth for min/maxThoughts per level. */
+export const LEVEL_BOUNDS = {
+    basic: { minThoughts: 3, maxThoughts: 5 },
+    normal: { minThoughts: 6, maxThoughts: 10 },
+    high: { minThoughts: 15, maxThoughts: 25 },
+};
+export const SESSION_STATUSES = ['active', 'completed', 'cancelled'];

package/dist/lib/validators.d.ts

@@ -1,6 +1,17 @@
-import type { ReasoningLevel } from './types.js';
+import { type ReasoningLevel } from './types.js';
 export declare function getThoughtBounds(level: ReasoningLevel): {
     minThoughts: number;
     maxThoughts: number;
 };
 export declare function getTargetThoughtsError(level: ReasoningLevel, targetThoughts: number): string | undefined;
+/**
+ * Parse a positive integer from an environment variable, returning `fallback`
+ * if the variable is absent or invalid. Values below `minimum` also fall back.
+ */
+export declare function parsePositiveIntEnv(name: string, fallback: number, minimum?: number): number;
+/**
+ * Parse a boolean from an environment variable, returning `fallback` when absent
+ * or when the value is not a recognized boolean literal.
+ */
+export declare function parseBooleanEnv(name: string, fallback: boolean): boolean;
+export declare function collectPrefixMatches(candidates: readonly string[], value: string, limit: number): string[];

package/dist/lib/validators.js

@@ -1,14 +1,9 @@
-/** Level-specific thought count boundaries for validation. */
-const THOUGHT_BOUNDS = Object.freeze({
-    basic: Object.freeze({ minThoughts: 3, maxThoughts: 5 }),
-    normal: Object.freeze({ minThoughts: 6, maxThoughts: 10 }),
-    high: Object.freeze({ minThoughts: 15, maxThoughts: 25 }),
-});
+import { LEVEL_BOUNDS } from './types.js';
 function isOutOfBounds(value, bounds) {
     return value < bounds.minThoughts || value > bounds.maxThoughts;
 }
 export function getThoughtBounds(level) {
-    return THOUGHT_BOUNDS[level];
+    return LEVEL_BOUNDS[level];
 }
 export function getTargetThoughtsError(level, targetThoughts) {
     if (!Number.isInteger(targetThoughts)) {
@@ -20,3 +15,49 @@ export function getTargetThoughtsError(level, targetThoughts) {
     }
     return undefined;
 }
+/**
+ * Parse a positive integer from an environment variable, returning `fallback`
+ * if the variable is absent or invalid. Values below `minimum` also fall back.
+ */
+export function parsePositiveIntEnv(name, fallback, minimum = 1) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < minimum) {
+        return fallback;
+    }
+    return parsed;
+}
+/**
+ * Parse a boolean from an environment variable, returning `fallback` when absent
+ * or when the value is not a recognized boolean literal.
+ */
+export function parseBooleanEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    return fallback;
+}
+export function collectPrefixMatches(candidates, value, limit) {
+    const results = [];
+    for (const candidate of candidates) {
+        if (!candidate.startsWith(value)) {
+            continue;
+        }
+        results.push(candidate);
+        if (results.length >= limit) {
+            break;
+        }
+    }
+    return results;
+}