@outfitter/mcp 0.4.3 → 0.5.0

package/dist/shared/@outfitter/mcp-7btcghjj.d.ts

@@ -0,0 +1,304 @@
+import { SerializedTool, ToolDefinition } from "./mcp-knc1gq0g.js";
+import { ResourceContent, ResourceDefinition, ResourceTemplateDefinition } from "./mcp-9ry52yg3.js";
+import { CompletionRef, CompletionResult, PromptArgument, PromptDefinition, PromptResult } from "./mcp-dgwj3jna.js";
+import { McpLogLevel } from "./mcp-cqpyer9m.js";
+import { Handler, HandlerContext, Logger, OutfitterError, Result, TaggedErrorClass } from "@outfitter/contracts";
+import { Result as Result2 } from "@outfitter/contracts";
+import { TaggedError } from "@outfitter/contracts";
+/**
+* Configuration options for creating an MCP server.
+*
+* @example
+* ```typescript
+* const options: McpServerOptions = {
+*   name: "my-mcp-server",
+*   version: "1.0.0",
+*   logger: createLogger({ name: "mcp" }),
+* };
+*
+* const server = createMcpServer(options);
+* ```
+*/
+interface McpServerOptions {
+	/**
+	* Default MCP log level for client-facing log forwarding.
+	*
+	* Precedence (highest wins):
+	* 1. `OUTFITTER_LOG_LEVEL` environment variable
+	* 2. This option
+	* 3. Environment profile (`OUTFITTER_ENV`)
+	* 4. `null` (no forwarding until client opts in)
+	*
+	* Set to `null` to explicitly disable forwarding regardless of environment.
+	* The MCP client can always override via `logging/setLevel`.
+	*/
+	defaultLogLevel?: McpLogLevel | null;
+	/**
+	* Optional logger instance for server logging.
+	* If not provided, the server uses the Outfitter logger factory defaults.
+	*/
+	logger?: Logger;
+	/**
+	* Server name, used in MCP protocol handshake.
+	* Should be a short, descriptive identifier.
+	*/
+	name: string;
+	/**
+	* Server version (semver format recommended).
+	* Sent to clients during initialization.
+	*/
+	version: string;
+}
+declare const McpErrorBase: TaggedErrorClass<"McpError", {
+	message: string;
+	code: number;
+	context?: Record<string, unknown>;
+}>;
+/**
+* MCP-specific error with JSON-RPC error code.
+*
+* Used when tool invocations fail or when there are protocol-level errors.
+* Follows the JSON-RPC 2.0 error object format.
+*
+* Standard error codes:
+* - `-32700`: Parse error
+* - `-32600`: Invalid request
+* - `-32601`: Method not found
+* - `-32602`: Invalid params
+* - `-32603`: Internal error
+* - `-32000` to `-32099`: Server errors (reserved)
+*
+* @example
+* ```typescript
+* const error = new McpError({
+*   message: "Tool not found: unknown-tool",
+*   code: -32601,
+*   context: { tool: "unknown-tool" },
+* });
+* ```
+*/
+declare class McpError extends McpErrorBase {
+	/** Error category for Outfitter error taxonomy compatibility */
+	readonly category: "internal";
+}
+/**
+* Options for invoking a tool.
+*/
+interface InvokeToolOptions {
+	/** Progress token from client for tracking progress */
+	progressToken?: string | number;
+	/** Custom request ID (auto-generated if not provided) */
+	requestId?: string;
+	/** Abort signal for cancellation */
+	signal?: AbortSignal;
+}
+/**
+* MCP Server instance.
+*
+* Provides methods for registering tools and resources, and for
+* starting/stopping the server.
+*
+* @example
+* ```typescript
+* const server = createMcpServer({
+*   name: "my-server",
+*   version: "1.0.0",
+* });
+*
+* server.registerTool(myTool);
+* server.registerResource(myResource);
+*
+* await server.start();
+* ```
+*/
+interface McpServer {
+	/**
+	* Bind the SDK server instance for notifications.
+	* Called internally by the transport layer.
+	* @param sdkServer - The MCP SDK Server instance
+	*/
+	bindSdkServer?(sdkServer: any): void;
+	/**
+	* Complete an argument value.
+	* @param ref - Reference to the prompt or resource template
+	* @param argumentName - Name of the argument to complete
+	* @param value - Current value to complete
+	* @returns Result with completion values or McpError
+	*/
+	complete(ref: CompletionRef, argumentName: string, value: string): Promise<Result<CompletionResult, InstanceType<typeof McpError>>>;
+	/**
+	* Get a specific prompt's messages.
+	* @param name - Prompt name
+	* @param args - Prompt arguments
+	* @returns Result with prompt result or McpError
+	*/
+	getPrompt(name: string, args: Record<string, string | undefined>): Promise<Result<PromptResult, InstanceType<typeof McpError>>>;
+	/**
+	* Get all registered prompts.
+	* @returns Array of prompt definitions (without handlers)
+	*/
+	getPrompts(): Array<{
+		name: string;
+		description?: string;
+		arguments: PromptArgument[];
+	}>;
+	/**
+	* Get all registered resources.
+	* @returns Array of resource definitions
+	*/
+	getResources(): ResourceDefinition[];
+	/**
+	* Get all registered resource templates.
+	* @returns Array of resource template definitions
+	*/
+	getResourceTemplates(): ResourceTemplateDefinition[];
+	/**
+	* Get all registered tools.
+	* @returns Array of serialized tool information
+	*/
+	getTools(): SerializedTool[];
+	/**
+	* Invoke a tool by name.
+	* @param name - Tool name
+	* @param input - Tool input (will be validated)
+	* @param options - Optional invocation options
+	* @returns Result with tool output or McpError
+	*/
+	invokeTool<T = unknown>(name: string, input: unknown, options?: InvokeToolOptions): Promise<Result<T, InstanceType<typeof McpError>>>;
+	/** Server name */
+	readonly name: string;
+	/**
+	* Notify connected clients that the prompt list has changed.
+	*/
+	notifyPromptsChanged(): void;
+	/**
+	* Notify connected clients that the resource list has changed.
+	*/
+	notifyResourcesChanged(): void;
+	/**
+	* Notify connected clients that a specific resource has been updated.
+	* Only emits for subscribed URIs.
+	* @param uri - URI of the updated resource
+	*/
+	notifyResourceUpdated(uri: string): void;
+	/**
+	* Notify connected clients that the tool list has changed.
+	*/
+	notifyToolsChanged(): void;
+	/**
+	* Read a resource by URI.
+	* @param uri - Resource URI
+	* @returns Result with resource content or McpError
+	*/
+	readResource(uri: string): Promise<Result<ResourceContent[], InstanceType<typeof McpError>>>;
+	/**
+	* Register a prompt with the server.
+	* @param prompt - Prompt definition to register
+	*/
+	registerPrompt(prompt: PromptDefinition): void;
+	/**
+	* Register a resource with the server.
+	* @param resource - Resource definition to register
+	*/
+	registerResource(resource: ResourceDefinition): void;
+	/**
+	* Register a resource template with the server.
+	* @param template - Resource template definition to register
+	*/
+	registerResourceTemplate(template: ResourceTemplateDefinition): void;
+	/**
+	* Register a tool with the server.
+	* @param tool - Tool definition to register
+	*/
+	registerTool<
+		TInput,
+		TOutput,
+		TError extends OutfitterError
+	>(tool: ToolDefinition<TInput, TOutput, TError>): void;
+	/**
+	* Send a log message to connected clients.
+	* Filters by the client-requested log level threshold.
+	* No-op if no SDK server is bound or if the message is below the threshold.
+	*
+	* @param level - MCP log level for the message
+	* @param data - Log data (string, object, or any serializable value)
+	* @param loggerName - Optional logger name for client-side filtering
+	*/
+	sendLogMessage(level: McpLogLevel, data: unknown, loggerName?: string): void;
+	/**
+	* Set the client-requested log level.
+	* Only log messages at or above this level will be forwarded.
+	* @param level - MCP log level string
+	*/
+	setLogLevel?(level: string): void;
+	/**
+	* Start the MCP server.
+	* Begins listening for client connections.
+	*/
+	start(): Promise<void>;
+	/**
+	* Stop the MCP server.
+	* Closes all connections and cleans up resources.
+	*/
+	stop(): Promise<void>;
+	/**
+	* Subscribe to updates for a resource URI.
+	* @param uri - Resource URI to subscribe to
+	*/
+	subscribe(uri: string): void;
+	/**
+	* Unsubscribe from updates for a resource URI.
+	* @param uri - Resource URI to unsubscribe from
+	*/
+	unsubscribe(uri: string): void;
+	/** Server version */
+	readonly version: string;
+}
+type HandlerProgress = HandlerContext extends {
+	progress?: infer P;
+} ? P : never;
+type LegacyProgressReporter = {
+	report(progress: number, total?: number, message?: string): void;
+};
+/**
+* Backward-compatible progress reporter type.
+*
+* - When `HandlerContext.progress` exists (streaming branches), this becomes
+*   `ProgressCallback & { report(...) }`.
+* - When it does not exist (older branches), this falls back to
+*   `{ report(...) }`.
+*/
+type ProgressReporter = [HandlerProgress] extends [never] ? LegacyProgressReporter : NonNullable<HandlerProgress> & LegacyProgressReporter;
+/**
+* Extended handler context for MCP tools.
+* Includes MCP-specific information in addition to standard HandlerContext.
+*/
+interface McpHandlerContext extends Omit<HandlerContext, "progress"> {
+	/** Progress reporter, present when client provides a progressToken */
+	progress?: ProgressReporter;
+	/** The name of the tool being invoked */
+	toolName?: string;
+}
+/**
+* Adapt a handler with a domain error type for use with MCP tools.
+*
+* MCP tool definitions constrain `TError extends OutfitterError`. When your
+* handler returns domain-specific errors that extend `Error` but not
+* `OutfitterError`, use this function instead of an unsafe cast:
+*
+* ```typescript
+* import { adaptHandler } from "@outfitter/mcp";
+*
+* const tool = defineTool({
+*   name: "my-tool",
+*   inputSchema: z.object({ id: z.string() }),
+*   handler: adaptHandler(myDomainHandler),
+* });
+* ```
+*/
+declare function adaptHandler<
+	TInput,
+	TOutput,
+	TError extends Error
+>(handler: (input: TInput, ctx: HandlerContext) => Promise<Result<TOutput, TError>>): Handler<TInput, TOutput, OutfitterError>;
+export { McpServerOptions, McpError, InvokeToolOptions, McpServer, ProgressReporter, McpHandlerContext, adaptHandler, Result2 as Result, TaggedError };

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-d8vs6vry.d.ts → mcp-f67dnr72.d.ts}

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