@ttctl/mcp 0.0.0 → 0.1.0-rc.2

package/dist/tools/_shared.d.ts

@@ -0,0 +1,227 @@
+import { ConfigError } from "@ttctl/core";
+import type { DryRunPreview, ToptalSurface } from "@ttctl/core";
+import type { AuthResult } from "../auth.js";
+import type { ToolErrorResponse } from "../errors.js";
+/**
+ * Shared MCP-tool helpers — auth-token loading, response shaping, error
+ * mapping. Kept in one module so each `profile_basic_*` / `profile_skills_*`
+ * tool file stays small and focused on its own input shape.
+ *
+ * **Auth**: tools load the token per-call rather than caching it at server
+ * startup. The MCP server is a long-lived process; the user may re-run
+ * `ttctl auth signin` while the server is up, and the next tool call should
+ * pick up the new token without restarting the server.
+ *
+ * Post-#113: the per-call read targets the config path captured at
+ * `buildServer()` time, NOT a fresh per-invocation `resolveConfig()` call.
+ * Tools receive the bound `loadTokenForTool` closure via the registration
+ * context, not as a free import. Env-var shifts mid-session do not
+ * retarget reads or writes — the captured path is canonical for the
+ * session's lifetime.
+ *
+ * **Error contract**: domain failures (`ProfileError`, `SkillsError`) and
+ * typed `TtctlError` subclasses both render as MCP `isError: true` tool
+ * responses. Untyped throws bubble up to the SDK's default error path.
+ */
+/**
+ * MCP tool-success response shape. Mirrors the SDK's `CallToolResult`
+ * happy-path: a text-content array carrying the rendered payload.
+ *
+ * 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). The `structuredContent` field is populated by
+ * {@link jsonResponse} so tools that declare an `outputSchema` (#226) get
+ * SDK-validated structured payload alongside the `text` slot.
+ * `structuredContent` is harmless metadata for tools without
+ * `outputSchema` — the SDK skips validation when `outputSchema` is
+ * absent.
+ */
+export interface ToolSuccessResponse {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Render a JSON-shaped payload as a tool-success response. Stringifies
+ * with two-space indentation so LLM clients see an easy-to-read response,
+ * and mirrors the payload into `structuredContent` so tools that declare
+ * an `outputSchema` (#226) get SDK-validated structured output without
+ * each tool having to plumb the field manually.
+ *
+ * `structuredContent` is only populated when `payload` is an object — the
+ * MCP SDK's `structuredContent` slot expects an object shape per
+ * `CallToolResult`, and arrays / primitives are encoded only via the
+ * `text` slot (callers that emit array payloads can still validate the
+ * JSON-decoded `text` field client-side).
+ */
+export declare function jsonResponse(payload: unknown): ToolSuccessResponse;
+/**
+ * Render a plain string as a tool-success response (e.g., for tools that
+ * return a confirmation rather than structured data). Use
+ * {@link textWithStructuredResponse} when both a human-readable line and
+ * a typed acknowledgment are desired (e.g., `*_remove` tools per #226).
+ */
+export declare function textResponse(text: string): ToolSuccessResponse;
+/**
+ * Render a confirmation line as the `text` content slot while also
+ * publishing a typed acknowledgment via `structuredContent`. Used by
+ * `*_remove` tools (#226) where the human-readable text stays for
+ * compatibility and the structured payload is `{ id, removed: true }`
+ * matching the tool's declared `outputSchema`.
+ */
+export declare function textWithStructuredResponse(text: string, structuredContent: Record<string, unknown>): ToolSuccessResponse;
+/**
+ * Uniform MCP dry-run response envelope (issue #165). Every tool's
+ * `dryRun: true` branch renders through this so MCP clients can treat
+ * `dryRun` as a universal "preview" affordance without per-tool envelope
+ * knowledge. The shape is `{ ok: true, dryRun: true, preview }` where
+ * `preview` is the canonical {@link DryRunPreview} carrying surface,
+ * transport, endpoint, operationName, variables, and (bearer-redacted)
+ * headers. The same envelope is emitted whether the preview was
+ * constructed at the MCP layer (via {@link buildMcpDryRunPreview}) or
+ * received from a core service whose `dryRun` option is supported
+ * (`profile.basic.set`, `jobs.*`, `engagements.breaks.*`,
+ * `availability.*Set`).
+ */
+export declare function dryRunResponse(preview: DryRunPreview): ToolSuccessResponse;
+/**
+ * Sibling envelope for multi-mutation tools (issue #165). Some tools fire
+ * MORE than one wire operation per invocation — `profile.skills.update`
+ * fires one mutation per supplied field (rating, experience, publicity).
+ * Single-preview envelope would lie: a caller previewing
+ * `update({id, rating, experience})` with the singular envelope would see
+ * one mutation while the apply path would actually fire two.
+ *
+ * The plural form preserves honesty without diverging from the dry-run
+ * contract: same `{ ok: true, dryRun: true, ... }` shape, but the `preview`
+ * key is replaced by `previews` (array). Tools using this helper MUST
+ * document the plural form on the tool description so MCP clients can
+ * branch on shape. The cross-cutting dry-run smoke test (#165 AC)
+ * accepts EITHER `preview` (single) OR `previews` (array).
+ */
+export declare function dryRunMultiResponse(previews: DryRunPreview[]): ToolSuccessResponse;
+/**
+ * Build a {@link DryRunPreview} at the MCP layer for tools whose core
+ * service does NOT carry its own `dryRun` option — i.e. read-only tools
+ * across every group and the profile sub-domains beyond `profile.basic`
+ * (`skills`, `industries`, `education`, `certifications`, `employment`,
+ * `portfolio`, `visas`, `resume`, `external`, `reviews`). The MCP tool
+ * supplies the operation's metadata + would-be variables; the helper
+ * constructs the preview via the public {@link buildDryRunPreview}
+ * primitive without invoking any transport (read or write).
+ *
+ * For mutating tools whose core supports `dryRun` (the four exceptions
+ * listed above), prefer passing `{ dryRun: true }` through to the core
+ * call and branching on the returned `{ kind: "preview", preview }`
+ * outcome — that path reuses the canonical variable-construction
+ * (including placeholder substitution for fields like `profileId` that
+ * would otherwise be resolved via a sibling read) and avoids drift
+ * between MCP-built variables and what core would actually send.
+ *
+ * The `token` is forwarded as `authToken` on the synthesised
+ * {@link TransportRequest} so {@link buildDryRunPreview} sets the
+ * `authorization` header to {@link DRY_RUN_REDACTED_AUTHORIZATION}
+ * (i.e. `Token token=<redacted>`) without ever placing the live bearer
+ * in the preview payload.
+ */
+export declare function buildMcpDryRunPreview(operationName: string, surface: ToptalSurface, variables: Record<string, unknown>, token: string): DryRunPreview;
+/**
+ * Build a tool-error response for a missing / unreadable auth token. The
+ * MCP equivalent of the CLI's `(UNAUTHENTICATED): No auth token found`
+ * branch.
+ */
+export declare function unauthenticatedResponse(toolName: string): ToolErrorResponse;
+/**
+ * Build a tool-error response for a config-resolution or write-back
+ * failure. The `ConfigError.code` discriminator (`NO_CREDS` / `PARSE` /
+ * `VALIDATION` / `PERMISSION` / `LOCKED`) is surfaced verbatim as the
+ * wire-format code so MCP clients can branch on it without string-matching
+ * the prose message. `LOCKED` indicates another ttctl process holds the
+ * config write-back lock — the MCP client should retry after a brief delay.
+ */
+export declare function configErrorResponse(toolName: string, err: ConfigError): ToolErrorResponse;
+/**
+ * Build a tool-error response for a domain error carrying a `code` +
+ * `message`. Used for `ProfileError` and `SkillsError` — both expose the
+ * same shape (`{code, message}`) but live in different modules.
+ */
+export declare function domainErrorResponse(toolName: string, err: {
+    code: string;
+    message: string;
+}): ToolErrorResponse;
+/**
+ * Build a tool-error response for an unexpected exception (anything that
+ * isn't a `TtctlError` or domain error). Surfaced so the LLM client gets
+ * a structured response rather than the SDK's untyped error fallback.
+ */
+export declare function genericErrorResponse(toolName: string, err: unknown): ToolErrorResponse;
+/**
+ * Shared auth-token loader. Returns either the token (string) or a
+ * tool-error response that the caller should return verbatim.
+ *
+ * Routes via `ttctlErrorToToolResponseOrNull` first so any `TtctlError`
+ * thrown by the resolver chain (rare but possible) gets the uniform
+ * Error/Recovery/Code rendering.
+ *
+ * The loader is a factory closure over the MCP session's canonical config
+ * path captured at startup (#113). Per-call reads always target that path;
+ * env-var shifts during the session do NOT retarget the read.
+ */
+export type TokenLoader = (toolName: string) => Promise<{
+    token: string;
+} | ToolErrorResponse>;
+export declare function createTokenLoader(configPath: string): TokenLoader;
+/**
+ * Type guard: true when `value` is one of our tool responses (success or
+ * error). Used by tool handlers to decide whether to short-circuit on a
+ * failed token load.
+ */
+export declare function isToolErrorResponse(value: unknown): value is ToolErrorResponse;
+/**
+ * Resolver-shape used by `tools/profile/shared.ts` (`commandLabel`-flavored
+ * auth resolution returning `{token} | {error}`). Defined here so the
+ * `ToolRegistrationContext` can carry it without `_shared.ts` having to
+ * import from `tools/profile/`.
+ */
+export type TokenResolver = (commandLabel: string) => Promise<{
+    token: string;
+} | {
+    error: ToolErrorResponse;
+}>;
+/**
+ * Dependency-injection context threaded through `registerAllTools` (#113).
+ *
+ * `buildServer({configPath})` calls `resolveConfig` ONCE at startup and
+ * uses the resulting absolute path to construct each resolver. The
+ * context is then handed to `registerAllTools`, which forwards it to each
+ * per-tool registrar so per-tool callbacks invoke `ctx.resolveToolAuth()`
+ * / `ctx.loadTokenForTool(toolName)` / `ctx.resolveTokenForTool(label)`
+ * instead of free-importing module-scoped functions that would re-resolve
+ * config (and re-read env) on each call.
+ *
+ * Three resolver shapes co-exist because the existing tool surface uses
+ * three different conventions:
+ *
+ * - `resolveToolAuth` — discriminated-union `AuthResult`
+ *   (`{ok: true, token} | {ok: false, response}`) consumed by
+ *   `tools/profile/portfolio|resume|visas.ts`.
+ * - `loadTokenForTool(toolName)` — toolName-aware error path that
+ *   includes the tool name in the rendered `Error: <toolName> failed
+ *   (...)` text. Used by every per-file `profile_*_*.ts` tool.
+ * - `resolveTokenForTool(commandLabel)` — `commandLabel`-prefixed errors
+ *   (`{token} | {error}` shape) used by sub-domain registrars in
+ *   `tools/profile/certifications|education|employment|industries.ts`.
+ *
+ * All three target the captured configPath; mid-session env shifts do
+ * NOT retarget reads or writes for any of the three.
+ */
+export interface ToolRegistrationContext {
+    resolveToolAuth: () => Promise<AuthResult>;
+    loadTokenForTool: TokenLoader;
+    resolveTokenForTool: TokenResolver;
+}
+//# sourceMappingURL=_shared.d.ts.map

package/dist/tools/_shared.d.ts.map

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

package/dist/tools/_shared.js

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { ConfigError, TtctlError, buildDryRunPreview, resolveConfig } from "@ttctl/core";
+import { emitMcpAuthResolve } from "../diagnostic.js";
+import { ttctlErrorToToolResponseOrNull } from "../errors.js";
+/**
+ * Render a JSON-shaped payload as a tool-success response. Stringifies
+ * with two-space indentation so LLM clients see an easy-to-read response,
+ * and mirrors the payload into `structuredContent` so tools that declare
+ * an `outputSchema` (#226) get SDK-validated structured output without
+ * each tool having to plumb the field manually.
+ *
+ * `structuredContent` is only populated when `payload` is an object — the
+ * MCP SDK's `structuredContent` slot expects an object shape per
+ * `CallToolResult`, and arrays / primitives are encoded only via the
+ * `text` slot (callers that emit array payloads can still validate the
+ * JSON-decoded `text` field client-side).
+ */
+export function jsonResponse(payload) {
+    const response = {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+    if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+        response.structuredContent = payload;
+    }
+    return response;
+}
+/**
+ * Render a plain string as a tool-success response (e.g., for tools that
+ * return a confirmation rather than structured data). Use
+ * {@link textWithStructuredResponse} when both a human-readable line and
+ * a typed acknowledgment are desired (e.g., `*_remove` tools per #226).
+ */
+export function textResponse(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Render a confirmation line as the `text` content slot while also
+ * publishing a typed acknowledgment via `structuredContent`. Used by
+ * `*_remove` tools (#226) where the human-readable text stays for
+ * compatibility and the structured payload is `{ id, removed: true }`
+ * matching the tool's declared `outputSchema`.
+ */
+export function textWithStructuredResponse(text, structuredContent) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent,
+    };
+}
+/**
+ * Uniform MCP dry-run response envelope (issue #165). Every tool's
+ * `dryRun: true` branch renders through this so MCP clients can treat
+ * `dryRun` as a universal "preview" affordance without per-tool envelope
+ * knowledge. The shape is `{ ok: true, dryRun: true, preview }` where
+ * `preview` is the canonical {@link DryRunPreview} carrying surface,
+ * transport, endpoint, operationName, variables, and (bearer-redacted)
+ * headers. The same envelope is emitted whether the preview was
+ * constructed at the MCP layer (via {@link buildMcpDryRunPreview}) or
+ * received from a core service whose `dryRun` option is supported
+ * (`profile.basic.set`, `jobs.*`, `engagements.breaks.*`,
+ * `availability.*Set`).
+ */
+export function dryRunResponse(preview) {
+    // Intentionally emits ONLY the `text` content slot — no
+    // `structuredContent`. The dry-run envelope shape does NOT match the
+    // success-path `outputSchema` declared by #226 tools, and the MCP SDK
+    // validates `structuredContent` against `outputSchema` when both are
+    // present. Leaving `structuredContent` absent lets the SDK skip
+    // validation for dry-run responses (per `_validateOutput`: "if
+    // `!result.structuredContent` return"), preserving the universal
+    // `{ ok, dryRun, preview }` envelope contract without forcing every
+    // tool's `outputSchema` to absorb the dry-run shape.
+    const envelope = { ok: true, dryRun: true, preview };
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    };
+}
+/**
+ * Sibling envelope for multi-mutation tools (issue #165). Some tools fire
+ * MORE than one wire operation per invocation — `profile.skills.update`
+ * fires one mutation per supplied field (rating, experience, publicity).
+ * Single-preview envelope would lie: a caller previewing
+ * `update({id, rating, experience})` with the singular envelope would see
+ * one mutation while the apply path would actually fire two.
+ *
+ * The plural form preserves honesty without diverging from the dry-run
+ * contract: same `{ ok: true, dryRun: true, ... }` shape, but the `preview`
+ * key is replaced by `previews` (array). Tools using this helper MUST
+ * document the plural form on the tool description so MCP clients can
+ * branch on shape. The cross-cutting dry-run smoke test (#165 AC)
+ * accepts EITHER `preview` (single) OR `previews` (array).
+ */
+export function dryRunMultiResponse(previews) {
+    // Same rationale as `dryRunResponse` — emits ONLY `content`, no
+    // `structuredContent`, so #226 tools with declared `outputSchema`
+    // don't fail validation on the dry-run shape.
+    const envelope = { ok: true, dryRun: true, previews };
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    };
+}
+/**
+ * Build a {@link DryRunPreview} at the MCP layer for tools whose core
+ * service does NOT carry its own `dryRun` option — i.e. read-only tools
+ * across every group and the profile sub-domains beyond `profile.basic`
+ * (`skills`, `industries`, `education`, `certifications`, `employment`,
+ * `portfolio`, `visas`, `resume`, `external`, `reviews`). The MCP tool
+ * supplies the operation's metadata + would-be variables; the helper
+ * constructs the preview via the public {@link buildDryRunPreview}
+ * primitive without invoking any transport (read or write).
+ *
+ * For mutating tools whose core supports `dryRun` (the four exceptions
+ * listed above), prefer passing `{ dryRun: true }` through to the core
+ * call and branching on the returned `{ kind: "preview", preview }`
+ * outcome — that path reuses the canonical variable-construction
+ * (including placeholder substitution for fields like `profileId` that
+ * would otherwise be resolved via a sibling read) and avoids drift
+ * between MCP-built variables and what core would actually send.
+ *
+ * The `token` is forwarded as `authToken` on the synthesised
+ * {@link TransportRequest} so {@link buildDryRunPreview} sets the
+ * `authorization` header to {@link DRY_RUN_REDACTED_AUTHORIZATION}
+ * (i.e. `Token token=<redacted>`) without ever placing the live bearer
+ * in the preview payload.
+ */
+export function buildMcpDryRunPreview(operationName, surface, variables, token) {
+    return buildDryRunPreview({
+        surface,
+        body: { operationName, variables },
+        authToken: token,
+    });
+}
+/**
+ * Build a tool-error response for a missing / unreadable auth token. The
+ * MCP equivalent of the CLI's `(UNAUTHENTICATED): No auth token found`
+ * branch.
+ */
+export function unauthenticatedResponse(toolName) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: ${toolName} failed (UNAUTHENTICATED): No auth token found.\n\nRecovery: Run \`ttctl auth signin\` to sign in.\n\n(Code: UNAUTHENTICATED)`,
+            },
+        ],
+    };
+}
+/**
+ * Build a tool-error response for a config-resolution or write-back
+ * failure. The `ConfigError.code` discriminator (`NO_CREDS` / `PARSE` /
+ * `VALIDATION` / `PERMISSION` / `LOCKED`) is surfaced verbatim as the
+ * wire-format code so MCP clients can branch on it without string-matching
+ * the prose message. `LOCKED` indicates another ttctl process holds the
+ * config write-back lock — the MCP client should retry after a brief delay.
+ */
+export function configErrorResponse(toolName, err) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: ${toolName} failed (${err.code}): ${err.message}\n\n(Code: ${err.code})`,
+            },
+        ],
+    };
+}
+/**
+ * Build a tool-error response for a domain error carrying a `code` +
+ * `message`. Used for `ProfileError` and `SkillsError` — both expose the
+ * same shape (`{code, message}`) but live in different modules.
+ */
+export function domainErrorResponse(toolName, err) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: ${toolName} failed (${err.code}): ${err.message}\n\n(Code: ${err.code})`,
+            },
+        ],
+    };
+}
+/**
+ * Build a tool-error response for an unexpected exception (anything that
+ * isn't a `TtctlError` or domain error). Surfaced so the LLM client gets
+ * a structured response rather than the SDK's untyped error fallback.
+ */
+export function genericErrorResponse(toolName, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Error: ${toolName} failed: ${message}\n\n(Code: UNKNOWN)`,
+            },
+        ],
+    };
+}
+export function createTokenLoader(configPath) {
+    return async function loadTokenForTool(toolName) {
+        let token;
+        try {
+            const { config } = resolveConfig({ path: configPath });
+            token = config.auth.token;
+        }
+        catch (err) {
+            if (err instanceof ConfigError) {
+                emitMcpAuthResolve(configPath, "config_error", false);
+                return configErrorResponse(toolName, err);
+            }
+            if (err instanceof TtctlError) {
+                const typed = ttctlErrorToToolResponseOrNull(err);
+                if (typed !== null) {
+                    emitMcpAuthResolve(configPath, "config_error", false);
+                    return typed;
+                }
+            }
+            throw err;
+        }
+        if (token === undefined) {
+            emitMcpAuthResolve(configPath, "unauthenticated", false);
+            return unauthenticatedResponse(toolName);
+        }
+        emitMcpAuthResolve(configPath, "ok", true);
+        return Promise.resolve({ token });
+    };
+}
+/**
+ * Type guard: true when `value` is one of our tool responses (success or
+ * error). Used by tool handlers to decide whether to short-circuit on a
+ * failed token load.
+ */
+export function isToolErrorResponse(value) {
+    return typeof value === "object" && value !== null && "isError" in value && value.isError === true;
+}
+//# sourceMappingURL=_shared.js.map

package/dist/tools/_shared.js.map

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

package/dist/tools/applications.d.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolRegistrationContext } from "./_shared.js";
+/**
+ * Register the three `ttctl_applications_*` MCP tools per the #15 spec.
+ * Tool names use the `ttctl_` prefix and the canonical CLI path joined
+ * with `_` per project naming policy:
+ *
+ *   - `ttctl_applications_list`
+ *   - `ttctl_applications_show`
+ *   - `ttctl_applications_stats`
+ *
+ * Each tool maps 1:1 to a CLI leaf — the schemas describe the same set
+ * of fields. The list tool's `keywords` and `statusGroups` mirror the
+ * `--keywords` / `--status-group` CLI flags.
+ *
+ * **Read-only** — per project non-goals (#15), no apply / withdraw /
+ * edit tools are exposed. `applications` is intentionally a smaller
+ * surface than the profile sub-domains.
+ *
+ * Dry-run path (issue #165): every tool accepts `dryRun?: boolean`.
+ * `list` and `show` emit the singular `{ preview }` envelope (one
+ * operation per call); `stats` emits the plural `{ previews: [...] }`
+ * envelope because the apply path fires 5 parallel `JobActivityItems`
+ * calls (one per STATUS_GROUPS member) — see {@link dryRunMultiResponse}.
+ */
+export declare function registerApplicationsTools(server: McpServer, ctx: ToolRegistrationContext): void;
+//# sourceMappingURL=applications.d.ts.map

package/dist/tools/applications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applications.d.ts","sourceRoot":"","sources":["../../src/tools/applications.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOzE,OAAO,EAA8D,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AASxH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,uBAAuB,GAAG,IAAI,CAwH/F"}