@ttctl/mcp 0.0.0 → 0.1.0-rc.1

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+import { TtctlError } from "@ttctl/core";
+/**
+ * MCP tool-error response shape. Mirrors the Model Context Protocol's
+ * `CallToolResult` for error cases (`isError: true` + `content: [TextContent]`).
+ *
+ * Defined locally rather than re-exporting from `@modelcontextprotocol/sdk`
+ * to keep the typing focused on what TTCtl emits — the upstream SDK type is
+ * a wide union covering all content types we don't return. This shape is
+ * the SUBSET we promise.
+ *
+ * The `[key: string]: unknown` index signature keeps the type structurally
+ * compatible with the SDK's `CallToolResult` (whose own type carries the
+ * same signature for forward-compatibility with new optional fields).
+ * Without it, returning this shape from a `registerTool` callback fails
+ * strict type-checking even though the runtime values are identical.
+ */
+export interface ToolErrorResponse {
+    [key: string]: unknown;
+    isError: true;
+    content: [{
+        type: "text";
+        text: string;
+    }];
+}
+/**
+ * Render a `TtctlError` as an MCP tool-error response (issue #77 § MCP
+ * error presentation).
+ *
+ * The text payload follows the same Error/Recovery/Code blocks the CLI
+ * surface emits, with the `code` echoed as a structured tag MCP-aware LLM
+ * clients can detect programmatically without parsing prose. Multi-line
+ * content stays in `text` since MCP's `TextContent` is a free-form string.
+ */
+export declare function ttctlErrorToToolResponse(err: TtctlError): ToolErrorResponse;
+/**
+ * Convenience guard for tool implementations: if `err` is a `TtctlError`,
+ * return the structured tool response; otherwise fall through (return
+ * `null`) so the caller can apply its own non-typed-error handling.
+ *
+ * Tool implementations consume this as:
+ *
+ * ```ts
+ * try {
+ *   const value = await someService(...);
+ *   return successResponse(value);
+ * } catch (err) {
+ *   const typed = ttctlErrorToToolResponseOrNull(err);
+ *   if (typed !== null) return typed;
+ *   throw err;  // or generic-error response
+ * }
+ * ```
+ */
+export declare function ttctlErrorToToolResponseOrNull(err: unknown): ToolErrorResponse | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAU3E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAKrF"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { TtctlError } from "@ttctl/core";
+/**
+ * Render a `TtctlError` as an MCP tool-error response (issue #77 § MCP
+ * error presentation).
+ *
+ * The text payload follows the same Error/Recovery/Code blocks the CLI
+ * surface emits, with the `code` echoed as a structured tag MCP-aware LLM
+ * clients can detect programmatically without parsing prose. Multi-line
+ * content stays in `text` since MCP's `TextContent` is a free-form string.
+ */
+export function ttctlErrorToToolResponse(err) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: [`Error: ${err.message}`, "", `Recovery: ${err.recovery}`, "", `(Code: ${err.code})`].join("\n"),
+            },
+        ],
+    };
+}
+/**
+ * Convenience guard for tool implementations: if `err` is a `TtctlError`,
+ * return the structured tool response; otherwise fall through (return
+ * `null`) so the caller can apply its own non-typed-error handling.
+ *
+ * Tool implementations consume this as:
+ *
+ * ```ts
+ * try {
+ *   const value = await someService(...);
+ *   return successResponse(value);
+ * } catch (err) {
+ *   const typed = ttctlErrorToToolResponseOrNull(err);
+ *   if (typed !== null) return typed;
+ *   throw err;  // or generic-error response
+ * }
+ * ```
+ */
+export function ttctlErrorToToolResponseOrNull(err) {
+    if (err instanceof TtctlError) {
+        return ttctlErrorToToolResponse(err);
+    }
+    return null;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAuBzC;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAe;IACtD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,aAAa,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;aACvG;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,8BAA8B,CAAC,GAAY;IACzD,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;QAC9B,OAAO,wBAAwB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { buildServer, runMcpStdio } from "./server.js";
+export type { BuildServerOptions } from "./server.js";
+export { DATA_HANDLING_FOOTER, HIGH_RISK_TOOLS, THIRDPARTY_FREETEXT_FOOTER, composeDescription, } from "./data-handling.js";
+export { ttctlErrorToToolResponse, ttctlErrorToToolResponseOrNull } from "./errors.js";
+export type { ToolErrorResponse } from "./errors.js";
+export { emitMcpAuthResolve, emitMcpDebug, extractTransportStatus, extractTransportSurface, getMcpDiagnosticLogger, isTransportError, redactToolArgs, resetMcpDiagnosticLogger, setMcpDiagnosticLogger, wrapToolHandler, } from "./diagnostic.js";
+export type { McpAuthResolveRecord, McpDebugRecord, McpDiagnosticLogger, McpToolInvokeEndRecord, McpToolInvokeStartRecord, McpToolInvokeStatus, McpTransportErrorRecord, } from "./diagnostic.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { buildServer, runMcpStdio } from "./server.js";
+export { DATA_HANDLING_FOOTER, HIGH_RISK_TOOLS, THIRDPARTY_FREETEXT_FOOTER, composeDescription, } from "./data-handling.js";
+export { ttctlErrorToToolResponse, ttctlErrorToToolResponseOrNull } from "./errors.js";
+export { emitMcpAuthResolve, emitMcpDebug, extractTransportStatus, extractTransportSurface, getMcpDiagnosticLogger, isTransportError, redactToolArgs, resetMcpDiagnosticLogger, setMcpDiagnosticLogger, wrapToolHandler, } from "./diagnostic.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAGvF,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/kill-switch-hook.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MCP-side wire-up for the remote version-killed manifest (#312).
+ *
+ * Invoked from `buildServer` at construction time (AC 4). Two
+ * differences from the CLI hook:
+ *
+ *   1. **Fire-and-forget**: the server constructor must stay sync
+ *      (the MCP SDK's `McpServer` doesn't support an async build path,
+ *      and a long blocking startup would interrupt the JSON-RPC
+ *      handshake with the client). The check runs as a detached
+ *      Promise; the warning lands on stderr whenever the fetch
+ *      resolves.
+ *   2. **Always warn, never refuse**: refusing a long-lived MCP
+ *      server has no usable semantics — mid-flight tool calls would
+ *      be interrupted, the Claude Desktop / Cursor session would
+ *      receive a partial response, and the operator may not see the
+ *      stderr trail. The runbook documents this asymmetry.
+ *
+ * Also schedules a recurring refetch every ~24h per the issue's
+ * frequency spec, with `.unref()` so the timer never holds the
+ * process alive — natural Node exit semantics remain intact.
+ *
+ * **Fail-silent contract**: every error path is swallowed. Even an
+ * unexpected throw inside the fire-and-forget Promise is caught (via
+ * the `.catch()` on the returned Promise) so no `unhandledRejection`
+ * fires.
+ */
+export interface McpKillSwitchHookOptions {
+    /** Override stderr writer. Default: `process.stderr.write`. */
+    writeStderr?: (chunk: string) => void;
+    /** Override the running version (default: read from this package's package.json). */
+    version?: string;
+    /** Override the manifest URL. */
+    url?: string;
+    /** Override the per-fetch timeout (ms). */
+    timeoutMs?: number;
+    /** Override the refetch interval (ms). Default: ~24h. */
+    refetchIntervalMs?: number;
+    /** Injected fetch. Tests pass a mock. */
+    fetchFn?: typeof globalThis.fetch;
+    /**
+     * Override `setInterval`. Tests inject a controllable timer to verify
+     * the refetch loop without waiting 24h. The returned handle must
+     * carry an `unref` method (Node's `Timeout`). When omitted, the real
+     * `setInterval` is used.
+     */
+    setIntervalFn?: typeof globalThis.setInterval;
+}
+/** Returned handle for callers that want to cancel the refetch loop. */
+export interface McpKillSwitchHandle {
+    /** Stop the refetch timer. After this, no further checks fire. */
+    stop: () => void;
+    /**
+     * The Promise from the initial at-startup check. Exposed for tests
+     * that need to await the first-fetch completion. Production callers
+     * do NOT await this — buildServer is sync.
+     */
+    initialCheck: Promise<void>;
+}
+/**
+ * Schedule the startup + recurring kill-switch checks for the MCP
+ * server. Returns a handle the caller can use to stop the refetch
+ * timer (mostly useful for tests; production callers ignore it — the
+ * `.unref()` timer dies naturally on process exit).
+ */
+export declare function scheduleMcpKillSwitch(opts?: McpKillSwitchHookOptions): McpKillSwitchHandle;
+//# sourceMappingURL=kill-switch-hook.d.ts.map

package/dist/kill-switch-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-switch-hook.d.ts","sourceRoot":"","sources":["../src/kill-switch-hook.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAClC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,UAAU,CAAC,WAAW,CAAC;CAC/C;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAmCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,wBAA6B,GAAG,mBAAmB,CAwB9F"}

package/dist/kill-switch-hook.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { checkKillSwitch, formatKillSwitchMessage, KILL_SWITCH_DEFAULT_REFETCH_INTERVAL_MS, KILL_SWITCH_DEFAULT_TIMEOUT_MS, readPackageVersion, } from "@ttctl/core";
+async function runOnce(opts, version) {
+    try {
+        const result = await checkKillSwitch({
+            version,
+            ...(opts.url !== undefined ? { url: opts.url } : {}),
+            timeoutMs: opts.timeoutMs ?? KILL_SWITCH_DEFAULT_TIMEOUT_MS,
+            ...(opts.fetchFn !== undefined ? { fetchFn: opts.fetchFn } : {}),
+        });
+        if (result.status !== "match")
+            return;
+        const writeStderr = opts.writeStderr ??
+            ((chunk) => {
+                process.stderr.write(chunk);
+            });
+        writeStderr(formatKillSwitchMessage({
+            toolName: "ttctl mcp",
+            version,
+            entry: result.entry,
+        }));
+        // Per docstring: MCP always warns even when entry.action === "refuse".
+        // No process.exit, no server-side enforcement of refuse.
+    }
+    catch {
+        // Outer envelope: even if checkKillSwitch were to throw (it shouldn't —
+        // it returns a discriminated result for every failure path), swallow
+        // here so the fire-and-forget Promise never surfaces as an
+        // unhandledRejection.
+    }
+}
+/**
+ * Schedule the startup + recurring kill-switch checks for the MCP
+ * server. Returns a handle the caller can use to stop the refetch
+ * timer (mostly useful for tests; production callers ignore it — the
+ * `.unref()` timer dies naturally on process exit).
+ */
+export function scheduleMcpKillSwitch(opts = {}) {
+    const version = opts.version ?? readPackageVersion(import.meta.url);
+    const refetchIntervalMs = opts.refetchIntervalMs ?? KILL_SWITCH_DEFAULT_REFETCH_INTERVAL_MS;
+    const setIntervalImpl = opts.setIntervalFn ?? globalThis.setInterval;
+    const initialCheck = runOnce(opts, version);
+    const timer = setIntervalImpl(() => {
+        void runOnce(opts, version);
+    }, refetchIntervalMs);
+    // Don't hold the process alive solely for this timer — natural Node
+    // exit semantics (e.g., stdin EOF terminating the MCP transport)
+    // must still terminate the daemon. The injected setIntervalFn type
+    // is `typeof globalThis.setInterval` which returns NodeJS.Timeout —
+    // .unref() is always present on the contract; tests supply a stub
+    // that includes the method.
+    timer.unref();
+    return {
+        stop: () => {
+            clearInterval(timer);
+        },
+        initialCheck,
+    };
+}
+//# sourceMappingURL=kill-switch-hook.js.map

package/dist/kill-switch-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-switch-hook.js","sourceRoot":"","sources":["../src/kill-switch-hook.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,uCAAuC,EACvC,8BAA8B,EAC9B,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAgErB,KAAK,UAAU,OAAO,CAAC,IAA8B,EAAE,OAAe;IACpE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;YACnC,OAAO;YACP,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,8BAA8B;YAC3D,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO;QAEtC,MAAM,WAAW,GACf,IAAI,CAAC,WAAW;YAChB,CAAC,CAAC,KAAa,EAAQ,EAAE;gBACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC,CAAC,CAAC;QACL,WAAW,CACT,uBAAuB,CAAC;YACtB,QAAQ,EAAE,WAAW;YACrB,OAAO;YACP,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CACH,CAAC;QACF,uEAAuE;QACvE,yDAAyD;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,qEAAqE;QACrE,2DAA2D;QAC3D,sBAAsB;IACxB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAiC,EAAE;IACvE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,uCAAuC,CAAC;IAC5F,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,IAAI,UAAU,CAAC,WAAW,CAAC;IAErE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE;QACjC,KAAK,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtB,oEAAoE;IACpE,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,4BAA4B;IAC5B,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,OAAO;QACL,IAAI,EAAE,GAAS,EAAE;YACf,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,YAAY;KACb,CAAC;AACJ,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,100 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type McpDiagnosticLogger } from "./diagnostic.js";
+import { type McpKillSwitchHookOptions } from "./kill-switch-hook.js";
+/**
+ * Options accepted by `buildServer` and `runMcpStdio`.
+ *
+ * - `configPath` — explicit config-file path captured by the CLI's
+ *   `--config <path>` flag (or any future SSE/HTTP transport entry).
+ *   When undefined, `resolveConfig` falls through to the
+ *   `TTCTL_CONFIG_FILE` env var, then to `~/.ttctl.yaml` (the canonical
+ *   3-step chain documented in CLAUDE.md § Config File Resolution).
+ * - `logger` — optional MCP diagnostic logger override (issue #224).
+ *   When supplied to `runMcpStdio`, the logger is installed BEFORE
+ *   `buildServer` runs, so every tool-registration instrumentation +
+ *   every per-call emission routes through the injected logger.
+ *   Production callers omit this field; tests inject a capturing
+ *   logger to assert emission shape without manipulating
+ *   `process.env`. When `runMcpStdio` is called with no `logger`, the
+ *   module-default env-gated stderr emitter (`TTCTL_DEBUG_MCP=1`) is
+ *   used. `buildServer` itself does NOT install the logger — it
+ *   only consumes the currently-installed one when wrapping tool
+ *   handlers — so callers that bypass `runMcpStdio` (e.g. tests
+ *   building a server directly) must call
+ *   `setMcpDiagnosticLogger` themselves if they want custom emission.
+ */
+export interface BuildServerOptions {
+    configPath?: string;
+    logger?: McpDiagnosticLogger;
+    /**
+     * Remote version-killed manifest check (#312, AC 4). When omitted,
+     * `buildServer` fires the default at-startup check and schedules a
+     * recurring ~24h refetch. Production callers omit this; tests inject
+     * a mocked `fetchFn` + `setIntervalFn` + `writeStderr` to assert
+     * the wiring without hitting the network or polluting stderr.
+     *
+     * Set to `null` to opt out entirely (used by some test setups where
+     * the kill-switch is exercised separately or is irrelevant to the
+     * scenario under test).
+     */
+    killSwitch?: McpKillSwitchHookOptions | null;
+}
+/**
+ * Build the TTCtl MCP server. Tools are wired in via `registerAllTools` —
+ * a single registration site that pulls in every per-tool module so each
+ * tool file stays focused on its own input shape.
+ *
+ * Trust model: process-level — any process that can spawn `ttctl mcp` gets
+ * full access to the user's Toptal Talent session. See SECURITY.md.
+ *
+ * Tools are registered in `tools/index.ts`. Today's surface: 4
+ * `profile.basic` + 7 `profile.skills` (#73) + 5 `profile.industries` +
+ * 5 `profile.education` + 5 `profile.certifications` +
+ * 6 `profile.employment` (#74) = 32 tools. MCP tool names use ONLY the
+ * canonical sub-domain names per project policy (#72) — CLI aliases like
+ * `certs` and `experience` are CLI-only and never appear in the MCP catalog.
+ *
+ * Path capture (#113): `resolveConfig` is invoked ONCE here at server-
+ * construction time. The resolved absolute path is captured into closures
+ * for each per-tool auth resolver (`resolveToolAuth`, `loadTokenForTool`,
+ * `resolveTokenForTool`) so subsequent tool invocations read AND write
+ * the path that was canonical at startup. Mid-session env-var shifts
+ * (e.g., parent shell re-exporting `TTCTL_CONFIG_FILE`) are intentionally
+ * ignored — long-running MCP sessions need read/write symmetry.
+ *
+ * Diagnostic instrumentation (#224): every tool registered through this
+ * server has its callback wrapped with `wrapToolHandler` so the active
+ * MCP diagnostic logger sees `mcp_tool_invoke_start` BEFORE the callback
+ * runs, `mcp_tool_invoke_end` AFTER it resolves (or throws), and
+ * `mcp_transport_error` when the throw is a transport-class error
+ * (`Cf403Error`, `Cf403PersistentError`, `SchedulerBearerExpired`). The
+ * wrap is applied transparently by monkey-patching `server.registerTool`
+ * BEFORE `registerAllTools` runs, so per-tool files (~30+ registrars)
+ * are not aware of the instrumentation — the wiring lives in this one
+ * place.
+ *
+ * Fail-fast: any `ConfigError` thrown by the startup-time `resolveConfig`
+ * (e.g., `NO_CREDS` when no candidate file exists) propagates verbatim —
+ * the server does NOT start in a half-initialized state.
+ */
+export declare function buildServer(opts?: BuildServerOptions): McpServer;
+/**
+ * Run the MCP server over stdio (the canonical transport for Claude Desktop /
+ * Claude Code / Cursor / Windsurf).
+ *
+ * Accepts the same `configPath` knob as `buildServer`. Threading the path
+ * through here keeps the umbrella `ttctl mcp [--config <path>]` entry
+ * surface as the single point of CLI-flag parsing, with no per-tool
+ * config knowledge needed inside the server module.
+ *
+ * Diagnostic logger wiring (issue #224): when `opts.logger` is supplied,
+ * `setMcpDiagnosticLogger(opts.logger)` is called BEFORE `buildServer`
+ * so the tool-registration wrapping in `buildServer` already routes
+ * through the injected logger. When omitted, the module-scoped default
+ * (env-gated stderr emitter for `TTCTL_DEBUG_MCP=1`) remains active.
+ * Tests calling `runMcpStdio` with a fake logger thus get full
+ * tool-start / tool-end / transport-error visibility without needing
+ * to manipulate `process.env`.
+ */
+export declare function runMcpStdio(opts?: BuildServerOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOpE,OAAO,EAAE,KAAK,mBAAmB,EAA2C,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAK7F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CAsFpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9E"}

package/dist/server.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "@ttctl/core";
+import { createToolAuthResolver } from "./auth.js";
+import { composeDescription } from "./data-handling.js";
+import { setMcpDiagnosticLogger, wrapToolHandler } from "./diagnostic.js";
+import { scheduleMcpKillSwitch } from "./kill-switch-hook.js";
+import { createTokenLoader } from "./tools/_shared.js";
+import { createTokenResolver } from "./tools/profile/shared.js";
+import { registerAllTools } from "./tools/index.js";
+/**
+ * Build the TTCtl MCP server. Tools are wired in via `registerAllTools` —
+ * a single registration site that pulls in every per-tool module so each
+ * tool file stays focused on its own input shape.
+ *
+ * Trust model: process-level — any process that can spawn `ttctl mcp` gets
+ * full access to the user's Toptal Talent session. See SECURITY.md.
+ *
+ * Tools are registered in `tools/index.ts`. Today's surface: 4
+ * `profile.basic` + 7 `profile.skills` (#73) + 5 `profile.industries` +
+ * 5 `profile.education` + 5 `profile.certifications` +
+ * 6 `profile.employment` (#74) = 32 tools. MCP tool names use ONLY the
+ * canonical sub-domain names per project policy (#72) — CLI aliases like
+ * `certs` and `experience` are CLI-only and never appear in the MCP catalog.
+ *
+ * Path capture (#113): `resolveConfig` is invoked ONCE here at server-
+ * construction time. The resolved absolute path is captured into closures
+ * for each per-tool auth resolver (`resolveToolAuth`, `loadTokenForTool`,
+ * `resolveTokenForTool`) so subsequent tool invocations read AND write
+ * the path that was canonical at startup. Mid-session env-var shifts
+ * (e.g., parent shell re-exporting `TTCTL_CONFIG_FILE`) are intentionally
+ * ignored — long-running MCP sessions need read/write symmetry.
+ *
+ * Diagnostic instrumentation (#224): every tool registered through this
+ * server has its callback wrapped with `wrapToolHandler` so the active
+ * MCP diagnostic logger sees `mcp_tool_invoke_start` BEFORE the callback
+ * runs, `mcp_tool_invoke_end` AFTER it resolves (or throws), and
+ * `mcp_transport_error` when the throw is a transport-class error
+ * (`Cf403Error`, `Cf403PersistentError`, `SchedulerBearerExpired`). The
+ * wrap is applied transparently by monkey-patching `server.registerTool`
+ * BEFORE `registerAllTools` runs, so per-tool files (~30+ registrars)
+ * are not aware of the instrumentation — the wiring lives in this one
+ * place.
+ *
+ * Fail-fast: any `ConfigError` thrown by the startup-time `resolveConfig`
+ * (e.g., `NO_CREDS` when no candidate file exists) propagates verbatim —
+ * the server does NOT start in a half-initialized state.
+ */
+export function buildServer(opts = {}) {
+    // resolveConfig honors `path` when provided, else falls through to the
+    // env→home chain. We always read the canonical absolute path off the
+    // returned `path` field; that's what the resolvers close over.
+    const resolved = opts.configPath !== undefined ? resolveConfig({ path: opts.configPath }) : resolveConfig();
+    const capturedPath = resolved.path;
+    const server = new McpServer({
+        name: "ttctl",
+        version: "0.0.0",
+    });
+    // Monkey-patch `server.registerTool` BEFORE `registerAllTools` runs so
+    // every per-tool registrar's callback is transparently wrapped with the
+    // diagnostic-instrumentation contract (#224) AND every per-tool
+    // description is augmented with response-side data-handling guidance
+    // (#265). The patch:
+    //   1. Captures `originalRegisterTool` bound to the McpServer instance
+    //      so the SDK's internal `_registeredTools` bookkeeping fires normally.
+    //   2. Replaces `server.registerTool` with a wrapper that (a) augments
+    //      the config's `description` field via `composeDescription` (#265),
+    //      and (b) wraps the callback with `wrapToolHandler(name, cb)` (#224).
+    //      The wrapper's return is the same `RegisteredTool` handle as the
+    //      original — `.enable()` / `.disable()` / `.update()` work unchanged
+    //      on the registered tool.
+    //   3. Uses an `unknown` cast on the patch because `registerTool`'s
+    //      generic signature (with `ZodRawShapeCompat | AnySchema` + the
+    //      output schema variant) is hostile to a single typed override.
+    //      The wrapper preserves runtime behavior; type safety at the
+    //      callsites (each registrar) is unaffected.
+    // The signature of McpServer.registerTool is an overload set that
+    // resolves to `never` under `Parameters<...>`, so we type the patch
+    // as a permissive `(...args: unknown[]) => unknown` and lean on the
+    // outer cast to restore the McpServer's view. Runtime semantics are
+    // unchanged — name is always args[0]: string, config args[1]: object,
+    // cb args[2]: function — and the original registerTool reapplies the
+    // overload-correct type check on its side.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalRegisterTool = server.registerTool.bind(server);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const patchedRegisterTool = (...args) => {
+        const name = args[0];
+        const config = args[1];
+        const cb = args[2];
+        // Augment the tool's description with response-side data-handling
+        // guidance (#265). The augmentation is at registration time so every
+        // tool — current and future — inherits the footer without per-tool
+        // boilerplate. High-risk tools (per the threat-model § 5 audit, set
+        // membership lives in `data-handling.ts`) additionally get a
+        // third-party-content notice.
+        let patchedConfig = config;
+        if (typeof config === "object" && config !== null) {
+            const cfg = config;
+            patchedConfig = {
+                ...cfg,
+                description: composeDescription(name, cfg.description),
+            };
+        }
+        const wrappedCb = wrapToolHandler(name, cb);
+        return originalRegisterTool(name, patchedConfig, wrappedCb);
+    };
+    server.registerTool = patchedRegisterTool;
+    registerAllTools(server, {
+        resolveToolAuth: createToolAuthResolver(capturedPath),
+        loadTokenForTool: createTokenLoader(capturedPath),
+        resolveTokenForTool: createTokenResolver(capturedPath),
+    });
+    // Fire-and-forget kill-switch check (#312, AC 4). Detached on
+    // purpose — buildServer is sync (the MCP SDK has no async-build
+    // path), and a synchronous block here would delay the JSON-RPC
+    // handshake. The check writes to stderr when the running version
+    // matches an entry; never throws (fail-silent contract); never
+    // refuses (refusing a long-lived MCP server has no usable
+    // semantics — see kill-switch-hook.ts docstring).
+    //
+    // Schedules a ~24h refetch with `.unref()` so the timer doesn't
+    // keep the process alive solely for the recurring fetch.
+    if (opts.killSwitch !== null) {
+        scheduleMcpKillSwitch(opts.killSwitch ?? {});
+    }
+    return server;
+}
+/**
+ * Run the MCP server over stdio (the canonical transport for Claude Desktop /
+ * Claude Code / Cursor / Windsurf).
+ *
+ * Accepts the same `configPath` knob as `buildServer`. Threading the path
+ * through here keeps the umbrella `ttctl mcp [--config <path>]` entry
+ * surface as the single point of CLI-flag parsing, with no per-tool
+ * config knowledge needed inside the server module.
+ *
+ * Diagnostic logger wiring (issue #224): when `opts.logger` is supplied,
+ * `setMcpDiagnosticLogger(opts.logger)` is called BEFORE `buildServer`
+ * so the tool-registration wrapping in `buildServer` already routes
+ * through the injected logger. When omitted, the module-scoped default
+ * (env-gated stderr emitter for `TTCTL_DEBUG_MCP=1`) remains active.
+ * Tests calling `runMcpStdio` with a fake logger thus get full
+ * tool-start / tool-end / transport-error visibility without needing
+ * to manipulate `process.env`.
+ */
+export async function runMcpStdio(opts = {}) {
+    if (opts.logger !== undefined) {
+        setMcpDiagnosticLogger(opts.logger);
+    }
+    const server = buildServer(opts);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}