@withpica/mcp-server 1.3.0

package/dist/tools/index.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Tool Registry for MCP Server
+ * Manages all available tools that AI assistants can call
+ */
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ServerConfig } from "../config.js";
+import { McpAuditLogger, type CallerContext } from "@withpica/mcp-utils";
+import { type SessionState } from "@withpica/mcp-utils";
+/**
+ * ADR-199 NextStep hint shape — declared on a ToolDefinition,
+ * surfaced on the success result by the dispatcher. Consumed by
+ * agents to discover the happy-path follow-on tool without reading
+ * description prose.
+ */
+export interface NextStepHint {
+    /** Must resolve to a registered tool name; registry validates at init. */
+    tool: string;
+    /** Single-sentence plain-English explanation. */
+    reason: string;
+    /**
+     * When this step applies:
+     *  - on_success: standard happy path
+     *  - on_partial: partial-success branches (subset processed)
+     *  - on_subset_returned: paginated reads where more pages exist
+     */
+    when: "on_success" | "on_partial" | "on_subset_returned";
+}
+/**
+ * ADR-214 — workflow membership for a tool. Used by the schema-resource
+ * registry (`mcp-server/src/resources/required-schemas.source.ts` — W2)
+ * and the lint-required-schemas CI check (W3) to prove every tool that
+ * participates in a workflow is referenced in that workflow's resource
+ * (as `primary_tool` or `companion_calls[].tool`).
+ *
+ * `"infrastructure"` is the explicit opt-out for tools not part of any
+ * user-facing workflow.
+ *
+ * Optional in W1; W4 flips it to required after W2's resource registry
+ * lands so every tool is forced to declare its workflow at compile time.
+ */
+export type WorkflowTag = "work-required" | "recording-required" | "work-credits-required" | "recording-credits-required" | "person-required" | "audio-upload-required" | "enrichment-resolve-required" | "agreement-required" | "multimedia-required" | "export-required" | "claim-required" | "session-required" | "split-sheet-required" | "recording-splits-required" | "sync-placement-required" | "infrastructure";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /**
+     * ADR-214 — workflow(s) this tool belongs to. See `WorkflowTag` above.
+     * Required as of W4 (2026-04-30): every tool must declare its workflow
+     * membership at compile time. Use `"infrastructure"` for tools not
+     * part of any user-facing workflow.
+     */
+    workflows: WorkflowTag | WorkflowTag[];
+    inputSchema: {
+        type: string;
+        properties: Record<string, any>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    /**
+     * ADR-199 — formal output shape so agents can predict where IDs live.
+     * Optional; existing tools register unchanged. Surface via pica_tool_details.
+     */
+    outputSchema?: {
+        type: string;
+        properties?: Record<string, any>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    /**
+     * ADR-199 — happy-path follow-on tools. Dispatcher copies onto success
+     * results (in `structuredContent.next_steps`) so per-tool executors
+     * don't have to remember.
+     */
+    nextSteps?: NextStepHint[];
+    /**
+     * ADR-199 — for inspect tools on entities with a state machine, the
+     * map from current-state → array of valid next states. Source of truth
+     * is `lib/utils/state-machine.ts` (work + agreement) and the corresponding
+     * DB CHECK constraint. Build-step assertion catches drift.
+     */
+    validTransitionsFrom?: Record<string, string[]>;
+    /**
+     * ADR-199 — declarative preview affordance.
+     *  - dry_run: tool accepts dry_run:boolean and short-circuits
+     *  - two_step_token: tool requires confirmation token (existing pattern)
+     *  - none: immediate execution
+     * The runtime still enforces — this field is for discoverability
+     * + the compliance-score lint.
+     */
+    previewMode?: "dry_run" | "two_step_token" | "none";
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        /**
+         * ADR-199 annotation classes derived from metadata.ts at registration.
+         * Populated by the registration loop; ChatGPT/Claude.ai connectors
+         * read these directly from pica_tool_details.
+         */
+        riskLevel?: "safe" | "mutating" | "destructive";
+        category?: string;
+        requiresConfirmation?: boolean;
+        requiresAuthScope?: string;
+        createsExternalSideEffects?: boolean;
+        returnsPaginated?: boolean;
+        requiresFollowUpInspection?: boolean;
+    };
+    _meta?: {
+        ui?: {
+            resourceUri: string;
+        };
+        "ui/resourceUri"?: string;
+        [key: string]: unknown;
+    };
+}
+export type ToolCategory = "catalog" | "enrichment" | "business" | "discovery" | "media" | "comms" | "settings";
+export interface ToolMetadata {
+    category: ToolCategory;
+    risk: "safe" | "mutating" | "destructive";
+    retry_safe: boolean;
+    display_name: string;
+}
+/**
+ * Build a tool description with metadata injected.
+ * Format: "[category] original description"
+ */
+export declare function injectMetadataIntoDescription(description: string, metadata: ToolMetadata): string;
+export declare const CATEGORY_DISPLAY: Record<ToolCategory, string>;
+/**
+ * Result envelope returned by tool executors. The legacy shape was
+ * `Array<{ type: string; text: string }>` (text-only) — ADR-200 Phase 1
+ * widens it to permit `resource_link` content blocks per the spec's
+ * universal floor for portable upload/download surfaces. Keeping the
+ * shape structural rather than importing the SDK union avoids forcing
+ * 30+ existing executors to satisfy every variant.
+ */
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "resource_link";
+        uri: string;
+        name: string;
+        description?: string;
+        mimeType?: string;
+    } | {
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    /**
+     * Result-level `_meta` carries dispatcher-attached hints. Two keys are
+     * known today; the index signature keeps the shape open for future
+     * additions without per-add interface churn:
+     *  - `session_state` (ADR-208 Primitive B) — ambient catalog counters,
+     *    attached to successful write results by `attachSessionState`.
+     *  - `schemas` (P3c) — `pica://schemas/<workflow>-required` URIs derived
+     *    from the tool's `workflows` tag, attached to every successful
+     *    workflow-tagged tool result by `attachSchemaHints`.
+     * Read tools may carry `schemas` (Option X) but skip `session_state`
+     * (high-volume read path stays cheap).
+     */
+    _meta?: {
+        session_state?: SessionState;
+        schemas?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * ADR-200 Phase 1 — context passed to executors that need access to the
+ * connected MCP transport (e.g. for `server.elicitInput()` capability
+ * checks). Optional so the legacy `(args) => ...` executor signature
+ * keeps working unchanged for the ~99% of tools that don't need it.
+ */
+export interface ToolExecutorContext {
+    server?: Server;
+}
+export type ToolExecutor = (args: Record<string, any>, ctx?: ToolExecutorContext) => Promise<any>;
+export declare class ToolRegistry {
+    private tools;
+    private pica;
+    private config?;
+    private reinitializeCallback?;
+    private signOutCallback?;
+    private auditLogger?;
+    private callerContext;
+    constructor(pica: PicaClient | null, config?: ServerConfig, reinitializeCallback?: (apiKey: string) => void, callerContext?: CallerContext, signOutCallback?: () => void);
+    setAuditLogger(logger: McpAuditLogger): void;
+    setCallerContext(context: CallerContext): void;
+    /**
+     * Register all available tools
+     */
+    private registerAllTools;
+    private static readonly DESTRUCTIVE_PATTERNS;
+    private static readonly MUTATING_PATTERNS;
+    private static readonly SAFE_OVERRIDES;
+    private classifyTool;
+    /**
+     * List all available tools with write-safety prefixes injected.
+     * When discoveryMode is enabled, only the 5 handshake-visible tools are returned.
+     * All other tools remain registered and callable via pica_execute.
+     */
+    listTools(): ToolDefinition[];
+    /**
+     * ADR-199 — derive the extended annotation classes (riskLevel, category,
+     * requiresConfirmation, createsExternalSideEffects, returnsPaginated,
+     * requiresFollowUpInspection) from existing metadata + tool name patterns.
+     *
+     * Called from listTools() for every tool. Pure derivation: zero per-tool
+     * edits required for the retrofit. Future tool authors can override by
+     * setting fields directly on definition.annotations.
+     */
+    private deriveExtendedAnnotations;
+    /**
+     * Build a human-readable preview of what a destructive operation will affect.
+     */
+    private buildDestructivePreview;
+    /**
+     * Sanitize tool parameters for audit logging.
+     * Strips confirmation tokens and truncates large string values.
+     */
+    private sanitizeParams;
+    /**
+     * ADR-208 Primitive B — opaque per-org cache key.
+     *
+     * Stdio: `config.picaApiKey` is the org-bound API key from credentials,
+     * unique per org. HTTP non-discovery: `callerContext.callerIdentity` is
+     * `http:${authContext.keyId}` set by `app/api/mcp/route.ts`, also unique
+     * per org. This is the cross-org cache isolation invariant required by
+     * acceptance criterion 4 — two orgs sharing a worker process never share
+     * a cacheKey. Returns `null` (and the wrapper skips session_state) when
+     * neither identifier is present.
+     */
+    private getSessionCacheKey;
+    /**
+     * ADR-208 Primitive B + ADR-208 Phase 2 + ADR-210 Phase 1 — fetch the
+     * org-scoped counts + billing slice via `pica.catalogStats()`. The
+     * endpoint composes the billing slice server-side via
+     * `subscriptionService.getOrgBillingSlice` and the pending-uploads count
+     * via the new `organisations.pending_uploads_count` column so stdio +
+     * HTTP transports stay symmetric.
+     *
+     * `completeness_pct` is stubbed at 0 in Phase 1 and will be wired in a
+     * Phase 1.5 follow-up. The stub keeps the shape contract green without
+     * forcing a separate endpoint extension into this PR.
+     *
+     * Fail-soft: when `this.pica` is missing (HTTP-discovery without bearer
+     * scope, mostly), every count is 0 and the billing slice falls back to
+     * a conservative "trial" shape so the agent doesn't see misleading
+     * "active" billing for an uninitialized context.
+     */
+    private fetchSessionCounts;
+    /**
+     * P3c — attach `_meta.schemas` (workflow-resource URIs) to a successful
+     * workflow-tagged tool result. Mirrors `attachSessionState`'s merge
+     * semantics: spread existing `_meta`, add the new key, leave other
+     * keys (e.g. `session_state`) untouched.
+     *
+     * Applies to ALL workflow-tagged tools (Option X), including read
+     * companions like `pica_sessions_list`, so the agent gets the schema
+     * pointer no matter which verb they hit first. Skips when:
+     *  - the tool's `workflows` is or contains only `"infrastructure"`
+     *    (no schema resource exists), or
+     *  - the result is an error (the workflow didn't progress).
+     *
+     * Fail-open like `attachSessionState`: derivation is pure today, but
+     * any future throw must not turn a successful tool result into a
+     * failure.
+     */
+    private attachSchemaHints;
+    /**
+     * ADR-208 Primitive B — bump the session-mutation counters and attach
+     * the resolved `_meta.session_state` to a successful write-tool result.
+     * Mutates `result` in-place to keep the existing return contract.
+     * Fail-open: any error here is swallowed — ambient state is best-effort
+     * and must not turn a successful mutation into a tool failure.
+     */
+    private attachSessionState;
+    /**
+     * Execute a tool by name. `ctx.server` carries the transport-scoped
+     * MCP `Server` reference so executors that need `server.elicitInput()`
+     * (ADR-200 Phase 1) can reach it. Each per-request HTTP server is
+     * different; passing it through positionally avoids registry-level
+     * mutable state that would race between concurrent requests.
+     */
+    executeTool(name: string, args: Record<string, any>, ctx?: ToolExecutorContext): Promise<any>;
+}
+//# sourceMappingURL=index.d.ts.map

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

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