@outfitter/mcp 0.2.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.

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,19 @@ 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.
@@ -560,6 +599,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
@@ -697,32 +746,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.

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);
@@ -367,6 +402,40 @@ function createNoOpLogger() {
     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();
@@ -376,6 +445,7 @@ function createMcpServer(options) {
   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 +822,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() {
@@ -969,39 +1054,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";

package/package.json

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