@outfitter/mcp 0.4.2 → 0.5.0

package/dist/internal/content-types.d.ts

@@ -0,0 +1,2 @@
+import { ContentAnnotations } from "../shared/@outfitter/mcp-q5hr7227.js";
+export { ContentAnnotations };

package/dist/internal/content-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/internal/log-config.d.ts

@@ -0,0 +1,24 @@
+import { McpServerOptions } from "../shared/@outfitter/mcp-7btcghjj.js";
+import "../shared/@outfitter/mcp-knc1gq0g.js";
+import "../shared/@outfitter/mcp-9ry52yg3.js";
+import "../shared/@outfitter/mcp-dgwj3jna.js";
+import "../shared/@outfitter/mcp-q5hr7227.js";
+import { McpLogLevel } from "../shared/@outfitter/mcp-cqpyer9m.js";
+import { Sink } from "@outfitter/logging";
+/** Valid MCP log levels for env var and option validation. */
+declare const VALID_MCP_LOG_LEVELS: ReadonlySet<string>;
+/** Map from EnvironmentDefaults logLevel to McpLogLevel. */
+declare const DEFAULTS_TO_MCP: Readonly<Record<string, McpLogLevel>>;
+/** Create a stderr sink with plain-text formatting for fallback logging. */
+declare function createDefaultMcpSink(): Sink;
+/**
+* Resolve the default client log level from the precedence chain.
+*
+* Precedence (highest wins):
+* 1. `OUTFITTER_LOG_LEVEL` environment variable
+* 2. `options.defaultLogLevel` (validated against MCP levels)
+* 3. Environment profile (`OUTFITTER_ENV`)
+* 4. `null` (no forwarding)
+*/
+declare function resolveDefaultLogLevel(options: McpServerOptions): McpLogLevel | null;
+export { resolveDefaultLogLevel, createDefaultMcpSink, VALID_MCP_LOG_LEVELS, DEFAULTS_TO_MCP };

package/dist/internal/log-config.js

@@ -0,0 +1,13 @@
+// @bun
+import {
+  DEFAULTS_TO_MCP,
+  VALID_MCP_LOG_LEVELS,
+  createDefaultMcpSink,
+  resolveDefaultLogLevel
+} from "../shared/@outfitter/mcp-n9vzcp37.js";
+export {
+  resolveDefaultLogLevel,
+  createDefaultMcpSink,
+  VALID_MCP_LOG_LEVELS,
+  DEFAULTS_TO_MCP
+};

package/dist/internal/prompt-types.d.ts

@@ -0,0 +1,3 @@
+import { CompletionHandler, CompletionRef, CompletionResult, PromptArgument, PromptDefinition, PromptHandler, PromptMessage, PromptMessageContent, PromptResult } from "../shared/@outfitter/mcp-dgwj3jna.js";
+import "../shared/@outfitter/mcp-q5hr7227.js";
+export { PromptResult, PromptMessageContent, PromptMessage, PromptHandler, PromptDefinition, PromptArgument, CompletionResult, CompletionRef, CompletionHandler };

package/dist/internal/prompt-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/internal/resource-types.d.ts

@@ -0,0 +1,4 @@
+import { BlobResourceContent, ResourceContent, ResourceDefinition, ResourceReadHandler, ResourceTemplateDefinition, ResourceTemplateReadHandler, TextResourceContent, TypedResourceTemplateDefinition, TypedResourceTemplateReadHandler } from "../shared/@outfitter/mcp-9ry52yg3.js";
+import "../shared/@outfitter/mcp-dgwj3jna.js";
+import { ContentAnnotations } from "../shared/@outfitter/mcp-q5hr7227.js";
+export { TypedResourceTemplateReadHandler, TypedResourceTemplateDefinition, TextResourceContent, ResourceTemplateReadHandler, ResourceTemplateDefinition, ResourceReadHandler, ResourceDefinition, ResourceContent, ContentAnnotations, BlobResourceContent };

package/dist/internal/resource-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/internal/server-types.d.ts

@@ -0,0 +1,7 @@
+import { InvokeToolOptions, McpError, McpHandlerContext, McpServer, McpServerOptions, ProgressReporter, Result, TaggedError, adaptHandler } from "../shared/@outfitter/mcp-7btcghjj.js";
+import "../shared/@outfitter/mcp-knc1gq0g.js";
+import "../shared/@outfitter/mcp-9ry52yg3.js";
+import "../shared/@outfitter/mcp-dgwj3jna.js";
+import "../shared/@outfitter/mcp-q5hr7227.js";
+import "../shared/@outfitter/mcp-cqpyer9m.js";
+export { adaptHandler, TaggedError, Result, ProgressReporter, McpServerOptions, McpServer, McpHandlerContext, McpError, InvokeToolOptions };

package/dist/internal/server-types.js

@@ -0,0 +1,20 @@
+// @bun
+// packages/mcp/src/internal/server-types.ts
+import {
+  TaggedError as TaggedErrorImpl
+} from "@outfitter/contracts";
+import { TaggedError } from "@outfitter/contracts";
+var TaggedError2 = TaggedErrorImpl;
+var McpErrorBase = TaggedError2("McpError")();
+
+class McpError extends McpErrorBase {
+  category = "internal";
+}
+function adaptHandler(handler) {
+  return handler;
+}
+export {
+  adaptHandler,
+  TaggedError,
+  McpError
+};

package/dist/internal/tool-types.d.ts

@@ -0,0 +1,2 @@
+import { SerializedTool, TOOL_ANNOTATIONS, ToolAnnotations, ToolDefinition } from "../shared/@outfitter/mcp-knc1gq0g.js";
+export { ToolDefinition, ToolAnnotations, TOOL_ANNOTATIONS, SerializedTool };

package/dist/{shared/@outfitter/mcp-9m5hs2z0.js → internal/tool-types.js}

@@ -1,10 +1,5 @@
 // @bun
-// packages/mcp/src/types.ts
-import {
-  TaggedError as TaggedErrorImpl
-} from "@outfitter/contracts";
-import { TaggedError } from "@outfitter/contracts";
-var TaggedError2 = TaggedErrorImpl;
+// packages/mcp/src/internal/tool-types.ts
 var TOOL_ANNOTATIONS = {
   readOnly: {
     readOnlyHint: true,
@@ -37,13 +32,6 @@ var TOOL_ANNOTATIONS = {
     openWorldHint: true
   }
 };
-var McpErrorBase = TaggedError2("McpError")();
-
-class McpError extends McpErrorBase {
-  category = "internal";
-}
-function adaptHandler(handler) {
-  return handler;
-}
-
-export { TOOL_ANNOTATIONS, McpError, adaptHandler, TaggedError };
+export {
+  TOOL_ANNOTATIONS
+};

package/dist/internal/uri-template.d.ts

@@ -0,0 +1,8 @@
+/**
+* Match a URI against a RFC 6570 Level 1 URI template.
+*
+* Extracts named variables from `{param}` segments.
+* Returns null if the URI doesn't match the template.
+*/
+declare function matchUriTemplate(template: string, uri: string): Record<string, string> | null;
+export { matchUriTemplate };

package/dist/internal/uri-template.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  matchUriTemplate
+} from "../shared/@outfitter/mcp-zt2s3r38.js";
+export {
+  matchUriTemplate
+};

package/dist/progress.d.ts

@@ -0,0 +1,2 @@
+import { McpNotificationSender, McpProgressNotification, createMcpProgressCallback } from "./shared/@outfitter/mcp-r27vbpc1.js";
+export { createMcpProgressCallback, McpProgressNotification, McpNotificationSender };

package/dist/progress.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  createMcpProgressCallback
+} from "./shared/@outfitter/mcp-q70dtfj6.js";
+export {
+  createMcpProgressCallback
+};

package/dist/schema.js

@@ -1,7 +1,7 @@
 // @bun
 import {
   zodToJsonSchema
-} from "./shared/@outfitter/mcp-zy7b487d.js";
+} from "./shared/@outfitter/mcp-hw5wz4gb.js";
 export {
   zodToJsonSchema
 };

package/dist/server.d.ts

@@ -1,4 +1,9 @@
-import { createMcpServer, definePrompt, defineResource, defineResourceTemplate, defineTool } from "./shared/@outfitter/mcp-5b5726ga.js";
-import "./shared/@outfitter/mcp-fks4zt1z.js";
+import { createMcpServer, definePrompt, defineResource, defineResourceTemplate, defineTool } from "./shared/@outfitter/mcp-3hxaatj9.js";
+import "./shared/@outfitter/mcp-qmdmgxa1.js";
+import "./shared/@outfitter/mcp-7btcghjj.js";
+import "./shared/@outfitter/mcp-knc1gq0g.js";
+import "./shared/@outfitter/mcp-9ry52yg3.js";
+import "./shared/@outfitter/mcp-dgwj3jna.js";
+import "./shared/@outfitter/mcp-q5hr7227.js";
 import "./shared/@outfitter/mcp-cqpyer9m.js";
 export { defineTool, defineResourceTemplate, defineResource, definePrompt, createMcpServer };

package/dist/server.js

@@ -5,10 +5,13 @@ import {
   defineResource,
   defineResourceTemplate,
   defineTool
-} from "./shared/@outfitter/mcp-hh12tqfg.js";
+} from "./shared/@outfitter/mcp-yf1n85e9.js";
+import"./shared/@outfitter/mcp-n9vzcp37.js";
+import"./shared/@outfitter/mcp-zt2s3r38.js";
+import"./shared/@outfitter/mcp-q70dtfj6.js";
 import"./shared/@outfitter/mcp-fjtxsa0x.js";
-import"./shared/@outfitter/mcp-zy7b487d.js";
-import"./shared/@outfitter/mcp-9m5hs2z0.js";
+import"./shared/@outfitter/mcp-s2vnhzav.js";
+import"./shared/@outfitter/mcp-hw5wz4gb.js";
 export {
   defineTool,
   defineResourceTemplate,

package/dist/shared/@outfitter/{mcp-5b5726ga.d.ts → mcp-3hxaatj9.d.ts}

@@ -1,4 +1,7 @@
-import { McpServer, McpServerOptions, PromptDefinition, ResourceDefinition, ResourceTemplateDefinition, ToolDefinition } from "./mcp-fks4zt1z.js";
+import { McpServer, McpServerOptions } from "./mcp-7btcghjj.js";
+import { ToolDefinition } from "./mcp-knc1gq0g.js";
+import { ResourceDefinition, ResourceTemplateDefinition, TypedResourceTemplateDefinition } from "./mcp-9ry52yg3.js";
+import { PromptDefinition } from "./mcp-dgwj3jna.js";
 import { OutfitterError } from "@outfitter/contracts";
 /**
 * Create an MCP server instance.
@@ -82,14 +85,42 @@ declare function defineTool<
 */
 declare function defineResource(definition: ResourceDefinition): ResourceDefinition;
 /**
-* Define a resource template.
+* Define a resource template with optional Zod schema validation.
 *
-* Helper function for creating resource template definitions
-* with URI pattern matching.
+* When `paramSchema` is provided, URI template variables are validated
+* and coerced before handler invocation — parallel to how `defineTool()`
+* validates input via `inputSchema`. Invalid parameters produce an
+* McpError with code -32602 (Invalid params) and the handler is never called.
 *
-* @param definition - Resource template definition object
-* @returns The same resource template definition
+* @param definition - Resource template definition with optional `paramSchema`
+* @returns A `ResourceTemplateDefinition` compatible with `registerResourceTemplate()`
+*
+* @example
+* ```typescript
+* // With Zod schema validation (recommended for typed params)
+* 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 typed as { userId: string; postId: number }
+*     return Result.ok([{ uri, text: JSON.stringify(params) }]);
+*   },
+* });
+*
+* // Without schema (backward compatible)
+* const simpleTemplate = defineResourceTemplate({
+*   uriTemplate: "db:///items/{itemId}",
+*   name: "Item",
+*   handler: async (uri, variables) =>
+*     Result.ok([{ uri, text: variables.itemId }]),
+* });
+* ```
 */
+declare function defineResourceTemplate<TParams>(definition: TypedResourceTemplateDefinition<TParams>): ResourceTemplateDefinition;
 declare function defineResourceTemplate(definition: ResourceTemplateDefinition): ResourceTemplateDefinition;
 /**
 * Define a prompt.

package/dist/shared/@outfitter/{mcp-zb3p61y9.d.ts → mcp-4s22693j.d.ts}

@@ -1,4 +1,4 @@
-import { ToolDefinition } from "./mcp-fks4zt1z.js";
+import { ToolDefinition } from "./mcp-knc1gq0g.js";
 import { HandlerContext, OutfitterError } from "@outfitter/contracts";
 import { Result } from "@outfitter/contracts";
 type DocsSection = "overview" | "tools" | "examples" | "schemas";

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 };