@taplid/mcp 0.4.6

package/README.md

@@ -0,0 +1,165 @@
+# @taplid/mcp
+
+Local MCP (Model Context Protocol) server exposing Taplid's artifact audit as a single tool for AI coding agents.
+
+Use Taplid from Claude Desktop, Cursor, or any MCP-aware client to verify AI-generated artifacts (implementation plans, code reviews, PR reviews, generated technical reports, proposed code changes) against supplied context before trusting, applying, merging, sending, or acting on them.
+
+## 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.
+
+- One tool only. No file reading. No command execution. No repo scanning.
+- Stdio transport. Local process launched by the MCP client.
+- HTTP caller boundary to the existing Taplid API. No engine code is imported.
+
+## Install and configure
+
+The package is invoked as a local binary by an MCP-aware client (Claude Desktop, Cursor, others). It does not need to be globally installed; `npx` resolves it on first invocation.
+
+### Claude Desktop / Cursor (cross-platform)
+
+Add this block to your MCP client's `mcpServers` config and `npx` will resolve the package on first invocation:
+
+```json
+{
+  "mcpServers": {
+    "taplid": {
+      "command": "npx",
+      "args": ["-y", "@taplid/mcp"],
+      "env": {
+        "TAPLID_API_KEY": "tap_live_...",
+        "TAPLID_API_URL": "https://api.taplid.com"
+      }
+    }
+  }
+}
+```
+
+### Local development (Windows path)
+
+For local development against a Taplid API running on your machine:
+
+```json
+{
+  "mcpServers": {
+    "taplid-local": {
+      "command": "node",
+      "args": ["C:\\code\\taplid\\packages\\taplid-mcp\\dist\\server.js"],
+      "env": {
+        "TAPLID_API_KEY": "tap_live_...",
+        "TAPLID_API_URL": "http://127.0.0.1:7000"
+      }
+    }
+  }
+}
+```
+
+Compatible with MCP-aware clients such as Claude Desktop and Cursor where stdio MCP servers are supported. Specific clients may use their own config formats.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TAPLID_API_KEY` | required | Bearer token for the Taplid API. Set this in your MCP client config block. Never passed as a tool input. |
+| `TAPLID_API_URL` | falls back to `TAPLID_PUBLIC_API_URL`, then `https://api.taplid.com` | Base URL for the Taplid API. |
+| `TAPLID_MCP_TIMEOUT_MS` | `60000` | AbortController deadline for each request. Range 1000-600000ms; out-of-range values revert to default. |
+| `TAPLID_MCP_DEBUG` | `false` | When `"true"`, successful responses include a `_debug` object with `{latencyMs, bytesIn, httpStatus}`. Bodies and secrets are never included. |
+| `TAPLID_MCP_LOG_LEVEL` | `info` | Pino log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`. |
+
+Logs go to stderr only. Stdout is reserved for the MCP protocol.
+
+## Tool: `taplid_audit`
+
+`MAX_REVIEW_FIELD_CHARS` characters (120,000). Oversize input is rejected before the network call.
+
+`TAPLID_API_KEY` is read from the MCP client env block.
+
+### Worked example
+
+Input:
+
+```json
+{
+  "context": "The number is 1.",
+  "prompt": "What is the number?",
+  "response": "The number is 2."
+}
+```
+
+Expected envelope:
+
+```json
+{
+  "auditId": "AUD-XXX...",
+  "decision": "BLOCK",
+  "trustScore": 0,
+  "summary": "This answer conflicts with the provided context.",
+  "issues": [
+    {
+      "message": "Contradicts the provided context.",
+      "snippet": "The number is 2.",
+      "reason": "The answer says the opposite of what the context says."
+    }
+  ],
+  "nextStep": "Do not use this yet. Adjust the answer to match the provided context, then re-run the check.",
+  "repairActions": [
+    {
+      "action": "Rewrite the answer so it aligns with the provided context.",
+      "priority": "high",
+      "target": "response"
+    }
+  ],
+  "claims": [
+    {
+      "status": "contradicted",
+      "text": "The number is 2."
+    }
+  ],
+  "details": {
+    "passThreshold": 80,
+    "reviewThreshold": 60
+  }
+}
+```
+
+### Response fields
+
+- **auditId** — unique identifier for this audit run
+- **decision** — `ALLOW`, `REVIEW`, or `BLOCK`
+- **trustScore** — 0 to 100 public trust signal
+- **summary** — short explanation for the verdict
+- **issues** — concrete problems found in the response
+- **nextStep** — practical guidance for what to do next
+- **repairActions** — prioritized steps to fix the response
+- **claims** — individual claims extracted and verified against the context
+- **details.passThreshold / details.reviewThreshold** — decision thresholds set on your account
+
+`repairActions` and `auditId` are present only when the API returns them.
+
+## Error codes
+
+The MCP tool returns structured errors with stable codes; no stack traces, no raw upstream bodies.
+
+| Code | When |
+|---|---|
+| `INVALID_INPUT` | A required field is missing or not a non-empty string. |
+| `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. |
+| `UPSTREAM_RATE_LIMITED` | The Taplid API returned 429. |
+| `UPSTREAM_TIMEOUT` | The request did not complete within `TAPLID_MCP_TIMEOUT_MS`. |
+| `UPSTREAM_UNAVAILABLE` | The Taplid API returned 5xx or the host was unreachable. |
+| `UPSTREAM_BAD_RESPONSE` | The Taplid API returned a body that was not valid JSON or not the expected shape. |
+| `MCP_INTERNAL` | Unexpected internal error. |
+
+## Security model
+
+- One MCP tool. No file I/O, no shell, no process spawning, no inbound network listener.
+- Stdio transport launched by the MCP client. The threat model includes hostile tool input and hostile generated artifacts.
+- `TAPLID_API_KEY` is read from the environment only and is never accepted as a tool input.
+- 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 the public `/api/review` HTTP endpoint, which preserves all server-side guards.
+
+## License
+
+Same license as the parent Taplid workspace.

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+export interface ResolvedConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    debug: boolean;
+    logLevel: string;
+}
+export interface RawEnv {
+    TAPLID_API_URL?: string | undefined;
+    TAPLID_PUBLIC_API_URL?: string | undefined;
+    TAPLID_API_KEY?: string | undefined;
+    TAPLID_MCP_TIMEOUT_MS?: string | undefined;
+    TAPLID_MCP_DEBUG?: string | undefined;
+    TAPLID_MCP_LOG_LEVEL?: string | undefined;
+}
+export declare function resolveConfigOrThrow(envOverride?: RawEnv): ResolvedConfig;
+export declare function resolveConfigForLogger(envOverride?: RawEnv): {
+    debug: boolean;
+    logLevel: string;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,66 @@
+import { McpToolError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://api.taplid.com';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 600_000;
+function readEnv() {
+    return {
+        TAPLID_API_URL: process.env['TAPLID_API_URL'],
+        TAPLID_PUBLIC_API_URL: process.env['TAPLID_PUBLIC_API_URL'],
+        TAPLID_API_KEY: process.env['TAPLID_API_KEY'],
+        TAPLID_MCP_TIMEOUT_MS: process.env['TAPLID_MCP_TIMEOUT_MS'],
+        TAPLID_MCP_DEBUG: process.env['TAPLID_MCP_DEBUG'],
+        TAPLID_MCP_LOG_LEVEL: process.env['TAPLID_MCP_LOG_LEVEL'],
+    };
+}
+function pickBaseUrl(env) {
+    const candidates = [env.TAPLID_API_URL, env.TAPLID_PUBLIC_API_URL];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string') {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0)
+                return trimmed.replace(/\/+$/u, '');
+        }
+    }
+    return DEFAULT_BASE_URL;
+}
+function pickTimeoutMs(env) {
+    const raw = env.TAPLID_MCP_TIMEOUT_MS;
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return DEFAULT_TIMEOUT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < MIN_TIMEOUT_MS || parsed > MAX_TIMEOUT_MS) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    return parsed;
+}
+function pickDebug(env) {
+    return env.TAPLID_MCP_DEBUG === 'true';
+}
+function pickLogLevel(env) {
+    const allowed = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent']);
+    const raw = env.TAPLID_MCP_LOG_LEVEL?.trim().toLowerCase();
+    if (raw !== undefined && allowed.has(raw))
+        return raw;
+    return 'info';
+}
+export function resolveConfigOrThrow(envOverride) {
+    const env = envOverride ?? readEnv();
+    const apiKeyRaw = env.TAPLID_API_KEY;
+    const apiKey = typeof apiKeyRaw === 'string' ? apiKeyRaw.trim() : '';
+    if (apiKey.length === 0) {
+        throw new McpToolError('MISSING_API_KEY', 'TAPLID_API_KEY environment variable is not set. Configure it in your MCP client config block.');
+    }
+    return {
+        baseUrl: pickBaseUrl(env),
+        apiKey,
+        timeoutMs: pickTimeoutMs(env),
+        debug: pickDebug(env),
+        logLevel: pickLogLevel(env),
+    };
+}
+export function resolveConfigForLogger(envOverride) {
+    const env = envOverride ?? readEnv();
+    return { debug: pickDebug(env), logLevel: pickLogLevel(env) };
+}
+//# sourceMappingURL=config.js.map

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare const MCP_ERROR_CODES: readonly ["INVALID_INPUT", "INPUT_TOO_LARGE", "MISSING_API_KEY", "UPSTREAM_AUTH_FAILED", "UPSTREAM_RATE_LIMITED", "UPSTREAM_TIMEOUT", "UPSTREAM_UNAVAILABLE", "UPSTREAM_BAD_RESPONSE", "MCP_INTERNAL"];
+export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
+export declare class McpToolError extends Error {
+    readonly code: McpErrorCode;
+    readonly publicMessage: string;
+    constructor(code: McpErrorCode, publicMessage: string);
+}
+export interface McpErrorPayload {
+    code: McpErrorCode;
+    message: string;
+}
+export declare function mcpErrorPayload(err: McpToolError): McpErrorPayload;
+export declare function errorName(err: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,31 @@
+export const MCP_ERROR_CODES = [
+    'INVALID_INPUT',
+    'INPUT_TOO_LARGE',
+    'MISSING_API_KEY',
+    'UPSTREAM_AUTH_FAILED',
+    'UPSTREAM_RATE_LIMITED',
+    'UPSTREAM_TIMEOUT',
+    'UPSTREAM_UNAVAILABLE',
+    'UPSTREAM_BAD_RESPONSE',
+    'MCP_INTERNAL',
+];
+export class McpToolError extends Error {
+    code;
+    publicMessage;
+    constructor(code, publicMessage) {
+        super(publicMessage);
+        this.code = code;
+        this.publicMessage = publicMessage;
+        this.name = 'McpToolError';
+    }
+}
+export function mcpErrorPayload(err) {
+    return { code: err.code, message: err.publicMessage };
+}
+export function errorName(err) {
+    if (err instanceof Error && typeof err.name === 'string' && err.name.length > 0) {
+        return err.name;
+    }
+    return 'UnknownError';
+}
+//# sourceMappingURL=errors.js.map

package/dist/input-schema.d.ts

@@ -0,0 +1,42 @@
+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: z.ZodObject<{
+    readonly context: z.ZodString;
+    readonly prompt: z.ZodString;
+    readonly response: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    context: string;
+    prompt: string;
+    response: string;
+}, {
+    context: string;
+    prompt: string;
+    response: string;
+}>;
+export type TaplidAuditInput = z.infer<typeof TAPLID_AUDIT_INPUT>;
+export declare const TOOL_INPUT_JSON_SCHEMA: {
+    type: "object";
+    properties: {
+        context: {
+            type: "string";
+            description: string;
+        };
+        prompt: {
+            type: "string";
+            description: string;
+        };
+        response: {
+            type: "string";
+            description: string;
+        };
+    };
+    required: readonly ["context", "prompt", "response"];
+    additionalProperties: false;
+};
+export declare const TOOL_DESCRIPTION: string;
+export declare const TOOL_NAME = "taplid_audit";
+//# sourceMappingURL=input-schema.d.ts.map

package/dist/input-schema.js

@@ -0,0 +1,33 @@
+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),
+    response: z.string().min(1).max(MAX_REVIEW_FIELD_CHARS),
+};
+export const TAPLID_AUDIT_INPUT = z.object(TAPLID_AUDIT_INPUT_SHAPE).strict();
+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).',
+        },
+        prompt: {
+            type: 'string',
+            description: 'The prompt or task that produced the artifact.',
+        },
+        response: {
+            type: 'string',
+            description: 'The AI-generated artifact to verify.',
+        },
+    },
+    required: ['context', 'prompt', 'response'],
+    additionalProperties: false,
+};
+export const TOOL_DESCRIPTION = 'Use this before trusting, applying, merging, sending, or acting on an AI-generated artifact. ' +
+    'Suitable for code reviews, implementation plans, PR reviews, generated technical reports, ' +
+    'proposed code changes, and other structured AI outputs. ' +
+    'Returns ALLOW / REVIEW / BLOCK with a 0-100 trust score and a structured summary.';
+export const TOOL_NAME = 'taplid_audit';
+//# sourceMappingURL=input-schema.js.map

package/dist/logger.d.ts

@@ -0,0 +1,5 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;
+export declare function runRedactSelfTest(): void;
+export declare function truncateForLog(value: string, limit?: number): string;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.js

@@ -0,0 +1,62 @@
+import pino from 'pino';
+import { resolveConfigForLogger } from './config.js';
+const REDACT_PATHS = [
+    'authorization',
+    'Authorization',
+    'apiKey',
+    'api_key',
+    'TAPLID_API_KEY',
+    'context',
+    'prompt',
+    'response',
+    '*.authorization',
+    '*.Authorization',
+    '*.apiKey',
+    '*.api_key',
+    '*.TAPLID_API_KEY',
+    '*.context',
+    '*.prompt',
+    '*.response',
+];
+const stderrSink = {
+    write(chunk) {
+        process.stderr.write(chunk);
+    },
+};
+function buildLogger() {
+    const cfg = resolveConfigForLogger();
+    return pino({
+        level: cfg.logLevel,
+        redact: { paths: REDACT_PATHS, censor: '[REDACTED]', remove: false },
+        base: { service: 'taplid-mcp' },
+    }, stderrSink);
+}
+export const logger = buildLogger();
+export function runRedactSelfTest() {
+    const sentinel = `sk-self-test-secret-${Math.random().toString(36).slice(2)}`;
+    let captured = '';
+    const captureSink = {
+        write(chunk) {
+            captured += chunk;
+        },
+    };
+    const probe = pino({
+        // Force level=trace so the probe info() emits regardless of TAPLID_MCP_LOG_LEVEL.
+        level: 'trace',
+        redact: { paths: REDACT_PATHS, censor: '[REDACTED]', remove: false },
+        base: { service: 'taplid-mcp' },
+    }, captureSink);
+    probe.info({ event: 'redact.self-test', authorization: `Bearer ${sentinel}`, TAPLID_API_KEY: sentinel }, 'redact self-test');
+    if (captured.length === 0) {
+        throw new Error('[taplid-mcp] redact self-test FAILED: no probe record emitted. Refusing to start.');
+    }
+    if (captured.includes(sentinel)) {
+        throw new Error('[taplid-mcp] redact self-test FAILED: secret leaked to stderr. Refusing to start.');
+    }
+}
+export function truncateForLog(value, limit = 200) {
+    if (value.length <= limit)
+        return value;
+    return `${value.slice(0, limit)}[+${value.length - limit} chars]`;
+}
+//# sourceMappingURL=logger.js.map

package/dist/mcp-output.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedConfig } from './config.js';
+import type { ReviewClientResult } from './taplid-client.js';
+export declare function buildMcpOutput(result: ReviewClientResult, cfg: ResolvedConfig): Record<string, unknown>;
+//# sourceMappingURL=mcp-output.d.ts.map

package/dist/mcp-output.js

@@ -0,0 +1,13 @@
+export function buildMcpOutput(result, cfg) {
+    const envelope = result.envelope;
+    if (!cfg.debug)
+        return envelope;
+    const debug = {
+        auditMode: 'artifact',
+        latencyMs: result.latencyMs,
+        bytesIn: result.bytesIn,
+        httpStatus: result.httpStatus,
+    };
+    return { ...envelope, _debug: debug };
+}
+//# sourceMappingURL=mcp-output.js.map

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+export declare function main(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { errorName } from './errors.js';
+import { logger, runRedactSelfTest } from './logger.js';
+import { TAPLID_AUDIT_INPUT_SHAPE, TOOL_DESCRIPTION, TOOL_NAME, } from './input-schema.js';
+import { handleTaplidAudit } from './tool.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'taplid-mcp',
+        version: '0.4.6',
+    });
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TAPLID_AUDIT_INPUT_SHAPE,
+    }, async (rawInput) => handleTaplidAudit(rawInput));
+    return server;
+}
+export async function main() {
+    runRedactSelfTest();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info({ event: 'taplid_mcp.ready' });
+}
+const entry = process.argv[1];
+const invokedDirectly = typeof entry === 'string' && entry.length > 0 && pathToFileURL(entry).href === import.meta.url;
+if (invokedDirectly) {
+    main().catch((err) => {
+        logger.error({ event: 'taplid_mcp.fatal', errorName: errorName(err) });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/taplid-client.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedConfig } from './config.js';
+export interface ReviewRequest {
+    context: string;
+    prompt: string;
+    response: string;
+}
+export interface ReviewClientDeps {
+    fetchImpl?: typeof globalThis.fetch;
+    now?: () => number;
+}
+export interface ReviewClientResult {
+    envelope: unknown;
+    latencyMs: number;
+    bytesIn: number;
+    httpStatus: number;
+}
+export declare function postArtifactReview(req: ReviewRequest, cfg: ResolvedConfig, deps?: ReviewClientDeps): Promise<ReviewClientResult>;
+//# sourceMappingURL=taplid-client.d.ts.map

package/dist/taplid-client.js

@@ -0,0 +1,116 @@
+import { McpToolError } from './errors.js';
+export async function postArtifactReview(req, cfg, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const now = deps.now ?? (() => Date.now());
+    const controller = new AbortController();
+    const t0 = now();
+    let timer;
+    const timeoutSignal = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new McpToolError('UPSTREAM_TIMEOUT', `Taplid API did not respond within ${cfg.timeoutMs}ms. Check TAPLID_API_URL and network connectivity.`));
+        }, cfg.timeoutMs);
+    });
+    let res;
+    let text;
+    try {
+        try {
+            res = await Promise.race([
+                fetchImpl(`${cfg.baseUrl}/api/review`, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${cfg.apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        auditMode: 'artifact',
+                        context: req.context,
+                        prompt: req.prompt,
+                        response: req.response,
+                    }),
+                    signal: controller.signal,
+                }),
+                timeoutSignal,
+            ]);
+        }
+        catch (err) {
+            if (err instanceof McpToolError)
+                throw err;
+            const name = err?.name;
+            if (name === 'AbortError') {
+                throw new McpToolError('UPSTREAM_TIMEOUT', `Taplid API did not respond within ${cfg.timeoutMs}ms. Check TAPLID_API_URL and network connectivity.`);
+            }
+            throw new McpToolError('UPSTREAM_UNAVAILABLE', 'Taplid API is unreachable. Check TAPLID_API_URL and network connectivity.');
+        }
+        try {
+            text = await Promise.race([res.text(), timeoutSignal]);
+        }
+        catch (err) {
+            if (err instanceof McpToolError)
+                throw err;
+            const name = err?.name;
+            if (name === 'AbortError') {
+                throw new McpToolError('UPSTREAM_TIMEOUT', `Taplid API did not respond within ${cfg.timeoutMs}ms. Check TAPLID_API_URL and network connectivity.`);
+            }
+            throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API returned an unreadable response body.');
+        }
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+    const latencyMs = now() - t0;
+    if (res.status === 401 || res.status === 403) {
+        throw new McpToolError('UPSTREAM_AUTH_FAILED', 'Taplid API rejected the API key.');
+    }
+    if (res.status === 429) {
+        throw new McpToolError('UPSTREAM_RATE_LIMITED', 'Taplid API rate limit exceeded. Retry later.');
+    }
+    if (res.status >= 500 && res.status < 600) {
+        throw new McpToolError('UPSTREAM_UNAVAILABLE', 'Taplid API returned a server error.');
+    }
+    if (!res.ok) {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API returned an unexpected response.');
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(text);
+    }
+    catch {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API returned non-JSON.');
+    }
+    assertEnvelopeShape(envelope);
+    return {
+        envelope,
+        latencyMs,
+        bytesIn: Buffer.byteLength(text, 'utf8'),
+        httpStatus: res.status,
+    };
+}
+function assertEnvelopeShape(envelope) {
+    if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response did not match the expected shape.');
+    }
+    const record = envelope;
+    const decision = record['decision'];
+    if (decision !== 'ALLOW' && decision !== 'REVIEW' && decision !== 'BLOCK') {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response is missing a valid decision.');
+    }
+    const trustScore = record['trustScore'];
+    if (typeof trustScore !== 'number' || !Number.isFinite(trustScore)) {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response is missing a valid trustScore.');
+    }
+    const summary = record['summary'];
+    if (typeof summary !== 'string') {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response is missing a valid summary.');
+    }
+    const issues = record['issues'];
+    if (!Array.isArray(issues)) {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response is missing a valid issues array.');
+    }
+    const nextStep = record['nextStep'];
+    if (typeof nextStep !== 'string') {
+        throw new McpToolError('UPSTREAM_BAD_RESPONSE', 'Taplid API response is missing a valid nextStep.');
+    }
+}
+//# sourceMappingURL=taplid-client.js.map

package/dist/tool.d.ts

@@ -0,0 +1,7 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type ReviewClientDeps } from './taplid-client.js';
+export interface HandleAuditDeps extends ReviewClientDeps {
+    envOverride?: Record<string, string | undefined>;
+}
+export declare function handleTaplidAudit(rawInput: unknown, deps?: HandleAuditDeps): Promise<CallToolResult>;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.js

@@ -0,0 +1,64 @@
+import { resolveConfigOrThrow } from './config.js';
+import { McpToolError, errorName, mcpErrorPayload } from './errors.js';
+import { TAPLID_AUDIT_INPUT } from './input-schema.js';
+import { logger, truncateForLog } from './logger.js';
+import { buildMcpOutput } from './mcp-output.js';
+import { postArtifactReview } from './taplid-client.js';
+export async function handleTaplidAudit(rawInput, deps = {}) {
+    let cfg;
+    try {
+        cfg = resolveConfigOrThrow(deps.envOverride);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+    const parsed = TAPLID_AUDIT_INPUT.safeParse(rawInput);
+    if (!parsed.success) {
+        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.';
+        return toolErrorResult(new McpToolError(code, message));
+    }
+    try {
+        const result = await postArtifactReview(parsed.data, cfg, deps);
+        const envelope = buildMcpOutput(result, cfg);
+        const decision = typeof envelope.decision === 'string'
+            ? envelope.decision
+            : 'unknown';
+        const trustScore = typeof envelope.trustScore === 'number'
+            ? envelope.trustScore
+            : null;
+        logger.info({
+            event: 'taplid_audit.ok',
+            auditMode: 'artifact',
+            decision,
+            trustScore,
+            latencyMs: result.latencyMs,
+            bytesIn: result.bytesIn,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(envelope) }],
+        };
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+function toolErrorResult(err) {
+    if (err instanceof McpToolError) {
+        logger.warn({ event: 'taplid_audit.err', errorCode: err.code });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(mcpErrorPayload(err)) }],
+            isError: true,
+        };
+    }
+    logger.error({ event: 'taplid_audit.unhandled', errorName: truncateForLog(errorName(err), 80) });
+    const internal = new McpToolError('MCP_INTERNAL', 'Internal error inside the Taplid MCP server.');
+    return {
+        content: [{ type: 'text', text: JSON.stringify(mcpErrorPayload(internal)) }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=tool.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@taplid/mcp",
+  "version": "0.4.6",
+  "description": "Local MCP (Model Context Protocol) server exposing Taplid artifact audit as a single tool for AI coding agents.",
+  "keywords": [
+    "taplid",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "audit",
+    "trust-score",
+    "claude",
+    "cursor",
+    "ai-safety",
+    "guardrails",
+    "verification"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "taplid-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@taplid/contract": "0.4.6",
+    "pino": "^9.0.0",
+    "zod": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "npm --prefix ../.. --workspace @taplid/contract run build",
+    "build": "tsc -p tsconfig.json",
+    "pretest": "npm --prefix ../.. --workspace @taplid/contract run build",
+    "test": "vitest run -c vitest.config.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm --prefix ../.. run verify:pack:mcp",
+    "publish:public": "npm publish --access public"
+  }
+}