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

package/AGENTS.md

@@ -3,7 +3,7 @@
 ## Project Overview
 
 - **Goal**: MCP server for refining, analyzing, optimizing, and validating AI prompts.
-- **Stack**: Node.js (>=20), TypeScript, Model Context Protocol (MCP), Zod, Vitest.
+- **Stack**: Node.js (>=20), TypeScript, Model Context Protocol (MCP), Zod, `node:test`.
 - **Key Libraries**: `@modelcontextprotocol/sdk`, `openai`, `@anthropic-ai/sdk`, `@google/genai`, `zod`.
 
 ## Repo Map / Structure
@@ -38,7 +38,7 @@
 
 ## Testing
 
-- **Run all tests**: `npm run test` (uses Vitest).
+- **Run all tests**: `npm run test` (uses `node:test`).
 - **Watch mode**: `npm run test:watch`.
 - **Coverage**: `npm run test:coverage`.
 - **Test files**: Located in `tests/` directory, matching `*.test.ts`.

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
 
@@ -25,18 +25,37 @@ PromptTuner checks that the correct API key environment variable is set at start
 
 Set `LLM_MODEL` to override the default model for the chosen provider.
 
+## CLI overrides
+
+CLI flags override environment variables. Flags only cover a subset of settings; retry options and `GOOGLE_SAFETY_DISABLED` are env-only.
+
+| Flag                           | Env var                 | Description                                 |
+| ------------------------------ | ----------------------- | ------------------------------------------- | --------------------------------------- |
+| `--log-format <text            | json>`                  | `LOG_FORMAT`                                | Override log format (currently unused). |
+| `--debug / --no-debug`         | `DEBUG`                 | Enable/disable debug logging.               |
+| `--include-error-context`      | `INCLUDE_ERROR_CONTEXT` | Include sanitized prompt snippet in errors. |
+| `--llm-provider <provider>`    | `LLM_PROVIDER`          | `openai`, `anthropic`, or `google`.         |
+| `--llm-model <name>`           | `LLM_MODEL`             | Override the default model.                 |
+| `--llm-timeout-ms <number>`    | `LLM_TIMEOUT_MS`        | Override request timeout (ms).              |
+| `--llm-max-tokens <number>`    | `LLM_MAX_TOKENS`        | Override output token cap.                  |
+| `--max-prompt-length <number>` | `MAX_PROMPT_LENGTH`     | Override max prompt length (chars).         |
+
 ## Limits and timeouts (optional)
 
 | Variable            | Default | Description                          |
 | ------------------- | ------- | ------------------------------------ |
 | `MAX_PROMPT_LENGTH` | `10000` | Max trimmed prompt length (chars).   |
 | `LLM_MAX_TOKENS`    | `8000`  | Upper bound for model output tokens. |
-| `LLM_TIMEOUT_MS`    | `60000` | Per-request timeout (ms).            |
+| `LLM_TIMEOUT_MS`    | `60000` | 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.
-- If raw input exceeds `MAX_PROMPT_LENGTH * 2`, it is rejected as excessive whitespace.
+- Raw input length is capped at `MAX_PROMPT_LENGTH * 2` before trimming.
 - If trimmed input exceeds `MAX_PROMPT_LENGTH`, it is rejected.
 
 ### Tool token caps
@@ -59,15 +78,19 @@ Tool max tokens are derived from `LLM_MAX_TOKENS`:
 | `RETRY_MAX_DELAY_MS`     | `10000`  | Max delay between retries.                     |
 | `RETRY_TOTAL_TIMEOUT_MS` | `180000` | Total time allowed across retries.             |
 
-Retries use exponential backoff with jitter and stop when the total timeout is exceeded.
+Retries use exponential backoff (no 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.                             |
+
+When `DEBUG=true`, the server also logs diagnostics-channel telemetry for LLM requests and event-loop health.
 
 ## Provider-specific settings
 
@@ -179,7 +202,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 +215,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 +238,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
 
@@ -24,10 +24,11 @@ PromptTuner MCP is an MCP server that refines, analyzes, optimizes, and validate
 - Auto-detect target format (Claude XML, GPT Markdown, or JSON).
 - Structured outputs with provider/model metadata, fallback indicators, and score normalization.
 - Retry logic with exponential backoff for transient provider failures.
+- Emits MCP progress notifications for `analyze_prompt` when a progress token is provided.
 
 ## 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
 
@@ -52,7 +53,7 @@ Add to `claude_desktop_config.json`:
 
 ## Configuration (Essentials)
 
-PromptTuner reads configuration from environment variables. Full reference in `CONFIGURATION.md`.
+PromptTuner reads configuration from environment variables. CLI flags can override them (run `prompt-tuner-mcp-server --help`). Full reference in `CONFIGURATION.md`.
 
 | Variable            | Default          | Description                                    |
 | ------------------- | ---------------- | ---------------------------------------------- |
@@ -65,6 +66,21 @@ PromptTuner reads configuration from environment variables. Full reference in `C
 | `LLM_MAX_TOKENS`    | `8000`           | Upper bound for LLM outputs (tool caps apply). |
 | `MAX_PROMPT_LENGTH` | `10000`          | Max trimmed prompt length (chars).             |
 
+## CLI Options
+
+CLI flags override environment variables (run `prompt-tuner-mcp-server --help`).
+
+| Flag                           | Env var                 | Description                                 |
+| ------------------------------ | ----------------------- | ------------------------------------------- | --------------------------------------- |
+| `--log-format <text            | json>`                  | `LOG_FORMAT`                                | Override log format (currently unused). |
+| `--debug / --no-debug`         | `DEBUG`                 | Enable/disable debug logging.               |
+| `--include-error-context`      | `INCLUDE_ERROR_CONTEXT` | Include sanitized prompt snippet in errors. |
+| `--llm-provider <provider>`    | `LLM_PROVIDER`          | `openai`, `anthropic`, or `google`.         |
+| `--llm-model <name>`           | `LLM_MODEL`             | Override the default model.                 |
+| `--llm-timeout-ms <number>`    | `LLM_TIMEOUT_MS`        | Override request timeout (ms).              |
+| `--llm-max-tokens <number>`    | `LLM_MAX_TOKENS`        | Override output token cap.                  |
+| `--max-prompt-length <number>` | `MAX_PROMPT_LENGTH`     | Override max prompt length (chars).         |
+
 ## Tools
 
 All tools accept plain text, Markdown, or XML prompts. Responses include `content` (human-readable) and `structuredContent` (machine-readable).
@@ -95,11 +111,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; order preserved. `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 +135,11 @@ 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.
+- Error responses also include `isError: true`.
+- `refine_prompt` and `optimize_prompt` include a `resource` content block with a `file:///` URI and the prompt text in `resource.text` (Markdown).
 
 ## Prompts
 
@@ -132,6 +149,8 @@ Token limits used for `validate_prompt`: `claude` 200000, `gpt` 128000, `gemini`
 | `deep-optimize`  | Comprehensive optimization using the `comprehensive` technique. |
 | `analyze`        | Score prompt quality and return suggestions.                    |
 
+All prompts accept a single argument: `{ "prompt": "..." }`.
+
 ## Prompt Optimization Workflow
 
 ### Technique selection guide
@@ -159,27 +178,29 @@ 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 prepare`        | Build on install (publishing helper).                 |
+| `npm run dev`            | Run from source in watch mode.                        |
+| `npm run dev:http`       | Alias of `npm run dev` (no HTTP transport yet).       |
+| `npm run watch`          | TypeScript compiler in watch mode.                    |
+| `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 `node:test` once.                                 |
+| `npm run test:coverage`  | Run `node:test` with experimental coverage.           |
+| `npm run test:watch`     | Run `node:test` 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,12 +211,10 @@ 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
 
-tests/            Vitest suites
+tests/            node:test suites
 
 dist/             Compiled output (generated)
 

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,15 @@
-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;
-}
-interface BlobResourcePayload {
-    uri: string;
     mimeType?: string;
-    blob: string;
 }
-interface ResourceContentBlock {
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
     type: 'resource';
-    resource: TextResourcePayload | BlobResourcePayload;
-}
-interface ResourceLinkContentBlock {
-    type: 'resource_link';
-    uri: string;
-    name: string;
-    description?: string;
-    mimeType?: string;
-}
-export type ContentBlock = TextContentBlock | ResourceContentBlock | ResourceLinkContentBlock;
+    resource: ResourceTextPayload;
+};
 export interface ErrorResponse {
     [key: string]: unknown;
     content: ContentBlock[];
@@ -86,7 +70,10 @@ export interface FormatResult {
     rawScore: number;
 }
 export type LLMProvider = 'openai' | 'anthropic' | 'google';
-export type ValidProvider = 'openai' | 'anthropic' | 'google';
+export interface ProviderInfo {
+    provider: LLMProvider;
+    model: string;
+}
 export interface SafeErrorDetails {
     status?: number;
     code?: string;
@@ -113,12 +100,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>;