@taplid/mcp 0.4.8 → 0.5.1

package/README.md

@@ -12,7 +12,7 @@ Use Taplid from Claude Desktop, Cursor, or any MCP-aware client to verify AI-gen
 
 ## What it does
 
-Registers one MCP tool, `taplid_audit`, that accepts three text fields and returns ALLOW / REVIEW / BLOCK with a 0-100 trust score and a structured summary.
+Registers one MCP tool, `taplid_audit`. Only `response` is required; `context`, `prompt`, and `auditMode` are all optional (matches the public API and CLI). Returns ALLOW / REVIEW / BLOCK with a 0-100 trust score and a structured summary.
 
 - One tool only. No file reading. No command execution. No repo scanning.
 - Stdio transport. Local process launched by the MCP client.
@@ -80,15 +80,25 @@ Logs go to stderr only. Stdout is reserved for the MCP protocol.
 
 `TAPLID_API_KEY` is read from the MCP client env block.
 
+### Input fields
+
+| Field | Required | Description |
+|---|---|---|
+| `context` | no | The source material the artifact must be consistent with (diff, spec, code, docs). |
+| `prompt` | no | The prompt or task that produced the artifact. |
+| `response` | yes | The AI-generated artifact to verify. |
+| `auditMode` | no | `'artifact'` (default) or `'standard'`. Artifact mode is recommended for code reviews, PRs, implementation plans, long answers, and structured outputs. Standard mode is best for short factual, policy, refund, pricing, entitlement, and simple answer checks. Still being calibrated. |
+
 ### Worked example
 
-Input:
+Input (short factual check, standard mode):
 
 ```json
 {
   "context": "The number is 1.",
   "prompt": "What is the number?",
-  "response": "The number is 2."
+  "response": "The number is 2.",
+  "auditMode": "standard"
 }
 ```
 
@@ -97,6 +107,7 @@ Expected envelope:
 ```json
 {
   "auditId": "AUD-XXX...",
+  "auditMode": "standard",
   "decision": "BLOCK",
   "trustScore": 0,
   "summary": "This answer conflicts with the provided context.",
@@ -131,6 +142,7 @@ Expected envelope:
 ### Response fields
 
 - **auditId** — unique identifier for this audit run
+- **auditMode** — the effective mode that actually ran: `'artifact'` or `'standard'`
 - **decision** — `ALLOW`, `REVIEW`, or `BLOCK`
 - **trustScore** — 0 to 100 public trust signal
 - **summary** — short explanation for the verdict
@@ -148,7 +160,7 @@ The MCP tool returns structured errors with stable codes; no stack traces, no ra
 
 | Code | When |
 |---|---|
-| `INVALID_INPUT` | A required field is missing or not a non-empty string. |
+| `INVALID_INPUT` | `response` is missing or empty, or any other field has an invalid value. |
 | `INPUT_TOO_LARGE` | One of `context`, `prompt`, `response` exceeds 120,000 characters. Detected pre-network. |
 | `MISSING_API_KEY` | `TAPLID_API_KEY` is not set. Detected pre-network. |
 | `UPSTREAM_AUTH_FAILED` | The Taplid API returned 401 or 403. |
@@ -166,6 +178,19 @@ The MCP tool returns structured errors with stable codes; no stack traces, no ra
 - Logs redact the API key, the `Authorization` header, and the bodies of `context`, `prompt`, `response`. Stdout is reserved for the MCP protocol.
 - The package never imports core Taplid engine code. The audit pipeline is reached via Taplid's public HTTP audit endpoint, which preserves all server-side guards.
 
+## Release notes
+
+### v0.5.0 (ITD-442)
+
+Two changes to align the MCP tool with the public API + CLI contract:
+
+1. **Input schema relaxed**: only `response` is required now. `context`, `prompt`, and `auditMode` are all optional. This matches the public Taplid API schema and the CLI. Callers that previously sent all three fields keep working unchanged.
+2. **`auditMode` is now an exposed field**:
+   - `'artifact'` (default when omitted): recommended for code reviews, PRs, implementation plans, long answers, and structured outputs.
+   - `'standard'`: best for short factual, policy, refund, pricing, entitlement, and simple answer checks. Still being calibrated.
+
+The response envelope now always carries `auditMode` to show the effective mode that actually ran. MCP clients (Claude Desktop, Cursor) that cache tool schemas may need a hard refresh to pick up the new field.
+
 ## License
 
 Same license as the parent Taplid workspace.

package/dist/input-schema.d.ts

@@ -1,21 +1,35 @@
 import { z } from 'zod';
-export declare const TAPLID_AUDIT_INPUT_SHAPE: {
-    readonly context: z.ZodString;
-    readonly prompt: z.ZodString;
-    readonly response: z.ZodString;
-};
+export declare const TAPLID_AUDIT_INPUT_SHAPE: z.ZodObject<{
+    context: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    response: z.ZodString;
+    auditMode: z.ZodOptional<z.ZodEnum<["artifact", "standard"]>>;
+}, "strict", z.ZodTypeAny, {
+    response: string;
+    context?: string | undefined;
+    prompt?: string | undefined;
+    auditMode?: "artifact" | "standard" | undefined;
+}, {
+    response: string;
+    context?: string | undefined;
+    prompt?: string | undefined;
+    auditMode?: "artifact" | "standard" | undefined;
+}>;
 export declare const TAPLID_AUDIT_INPUT: z.ZodObject<{
-    readonly context: z.ZodString;
-    readonly prompt: z.ZodString;
-    readonly response: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    response: z.ZodString;
+    auditMode: z.ZodOptional<z.ZodEnum<["artifact", "standard"]>>;
 }, "strict", z.ZodTypeAny, {
-    context: string;
-    prompt: string;
     response: string;
+    context?: string | undefined;
+    prompt?: string | undefined;
+    auditMode?: "artifact" | "standard" | undefined;
 }, {
-    context: string;
-    prompt: string;
     response: string;
+    context?: string | undefined;
+    prompt?: string | undefined;
+    auditMode?: "artifact" | "standard" | undefined;
 }>;
 export type TaplidAuditInput = z.infer<typeof TAPLID_AUDIT_INPUT>;
 export declare const TOOL_INPUT_JSON_SCHEMA: {
@@ -33,8 +47,13 @@ export declare const TOOL_INPUT_JSON_SCHEMA: {
             type: "string";
             description: string;
         };
+        auditMode: {
+            type: "string";
+            description: string;
+            enum: readonly ["artifact", "standard"];
+        };
     };
-    required: readonly ["context", "prompt", "response"];
+    required: readonly ["response"];
     additionalProperties: false;
 };
 export declare const TOOL_DESCRIPTION: string;

package/dist/input-schema.js

@@ -1,28 +1,38 @@
 import { MAX_REVIEW_FIELD_CHARS } from '@taplid/contract';
 import { z } from 'zod';
-export const TAPLID_AUDIT_INPUT_SHAPE = {
-    context: z.string().min(1).max(MAX_REVIEW_FIELD_CHARS),
-    prompt: z.string().min(1).max(MAX_REVIEW_FIELD_CHARS),
+// ITD-442 2026-05-17: only `response` is required. `context`, `prompt`, and
+// `auditMode` are all optional - this matches the public API schema (see
+// `src/api/review-contract.ts` where every field is `.optional()`) and the
+// CLI flag set. The server defaults `auditMode` to 'artifact' when omitted.
+export const TAPLID_AUDIT_INPUT_SHAPE = z.object({
+    context: z.string().max(MAX_REVIEW_FIELD_CHARS).optional(),
+    prompt: z.string().max(MAX_REVIEW_FIELD_CHARS).optional(),
     response: z.string().min(1).max(MAX_REVIEW_FIELD_CHARS),
-};
-export const TAPLID_AUDIT_INPUT = z.object(TAPLID_AUDIT_INPUT_SHAPE).strict();
+    auditMode: z.enum(['artifact', 'standard']).optional(),
+}).strict();
+export const TAPLID_AUDIT_INPUT = TAPLID_AUDIT_INPUT_SHAPE;
 export const TOOL_INPUT_JSON_SCHEMA = {
     type: 'object',
     properties: {
         context: {
             type: 'string',
-            description: 'The source material the artifact must be consistent with (diff, spec, code, docs).',
+            description: 'Optional. The source material the artifact must be consistent with (diff, spec, code, docs).',
         },
         prompt: {
             type: 'string',
-            description: 'The prompt or task that produced the artifact.',
+            description: 'Optional. The prompt or task that produced the artifact.',
         },
         response: {
             type: 'string',
-            description: 'The AI-generated artifact to verify.',
+            description: 'Required. The AI-generated artifact to verify.',
+        },
+        auditMode: {
+            type: 'string',
+            description: "Optional. Audit mode: 'artifact' (default - recommended for code reviews, PRs, implementation plans, long answers, and structured outputs) or 'standard' (best for short factual, policy, refund, pricing, entitlement, and simple answer checks; still being calibrated).",
+            enum: ['artifact', 'standard'],
         },
     },
-    required: ['context', 'prompt', 'response'],
+    required: ['response'],
     additionalProperties: false,
 };
 export const TOOL_DESCRIPTION = 'Use this before trusting, applying, merging, sending, or acting on an AI-generated artifact. ' +

package/dist/mcp-output.js

@@ -1,12 +1,44 @@
+import { PUBLIC_REVIEW_API_RESPONSE_LOCKED_KEY_ORDER, serializePublicReviewResponse, } from '@taplid/contract';
+// Single canonical gate-out for MCP. Routes the upstream API envelope through
+// `serializePublicReviewResponse` (lenient mode) so any zero-filled or
+// invariant-violating diagnostic fields from upstream get stripped before the
+// envelope reaches the AI agent calling the MCP tool. Lenient mode is correct
+// here because MCP is a client surface: it must never throw on a malformed
+// upstream response; it must clean it up and pass it through. Unknown keys
+// (e.g. future server-added fields) survive passthrough because they sit
+// outside the locked key-order array and were not part of the input contract.
 export function buildMcpOutput(result, cfg) {
-    const envelope = result.envelope;
+    const raw = result.envelope;
+    // The canonical serializer enforces required fields (decision/trustScore/
+    // summary/issues/nextStep) and emits in locked key order. Any field whose
+    // value is undefined/non-finite/invalid is omitted (no zero-fill).
+    const canonical = serializePublicReviewResponse(raw, {
+        onInvariantViolation: () => {
+            // Silent in production. Backend logs the violation at emit time; the
+            // MCP client surface must never throw on a malformed upstream response.
+        },
+    });
+    // Preserve any forward-compat keys from `raw` that the contract's locked key
+    // order does not know about. The exclude set is the FULL locked-key array
+    // (not just the keys the canonical serializer chose to emit) so legacy keys
+    // like `appliedPolicy` and `details` - which the canonical intentionally
+    // strips per ITD-225 / 2026-05-15 envelope cleanup - cannot be re-injected
+    // by the passthrough loop. Truly-unknown future keys (anything not in the
+    // locked order) still flow through.
+    const lockedKeySet = new Set(PUBLIC_REVIEW_API_RESPONSE_LOCKED_KEY_ORDER);
+    const forward = { ...canonical };
+    for (const [k, v] of Object.entries(raw)) {
+        if (!lockedKeySet.has(k) && v !== undefined) {
+            forward[k] = v;
+        }
+    }
     if (!cfg.debug)
-        return envelope;
+        return forward;
     const debug = {
         latencyMs: result.latencyMs,
         bytesIn: result.bytesIn,
         httpStatus: result.httpStatus,
     };
-    return { ...envelope, _debug: debug };
+    return { ...forward, _debug: debug };
 }
 //# sourceMappingURL=mcp-output.js.map

package/dist/server.js

@@ -9,7 +9,7 @@ import { handleTaplidAudit } from './tool.js';
 export function createServer() {
     const server = new McpServer({
         name: 'taplid-mcp',
-        version: '0.4.8',
+        version: '0.5.1',
     });
     server.registerTool(TOOL_NAME, {
         description: TOOL_DESCRIPTION,

package/dist/taplid-client.d.ts

@@ -1,8 +1,9 @@
 import type { ResolvedConfig } from './config.js';
 export interface ReviewRequest {
-    context: string;
-    prompt: string;
+    context?: string;
+    prompt?: string;
     response: string;
+    auditMode?: 'artifact' | 'standard';
 }
 export interface ReviewClientDeps {
     fetchImpl?: typeof globalThis.fetch;

package/dist/taplid-client.js

@@ -1,3 +1,4 @@
+import { ContractValidationError, createReviewRequestPayload } from '@taplid/contract';
 import { McpToolError } from './errors.js';
 export async function postArtifactReview(req, cfg, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
@@ -11,6 +12,25 @@ export async function postArtifactReview(req, cfg, deps = {}) {
             reject(new McpToolError('UPSTREAM_TIMEOUT', `Taplid API did not respond within ${cfg.timeoutMs}ms. Check TAPLID_API_URL and network connectivity.`));
         }, cfg.timeoutMs);
     });
+    // Single canonical gate-in for the POST body. createReviewRequestPayload
+    // returns the three required keys, trimmed, with hard length caps enforced.
+    // auditMode (ITD-442) is appended separately; it is optional and has already
+    // been validated by the Zod schema in tool.ts before reaching this function.
+    let wireBody;
+    try {
+        const canonical = createReviewRequestPayload(req);
+        const body = { ...canonical };
+        if (req.auditMode !== undefined) {
+            body['auditMode'] = req.auditMode;
+        }
+        wireBody = JSON.stringify(body);
+    }
+    catch (err) {
+        if (err instanceof ContractValidationError) {
+            throw new McpToolError('INVALID_INPUT', `Taplid request payload is invalid: ${err.message}`);
+        }
+        throw err;
+    }
     let res;
     let text;
     try {
@@ -22,11 +42,7 @@ export async function postArtifactReview(req, cfg, deps = {}) {
                         'content-type': 'application/json',
                         authorization: `Bearer ${cfg.apiKey}`,
                     },
-                    body: JSON.stringify({
-                        context: req.context,
-                        prompt: req.prompt,
-                        response: req.response,
-                    }),
+                    body: wireBody,
                     signal: controller.signal,
                 }),
                 timeoutSignal,

package/dist/tool.js

@@ -17,12 +17,26 @@ export async function handleTaplidAudit(rawInput, deps = {}) {
         const tooLarge = parsed.error.issues.some((issue) => issue.code === 'too_big');
         const code = tooLarge ? 'INPUT_TOO_LARGE' : 'INVALID_INPUT';
         const message = tooLarge
-            ? 'One of context/prompt/response exceeds the Taplid artifact-mode length limit.'
-            : 'taplid_audit requires non-empty string fields: context, prompt, response.';
+            ? 'One of context/prompt/response exceeds the Taplid length limit.'
+            : 'taplid_audit requires a non-empty `response` string; `context`, `prompt`, and `auditMode` are optional.';
         return toolErrorResult(new McpToolError(code, message));
     }
     try {
-        const result = await postArtifactReview(parsed.data, cfg, deps);
+        // ITD-442 2026-05-17: only `response` is required. Build the ReviewRequest
+        // object explicitly so exactOptionalPropertyTypes is satisfied - do not
+        // spread parsed.data directly. Optional fields are only attached when
+        // present so the wire body stays minimal.
+        const req = { response: parsed.data.response };
+        if (parsed.data.context !== undefined) {
+            req.context = parsed.data.context;
+        }
+        if (parsed.data.prompt !== undefined) {
+            req.prompt = parsed.data.prompt;
+        }
+        if (parsed.data.auditMode !== undefined) {
+            req.auditMode = parsed.data.auditMode;
+        }
+        const result = await postArtifactReview(req, cfg, deps);
         const envelope = buildMcpOutput(result, cfg);
         const decision = typeof envelope.decision === 'string'
             ? envelope.decision

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taplid/mcp",
-  "version": "0.4.8",
+  "version": "0.5.1",
   "description": "Local MCP (Model Context Protocol) server exposing Taplid artifact audit as a single tool for AI coding agents.",
   "keywords": [
     "taplid",
@@ -36,7 +36,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@taplid/contract": "0.4.8",
+    "@taplid/contract": "0.5.1",
     "pino": "^9.0.0",
     "zod": "^3.0.0"
   },