@outfitter/mcp 0.3.0 → 0.4.1

package/README.md

@@ -56,14 +56,82 @@ Creates an MCP server instance.
 interface McpServerOptions {
   name: string;           // Server name for MCP handshake
   version: string;        // Server version (semver)
-  logger?: Logger;        // Optional structured logger
+  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) },
+  }),
 });
 ```
 
@@ -122,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);
   },
@@ -291,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.
@@ -393,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-ktapzh9d.js";
+import"./shared/@outfitter/mcp-nmp5wf0w.js";
+import"./shared/@outfitter/mcp-fjtxsa0x.js";
+import"./shared/@outfitter/mcp-9m5hs2z0.js";
+import"./shared/@outfitter/mcp-zy7b487d.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

@@ -54,7 +54,7 @@ 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;
 	/**
@@ -90,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.
@@ -647,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[];
 }
@@ -746,65 +819,7 @@ 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[];
-import { z as z2 } from "zod";
-/**
-* JSON Schema representation.
-*/
-interface JsonSchema {
-	type?: string;
-	properties?: Record<string, JsonSchema>;
-	required?: string[];
-	items?: JsonSchema | JsonSchema[];
-	description?: string;
-	default?: unknown;
-	minimum?: number;
-	maximum?: number;
-	exclusiveMinimum?: number;
-	exclusiveMaximum?: number;
-	minLength?: number;
-	maxLength?: number;
-	pattern?: string;
-	format?: string;
-	enum?: unknown[];
-	const?: unknown;
-	anyOf?: JsonSchema[];
-	oneOf?: JsonSchema[];
-	allOf?: JsonSchema[];
-	not?: JsonSchema | Record<string, never>;
-	$ref?: string;
-	$schema?: string;
-	$defs?: Record<string, JsonSchema>;
-	definitions?: Record<string, JsonSchema>;
-	additionalProperties?: boolean | JsonSchema;
-}
-/**
-* Convert a Zod schema to JSON Schema format.
-*
-* This is a simplified converter that handles common Zod types.
-* For complex schemas, consider using a full zod-to-json-schema library.
-*
-* @param schema - Zod schema to convert
-* @returns JSON Schema representation
-*
-* @example
-* ```typescript
-* const zodSchema = z.object({
-*   name: z.string(),
-*   age: z.number().optional(),
-* });
-*
-* const jsonSchema = zodToJsonSchema(zodSchema);
-* // {
-* //   type: "object",
-* //   properties: {
-* //     name: { type: "string" },
-* //     age: { type: "number" },
-* //   },
-* //   required: ["name"],
-* // }
-* ```
-*/
-declare function zodToJsonSchema(schema: z2.ZodType<unknown>): JsonSchema;
+import { JsonSchema, zodToJsonSchema } from "@outfitter/contracts/schema";
 import { OutfitterError as OutfitterError3 } from "@outfitter/contracts";
 /**
 * Create an MCP server instance.
@@ -912,6 +927,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;
@@ -919,4 +950,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 };