@outfitter/mcp 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,7 +2,46 @@
 import { DEFAULT_REGISTRY_SURFACES } from "@outfitter/contracts";
 
 // src/server.ts
+import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
 import { generateRequestId, Result } from "@outfitter/contracts";
+import {
+  createOutfitterLoggerFactory,
+  createPrettyFormatter
+} from "@outfitter/logging";
+
+// 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) {
@@ -349,33 +388,116 @@ import {
 } from "@outfitter/contracts";
 import { TaggedError } from "@outfitter/contracts";
 var TaggedError2 = TaggedErrorImpl;
+var TOOL_ANNOTATIONS = {
+  readOnly: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  write: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  writeIdempotent: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  destructive: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  openWorld: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
 var McpErrorBase = TaggedError2("McpError")();
 
 class McpError extends McpErrorBase {
   category = "internal";
 }
+function adaptHandler(handler) {
+  return handler;
+}
 
 // src/server.ts
-function 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 createDefaultMcpSink() {
+  const formatter = createPrettyFormatter({ colors: false });
   return {
-    trace: (..._args) => {},
-    debug: (..._args) => {},
-    info: (..._args) => {},
-    warn: (..._args) => {},
-    error: (..._args) => {},
-    fatal: (..._args) => {},
-    child: () => createNoOpLogger()
+    formatter,
+    write(record, formatted) {
+      const serialized = formatted ?? formatter.format(record);
+      const line = serialized.endsWith(`
+`) ? serialized : `${serialized}
+`;
+      if (typeof process !== "undefined" && process.stderr?.write) {
+        process.stderr.write(line);
+      }
+    }
   };
 }
+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();
+  let loggerFactory = null;
+  const logger = providedLogger ?? (() => {
+    loggerFactory = createOutfitterLoggerFactory({
+      defaults: { sinks: [createDefaultMcpSink()] }
+    });
+    return loggerFactory.createLogger({
+      name: "mcp",
+      context: { serverName: name, serverVersion: version, surface: "mcp" }
+    });
+  })();
   const tools = new Map;
   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,
@@ -752,10 +874,25 @@ function createMcpServer(options) {
       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() {
@@ -763,6 +900,9 @@ function createMcpServer(options) {
     },
     async stop() {
       logger.info("MCP server stopping", { name, version });
+      if (loggerFactory !== null) {
+        await loggerFactory.flush();
+      }
     }
   };
   return server;
@@ -969,39 +1109,6 @@ function createCoreTools(options = {}) {
     defineQueryTool(options.query)
   ];
 }
-// 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/transport.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -1079,16 +1186,12 @@ function toSdkError(error) {
 }
 function createSdkServer(server) {
   const capabilities = {
-    tools: { listChanged: true }
+    tools: { listChanged: true },
+    resources: { listChanged: true, subscribe: true },
+    prompts: { listChanged: true },
+    completions: {},
+    logging: {}
   };
-  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()
@@ -1170,6 +1273,8 @@ async function connectStdio(server, transport = new StdioServerTransport) {
 }
 export {
   zodToJsonSchema,
+  wrapToolResult,
+  wrapToolError,
   shouldEmitLog,
   mapLogLevelToMcp,
   defineTool,
@@ -1184,5 +1289,7 @@ export {
   createCoreTools,
   connectStdio,
   buildMcpTools,
+  adaptHandler,
+  TOOL_ANNOTATIONS,
   McpError
 };

package/dist/logging.d.ts

@@ -0,0 +1,2 @@
+import { McpLogLevel, mapLogLevelToMcp, shouldEmitLog } from "./shared/@outfitter/mcp-cqpyer9m";
+export { shouldEmitLog, mapLogLevelToMcp, McpLogLevel };

package/dist/logging.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  mapLogLevelToMcp,
+  shouldEmitLog
+} from "./shared/@outfitter/mcp-fjtxsa0x.js";
+export {
+  shouldEmitLog,
+  mapLogLevelToMcp
+};

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { JsonSchema, zodToJsonSchema } from "./shared/@outfitter/mcp-s80bqcsb";
+export { zodToJsonSchema, JsonSchema };

package/dist/schema.js

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

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { createMcpServer, definePrompt, defineResource, defineResourceTemplate, defineTool } from "./shared/@outfitter/mcp-2vqyt1fj";
+import "./shared/@outfitter/mcp-h2twz77x";
+import "./shared/@outfitter/mcp-cqpyer9m";
+export { defineTool, defineResourceTemplate, defineResource, definePrompt, createMcpServer };

package/dist/server.js

@@ -0,0 +1,18 @@
+// @bun
+import {
+  createMcpServer,
+  definePrompt,
+  defineResource,
+  defineResourceTemplate,
+  defineTool
+} from "./shared/@outfitter/mcp-k8r6kefr.js";
+import"./shared/@outfitter/mcp-fjtxsa0x.js";
+import"./shared/@outfitter/mcp-9m5hs2z0.js";
+import"./shared/@outfitter/mcp-f91wbr49.js";
+export {
+  defineTool,
+  defineResourceTemplate,
+  defineResource,
+  definePrompt,
+  createMcpServer
+};

package/dist/shared/@outfitter/mcp-2vqyt1fj.d.ts

@@ -0,0 +1,104 @@
+import { McpServer, McpServerOptions, PromptDefinition, ResourceDefinition, ResourceTemplateDefinition, ToolDefinition } from "./mcp-h2twz77x";
+import { OutfitterError } from "@outfitter/contracts";
+/**
+* Create an MCP server instance.
+*
+* The server provides:
+* - Tool registration with Zod schema validation
+* - Resource registration
+* - Tool invocation with Result-based error handling
+* - Automatic error translation from OutfitterError to McpError
+*
+* @param options - Server configuration options
+* @returns Configured McpServer instance
+*
+* @example
+* ```typescript
+* const server = createMcpServer({
+*   name: "calculator",
+*   version: "1.0.0",
+*   logger: createLogger({ name: "mcp" }),
+* });
+*
+* server.registerTool(defineTool({
+*   name: "add",
+*   description: "Add two numbers",
+*   inputSchema: z.object({ a: z.number(), b: z.number() }),
+*   handler: async (input) => Result.ok({ sum: input.a + input.b }),
+* }));
+*
+* const result = await server.invokeTool("add", { a: 2, b: 3 });
+* if (result.isOk()) {
+*   console.log(result.value.sum); // 5
+* }
+* ```
+*/
+declare function createMcpServer(options: McpServerOptions): McpServer;
+/**
+* Define a typed tool.
+*
+* This is a helper function that provides better type inference
+* when creating tool definitions.
+*
+* @param definition - Tool definition object
+* @returns The same tool definition with inferred types
+*
+* @example
+* ```typescript
+* const echoTool = defineTool({
+*   name: "echo",
+*   description: "Echo the input message",
+*   inputSchema: z.object({ message: z.string() }),
+*   handler: async (input, ctx) => {
+*     ctx.logger.debug("Echoing message");
+*     return Result.ok({ echo: input.message });
+*   },
+* });
+* ```
+*/
+declare function defineTool<
+	TInput,
+	TOutput,
+	TError extends OutfitterError = OutfitterError
+>(definition: ToolDefinition<TInput, TOutput, TError>): ToolDefinition<TInput, TOutput, TError>;
+/**
+* Define a resource.
+*
+* This is a helper function for creating resource definitions
+* with consistent typing.
+*
+* @param definition - Resource definition object
+* @returns The same resource definition
+*
+* @example
+* ```typescript
+* const configResource = defineResource({
+*   uri: "file:///etc/app/config.json",
+*   name: "Application Config",
+*   description: "Main configuration file",
+*   mimeType: "application/json",
+* });
+* ```
+*/
+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;
+export { createMcpServer, defineTool, defineResource, defineResourceTemplate, definePrompt };

package/dist/shared/@outfitter/mcp-9m5hs2z0.js

@@ -0,0 +1,49 @@
+// @bun
+// packages/mcp/src/types.ts
+import {
+  TaggedError as TaggedErrorImpl
+} from "@outfitter/contracts";
+import { TaggedError } from "@outfitter/contracts";
+var TaggedError2 = TaggedErrorImpl;
+var TOOL_ANNOTATIONS = {
+  readOnly: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  write: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  writeIdempotent: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  destructive: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  openWorld: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  }
+};
+var McpErrorBase = TaggedError2("McpError")();
+
+class McpError extends McpErrorBase {
+  category = "internal";
+}
+function adaptHandler(handler) {
+  return handler;
+}
+
+export { TOOL_ANNOTATIONS, McpError, adaptHandler, TaggedError };

package/dist/shared/@outfitter/mcp-9whem1wr.js

@@ -0,0 +1,28 @@
+// @bun
+import {
+  defineTool
+} from "./mcp-k8r6kefr.js";
+
+// packages/mcp/src/actions.ts
+import { DEFAULT_REGISTRY_SURFACES } from "@outfitter/contracts";
+function isActionRegistry(source) {
+  return "list" in source;
+}
+function buildMcpTools(source, options = {}) {
+  const actions = isActionRegistry(source) ? source.list() : source;
+  const includeSurfaces = options.includeSurfaces ?? [
+    "mcp"
+  ];
+  return actions.filter((action) => {
+    const surfaces = action.surfaces ?? DEFAULT_REGISTRY_SURFACES;
+    return surfaces.some((surface) => includeSurfaces.includes(surface));
+  }).map((action) => defineTool({
+    name: action.mcp?.tool ?? action.id,
+    description: action.mcp?.description ?? action.description ?? action.id,
+    inputSchema: action.input,
+    handler: async (input, ctx) => action.handler(input, ctx),
+    ...action.mcp?.deferLoading !== undefined ? { deferLoading: action.mcp.deferLoading } : {}
+  }));
+}
+
+export { buildMcpTools };

package/dist/shared/@outfitter/mcp-a0cgfsnw.d.ts

@@ -0,0 +1,8 @@
+import { ToolDefinition } from "./mcp-h2twz77x";
+import { ActionRegistry, ActionSurface, AnyActionSpec } from "@outfitter/contracts";
+interface BuildMcpToolsOptions {
+	readonly includeSurfaces?: readonly ActionSurface[];
+}
+type ActionSource = ActionRegistry | readonly AnyActionSpec[];
+declare function buildMcpTools(source: ActionSource, options?: BuildMcpToolsOptions): ToolDefinition<unknown, unknown>[];
+export { BuildMcpToolsOptions, buildMcpTools };

package/dist/shared/@outfitter/mcp-cqpyer9m.d.ts

@@ -0,0 +1,27 @@
+/**
+* @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;
+export { McpLogLevel, mapLogLevelToMcp, shouldEmitLog };

package/dist/shared/@outfitter/mcp-dwd800vf.d.ts

@@ -0,0 +1,96 @@
+import { ToolDefinition } from "./mcp-h2twz77x";
+import { HandlerContext, OutfitterError } from "@outfitter/contracts";
+import { Result } from "@outfitter/contracts";
+type DocsSection = "overview" | "tools" | "examples" | "schemas";
+interface DocsToolInput {
+	section?: DocsSection | undefined;
+}
+interface DocsToolEntry {
+	name: string;
+	summary?: string;
+	examples?: Array<{
+		input: Record<string, unknown>;
+		description?: string;
+	}>;
+}
+interface DocsToolResponse {
+	overview?: string;
+	tools?: DocsToolEntry[];
+	examples?: Array<{
+		name?: string;
+		description?: string;
+		input?: Record<string, unknown>;
+		output?: unknown;
+	}>;
+	schemas?: Record<string, unknown>;
+}
+interface DocsToolOptions {
+	/** Optional override for the docs tool description. */
+	description?: string;
+	/** Static docs payload (used when getDocs is not provided). */
+	docs?: DocsToolResponse;
+	/** Dynamic docs provider. */
+	getDocs?: (section?: DocsSection) => DocsToolResponse | Promise<DocsToolResponse>;
+}
+declare function defineDocsTool(options?: DocsToolOptions): ToolDefinition<DocsToolInput, DocsToolResponse>;
+type ConfigAction = "get" | "set" | "list";
+interface ConfigToolInput {
+	action: ConfigAction;
+	key?: string | undefined;
+	value?: unknown | undefined;
+}
+interface ConfigToolResponse {
+	action: ConfigAction;
+	key?: string;
+	value?: unknown;
+	found?: boolean;
+	config?: Record<string, unknown>;
+}
+interface ConfigStore {
+	get(key: string): {
+		value: unknown;
+		found: boolean;
+	} | Promise<{
+		value: unknown;
+		found: boolean;
+	}>;
+	set(key: string, value: unknown): void | Promise<void>;
+	list(): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+interface ConfigToolOptions {
+	/** Optional override for the config tool description. */
+	description?: string;
+	/** Initial config values when using the default in-memory store. */
+	initial?: Record<string, unknown>;
+	/** Custom config store implementation. */
+	store?: ConfigStore;
+}
+declare function defineConfigTool(options?: ConfigToolOptions): ToolDefinition<ConfigToolInput, ConfigToolResponse>;
+interface QueryToolInput {
+	q?: string | undefined;
+	query?: string | undefined;
+	limit?: number | undefined;
+	cursor?: string | undefined;
+	filters?: Record<string, unknown> | undefined;
+}
+interface QueryToolResponse<T = unknown> {
+	results: T[];
+	nextCursor?: string;
+	_meta?: Record<string, unknown>;
+}
+interface QueryToolOptions<T = unknown> {
+	/** Optional override for the query tool description. */
+	description?: string;
+	/** Custom query handler implementation. */
+	handler?: (input: NormalizedQueryInput, ctx: HandlerContext) => Promise<Result<QueryToolResponse<T>, OutfitterError>>;
+}
+declare function defineQueryTool<T = unknown>(options?: QueryToolOptions<T>): ToolDefinition<QueryToolInput, QueryToolResponse<T>>;
+interface CoreToolsOptions {
+	docs?: DocsToolOptions;
+	config?: ConfigToolOptions;
+	query?: QueryToolOptions;
+}
+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[];
+export { DocsSection, DocsToolInput, DocsToolEntry, DocsToolResponse, DocsToolOptions, defineDocsTool, ConfigAction, ConfigToolInput, ConfigToolResponse, ConfigStore, ConfigToolOptions, defineConfigTool, QueryToolInput, QueryToolResponse, QueryToolOptions, defineQueryTool, CoreToolsOptions, NormalizedQueryInput, CoreToolDefinition, createCoreTools };