@j0hanz/prompt-tuner-mcp-server 1.0.9 → 1.0.10

package/CONFIGURATION.md

@@ -1,6 +1,6 @@
 # PromptTuner MCP Configuration Guide
 
-PromptTuner MCP is configured entirely via environment variables. Set them in your MCP client configuration (for example `mcp.json`, `claude_desktop_config.json`) or a `.env` file.
+PromptTuner MCP is configured entirely via environment variables. Set them in your MCP client configuration (for example `mcp.json`, `claude_desktop_config.json`) or a `.env` file. Node.js >= 22.0.0 is required (see `package.json` engines).
 
 ## Required configuration
 
@@ -33,6 +33,10 @@ Set `LLM_MODEL` to override the default model for the chosen provider.
 | `LLM_MAX_TOKENS`    | `8000`  | Upper bound for model output tokens. |
 | `LLM_TIMEOUT_MS`    | `60000` | Per-request timeout (ms).            |
 
+All numeric values are parsed as integers. Invalid values or values below the minimum thresholds will fail startup validation.
+
+Minimums: `MAX_PROMPT_LENGTH` >= 1, `LLM_MAX_TOKENS` >= 1, `LLM_TIMEOUT_MS` >= 1000.
+
 ### Prompt length enforcement
 
 - Input is trimmed before validation.
@@ -61,13 +65,15 @@ Tool max tokens are derived from `LLM_MAX_TOKENS`:
 
 Retries use exponential backoff with jitter and stop when the total timeout is exceeded.
 
+Minimums: `RETRY_MAX_ATTEMPTS` >= 0, `RETRY_BASE_DELAY_MS` >= 100, `RETRY_MAX_DELAY_MS` >= 1000, `RETRY_TOTAL_TIMEOUT_MS` >= 10000.
+
 ## Logging and error context (optional)
 
-| Variable                | Default | Description                                                    |
-| ----------------------- | ------- | -------------------------------------------------------------- |
-| `DEBUG`                 | `false` | Enables debug logging. Logs are written to stderr.             |
-| `LOG_FORMAT`            | `text`  | Parsed but currently unused (logging output is JSON via pino). |
-| `INCLUDE_ERROR_CONTEXT` | `false` | Adds a sanitized prompt snippet (up to 200 chars) to errors.   |
+| Variable                | Default | Description                                                                              |
+| ----------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `DEBUG`                 | `false` | Enables debug logging (set to the string `true` or `false`). Logs are written to stderr. |
+| `LOG_FORMAT`            | `text`  | Accepted values: `json`, `text`. Currently ignored; output is always JSON via pino.      |
+| `INCLUDE_ERROR_CONTEXT` | `false` | Adds a sanitized prompt snippet (up to 200 chars) to errors.                             |
 
 ## Provider-specific settings
 
@@ -179,7 +185,7 @@ The following behaviors are hardcoded for stability:
 
 If you have an old `.env` file, remove unused settings:
 
-- `PORT`, `HOST`, `CORS_ORIGIN` (stdio transport only; `--http` is reserved).
+- `PORT`, `HOST`, `CORS_ORIGIN` (stdio transport only; no HTTP listener).
 - `API_KEY` (no server-level auth).
 - `LOG_LEVEL` (use `DEBUG=true` or false).
 - `RATE_LIMIT`, `RATE_WINDOW_MS` (no server-side rate limiting).
@@ -192,7 +198,7 @@ If you have an old `.env` file, remove unused settings:
 
 ### Prompt rejected
 
-- Reduce `MAX_PROMPT_LENGTH` or trim the input to remove excessive whitespace.
+- Shorten the prompt, remove excessive whitespace, or increase `MAX_PROMPT_LENGTH`.
 
 ### Timeout errors
 
@@ -215,4 +221,4 @@ If you have an old `.env` file, remove unused settings:
 2. Use input variables for secrets (for example `"OPENAI_API_KEY": "${input:openai-api-key}"`).
 3. Start with defaults and tune only when needed.
 4. Enable `DEBUG=true` temporarily for troubleshooting.
-5. Prefer JSON logging in production (current output is JSON via pino).
+5. Logs are JSON via pino; plan parsing/collection accordingly.

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@j0hanz/prompt-tuner-mcp-server.svg)](https://www.npmjs.com/package/@j0hanz/prompt-tuner-mcp-server)
 [![License](https://img.shields.io/npm/l/@j0hanz/prompt-tuner-mcp-server)](LICENSE)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/)
 
 PromptTuner MCP is an MCP server that refines, analyzes, optimizes, and validates prompts using OpenAI, Anthropic, or Google Gemini.
 
@@ -14,7 +14,7 @@ PromptTuner MCP is an MCP server that refines, analyzes, optimizes, and validate
 2. Resolves the target format (`auto` uses heuristics; falls back to `gpt` if no format is detected).
 3. Calls the selected provider with retry and timeout controls.
 4. Validates and normalizes LLM output, falling back to stricter prompts or the `basic` technique when needed.
-5. Returns human-readable text plus machine-friendly `structuredContent` (and prompt files for refined/optimized outputs).
+5. Returns human-readable text plus machine-friendly `structuredContent` (and resource blocks for refined/optimized outputs).
 
 ## Features
 
@@ -27,7 +27,7 @@ PromptTuner MCP is an MCP server that refines, analyzes, optimizes, and validate
 
 ## Quick Start
 
-PromptTuner runs over stdio (MCP default). The `--http` flag shown in some scripts is reserved and currently has no effect.
+PromptTuner runs over stdio only. The `dev:http` and `start:http` scripts are compatibility aliases (no HTTP transport yet).
 
 ### Claude Desktop
 
@@ -95,11 +95,11 @@ Returns: `ok`, `hasTypos`, `isVague`, `missingContext`, `suggestions`, `score`,
 
 Apply multiple techniques sequentially and return before/after scores.
 
-| Parameter      | Type     | Required | Default     | Notes                               |
-| -------------- | -------- | -------- | ----------- | ----------------------------------- |
-| `prompt`       | string   | Yes      | -           | Trimmed and length-checked.         |
-| `techniques`   | string[] | No       | `["basic"]` | 1-6 techniques; duplicates removed. |
-| `targetFormat` | string   | No       | `auto`      | `auto`, `claude`, `gpt`, `json`.    |
+| Parameter      | Type     | Required | Default     | Notes                                                                                                                           |
+| -------------- | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`       | string   | Yes      | -           | Trimmed and length-checked.                                                                                                     |
+| `techniques`   | string[] | No       | `["basic"]` | 1-6 techniques; duplicates removed. `comprehensive` expands to `basic -> roleBased -> structured -> fewShot -> chainOfThought`. |
+| `targetFormat` | string   | No       | `auto`      | `auto`, `claude`, `gpt`, `json`.                                                                                                |
 
 Returns: `ok`, `original`, `optimized`, `techniquesApplied`, `targetFormat`, `beforeScore`, `afterScore`, `scoreDelta`, `improvements`, `usedFallback`, `scoreAdjusted`, `overallSource`, `provider`, `model`.
 
@@ -119,10 +119,10 @@ Token limits used for `validate_prompt`: `claude` 200000, `gpt` 128000, `gemini`
 
 ## Response Format
 
-- `content`: human-readable Markdown summary.
+- `content`: array of content blocks (human-readable Markdown text plus optional resources).
 - `structuredContent`: machine-parseable results.
 - Errors return `structuredContent.ok=false` and an `error` object with `code`, `message`, optional `context` (sanitized, up to 200 chars), `details`, and `recoveryHint`.
-- `refine_prompt` and `optimize_prompt` include a `resource` content block with a `file:///` URI containing the refined or optimized prompt.
+- `refine_prompt` and `optimize_prompt` include a `resource` content block with a `file:///` URI and the prompt text in `resource.text` (Markdown).
 
 ## Prompts
 
@@ -159,27 +159,27 @@ Token limits used for `validate_prompt`: `claude` 200000, `gpt` 128000, `gemini`
 
 ### Prerequisites
 
-- Node.js >= 20.0.0
+- Node.js >= 22.0.0
 - npm
 
 ### Scripts
 
-| Command                  | Description                                              |
-| ------------------------ | -------------------------------------------------------- |
-| `npm run build`          | Compile TypeScript and set permissions.                  |
-| `npm run dev`            | Run from source in watch mode.                           |
-| `npm run dev:http`       | Run from source with `--http` (reserved, no effect).     |
-| `npm run start`          | Run the compiled server from `dist/`.                    |
-| `npm run start:http`     | Run compiled server with `--http` (reserved, no effect). |
-| `npm run test`           | Run Vitest once.                                         |
-| `npm run test:coverage`  | Run tests with coverage.                                 |
-| `npm run test:watch`     | Run Vitest in watch mode.                                |
-| `npm run lint`           | Run ESLint.                                              |
-| `npm run format`         | Run Prettier.                                            |
-| `npm run type-check`     | TypeScript type checking.                                |
-| `npm run inspector`      | Run MCP Inspector against `dist/index.js`.               |
-| `npm run inspector:http` | Inspector with `--http` (reserved, no effect).           |
-| `npm run duplication`    | Run jscpd duplication report.                            |
+| Command                  | Description                                           |
+| ------------------------ | ----------------------------------------------------- |
+| `npm run build`          | Compile TypeScript and set permissions.               |
+| `npm run dev`            | Run from source in watch mode.                        |
+| `npm run dev:http`       | Alias of `npm run dev` (no HTTP transport yet).       |
+| `npm run start`          | Run the compiled server from `dist/`.                 |
+| `npm run start:http`     | Alias of `npm run start` (no HTTP transport yet).     |
+| `npm run test`           | Run Vitest once.                                      |
+| `npm run test:coverage`  | Run tests with coverage.                              |
+| `npm run test:watch`     | Run Vitest in watch mode.                             |
+| `npm run lint`           | Run ESLint.                                           |
+| `npm run format`         | Run Prettier.                                         |
+| `npm run type-check`     | TypeScript type checking.                             |
+| `npm run inspector`      | Run MCP Inspector against `dist/index.js`.            |
+| `npm run inspector:http` | Alias of `npm run inspector` (no HTTP transport yet). |
+| `npm run duplication`    | Run jscpd duplication report.                         |
 
 ## Project Structure
 
@@ -190,8 +190,7 @@ src/
   config/         Configuration and constants
   lib/            Shared utilities (LLM, retry, validation)
   tools/          Tool implementations
-  prompts/        Prompt templates
-  resources/      Resource registration (currently none)
+  prompts/        MCP prompt templates
   schemas/        Zod input/output schemas
   types/          Shared types
 

package/dist/config/constants.js

@@ -11,7 +11,6 @@ export const SCORING_WEIGHTS = {
 };
 export const SERVER_NAME = 'prompttuner-mcp';
 export const SERVER_VERSION = packageJson.version;
-// Configurable via environment variables
 const { MAX_PROMPT_LENGTH: ENV_MAX_PROMPT_LENGTH, LLM_TIMEOUT_MS: ENV_LLM_TIMEOUT_MS, LLM_MAX_TOKENS: ENV_LLM_MAX_TOKENS, } = config;
 export const MAX_PROMPT_LENGTH = ENV_MAX_PROMPT_LENGTH;
 export const MIN_PROMPT_LENGTH = 1;

package/dist/config/env.js

@@ -11,11 +11,9 @@ const numberString = (def, min = 0) => z
     .transform((v) => parseInt(v, 10))
     .refine((n) => n >= min, { message: `Must be >= ${min}` });
 const envSchema = z.object({
-    // Server
     LOG_FORMAT: z.enum(['json', 'text']).optional().default('text'),
     DEBUG: booleanString,
     INCLUDE_ERROR_CONTEXT: booleanString,
-    // LLM
     LLM_PROVIDER: z
         .enum(['openai', 'anthropic', 'google'])
         .optional()
@@ -28,13 +26,10 @@ const envSchema = z.object({
         .optional()
         .default('false')
         .transform((v) => v === 'true'),
-    // Keys
     OPENAI_API_KEY: z.string().optional(),
     ANTHROPIC_API_KEY: z.string().optional(),
     GOOGLE_API_KEY: z.string().optional(),
-    // Constraints
     MAX_PROMPT_LENGTH: numberString(10000, 1),
-    // Retry
     RETRY_MAX_ATTEMPTS: numberString(3, 0),
     RETRY_BASE_DELAY_MS: numberString(1000, 100),
     RETRY_MAX_DELAY_MS: numberString(10000, 1000),

package/dist/config/patterns.d.ts

@@ -1,5 +1,4 @@
 export declare const PATTERNS: {
-    readonly roleIndicators: RegExp;
     readonly exampleIndicators: RegExp;
     readonly stepByStepIndicators: RegExp;
     readonly xmlStructure: RegExp;
@@ -8,12 +7,6 @@ export declare const PATTERNS: {
     readonly claudePatterns: RegExp;
     readonly gptPatterns: RegExp;
     readonly vagueWords: RegExp;
-    readonly needsReasoning: RegExp;
-    readonly hasStepByStep: RegExp;
     readonly hasRole: RegExp;
-    readonly constraintPatterns: RegExp;
-    readonly outputSpecPatterns: RegExp;
     readonly fewShotStructure: RegExp;
-    readonly qualityIndicators: RegExp;
-    readonly antiPatterns: RegExp;
 };

package/dist/config/patterns.js

@@ -1,5 +1,4 @@
 export const PATTERNS = {
-    roleIndicators: /\b(you are|act as|pretend to be|as a|role:|persona:|imagine you are|your role is|you're an?)\b/i,
     exampleIndicators: /(?:^|\s|[([{])(example:|for example|e\.g\.|such as|here's an example|input:|output:|sample:|demonstration:)(?:$|\s|[)\]}.!?,])/i,
     stepByStepIndicators: /(?:^|\s|[([{])(step by step|step-by-step|first,|then,|finally,|1\.|2\.|3\.|let's think|let's work through|let's analyze|let's break|systematically)(?:$|\s|[)\]}.!?,])/i,
     xmlStructure: /<[a-z_]+>[^<]*<\/[a-z_]+>/is,
@@ -8,12 +7,6 @@ export const PATTERNS = {
     claudePatterns: /<(thinking|response|context|instructions|example|task|requirements|output_format|rules|constraints)>/i,
     gptPatterns: /^##\s|^###\s|\*\*[^*]+\*\*|^>\s/m,
     vagueWords: /\b(something|stuff|things|maybe|kind of|sort of|etc|whatever|somehow|certain|various)\b/gi,
-    needsReasoning: /\b(calculate|analyze|compare|evaluate|explain|solve|debug|review|reason|deduce|derive|prove|assess|investigate|examine|determine)\b/i,
-    hasStepByStep: /step[- ]by[- ]step|first,|then,|finally,|let's think|let's work through|let's analyze/i,
     hasRole: /\b(you are|act as|as a|role:|persona:|your role|you're an?|imagine you are)\b/i,
-    constraintPatterns: /\b(NEVER|ALWAYS|MUST|MUST NOT|DO NOT|RULES:|CONSTRAINTS:|REQUIREMENTS:)\b/,
-    outputSpecPatterns: /\b(output format|respond with|return as|format:|expected output|response format|<output|## Output)\b/i,
     fewShotStructure: /<example>|Example \d+:|Input:|Output:|###\s*Example|Q:|A:/i,
-    qualityIndicators: /\b(specific|detailed|comprehensive|thorough|clear|concise|precise|accurate)\b/i,
-    antiPatterns: /\b(do whatever|anything|everything|all of it|any way you want)\b/i,
 };

package/dist/config/types.d.ts

@@ -1,31 +1,28 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export type ToolRegistrar = (server: McpServer) => void;
-interface TextContentBlock {
-    type: 'text';
-    text: string;
-}
-interface TextResourcePayload {
+interface ResourceTextPayload {
     uri: string;
-    mimeType?: string;
     text: string;
+    mimeType?: string;
 }
-interface BlobResourcePayload {
+interface ResourceBlobPayload {
     uri: string;
-    mimeType?: string;
     blob: string;
+    mimeType?: string;
 }
-interface ResourceContentBlock {
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
     type: 'resource';
-    resource: TextResourcePayload | BlobResourcePayload;
-}
-interface ResourceLinkContentBlock {
+    resource: ResourceTextPayload | ResourceBlobPayload;
+} | {
     type: 'resource_link';
     uri: string;
     name: string;
     description?: string;
     mimeType?: string;
-}
-export type ContentBlock = TextContentBlock | ResourceContentBlock | ResourceLinkContentBlock;
+};
 export interface ErrorResponse {
     [key: string]: unknown;
     content: ContentBlock[];
@@ -86,7 +83,6 @@ export interface FormatResult {
     rawScore: number;
 }
 export type LLMProvider = 'openai' | 'anthropic' | 'google';
-export type ValidProvider = 'openai' | 'anthropic' | 'google';
 export interface SafeErrorDetails {
     status?: number;
     code?: string;
@@ -113,12 +109,6 @@ export interface LLMToolOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
 }
-export interface RetryOptions {
-    maxRetries?: number;
-    baseDelayMs?: number;
-    maxDelayMs?: number;
-    totalTimeoutMs?: number;
-}
 export interface McpErrorOptions {
     context?: string;
     details?: Record<string, unknown>;

package/dist/index.js

@@ -1,108 +1,69 @@
 #!/usr/bin/env node
 import { logger } from './lib/errors.js';
-import { createServer, startServer, validateApiKeys } from './server.js';
+import { startServer, validateApiKeys } from './server.js';
 const SHUTDOWN_DELAY_MS = 500;
-const SIGNALS = [
-    'SIGHUP',
-    'SIGINT',
-    'SIGQUIT',
-    'SIGILL',
-    'SIGTRAP',
-    'SIGABRT',
-    'SIGBUS',
-    'SIGFPE',
-    'SIGSEGV',
-    'SIGUSR2',
-    'SIGTERM',
-];
-const ERROR_EVENTS = ['uncaughtException', 'unhandledRejection'];
-const EXIT_EVENTS = ['beforeExit'];
-let shuttingDown = false;
+const SIGNALS = ['SIGHUP', 'SIGINT', 'SIGTERM'];
 let server = null;
+let shuttingDown = false;
 function logSecondShutdown(reason) {
-    if (reason.signal) {
-        logger.error({ signal: reason.signal }, `Second ${reason.signal}, exiting`);
-        return;
-    }
-    if (reason.err) {
-        logger.error({ err: reason.err }, 'Second error, exiting');
-        return;
-    }
-    logger.error('Second shutdown event, exiting');
+    logger.error({ reason }, 'Second shutdown, exiting');
 }
-function logShutdownStart(reason) {
-    if (reason.err) {
-        logger.error({ err: reason.err }, 'Server closing due to error');
-    }
-    if (reason.signal) {
-        logger.info({ signal: reason.signal }, 'Server shutting down gracefully');
+function logShutdown(reason, err) {
+    if (err) {
+        logger.error({ err, reason }, 'Server shutting down due to error');
     }
-    if (reason.event) {
-        logger.info({ event: reason.event }, 'Server shutting down gracefully');
+    else {
+        logger.info({ reason }, 'Server shutting down');
     }
 }
-function resolveExitCode(reason) {
-    return reason.err ? 1 : 0;
-}
 function startForcedShutdownTimer() {
     return setTimeout(() => {
         logger.error({ delayMs: SHUTDOWN_DELAY_MS }, 'Forced shutdown due to timeout');
         process.exit(1);
     }, SHUTDOWN_DELAY_MS);
 }
-async function closeServerIfConnected() {
-    if (server?.isConnected()) {
+async function closeServer() {
+    if (!server?.isConnected())
+        return true;
+    try {
         await server.close();
+        return true;
+    }
+    catch (closeError) {
+        logger.error({ err: closeError }, 'Error during shutdown');
+        return false;
     }
 }
-async function beginShutdown(reason) {
+async function shutdown(reason, err) {
     if (shuttingDown) {
         logSecondShutdown(reason);
         process.exit(1);
         return;
     }
     shuttingDown = true;
-    logShutdownStart(reason);
-    let exitCode = resolveExitCode(reason);
+    logShutdown(reason, err);
     const timeout = startForcedShutdownTimer();
-    try {
-        await closeServerIfConnected();
-    }
-    catch (error) {
+    let exitCode = err ? 1 : 0;
+    if (!(await closeServer()))
         exitCode = 1;
-        logger.error({ err: error }, 'Error during shutdown');
-    }
-    finally {
-        clearTimeout(timeout);
-        process.exit(exitCode);
-    }
+    clearTimeout(timeout);
+    process.exit(exitCode);
 }
 for (const signal of SIGNALS) {
-    process.once(signal, (received) => {
-        void beginShutdown({ signal: received });
-    });
-}
-for (const event of ERROR_EVENTS) {
-    process.once(event, (err) => {
-        void beginShutdown({ err });
-    });
-}
-for (const event of EXIT_EVENTS) {
-    process.once(event, () => {
-        void beginShutdown({ event });
+    process.once(signal, () => {
+        void shutdown(signal);
     });
 }
-process.stdin.once('end', () => {
-    void beginShutdown({ event: 'stdin_end' });
+process.once('uncaughtException', (err) => {
+    void shutdown('uncaughtException', err);
 });
-process.stdin.once('close', () => {
-    void beginShutdown({ event: 'stdin_close' });
+process.once('unhandledRejection', (err) => {
+    void shutdown('unhandledRejection', err);
 });
 async function main() {
     await validateApiKeys();
-    server = createServer();
-    await startServer(server);
+    server = await startServer();
 }
-main().catch((error) => {
-    void beginShutdown({ err: error });
+main().catch((err) => {
+    void shutdown('startup', err);
 });

package/dist/lib/errors.js

@@ -27,7 +27,6 @@ export class McpError extends Error {
             this.recoveryHint = recoveryHint;
         }
     }
-    // Custom inspect output for better console debugging
     [inspect.custom]() {
         const hint = this.recoveryHint ? ` (Hint: ${this.recoveryHint})` : '';
         const details = this.details ? ` ${JSON.stringify(this.details)}` : '';
@@ -89,16 +88,13 @@ export function createErrorResponse(error, fallbackCode = ErrorCode.E_LLM_FAILED
         isError: true,
     };
 }
-// Sanitizes context by removing API keys and truncating prompts
 function sanitizeErrorContext(context) {
     if (!context)
         return undefined;
-    // Redact API keys (OpenAI, Anthropic, Google patterns)
     let sanitized = context
         .replace(/sk-[A-Za-z0-9_-]{20,}/g, '[REDACTED_OPENAI_KEY]')
         .replace(/sk-ant-[A-Za-z0-9_-]{20,}/g, '[REDACTED_ANTHROPIC_KEY]')
         .replace(/AIza[A-Za-z0-9_-]{35}/g, '[REDACTED_GOOGLE_KEY]');
-    // Truncate to first 200 chars for privacy
     const CONTEXT_MAX_LENGTH = 200;
     if (sanitized.length > CONTEXT_MAX_LENGTH) {
         sanitized = `${sanitized.slice(0, CONTEXT_MAX_LENGTH)}...`;
@@ -114,7 +110,6 @@ function resolveErrorMessage(error) {
 function resolveErrorDetails(mcpError) {
     return mcpError?.details;
 }
-// Default recovery hints for common error codes
 const DEFAULT_RECOVERY_HINTS = {
     E_INVALID_INPUT: 'Check the input parameters and try again.',
     E_LLM_FAILED: 'Retry the request. If the issue persists, check LLM provider status.',

package/dist/lib/llm-json.js

@@ -1,21 +1,14 @@
-// Shared utilities for parsing JSON from LLM responses
-// Handles common wrapping patterns like ```json code blocks``` and surrounding text.
 import { LLM_ERROR_PREVIEW_CHARS, LLM_MAX_RESPONSE_LENGTH, } from '../config/constants.js';
 import { logger, McpError } from './errors.js';
 import { extractFirstJsonFragment } from './llm-json/scan.js';
-// Matches opening code block: ```json or ``` at start (with optional whitespace/newlines before)
 const CODE_BLOCK_START_RE = /^[\s\n]*```(?:json)?[\s\n]*/i;
-// Matches closing code block at end (with optional whitespace/newlines after)
 const CODE_BLOCK_END_RE = /[\s\n]*```[\s\n]*$/;
-// Strips code block markers from the start and end of a string
 function stripCodeBlockMarkers(text) {
     let result = text;
-    // Remove opening code block marker
     const startMatch = CODE_BLOCK_START_RE.exec(result);
     if (startMatch) {
         result = result.slice(startMatch[0].length);
     }
-    // Remove closing code block marker
     const endMatch = CODE_BLOCK_END_RE.exec(result);
     if (endMatch) {
         result = result.slice(0, result.length - endMatch[0].length);
@@ -37,8 +30,9 @@ function tryParseJson(jsonText, parse, debugLabel, stageLabel) {
         return { success: true, value: result };
     }
     catch (error) {
-        logger.debug(`${debugLabel ?? 'JSON parse'}: ${stageLabel} parse failed: ${error instanceof Error ? error.message : String(error)}`);
-        return { success: false, error };
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug(`${debugLabel ?? 'JSON parse'}: ${stageLabel} parse failed: ${message}`);
+        return { success: false, error: { stage: stageLabel, message } };
     }
 }
 function logPreviewIfDebug(llmResponseText, maxPreviewChars, contextLabel) {
@@ -46,12 +40,18 @@ function logPreviewIfDebug(llmResponseText, maxPreviewChars, contextLabel) {
         return;
     logger.debug({ preview: llmResponseText.slice(0, maxPreviewChars) }, `${contextLabel}: raw response preview`);
 }
-function throwParseFailure(options, llmResponseText, maxPreviewChars) {
+function throwParseFailure(options, llmResponseText, maxPreviewChars, failureDetail) {
     const contextLabel = options.debugLabel ?? 'LLM response';
     logPreviewIfDebug(llmResponseText, maxPreviewChars, contextLabel);
     throw new McpError(options.errorCode, `Failed to parse ${contextLabel} as JSON`, undefined, {
         strategiesAttempted: ['raw', 'codeblock-stripped', 'extracted-json'],
         parseFailed: true,
+        ...(failureDetail
+            ? {
+                parseErrorStage: failureDetail.stage,
+                parseErrorMessage: failureDetail.message,
+            }
+            : {}),
     });
 }
 function resolveParseOptions(options) {
@@ -62,45 +62,43 @@ function resolveParseOptions(options) {
         debugLabel: options.debugLabel,
     };
 }
-function isJsonStart(text) {
+function shouldTryRawParse(text) {
+    if (text.startsWith('```'))
+        return false;
     const firstChar = text[0];
     return firstChar === '{' || firstChar === '[';
 }
-function shouldTryRawParse(text) {
-    return !text.startsWith('```') && isJsonStart(text);
-}
-function attemptParse(payload, label, parse, debugLabel) {
-    const attempt = tryParseJson(payload, parse, debugLabel, label);
-    return attempt.success ? attempt.value : null;
-}
-function parseRawCandidate(text, parse, debugLabel) {
-    if (!shouldTryRawParse(text))
-        return null;
-    return attemptParse(text, 'raw', parse, debugLabel);
-}
-function parseStrippedCandidate(text, parse, debugLabel) {
+function parseJsonCandidates(text, parse, debugLabel) {
     const stripped = stripCodeBlockMarkers(text);
-    if (shouldTryRawParse(text) && stripped === text)
-        return null;
-    return attemptParse(stripped, 'stripped markers', parse, debugLabel);
-}
-function parseExtractedCandidate(text, parse, debugLabel) {
     const extracted = extractFirstJsonFragment(text);
-    if (!extracted)
-        return null;
-    return attemptParse(extracted, 'extracted fragment', parse, debugLabel);
+    const candidates = [
+        { label: 'raw', value: shouldTryRawParse(text) ? text : null },
+        {
+            label: 'stripped markers',
+            value: stripped !== text ? stripped : null,
+        },
+        { label: 'extracted fragment', value: extracted },
+    ];
+    return parseCandidates(candidates, parse, debugLabel);
 }
-function parseJsonCandidates(text, parse, debugLabel) {
-    return (parseRawCandidate(text, parse, debugLabel) ??
-        parseStrippedCandidate(text, parse, debugLabel) ??
-        parseExtractedCandidate(text, parse, debugLabel));
+function parseCandidates(candidates, parse, debugLabel) {
+    let lastError = null;
+    for (const candidate of candidates) {
+        if (!candidate.value)
+            continue;
+        const attempt = tryParseJson(candidate.value, parse, debugLabel, candidate.label);
+        if (attempt.success)
+            return { value: attempt.value };
+        lastError = attempt.error;
+    }
+    return { error: lastError };
 }
 export function parseJsonFromLlmResponse(llmResponseText, parse, options) {
     const parseOptions = resolveParseOptions(options);
     enforceMaxInputLength(llmResponseText, parseOptions.maxInputLength, parseOptions.errorCode);
     const jsonStr = llmResponseText.trim();
     const parsed = parseJsonCandidates(jsonStr, parse, parseOptions.debugLabel);
-    if (parsed !== null)
-        return parsed;
-    return throwParseFailure(parseOptions, llmResponseText, parseOptions.maxPreviewChars);
+    if ('value' in parsed)
+        return parsed.value;
+    return throwParseFailure(parseOptions, llmResponseText, parseOptions.maxPreviewChars, parsed.error);
 }

package/dist/lib/llm-providers.js

@@ -41,7 +41,6 @@ class AnthropicClient {
         return this.model;
     }
 }
-// Google safety categories for content filtering
 const GOOGLE_SAFETY_CATEGORIES = [
     HarmCategory.HARM_CATEGORY_HATE_SPEECH,
     HarmCategory.HARM_CATEGORY_HARASSMENT,
@@ -74,8 +73,6 @@ class GoogleClient {
         return response.trim();
     }
     buildSafetySettings() {
-        // WARNING: Disabling safety settings can expose the application to harmful content.
-        // Use with caution and only in trusted environments.
         const disabled = config.GOOGLE_SAFETY_DISABLED;
         if (this.safetySettingsCache?.disabled === disabled) {
             return this.safetySettingsCache.settings;