@outfitter/mcp 0.4.2 → 0.5.0

package/dist/shared/@outfitter/mcp-9ry52yg3.d.ts

@@ -0,0 +1,187 @@
+import { CompletionHandler } from "./mcp-dgwj3jna.js";
+import { ContentAnnotations } from "./mcp-q5hr7227.js";
+import { HandlerContext, OutfitterError, Result } from "@outfitter/contracts";
+import { z } from "zod";
+/**
+* Text content returned from a resource read.
+*/
+interface TextResourceContent {
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+	/** Optional MIME type */
+	mimeType?: string;
+	/** Text content */
+	text: string;
+	/** Resource URI */
+	uri: string;
+}
+/**
+* Binary (base64-encoded) content returned from a resource read.
+*/
+interface BlobResourceContent {
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+	/** Base64-encoded binary content */
+	blob: string;
+	/** Optional MIME type */
+	mimeType?: string;
+	/** Resource URI */
+	uri: string;
+}
+/**
+* Content returned from reading a resource.
+*/
+type ResourceContent = TextResourceContent | BlobResourceContent;
+/**
+* Handler for reading a resource's content.
+*
+* @param uri - The resource URI being read
+* @param ctx - Handler context with logger and requestId
+* @returns Array of resource content items
+*/
+type ResourceReadHandler = (uri: string, ctx: HandlerContext) => Promise<Result<ResourceContent[], OutfitterError>>;
+/**
+* Definition of an MCP resource that can be read by clients.
+*
+* Resources represent data that clients can access, such as files,
+* database records, or API responses.
+*
+* @example
+* ```typescript
+* const configResource: ResourceDefinition = {
+*   uri: "file:///etc/app/config.json",
+*   name: "Application Config",
+*   description: "Main application configuration file",
+*   mimeType: "application/json",
+*   handler: async (uri, ctx) => {
+*     const content = await readFile(uri);
+*     return Result.ok([{ uri, text: content }]);
+*   },
+* };
+* ```
+*/
+interface ResourceDefinition {
+	/**
+	* Optional description of the resource.
+	* Provides additional context about the resource contents.
+	*/
+	description?: string;
+	/**
+	* Optional handler for reading the resource content.
+	* If not provided, the resource is metadata-only.
+	*/
+	handler?: ResourceReadHandler;
+	/**
+	* Optional MIME type of the resource content.
+	* Helps clients understand how to process the resource.
+	*/
+	mimeType?: string;
+	/**
+	* Human-readable resource name.
+	* Displayed to users in resource listings.
+	*/
+	name: string;
+	/**
+	* Unique resource URI.
+	* Must be a valid URI (file://, https://, custom://, etc.).
+	*/
+	uri: string;
+}
+/**
+* Handler for reading a resource template's content.
+*
+* @param uri - The matched URI
+* @param variables - Extracted template variables
+* @param ctx - Handler context
+*/
+type ResourceTemplateReadHandler = (uri: string, variables: Record<string, string>, ctx: HandlerContext) => Promise<Result<ResourceContent[], OutfitterError>>;
+/**
+* Definition of an MCP resource template with URI pattern matching.
+*
+* Templates use RFC 6570 Level 1 URI templates (e.g., `{param}`)
+* to match and extract variables from URIs.
+*
+* @example
+* ```typescript
+* const userTemplate: ResourceTemplateDefinition = {
+*   uriTemplate: "db:///users/{userId}/profile",
+*   name: "User Profile",
+*   handler: async (uri, variables) => {
+*     const profile = await getProfile(variables.userId);
+*     return Result.ok([{ uri, text: JSON.stringify(profile) }]);
+*   },
+* };
+* ```
+*/
+interface ResourceTemplateDefinition {
+	/** Optional completion handlers keyed by parameter name. */
+	complete?: Record<string, CompletionHandler>;
+	/** Optional description. */
+	description?: string;
+	/** Handler for reading matched resources. */
+	handler: ResourceTemplateReadHandler;
+	/** Optional MIME type. */
+	mimeType?: string;
+	/** Human-readable name for the template. */
+	name: string;
+	/** URI template with `{param}` placeholders (RFC 6570 Level 1). */
+	uriTemplate: string;
+}
+/**
+* Handler for reading a typed resource template's content.
+*
+* @param uri - The matched URI
+* @param params - Validated and parsed template parameters (typed via Zod schema)
+* @param ctx - Handler context
+*/
+type TypedResourceTemplateReadHandler<TParams> = (uri: string, params: TParams, ctx: HandlerContext) => Promise<Result<ResourceContent[], OutfitterError>>;
+/**
+* Typed definition of an MCP resource template with Zod schema validation.
+*
+* Parallel to `ToolDefinition` — the `paramSchema` validates URI template
+* variables before handler invocation, providing type-safe parameters
+* and automatic coercion (e.g., string → number via `z.coerce.number()`).
+*
+* @typeParam TParams - The validated parameter type (inferred from Zod schema)
+*
+* @example
+* ```typescript
+* const userTemplate = defineResourceTemplate({
+*   uriTemplate: "db:///users/{userId}/posts/{postId}",
+*   name: "User Post",
+*   paramSchema: z.object({
+*     userId: z.string().min(1),
+*     postId: z.coerce.number().int().positive(),
+*   }),
+*   handler: async (uri, params, ctx) => {
+*     // params is { userId: string; postId: number } — validated and coerced
+*     const post = await getPost(params.userId, params.postId);
+*     return Result.ok([{ uri, text: JSON.stringify(post) }]);
+*   },
+* });
+* ```
+*/
+interface TypedResourceTemplateDefinition<TParams> {
+	/** Optional completion handlers keyed by parameter name. */
+	complete?: Record<string, CompletionHandler>;
+	/** Optional description. */
+	description?: string;
+	/**
+	* Handler for reading matched resources.
+	* Receives validated and coerced parameters (typed via `paramSchema`).
+	*/
+	handler: TypedResourceTemplateReadHandler<TParams>;
+	/** Optional MIME type. */
+	mimeType?: string;
+	/** Human-readable name for the template. */
+	name: string;
+	/**
+	* Zod schema for validating and parsing URI template parameters.
+	* Variables extracted from the URI template are validated against this schema
+	* before being passed to the handler. Supports coercion (e.g., `z.coerce.number()`).
+	*/
+	paramSchema: z.ZodType<TParams>;
+	/** URI template with `{param}` placeholders (RFC 6570 Level 1). */
+	uriTemplate: string;
+}
+export { TextResourceContent, BlobResourceContent, ResourceContent, ResourceReadHandler, ResourceDefinition, ResourceTemplateReadHandler, ResourceTemplateDefinition, TypedResourceTemplateReadHandler, TypedResourceTemplateDefinition };

package/dist/shared/@outfitter/mcp-dgwj3jna.d.ts

@@ -0,0 +1,103 @@
+import { ContentAnnotations } from "./mcp-q5hr7227.js";
+import { OutfitterError, Result } from "@outfitter/contracts";
+/**
+* Result of a completion request.
+*/
+interface CompletionResult {
+	/** Whether there are more values */
+	hasMore?: boolean;
+	/** Total number of available values (for pagination) */
+	total?: number;
+	/** Completion values */
+	values: string[];
+}
+/**
+* Handler for generating completions.
+*/
+type CompletionHandler = (value: string) => Promise<CompletionResult>;
+/**
+* Reference to a prompt or resource for completion.
+*/
+type CompletionRef = {
+	type: "ref/prompt";
+	name: string;
+} | {
+	type: "ref/resource";
+	uri: string;
+};
+/**
+* Argument definition for a prompt.
+*/
+interface PromptArgument {
+	/** Optional completion handler for this argument */
+	complete?: CompletionHandler;
+	/** Human-readable description */
+	description?: string;
+	/** Argument name */
+	name: string;
+	/** Whether this argument is required */
+	required?: boolean;
+}
+/**
+* Content block within a prompt message.
+*/
+interface PromptMessageContent {
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+	/** Text content */
+	text: string;
+	/** Content type */
+	type: "text";
+}
+/**
+* A message in a prompt response.
+*/
+interface PromptMessage {
+	/** Message content */
+	content: PromptMessageContent;
+	/** Message role */
+	role: "user" | "assistant";
+}
+/**
+* Result returned from getting a prompt.
+*/
+interface PromptResult {
+	/** Optional description override */
+	description?: string;
+	/** Prompt messages */
+	messages: PromptMessage[];
+}
+/**
+* Handler for generating prompt messages.
+*/
+type PromptHandler = (args: Record<string, string | undefined>) => Promise<Result<PromptResult, OutfitterError>>;
+/**
+* Definition of an MCP prompt.
+*
+* Prompts are reusable templates that generate messages for LLMs.
+*
+* @example
+* ```typescript
+* const reviewPrompt: PromptDefinition = {
+*   name: "code-review",
+*   description: "Review code changes",
+*   arguments: [
+*     { name: "language", description: "Programming language", required: true },
+*   ],
+*   handler: async (args) => Result.ok({
+*     messages: [{ role: "user", content: { type: "text", text: `Review this ${args.language} code` } }],
+*   }),
+* };
+* ```
+*/
+interface PromptDefinition {
+	/** Prompt arguments */
+	arguments: PromptArgument[];
+	/** Human-readable description */
+	description?: string;
+	/** Handler to generate messages */
+	handler: PromptHandler;
+	/** Unique prompt name */
+	name: string;
+}
+export { CompletionResult, CompletionHandler, CompletionRef, PromptArgument, PromptMessageContent, PromptMessage, PromptResult, PromptHandler, PromptDefinition };

package/dist/shared/@outfitter/{mcp-5jcgb033.d.ts → mcp-f67dnr72.d.ts}

@@ -1,4 +1,4 @@
-import { ToolDefinition } from "./mcp-fks4zt1z.js";
+import { ToolDefinition } from "./mcp-knc1gq0g.js";
 import { ActionRegistry, ActionSurface, AnyActionSpec } from "@outfitter/contracts";
 interface BuildMcpToolsOptions {
 	readonly includeSurfaces?: readonly ActionSurface[];

package/dist/shared/@outfitter/mcp-hw5wz4gb.js

@@ -0,0 +1 @@
+export { zodToJsonSchema } from "@outfitter/contracts/schema";

package/dist/shared/@outfitter/mcp-knc1gq0g.d.ts

@@ -0,0 +1,130 @@
+import { Handler, OutfitterError } from "@outfitter/contracts";
+import { z } from "zod";
+/**
+* Behavioral hints for MCP tools.
+*
+* Annotations help clients understand tool behavior without invoking them.
+* All fields are optional — only include hints that apply.
+*
+* @see https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations
+*/
+interface ToolAnnotations {
+	/** When true, the tool may perform destructive operations (e.g., deleting data). */
+	destructiveHint?: boolean;
+	/** When true, calling the tool multiple times with the same input has the same effect. */
+	idempotentHint?: boolean;
+	/** When true, the tool may interact with external systems beyond the server. */
+	openWorldHint?: boolean;
+	/** When true, the tool does not modify any state. */
+	readOnlyHint?: boolean;
+}
+/**
+* Common annotation presets for MCP tools.
+*
+* Use these as a starting point and spread-override individual hints:
+*
+* ```typescript
+* annotations: { ...TOOL_ANNOTATIONS.readOnly, openWorldHint: true }
+* ```
+*
+* For multi-action tools (e.g., a single tool with read and write actions),
+* use the most conservative union of hints — if any action is destructive,
+* mark the whole tool as destructive. Per-action annotations are an MCP spec
+* limitation; presets + spread cover most edge cases.
+*/
+declare const TOOL_ANNOTATIONS: {
+	readonly destructive: ToolAnnotations;
+	readonly openWorld: ToolAnnotations;
+	readonly readOnly: ToolAnnotations;
+	readonly write: ToolAnnotations;
+	readonly writeIdempotent: ToolAnnotations;
+};
+/**
+* Definition of an MCP tool that can be invoked by clients.
+*
+* Tools are the primary way clients interact with MCP servers.
+* Each tool has a name, description, input schema (for validation),
+* and a handler function that processes requests.
+*
+* @typeParam TInput - The validated input type (inferred from Zod schema)
+* @typeParam TOutput - The success output type
+* @typeParam TError - The error type (must extend OutfitterError)
+*
+* @example
+* ```typescript
+* const getUserTool: ToolDefinition<
+*   { userId: string },
+*   { name: string; email: string },
+*   NotFoundError
+* > = {
+*   name: "get-user",
+*   description: "Retrieve a user by ID",
+*   inputSchema: z.object({ userId: z.string().uuid() }),
+*   handler: async (input, ctx) => {
+*     ctx.logger.debug("Fetching user", { userId: input.userId });
+*     const user = await db.users.find(input.userId);
+*     if (!user) {
+*       return Result.err(new NotFoundError({
+*         message: `User ${input.userId} not found`,
+*         resourceType: "user",
+*         resourceId: input.userId,
+*       }));
+*     }
+*     return Result.ok({ name: user.name, email: user.email });
+*   },
+* };
+* ```
+*/
+interface ToolDefinition<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+> {
+	/**
+	* Optional behavioral annotations for the tool.
+	* Helps clients understand tool behavior without invoking it.
+	*/
+	annotations?: ToolAnnotations;
+	/**
+	* Whether the tool should be deferred for tool search.
+	* Defaults to true for domain tools; core tools set this to false.
+	*/
+	deferLoading?: boolean;
+	/**
+	* Human-readable description of what the tool does.
+	* Shown to clients and used by LLMs to understand tool capabilities.
+	*/
+	description: string;
+	/**
+	* Handler function that processes the tool invocation.
+	* Receives validated input and HandlerContext, returns Result.
+	*/
+	handler: Handler<TInput, TOutput, TError>;
+	/**
+	* Zod schema for validating and parsing input.
+	* The schema defines the expected input structure.
+	*/
+	inputSchema: z.ZodType<TInput>;
+	/**
+	* Unique tool name (kebab-case recommended).
+	* Used by clients to invoke the tool.
+	*/
+	name: string;
+}
+/**
+* Serialized tool information for MCP protocol.
+* This is the format sent to clients during tool listing.
+*/
+interface SerializedTool {
+	/** Behavioral annotations for the tool */
+	annotations?: ToolAnnotations;
+	/** MCP tool-search hint: whether tool is deferred */
+	defer_loading?: boolean;
+	/** Tool description */
+	description: string;
+	/** JSON Schema representation of the input schema */
+	inputSchema: Record<string, unknown>;
+	/** Tool name */
+	name: string;
+}
+export { ToolAnnotations, TOOL_ANNOTATIONS, ToolDefinition, SerializedTool };

package/dist/shared/@outfitter/mcp-n9vzcp37.js

@@ -0,0 +1,55 @@
+// @bun
+// packages/mcp/src/internal/log-config.ts
+import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
+import { createPrettyFormatter } from "@outfitter/logging";
+var VALID_MCP_LOG_LEVELS = new Set([
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency"
+]);
+var DEFAULTS_TO_MCP = {
+  debug: "debug",
+  info: "info",
+  warn: "warning",
+  error: "error"
+};
+function createDefaultMcpSink() {
+  const formatter = createPrettyFormatter({ colors: false });
+  return {
+    formatter,
+    write(record, formatted) {
+      const serialized = formatted ?? formatter.format(record);
+      const line = serialized.endsWith(`
+`) ? serialized : `${serialized}
+`;
+      if (typeof process !== "undefined" && process.stderr?.write) {
+        process.stderr.write(line);
+      }
+    }
+  };
+}
+function resolveDefaultLogLevel(options) {
+  const envLogLevel = process.env["OUTFITTER_LOG_LEVEL"];
+  if (envLogLevel !== undefined && VALID_MCP_LOG_LEVELS.has(envLogLevel)) {
+    return envLogLevel;
+  }
+  if (options.defaultLogLevel !== undefined && (options.defaultLogLevel === null || VALID_MCP_LOG_LEVELS.has(options.defaultLogLevel))) {
+    return options.defaultLogLevel;
+  }
+  const env = getEnvironment();
+  const defaults = getEnvironmentDefaults(env);
+  if (defaults.logLevel !== null) {
+    const mapped = DEFAULTS_TO_MCP[defaults.logLevel];
+    if (mapped !== undefined) {
+      return mapped;
+    }
+  }
+  return null;
+}
+
+export { VALID_MCP_LOG_LEVELS, DEFAULTS_TO_MCP, createDefaultMcpSink, resolveDefaultLogLevel };

package/dist/shared/@outfitter/mcp-q5hr7227.d.ts

@@ -0,0 +1,24 @@
+/**
+* Shared content type definitions used across prompt and resource types.
+*
+* @internal
+*/
+/**
+* Annotations for content items (resource content, prompt messages).
+*
+* Provides hints about content audience and priority.
+*
+* @see https://spec.modelcontextprotocol.io/specification/2025-03-26/server/utilities/annotations/
+*/
+interface ContentAnnotations {
+	/**
+	* Who the content is intended for.
+	* Can include "user", "assistant", or both.
+	*/
+	audience?: Array<"user" | "assistant">;
+	/**
+	* Priority level from 0.0 (least) to 1.0 (most important).
+	*/
+	priority?: number;
+}
+export { ContentAnnotations };

package/dist/shared/@outfitter/mcp-q70dtfj6.js

@@ -0,0 +1,53 @@
+// @bun
+// packages/mcp/src/progress.ts
+function mapStreamEventToNotification(token, event, latestProgress) {
+  switch (event.type) {
+    case "start": {
+      return {
+        method: "notifications/progress",
+        params: {
+          progressToken: token,
+          progress: latestProgress,
+          message: `[start] ${event.command}`
+        }
+      };
+    }
+    case "step": {
+      const durationSuffix = event.duration_ms !== undefined ? ` (${event.duration_ms}ms)` : "";
+      return {
+        method: "notifications/progress",
+        params: {
+          progressToken: token,
+          progress: latestProgress,
+          message: `[step] ${event.name}: ${event.status}${durationSuffix}`
+        }
+      };
+    }
+    case "progress": {
+      const params = {
+        progressToken: token,
+        progress: event.current,
+        total: event.total
+      };
+      if (event.message !== undefined) {
+        params.message = event.message;
+      }
+      return {
+        method: "notifications/progress",
+        params
+      };
+    }
+  }
+}
+function createMcpProgressCallback(progressToken, send) {
+  let latestProgress = 0;
+  return (event) => {
+    if (event.type === "progress") {
+      latestProgress = event.current;
+    }
+    const notification = mapStreamEventToNotification(progressToken, event, latestProgress);
+    send(notification);
+  };
+}
+
+export { createMcpProgressCallback };

package/dist/shared/@outfitter/mcp-r27vbpc1.d.ts

@@ -0,0 +1,45 @@
+import { ProgressCallback } from "@outfitter/contracts/stream";
+/**
+* Function signature for sending a raw MCP notification.
+*
+* Matches the `sdkServer.notification()` method shape from the MCP SDK.
+*/
+type McpNotificationSender = (notification: unknown) => void;
+/**
+* MCP progress notification payload matching the MCP specification.
+*
+* @see https://spec.modelcontextprotocol.io/specification/2025-03-26/server/utilities/progress/
+*/
+interface McpProgressNotification {
+	method: "notifications/progress";
+	params: {
+		progressToken: string | number;
+		progress: number;
+		total?: number;
+		message?: string;
+	};
+}
+/**
+* Create a {@link ProgressCallback} that emits MCP `notifications/progress`.
+*
+* Each call to the returned callback translates a {@link StreamEvent} into
+* an MCP progress notification and sends it via the provided sender function.
+*
+* @param progressToken - The progress token from the MCP client request
+* @param send - Function to send the raw MCP notification (typically `sdkServer.notification`)
+* @returns A `ProgressCallback` compatible with `ctx.progress`
+*
+* @example
+* ```typescript
+* const progress = createMcpProgressCallback(
+*   "tok-123",
+*   (n) => sdkServer.notification(n)
+* );
+*
+* // In handler:
+* ctx.progress?.({ type: "start", command: "deploy", ts: new Date().toISOString() });
+* ctx.progress?.({ type: "progress", current: 5, total: 10 });
+* ```
+*/
+declare function createMcpProgressCallback(progressToken: string | number, send: McpNotificationSender): ProgressCallback;
+export { McpNotificationSender, McpProgressNotification, createMcpProgressCallback };

package/dist/shared/@outfitter/mcp-s2vnhzav.js

@@ -0,0 +1,2 @@
+export { adaptHandler, McpError, TaggedError } from "../../internal/server-types.js";
+export { TOOL_ANNOTATIONS } from "../../internal/tool-types.js";

package/dist/shared/@outfitter/{mcp-s3gfhcdk.d.ts → mcp-yf0w5cgh.d.ts}

@@ -1,4 +1,4 @@
-import { McpServer } from "./mcp-fks4zt1z.js";
+import { McpServer } from "./mcp-7btcghjj.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";