@outfitter/mcp 0.1.0 → 0.3.0

package/README.md

@@ -54,9 +54,10 @@ Creates an MCP server instance.
 
 ```typescript
 interface McpServerOptions {
-  name: string;      // Server name for MCP handshake
-  version: string;   // Server version (semver)
-  logger?: Logger;   // Optional structured logger
+  name: string;           // Server name for MCP handshake
+  version: string;        // Server version (semver)
+  logger?: Logger;        // Optional structured logger
+  defaultLogLevel?: McpLogLevel | null; // Default log forwarding level
 }
 
 const server = createMcpServer({
@@ -66,6 +67,41 @@ const server = createMcpServer({
 });
 ```
 
+### Log Forwarding
+
+MCP servers can forward log messages to the connected client. The default log level is resolved from environment configuration:
+
+**Precedence** (highest wins):
+1. `OUTFITTER_LOG_LEVEL` environment variable
+2. `options.defaultLogLevel`
+3. `OUTFITTER_ENV` profile defaults (`"debug"` in development, `null` otherwise)
+4. `null` (no forwarding)
+
+```typescript
+const server = createMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  // Forwarding level auto-resolved from OUTFITTER_ENV
+});
+
+// With OUTFITTER_ENV=development → forwards at "debug"
+// With OUTFITTER_ENV=production → no forwarding (null)
+// With OUTFITTER_LOG_LEVEL=error → forwards at "error"
+```
+
+Set `defaultLogLevel: null` to explicitly disable forwarding regardless of environment. The MCP client can always override via `logging/setLevel`.
+
+#### `sendLogMessage(level, data, loggerName?)`
+
+Send a log message to the connected MCP client.
+
+```typescript
+server.sendLogMessage("info", "Indexing complete", "my-server");
+server.sendLogMessage("warning", { message: "Rate limited", retryAfter: 30 });
+```
+
+Only sends if the message level meets or exceeds the current client log level threshold.
+
 ### defineTool(definition)
 
 Helper for defining typed tools with better type inference.
@@ -103,6 +139,7 @@ interface ResourceDefinition {
   name: string;          // Human-readable name
   description?: string;  // Optional description
   mimeType?: string;     // Content MIME type
+  handler?: ResourceReadHandler; // Optional resources/read handler
 }
 
 const configResource = defineResource({
@@ -110,9 +147,27 @@ const configResource = defineResource({
   name: "Application Config",
   description: "Main configuration file",
   mimeType: "application/json",
+  handler: async (uri, ctx) => {
+    ctx.logger.debug("Reading config resource", { uri });
+    return Result.ok([
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify({ debug: true }),
+      },
+    ]);
+  },
 });
 ```
 
+Registered resources with handlers are exposed through MCP `resources/read`.
+
+```typescript
+server.registerResource(configResource);
+
+const contentResult = await server.readResource("file:///etc/app/config.json");
+```
+
 ### Server Methods
 
 ```typescript
@@ -123,12 +178,15 @@ interface McpServer {
   // Registration
   registerTool<TInput, TOutput, TError>(tool: ToolDefinition): void;
   registerResource(resource: ResourceDefinition): void;
+  registerResourceTemplate(template: ResourceTemplateDefinition): void;
 
   // Introspection
   getTools(): SerializedTool[];
   getResources(): ResourceDefinition[];
+  getResourceTemplates(): ResourceTemplateDefinition[];
 
   // Invocation
+  readResource(uri: string): Promise<Result<ResourceContent[], McpError>>;
   invokeTool<T>(name: string, input: unknown, options?: InvokeToolOptions): Promise<Result<T, McpError>>;
 
   // Lifecycle

package/dist/index.d.ts

@@ -2,6 +2,32 @@ import { ActionRegistry, ActionSurface, AnyActionSpec } from "@outfitter/contrac
 import { Handler, HandlerContext, Logger, OutfitterError, Result, TaggedErrorClass } from "@outfitter/contracts";
 import { z } from "zod";
 /**
+* @outfitter/mcp - Logging Bridge
+*
+* Maps Outfitter log levels to MCP log levels for
+* server-to-client log message notifications.
+*
+* @packageDocumentation
+*/
+/**
+* MCP log levels as defined in the MCP specification.
+* Ordered from least to most severe.
+*/
+type McpLogLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+/**
+* Outfitter log levels.
+*/
+type OutfitterLogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/**
+* Map an Outfitter log level to the corresponding MCP log level.
+*/
+declare function mapLogLevelToMcp(level: OutfitterLogLevel): McpLogLevel;
+/**
+* Check whether a message at the given level should be emitted
+* based on the client-requested threshold.
+*/
+declare function shouldEmitLog(messageLevel: McpLogLevel, threshold: McpLogLevel): boolean;
+/**
 * Configuration options for creating an MCP server.
 *
 * @example
@@ -31,6 +57,37 @@ interface McpServerOptions {
 	* If not provided, a no-op logger is used.
 	*/
 	logger?: Logger;
+	/**
+	* 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;
+}
+/**
+* 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 does not modify any state. */
+	readOnlyHint?: boolean;
+	/** 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;
 }
 /**
 * Definition of an MCP tool that can be invoked by clients.
@@ -94,6 +151,11 @@ interface ToolDefinition<
 	*/
 	inputSchema: z.ZodType<TInput>;
 	/**
+	* Optional behavioral annotations for the tool.
+	* Helps clients understand tool behavior without invoking it.
+	*/
+	annotations?: ToolAnnotations;
+	/**
 	* Handler function that processes the tool invocation.
 	* Receives validated input and HandlerContext, returns Result.
 	*/
@@ -112,8 +174,66 @@ interface SerializedTool {
 	inputSchema: Record<string, unknown>;
 	/** MCP tool-search hint: whether tool is deferred */
 	defer_loading?: boolean;
+	/** Behavioral annotations for the tool */
+	annotations?: ToolAnnotations;
 }
 /**
+* 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;
+}
+/**
+* Text content returned from a resource read.
+*/
+interface TextResourceContent {
+	/** Resource URI */
+	uri: string;
+	/** Text content */
+	text: string;
+	/** Optional MIME type */
+	mimeType?: string;
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+}
+/**
+* Binary (base64-encoded) content returned from a resource read.
+*/
+interface BlobResourceContent {
+	/** Resource URI */
+	uri: string;
+	/** Base64-encoded binary content */
+	blob: string;
+	/** Optional MIME type */
+	mimeType?: string;
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+}
+/**
+* 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,
@@ -126,6 +246,10 @@ interface SerializedTool {
 *   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 }]);
+*   },
 * };
 * ```
 */
@@ -150,6 +274,151 @@ interface ResourceDefinition {
 	* Helps clients understand how to process the resource.
 	*/
 	mimeType?: string;
+	/**
+	* Optional handler for reading the resource content.
+	* If not provided, the resource is metadata-only.
+	*/
+	handler?: ResourceReadHandler;
+}
+/**
+* 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 {
+	/** URI template with `{param}` placeholders (RFC 6570 Level 1). */
+	uriTemplate: string;
+	/** Human-readable name for the template. */
+	name: string;
+	/** Optional description. */
+	description?: string;
+	/** Optional MIME type. */
+	mimeType?: string;
+	/** Optional completion handlers keyed by parameter name. */
+	complete?: Record<string, CompletionHandler>;
+	/** Handler for reading matched resources. */
+	handler: ResourceTemplateReadHandler;
+}
+/**
+* Result of a completion request.
+*/
+interface CompletionResult {
+	/** Completion values */
+	values: string[];
+	/** Total number of available values (for pagination) */
+	total?: number;
+	/** Whether there are more values */
+	hasMore?: boolean;
+}
+/**
+* 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 {
+	/** Argument name */
+	name: string;
+	/** Human-readable description */
+	description?: string;
+	/** Whether this argument is required */
+	required?: boolean;
+	/** Optional completion handler for this argument */
+	complete?: CompletionHandler;
+}
+/**
+* Content block within a prompt message.
+*/
+interface PromptMessageContent {
+	/** Content type */
+	type: "text";
+	/** Text content */
+	text: string;
+	/** Optional content annotations */
+	annotations?: ContentAnnotations;
+}
+/**
+* A message in a prompt response.
+*/
+interface PromptMessage {
+	/** Message role */
+	role: "user" | "assistant";
+	/** Message content */
+	content: PromptMessageContent;
+}
+/**
+* Result returned from getting a prompt.
+*/
+interface PromptResult {
+	/** Prompt messages */
+	messages: PromptMessage[];
+	/** Optional description override */
+	description?: string;
+}
+/**
+* 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 {
+	/** Unique prompt name */
+	name: string;
+	/** Human-readable description */
+	description?: string;
+	/** Prompt arguments */
+	arguments: PromptArgument[];
+	/** Handler to generate messages */
+	handler: PromptHandler;
 }
 declare const McpErrorBase: TaggedErrorClass<"McpError", {
 	message: string;
@@ -191,6 +460,8 @@ interface InvokeToolOptions {
 	signal?: AbortSignal;
 	/** Custom request ID (auto-generated if not provided) */
 	requestId?: string;
+	/** Progress token from client for tracking progress */
+	progressToken?: string | number;
 }
 /**
 * MCP Server instance.
@@ -236,11 +507,56 @@ interface McpServer {
 	*/
 	getTools(): SerializedTool[];
 	/**
+	* Register a resource template with the server.
+	* @param template - Resource template definition to register
+	*/
+	registerResourceTemplate(template: ResourceTemplateDefinition): void;
+	/**
 	* Get all registered resources.
 	* @returns Array of resource definitions
 	*/
 	getResources(): ResourceDefinition[];
 	/**
+	* Get all registered resource templates.
+	* @returns Array of resource template definitions
+	*/
+	getResourceTemplates(): ResourceTemplateDefinition[];
+	/**
+	* 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>>>;
+	/**
+	* Register a prompt with the server.
+	* @param prompt - Prompt definition to register
+	*/
+	registerPrompt(prompt: PromptDefinition): void;
+	/**
+	* Get all registered prompts.
+	* @returns Array of prompt definitions (without handlers)
+	*/
+	getPrompts(): Array<{
+		name: string;
+		description?: string;
+		arguments: PromptArgument[];
+	}>;
+	/**
+	* 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>>>;
+	/**
+	* 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>>>;
+	/**
 	* Invoke a tool by name.
 	* @param name - Tool name
 	* @param input - Tool input (will be validated)
@@ -249,6 +565,56 @@ interface McpServer {
 	*/
 	invokeTool<T = unknown>(name: string, input: unknown, options?: InvokeToolOptions): Promise<Result<T, InstanceType<typeof McpError>>>;
 	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* Notify connected clients that the resource list has changed.
+	*/
+	notifyResourcesChanged(): void;
+	/**
+	* Notify connected clients that the prompt list has changed.
+	*/
+	notifyPromptsChanged(): 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;
+	/**
+	* 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;
+	/**
+	* Bind the SDK server instance for notifications.
+	* Called internally by the transport layer.
+	* @param sdkServer - The MCP SDK Server instance
+	*/
+	bindSdkServer?(sdkServer: any): void;
+	/**
 	* Start the MCP server.
 	* Begins listening for client connections.
 	*/
@@ -260,12 +626,26 @@ interface McpServer {
 	stop(): Promise<void>;
 }
 /**
+* Reporter for sending progress updates to clients.
+*/
+interface ProgressReporter {
+	/**
+	* Report progress for the current operation.
+	* @param progress - Current progress value
+	* @param total - Optional total value (for percentage calculation)
+	* @param message - Optional human-readable status message
+	*/
+	report(progress: number, total?: number, message?: string): void;
+}
+/**
 * Extended handler context for MCP tools.
 * Includes MCP-specific information in addition to standard HandlerContext.
 */
 interface McpHandlerContext extends HandlerContext {
 	/** The name of the tool being invoked */
 	toolName?: string;
+	/** Progress reporter, present when client provides a progressToken */
+	progress?: ProgressReporter;
 }
 interface BuildMcpToolsOptions {
 	readonly includeSurfaces?: readonly ActionSurface[];
@@ -507,6 +887,26 @@ declare function defineTool<
 * ```
 */
 declare function defineResource(definition: ResourceDefinition): ResourceDefinition;
+/**
+* Define a resource template.
+*
+* Helper function for creating resource template definitions
+* with URI pattern matching.
+*
+* @param definition - Resource template definition object
+* @returns The same resource template definition
+*/
+declare function defineResourceTemplate(definition: ResourceTemplateDefinition): ResourceTemplateDefinition;
+/**
+* Define a prompt.
+*
+* Helper function for creating prompt definitions
+* with consistent typing.
+*
+* @param definition - Prompt definition object
+* @returns The same prompt definition
+*/
+declare function definePrompt(definition: PromptDefinition): PromptDefinition;
 import { Server } from "@modelcontextprotocol/sdk/server/index";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types";
@@ -519,4 +919,4 @@ declare function createSdkServer(server: McpServer): Server;
 * Connect an MCP server over stdio transport.
 */
 declare function connectStdio(server: McpServer, transport?: StdioServerTransport): Promise<Server>;
-export { zodToJsonSchema, defineTool, defineResource, defineQueryTool, defineDocsTool, defineConfigTool, createSdkServer, createMcpServer, createCoreTools, connectStdio, buildMcpTools, ToolDefinition, SerializedTool, ResourceDefinition, QueryToolResponse, QueryToolOptions, QueryToolInput, McpToolResponse, McpServerOptions, McpServer, McpHandlerContext, McpError, JsonSchema, InvokeToolOptions, DocsToolResponse, DocsToolOptions, DocsToolInput, DocsToolEntry, DocsSection, CoreToolsOptions, ConfigToolResponse, ConfigToolOptions, ConfigToolInput, ConfigStore, ConfigAction, BuildMcpToolsOptions };
+export { zodToJsonSchema, shouldEmitLog, mapLogLevelToMcp, defineTool, defineResourceTemplate, defineResource, defineQueryTool, definePrompt, defineDocsTool, defineConfigTool, createSdkServer, createMcpServer, createCoreTools, connectStdio, buildMcpTools, ToolDefinition, ToolAnnotations, TextResourceContent, SerializedTool, ResourceTemplateReadHandler, ResourceTemplateDefinition, ResourceReadHandler, ResourceDefinition, ResourceContent, QueryToolResponse, QueryToolOptions, QueryToolInput, PromptResult, PromptMessageContent, PromptMessage, PromptHandler, PromptDefinition, PromptArgument, ProgressReporter, McpToolResponse, McpServerOptions, McpServer, McpLogLevel, McpHandlerContext, McpError, JsonSchema, InvokeToolOptions, DocsToolResponse, DocsToolOptions, DocsToolInput, DocsToolEntry, DocsSection, CoreToolsOptions, ContentAnnotations, ConfigToolResponse, ConfigToolOptions, ConfigToolInput, ConfigStore, ConfigAction, CompletionResult, CompletionRef, CompletionHandler, BuildMcpToolsOptions, BlobResourceContent };

package/dist/index.js

@@ -2,8 +2,43 @@
 import { DEFAULT_REGISTRY_SURFACES } from "@outfitter/contracts";
 
 // src/server.ts
+import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
 import { generateRequestId, Result } from "@outfitter/contracts";
 
+// src/logging.ts
+var MCP_LEVEL_ORDER = [
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency"
+];
+function mapLogLevelToMcp(level) {
+  switch (level) {
+    case "trace":
+    case "debug":
+      return "debug";
+    case "info":
+      return "info";
+    case "warn":
+      return "warning";
+    case "error":
+      return "error";
+    case "fatal":
+      return "emergency";
+    default: {
+      const _exhaustiveCheck = level;
+      return _exhaustiveCheck;
+    }
+  }
+}
+function shouldEmitLog(messageLevel, threshold) {
+  return MCP_LEVEL_ORDER.indexOf(messageLevel) >= MCP_LEVEL_ORDER.indexOf(threshold);
+}
+
 // src/schema.ts
 function zodToJsonSchema(schema) {
   return convertZodType(schema);
@@ -357,23 +392,61 @@ class McpError extends McpErrorBase {
 
 // src/server.ts
 function createNoOpLogger() {
-  const noop = () => {};
   return {
-    trace: noop,
-    debug: noop,
-    info: noop,
-    warn: noop,
-    error: noop,
-    fatal: noop,
+    trace: (..._args) => {},
+    debug: (..._args) => {},
+    info: (..._args) => {},
+    warn: (..._args) => {},
+    error: (..._args) => {},
+    fatal: (..._args) => {},
     child: () => createNoOpLogger()
   };
 }
+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 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;
+}
 function createMcpServer(options) {
   const { name, version, logger: providedLogger } = options;
   const logger = providedLogger ?? createNoOpLogger();
   const tools = new Map;
-  const resources = [];
-  function createHandlerContext(toolName, requestId, signal) {
+  const resources = new Map;
+  const resourceTemplates = new Map;
+  const prompts = new Map;
+  let sdkServer = null;
+  const subscriptions = new Set;
+  let clientLogLevel = resolveDefaultLogLevel(options);
+  function createHandlerContext(toolName, requestId, signal, progressToken) {
     const ctx = {
       requestId,
       logger: logger.child({ tool: toolName, requestId }),
@@ -383,6 +456,21 @@ function createMcpServer(options) {
     if (signal !== undefined) {
       ctx.signal = signal;
     }
+    if (progressToken !== undefined && sdkServer) {
+      ctx.progress = {
+        report(progress, total, message) {
+          sdkServer?.notification?.({
+            method: "notifications/progress",
+            params: {
+              progressToken,
+              progress,
+              ...total !== undefined ? { total } : {},
+              ...message ? { message } : {}
+            }
+          });
+        }
+      };
+    }
     return ctx;
   }
   function translateError(error) {
@@ -423,34 +511,232 @@ function createMcpServer(options) {
       const jsonSchema = zodToJsonSchema(tool.inputSchema);
       const handler = (input, ctx) => tool.handler(input, ctx);
       const deferLoading = tool.deferLoading ?? true;
-      tools.set(tool.name, {
+      const stored = {
         name: tool.name,
         description,
         inputSchema: jsonSchema,
         deferLoading,
         handler,
         zodSchema: tool.inputSchema
-      });
+      };
+      if (tool.annotations !== undefined) {
+        stored.annotations = tool.annotations;
+      }
+      tools.set(tool.name, stored);
       logger.info("Tool registered", { name: tool.name });
+      if (sdkServer) {
+        sdkServer.sendToolListChanged?.();
+      }
     },
     registerResource(resource) {
       logger.debug("Registering resource", {
         uri: resource.uri,
         name: resource.name
       });
-      resources.push(resource);
+      resources.set(resource.uri, resource);
       logger.info("Resource registered", { uri: resource.uri });
+      if (sdkServer) {
+        sdkServer.sendResourceListChanged?.();
+      }
+    },
+    registerResourceTemplate(template) {
+      logger.debug("Registering resource template", {
+        uriTemplate: template.uriTemplate,
+        name: template.name
+      });
+      resourceTemplates.set(template.uriTemplate, template);
+      logger.info("Resource template registered", {
+        uriTemplate: template.uriTemplate
+      });
+      if (sdkServer) {
+        sdkServer.sendResourceListChanged?.();
+      }
     },
     getTools() {
       return Array.from(tools.values()).map((tool) => ({
         name: tool.name,
         description: tool.description,
         inputSchema: tool.inputSchema,
-        defer_loading: tool.deferLoading
+        defer_loading: tool.deferLoading,
+        ...tool.annotations ? { annotations: tool.annotations } : {}
       }));
     },
     getResources() {
-      return [...resources];
+      return Array.from(resources.values());
+    },
+    getResourceTemplates() {
+      return Array.from(resourceTemplates.values());
+    },
+    async complete(ref, argumentName, value) {
+      if (ref.type === "ref/prompt") {
+        const prompt = prompts.get(ref.name);
+        if (!prompt) {
+          return Result.err(new McpError({
+            message: `Prompt not found: ${ref.name}`,
+            code: -32601,
+            context: { prompt: ref.name }
+          }));
+        }
+        const arg = prompt.arguments.find((a) => a.name === argumentName);
+        if (!arg?.complete) {
+          return Result.ok({ values: [] });
+        }
+        try {
+          const result = await arg.complete(value);
+          return Result.ok(result);
+        } catch (error) {
+          return Result.err(new McpError({
+            message: error instanceof Error ? error.message : "Unknown error",
+            code: -32603,
+            context: {
+              prompt: ref.name,
+              argument: argumentName,
+              thrown: true
+            }
+          }));
+        }
+      }
+      if (ref.type === "ref/resource") {
+        const template = resourceTemplates.get(ref.uri);
+        if (!template) {
+          return Result.err(new McpError({
+            message: `Resource template not found: ${ref.uri}`,
+            code: -32601,
+            context: { uri: ref.uri }
+          }));
+        }
+        const handler = template.complete?.[argumentName];
+        if (!handler) {
+          return Result.ok({ values: [] });
+        }
+        try {
+          const result = await handler(value);
+          return Result.ok(result);
+        } catch (error) {
+          return Result.err(new McpError({
+            message: error instanceof Error ? error.message : "Unknown error",
+            code: -32603,
+            context: { uri: ref.uri, argument: argumentName, thrown: true }
+          }));
+        }
+      }
+      return Result.err(new McpError({
+        message: "Invalid completion reference type",
+        code: -32602,
+        context: { ref }
+      }));
+    },
+    registerPrompt(prompt) {
+      logger.debug("Registering prompt", { name: prompt.name });
+      prompts.set(prompt.name, prompt);
+      logger.info("Prompt registered", { name: prompt.name });
+      if (sdkServer) {
+        sdkServer.sendPromptListChanged?.();
+      }
+    },
+    getPrompts() {
+      return Array.from(prompts.values()).map((p) => ({
+        name: p.name,
+        ...p.description ? { description: p.description } : {},
+        arguments: p.arguments
+      }));
+    },
+    async getPrompt(promptName, args) {
+      const prompt = prompts.get(promptName);
+      if (!prompt) {
+        return Result.err(new McpError({
+          message: `Prompt not found: ${promptName}`,
+          code: -32601,
+          context: { prompt: promptName }
+        }));
+      }
+      for (const arg of prompt.arguments) {
+        if (arg.required && (args[arg.name] === undefined || args[arg.name] === "")) {
+          return Result.err(new McpError({
+            message: `Missing required argument: ${arg.name}`,
+            code: -32602,
+            context: { prompt: promptName, argument: arg.name }
+          }));
+        }
+      }
+      try {
+        const result = await prompt.handler(args);
+        if (result.isErr()) {
+          return Result.err(translateError(result.error));
+        }
+        return Result.ok(result.value);
+      } catch (error) {
+        return Result.err(new McpError({
+          message: error instanceof Error ? error.message : "Unknown error",
+          code: -32603,
+          context: { prompt: promptName, thrown: true }
+        }));
+      }
+    },
+    async readResource(uri) {
+      const resource = resources.get(uri);
+      if (resource) {
+        if (!resource.handler) {
+          return Result.err(new McpError({
+            message: `Resource not readable: ${uri}`,
+            code: -32002,
+            context: { uri }
+          }));
+        }
+        const requestId = generateRequestId();
+        const ctx = {
+          requestId,
+          logger: logger.child({ resource: uri, requestId }),
+          cwd: process.cwd(),
+          env: process.env
+        };
+        try {
+          const result = await resource.handler(uri, ctx);
+          if (result.isErr()) {
+            return Result.err(translateError(result.error));
+          }
+          return Result.ok(result.value);
+        } catch (error) {
+          return Result.err(new McpError({
+            message: error instanceof Error ? error.message : "Unknown error",
+            code: -32603,
+            context: { uri, thrown: true }
+          }));
+        }
+      }
+      for (const template of resourceTemplates.values()) {
+        const variables = matchUriTemplate(template.uriTemplate, uri);
+        if (variables) {
+          const templateRequestId = generateRequestId();
+          const templateCtx = {
+            requestId: templateRequestId,
+            logger: logger.child({
+              resource: uri,
+              requestId: templateRequestId
+            }),
+            cwd: process.cwd(),
+            env: process.env
+          };
+          try {
+            const result = await template.handler(uri, variables, templateCtx);
+            if (result.isErr()) {
+              return Result.err(translateError(result.error));
+            }
+            return Result.ok(result.value);
+          } catch (error) {
+            return Result.err(new McpError({
+              message: error instanceof Error ? error.message : "Unknown error",
+              code: -32603,
+              context: { uri, thrown: true }
+            }));
+          }
+        }
+      }
+      return Result.err(new McpError({
+        message: `Resource not found: ${uri}`,
+        code: -32002,
+        context: { uri }
+      }));
     },
     async invokeTool(toolName, input, invokeOptions) {
       const requestId = invokeOptions?.requestId ?? generateRequestId();
@@ -481,7 +767,7 @@ function createMcpServer(options) {
           }
         }));
       }
-      const ctx = createHandlerContext(toolName, requestId, invokeOptions?.signal);
+      const ctx = createHandlerContext(toolName, requestId, invokeOptions?.signal, invokeOptions?.progressToken);
       try {
         const result = await tool.handler(parseResult.data, ctx);
         if (result.isErr()) {
@@ -513,6 +799,50 @@ function createMcpServer(options) {
         }));
       }
     },
+    subscribe(uri) {
+      subscriptions.add(uri);
+      logger.debug("Resource subscription added", { uri });
+    },
+    unsubscribe(uri) {
+      subscriptions.delete(uri);
+      logger.debug("Resource subscription removed", { uri });
+    },
+    notifyResourceUpdated(uri) {
+      if (subscriptions.has(uri)) {
+        sdkServer?.sendResourceUpdated?.({ uri });
+      }
+    },
+    notifyToolsChanged() {
+      sdkServer?.sendToolListChanged?.();
+    },
+    notifyResourcesChanged() {
+      sdkServer?.sendResourceListChanged?.();
+    },
+    notifyPromptsChanged() {
+      sdkServer?.sendPromptListChanged?.();
+    },
+    setLogLevel(level) {
+      clientLogLevel = level;
+      logger.debug("Client log level set", { level });
+    },
+    sendLogMessage(level, data, loggerName) {
+      if (!sdkServer || clientLogLevel === null || !shouldEmitLog(level, clientLogLevel)) {
+        return;
+      }
+      const params = {
+        level,
+        data
+      };
+      if (loggerName !== undefined) {
+        params.logger = loggerName;
+      }
+      sdkServer.sendLoggingMessage?.(params);
+    },
+    bindSdkServer(server2) {
+      sdkServer = server2;
+      clientLogLevel = resolveDefaultLogLevel(options);
+      logger.debug("SDK server bound for notifications");
+    },
     async start() {
       logger.info("MCP server starting", { name, version, tools: tools.size });
     },
@@ -525,9 +855,44 @@ function createMcpServer(options) {
 function defineTool(definition) {
   return definition;
 }
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matchUriTemplate(template, uri) {
+  const paramNames = [];
+  const parts = template.split(/(\{[^}]+\})/);
+  const regexSource = parts.map((part) => {
+    const paramMatch = part.match(/^\{([^}]+)\}$/);
+    if (paramMatch?.[1]) {
+      paramNames.push(paramMatch[1]);
+      return "([^/]+)";
+    }
+    return escapeRegex(part);
+  }).join("");
+  const regex = new RegExp(`^${regexSource}$`);
+  const match = uri.match(regex);
+  if (!match) {
+    return null;
+  }
+  const variables = {};
+  for (let i = 0;i < paramNames.length; i++) {
+    const name = paramNames[i];
+    const value = match[i + 1];
+    if (name !== undefined && value !== undefined) {
+      variables[name] = value;
+    }
+  }
+  return variables;
+}
 function defineResource(definition) {
   return definition;
 }
+function defineResourceTemplate(definition) {
+  return definition;
+}
+function definePrompt(definition) {
+  return definition;
+}
 
 // src/actions.ts
 function isActionRegistry(source) {
@@ -694,7 +1059,17 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  CompleteRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+  McpError as SdkMcpError,
+  SetLevelRequestSchema,
+  SubscribeRequestSchema,
+  UnsubscribeRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { safeStringify } from "@outfitter/contracts";
 function isMcpToolResponse(value) {
@@ -751,19 +1126,93 @@ function wrapToolError(error) {
     isError: true
   };
 }
+function toSdkError(error) {
+  return new SdkMcpError(error.code, error.message, error.context);
+}
 function createSdkServer(server) {
-  const sdkServer = new Server({ name: server.name, version: server.version }, { capabilities: { tools: {} } });
+  const capabilities = {
+    tools: { listChanged: true }
+  };
+  if (server.getResources().length > 0 || server.getResourceTemplates().length > 0) {
+    capabilities["resources"] = { listChanged: true, subscribe: true };
+  }
+  if (server.getPrompts().length > 0) {
+    capabilities["prompts"] = { listChanged: true };
+  }
+  capabilities["completions"] = {};
+  capabilities["logging"] = {};
+  const sdkServer = new Server({ name: server.name, version: server.version }, { capabilities });
   sdkServer.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: server.getTools()
   }));
   sdkServer.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const result = await server.invokeTool(name, args ?? {});
+    const progressToken = request.params._meta?.progressToken;
+    const options = progressToken !== undefined ? { progressToken } : undefined;
+    const result = await server.invokeTool(name, args ?? {}, options);
     if (result.isErr()) {
       return wrapToolError(result.error);
     }
     return wrapToolResult(result.value);
   });
+  sdkServer.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: server.getResources().map((r) => ({
+      uri: r.uri,
+      name: r.name,
+      ...r.description ? { description: r.description } : {},
+      ...r.mimeType ? { mimeType: r.mimeType } : {}
+    }))
+  }));
+  sdkServer.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: server.getResourceTemplates().map((t) => ({
+      uriTemplate: t.uriTemplate,
+      name: t.name,
+      ...t.description ? { description: t.description } : {},
+      ...t.mimeType ? { mimeType: t.mimeType } : {}
+    }))
+  }));
+  sdkServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    const result = await server.readResource(uri);
+    if (result.isErr()) {
+      throw toSdkError(result.error);
+    }
+    return { contents: result.value };
+  });
+  sdkServer.setRequestHandler(SubscribeRequestSchema, async (request) => {
+    server.subscribe(request.params.uri);
+    return {};
+  });
+  sdkServer.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+    server.unsubscribe(request.params.uri);
+    return {};
+  });
+  sdkServer.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: server.getPrompts()
+  }));
+  sdkServer.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await server.getPrompt(name, args ?? {});
+    if (result.isErr()) {
+      throw toSdkError(result.error);
+    }
+    return { ...result.value };
+  });
+  sdkServer.setRequestHandler(CompleteRequestSchema, async (request) => {
+    const { ref, argument } = request.params;
+    const completionRef = ref.type === "ref/prompt" ? { type: "ref/prompt", name: ref.name } : { type: "ref/resource", uri: ref.uri };
+    const result = await server.complete(completionRef, argument.name, argument.value);
+    if (result.isErr()) {
+      throw toSdkError(result.error);
+    }
+    return { completion: result.value };
+  });
+  sdkServer.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const level = request.params.level;
+    server.setLogLevel?.(level);
+    return {};
+  });
+  server.bindSdkServer?.(sdkServer);
   return sdkServer;
 }
 async function connectStdio(server, transport = new StdioServerTransport) {
@@ -773,9 +1222,13 @@ async function connectStdio(server, transport = new StdioServerTransport) {
 }
 export {
   zodToJsonSchema,
+  shouldEmitLog,
+  mapLogLevelToMcp,
   defineTool,
+  defineResourceTemplate,
   defineResource,
   defineQueryTool,
+  definePrompt,
   defineDocsTool,
   defineConfigTool,
   createSdkServer,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/mcp",
   "description": "MCP server framework with typed tools for Outfitter",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist"
@@ -40,8 +40,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@outfitter/contracts": "0.1.0",
-    "@outfitter/logging": "0.1.0",
+    "@outfitter/config": "0.3.0",
+    "@outfitter/contracts": "0.2.0",
+    "@outfitter/logging": "0.3.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {