@outfitter/mcp 0.2.0 → 0.4.0

package/README.md

@@ -54,18 +54,122 @@ 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 (BYO)
+  defaultLogLevel?: McpLogLevel | null; // Default log forwarding level
 }
 
 const server = createMcpServer({
   name: "my-server",
   version: "1.0.0",
-  logger: createLogger({ name: "mcp" }),
 });
+
+// If `logger` is omitted, Outfitter logger factory defaults are used.
+```
+
+### Bring Your Own Logger (BYO)
+
+`createMcpServer` accepts any logger implementing the shared `Logger` contract.
+This lets you use the default Outfitter backend or a custom backend adapter.
+
+#### Outfitter factory backend
+
+```typescript
+import { createOutfitterLoggerFactory } from "@outfitter/logging";
+
+const loggerFactory = createOutfitterLoggerFactory();
+const server = createMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  logger: loggerFactory.createLogger({
+    name: "mcp",
+    context: { surface: "mcp" },
+  }),
+});
+```
+
+#### Custom adapter backend
+
+```typescript
+import {
+  createLoggerFactory,
+  type Logger,
+  type LoggerAdapter,
+} from "@outfitter/contracts";
+
+type BackendOptions = { write: (line: string) => void };
+
+const adapter: LoggerAdapter<BackendOptions> = {
+  createLogger(config) {
+    const write = config.backend?.write ?? (() => {});
+    const createMethod = (level: string): Logger["info"] =>
+      ((message: string) => {
+        write(`[${level}] ${config.name}: ${message}`);
+      }) as Logger["info"];
+
+    return {
+      trace: createMethod("trace"),
+      debug: createMethod("debug"),
+      info: createMethod("info"),
+      warn: createMethod("warn"),
+      error: createMethod("error"),
+      fatal: createMethod("fatal"),
+      child: (childContext) =>
+        adapter.createLogger({
+          ...config,
+          context: { ...(config.context ?? {}), ...childContext },
+        }),
+    };
+  },
+};
+
+const loggerFactory = createLoggerFactory(adapter);
+const server = createMcpServer({
+  name: "my-server",
+  version: "1.0.0",
+  logger: loggerFactory.createLogger({
+    name: "mcp",
+    backend: { write: (line) => console.log(line) },
+  }),
+});
+```
+
+### 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.
@@ -86,7 +190,7 @@ const getUserTool = defineTool({
   handler: async (input, ctx) => {
     const user = await db.users.find(input.userId);
     if (!user) {
-      return Result.err(new NotFoundError("user", input.userId));
+      return Result.err(NotFoundError.create("user", input.userId));
     }
     return Result.ok(user);
   },
@@ -255,8 +359,74 @@ for (const tool of coreTools) {
 }
 ```
 
+## Tool Annotations
+
+Use `TOOL_ANNOTATIONS` presets to declare tool behavior hints without manually specifying all four booleans:
+
+```typescript
+import { defineTool, TOOL_ANNOTATIONS } from "@outfitter/mcp";
+
+// Use a preset directly
+const listTool = defineTool({
+  name: "list-items",
+  description: "List all items",
+  inputSchema: z.object({}),
+  annotations: TOOL_ANNOTATIONS.readOnly,
+  handler: async (input, ctx) => { /* ... */ },
+});
+
+// Spread and override for edge cases
+const searchTool = defineTool({
+  name: "search",
+  description: "Search external APIs",
+  inputSchema: z.object({ q: z.string() }),
+  annotations: { ...TOOL_ANNOTATIONS.readOnly, openWorldHint: true },
+  handler: async (input, ctx) => { /* ... */ },
+});
+```
+
+| Preset | readOnly | destructive | idempotent | openWorld |
+|--------|----------|-------------|------------|-----------|
+| `readOnly` | true | false | true | false |
+| `write` | false | false | false | false |
+| `writeIdempotent` | false | false | true | false |
+| `destructive` | false | true | true | false |
+| `openWorld` | false | false | false | true |
+
+For multi-action tools, use the most conservative union of hints. Per-action annotations are an MCP spec limitation.
+
+### adaptHandler
+
+When your handler returns domain errors that extend `Error` but not `OutfitterError`, use `adaptHandler` instead of an unsafe cast:
+
+```typescript
+import { adaptHandler, defineTool } from "@outfitter/mcp";
+
+const tool = defineTool({
+  name: "my-tool",
+  inputSchema: z.object({ id: z.string() }),
+  handler: adaptHandler(myDomainHandler),
+});
+```
+
 ## Transport Helpers
 
+### wrapToolResult / wrapToolError
+
+Format handler output as MCP tool responses. Useful when building custom transport layers or testing:
+
+```typescript
+import { wrapToolResult, wrapToolError } from "@outfitter/mcp";
+
+// Wrap a plain value as MCP tool content
+const response = wrapToolResult({ count: 42 });
+// { content: [{ type: "text", text: '{"count":42}' }] }
+
+// Wrap an error with isError flag
+const errorResponse = wrapToolError(new Error("not found"));
+// { content: [{ type: "text", text: "not found" }], isError: true }
+```
+
 ### connectStdio
 
 Connect server to stdio transport for Claude Desktop integration.
@@ -357,6 +527,10 @@ Config location:
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/claude/claude_desktop_config.json`
 
+## Upgrading
+
+Run `outfitter update --guide` for version-specific migration instructions, or check the [migration docs](https://github.com/outfitter-dev/outfitter/tree/main/plugins/outfitter/shared/migrations) for detailed upgrade steps.
+
 ## Related Packages
 
 - [@outfitter/contracts](../contracts/README.md) — Result types and error taxonomy

package/dist/actions.d.ts

@@ -0,0 +1,4 @@
+import { BuildMcpToolsOptions, buildMcpTools } from "./shared/@outfitter/mcp-a0cgfsnw";
+import "./shared/@outfitter/mcp-h2twz77x";
+import "./shared/@outfitter/mcp-cqpyer9m";
+export { buildMcpTools, BuildMcpToolsOptions };

package/dist/actions.js

@@ -0,0 +1,11 @@
+// @bun
+import {
+  buildMcpTools
+} from "./shared/@outfitter/mcp-9whem1wr.js";
+import"./shared/@outfitter/mcp-k8r6kefr.js";
+import"./shared/@outfitter/mcp-fjtxsa0x.js";
+import"./shared/@outfitter/mcp-9m5hs2z0.js";
+import"./shared/@outfitter/mcp-f91wbr49.js";
+export {
+  buildMcpTools
+};

package/dist/core-tools.d.ts

@@ -0,0 +1,4 @@
+import { ConfigAction, ConfigStore, ConfigToolInput, ConfigToolOptions, ConfigToolResponse, CoreToolDefinition, CoreToolsOptions, DocsSection, DocsToolEntry, DocsToolInput, DocsToolOptions, DocsToolResponse, NormalizedQueryInput, QueryToolInput, QueryToolOptions, QueryToolResponse, createCoreTools, defineConfigTool, defineDocsTool, defineQueryTool } from "./shared/@outfitter/mcp-dwd800vf";
+import "./shared/@outfitter/mcp-h2twz77x";
+import "./shared/@outfitter/mcp-cqpyer9m";
+export { defineQueryTool, defineDocsTool, defineConfigTool, createCoreTools, QueryToolResponse, QueryToolOptions, QueryToolInput, NormalizedQueryInput, DocsToolResponse, DocsToolOptions, DocsToolInput, DocsToolEntry, DocsSection, CoreToolsOptions, CoreToolDefinition, ConfigToolResponse, ConfigToolOptions, ConfigToolInput, ConfigStore, ConfigAction };

package/dist/core-tools.js

@@ -0,0 +1,13 @@
+// @bun
+import {
+  createCoreTools,
+  defineConfigTool,
+  defineDocsTool,
+  defineQueryTool
+} from "./shared/@outfitter/mcp-zv3ej45k.js";
+export {
+  defineQueryTool,
+  defineDocsTool,
+  defineConfigTool,
+  createCoreTools
+};

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
@@ -28,9 +54,22 @@ interface McpServerOptions {
 	version: string;
 	/**
 	* Optional logger instance for server logging.
-	* If not provided, a no-op logger is used.
+	* If not provided, the server uses the Outfitter logger factory defaults.
 	*/
 	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.
@@ -51,6 +90,57 @@ interface ToolAnnotations {
 	openWorldHint?: 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: {
+	/** Read-only, safe to call repeatedly. */
+	readonly readOnly: {
+		readonly readOnlyHint: true;
+		readonly destructiveHint: false;
+		readonly idempotentHint: true;
+		readonly openWorldHint: false;
+	};
+	/** Creates or updates state, not destructive. */
+	readonly write: {
+		readonly readOnlyHint: false;
+		readonly destructiveHint: false;
+		readonly idempotentHint: false;
+		readonly openWorldHint: false;
+	};
+	/** Idempotent write (PUT-like). */
+	readonly writeIdempotent: {
+		readonly readOnlyHint: false;
+		readonly destructiveHint: false;
+		readonly idempotentHint: true;
+		readonly openWorldHint: false;
+	};
+	/** Deletes or permanently modifies data. */
+	readonly destructive: {
+		readonly readOnlyHint: false;
+		readonly destructiveHint: true;
+		readonly idempotentHint: true;
+		readonly openWorldHint: false;
+	};
+	/** Interacts with external systems (APIs, network). */
+	readonly openWorld: {
+		readonly readOnlyHint: false;
+		readonly destructiveHint: false;
+		readonly idempotentHint: false;
+		readonly openWorldHint: true;
+	};
+};
+/**
 * Definition of an MCP tool that can be invoked by clients.
 *
 * Tools are the primary way clients interact with MCP servers.
@@ -560,6 +650,16 @@ interface McpServer {
 	*/
 	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
@@ -598,6 +698,28 @@ interface McpHandlerContext extends HandlerContext {
 	/** Progress reporter, present when client provides a progressToken */
 	progress?: ProgressReporter;
 }
+/**
+* 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>;
 interface BuildMcpToolsOptions {
 	readonly includeSurfaces?: readonly ActionSurface[];
 }
@@ -697,32 +819,6 @@ interface CoreToolsOptions {
 type NormalizedQueryInput = Required<Pick<QueryToolInput, "q">> & Omit<QueryToolInput, "q">;
 type CoreToolDefinition = ToolDefinition<DocsToolInput, DocsToolResponse> | ToolDefinition<ConfigToolInput, ConfigToolResponse> | ToolDefinition<QueryToolInput, QueryToolResponse>;
 declare function createCoreTools(options?: CoreToolsOptions): CoreToolDefinition[];
-/**
-* @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;
 import { z as z2 } from "zod";
 /**
 * JSON Schema representation.
@@ -889,6 +985,22 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types";
 type McpToolResponse = CallToolResult;
 /**
+* Wrap a handler success value into an MCP CallToolResult.
+*
+* If the value is already a valid McpToolResponse (has a `content` array),
+* it is returned as-is. Otherwise it is wrapped in a text content block.
+* Plain objects are also attached as `structuredContent` for SDK clients
+* that support structured output.
+*/
+declare function wrapToolResult(value: unknown): McpToolResponse;
+/**
+* Wrap an error into an MCP CallToolResult with `isError: true`.
+*
+* Serializes the error (preserving `_tag`, `message`, `code`, `context` if
+* present) and wraps it as a text content block.
+*/
+declare function wrapToolError(error: unknown): McpToolResponse;
+/**
 * Create an MCP SDK server from an Outfitter MCP server.
 */
 declare function createSdkServer(server: McpServer): Server;
@@ -896,4 +1008,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, 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 };
+export { zodToJsonSchema, wrapToolResult, wrapToolError, shouldEmitLog, mapLogLevelToMcp, defineTool, defineResourceTemplate, defineResource, defineQueryTool, definePrompt, defineDocsTool, defineConfigTool, createSdkServer, createMcpServer, createCoreTools, connectStdio, buildMcpTools, adaptHandler, ToolDefinition, ToolAnnotations, TextResourceContent, TOOL_ANNOTATIONS, 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 };