@outfitter/mcp 0.4.2 → 0.5.0

package/README.md

@@ -54,9 +54,9 @@ 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 (BYO)
+  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
 }
 
@@ -140,6 +140,7 @@ const server = createMcpServer({
 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)
@@ -176,11 +177,11 @@ Helper for defining typed tools with better type inference.
 
 ```typescript
 interface ToolDefinition<TInput, TOutput, TError> {
-  name: string;                    // Unique tool name (kebab-case)
-  description: string;             // Human-readable description
-  inputSchema: z.ZodType<TInput>;  // Zod schema for validation
+  name: string; // Unique tool name (kebab-case)
+  description: string; // Human-readable description
+  inputSchema: z.ZodType<TInput>; // Zod schema for validation
   handler: Handler<TInput, TOutput, TError>;
-  deferLoading?: boolean;          // Default: true
+  deferLoading?: boolean; // Default: true
 }
 
 const getUserTool = defineTool({
@@ -203,10 +204,10 @@ Helper for defining MCP resources.
 
 ```typescript
 interface ResourceDefinition {
-  uri: string;           // Unique resource URI
-  name: string;          // Human-readable name
-  description?: string;  // Optional description
-  mimeType?: string;     // Content MIME type
+  uri: string; // Unique resource URI
+  name: string; // Human-readable name
+  description?: string; // Optional description
+  mimeType?: string; // Content MIME type
   handler?: ResourceReadHandler; // Optional resources/read handler
 }
 
@@ -236,6 +237,47 @@ server.registerResource(configResource);
 const contentResult = await server.readResource("file:///etc/app/config.json");
 ```
 
+### defineResourceTemplate(definition)
+
+Helper for defining MCP resource templates with URI pattern matching and optional Zod validation.
+
+```typescript
+import { defineResourceTemplate } from "@outfitter/mcp";
+import { z } from "zod";
+
+// Basic template with string variables
+const userTemplate = defineResourceTemplate({
+  uriTemplate: "db:///users/{userId}/profile",
+  name: "User Profile",
+  handler: async (uri, variables, ctx) => {
+    const profile = await getProfile(variables.userId);
+    return Result.ok([
+      { uri, text: JSON.stringify(profile), mimeType: "application/json" },
+    ]);
+  },
+});
+
+// Typed template with Zod validation and coercion
+const postTemplate = defineResourceTemplate({
+  uriTemplate: "db:///users/{userId}/posts/{postId}",
+  name: "User Post",
+  paramSchema: z.object({
+    userId: z.string().min(1),
+    postId: z.coerce.number().int().positive(),
+  }),
+  handler: async (uri, params, ctx) => {
+    // params is { userId: string; postId: number } — validated and coerced
+    const post = await getPost(params.userId, params.postId);
+    return Result.ok([{ uri, text: JSON.stringify(post) }]);
+  },
+});
+
+server.registerResourceTemplate(userTemplate);
+server.registerResourceTemplate(postTemplate);
+```
+
+Templates use RFC 6570 Level 1 URI templates (`{param}` placeholders). Typed templates validate extracted variables against a Zod schema before handler invocation.
+
 ### Server Methods
 
 ```typescript
@@ -255,7 +297,11 @@ interface McpServer {
 
   // Invocation
   readResource(uri: string): Promise<Result<ResourceContent[], McpError>>;
-  invokeTool<T>(name: string, input: unknown, options?: InvokeToolOptions): Promise<Result<T, McpError>>;
+  invokeTool<T>(
+    name: string,
+    input: unknown,
+    options?: InvokeToolOptions
+  ): Promise<Result<T, McpError>>;
 
   // Lifecycle
   start(): Promise<void>;
@@ -269,10 +315,61 @@ Extended handler context for MCP tools with additional metadata:
 
 ```typescript
 interface McpHandlerContext extends HandlerContext {
-  toolName?: string;  // Name of the tool being invoked
+  toolName?: string; // Name of the tool being invoked
 }
 ```
 
+## Streaming and Progress (`@outfitter/mcp/progress`)
+
+When an MCP client provides a `progressToken` in the tool call params, the server automatically creates a progress callback and injects it into the handler context as `ctx.progress`. Each call emits a `notifications/progress` notification.
+
+```typescript
+const tool = defineTool({
+  name: "index-files",
+  description: "Index workspace files",
+  inputSchema: z.object({ path: z.string() }),
+  handler: async (input, ctx) => {
+    const files = await listFiles(input.path);
+
+    for (let i = 0; i < files.length; i++) {
+      await indexFile(files[i]);
+      ctx.progress?.({ type: "progress", current: i + 1, total: files.length });
+    }
+
+    ctx.progress?.({
+      type: "step",
+      name: "complete",
+      status: "complete",
+      duration_ms: 150,
+    });
+
+    return Result.ok({ indexed: files.length });
+  },
+});
+```
+
+Use optional chaining (`ctx.progress?.()`) so the handler works whether or not the client requested progress tracking. Without a `progressToken`, `ctx.progress` is `undefined` and no notifications are sent.
+
+**Event mapping to MCP notifications:**
+
+| StreamEvent type | MCP `progress` | MCP `total` | MCP `message`             |
+| ---------------- | -------------- | ----------- | ------------------------- |
+| `start`          | `0`            | --          | `[start] {command}`       |
+| `step`           | `0`            | --          | `[step] {name}: {status}` |
+| `progress`       | `current`      | `total`     | `message` (if provided)   |
+
+The progress callback uses the same `StreamEvent` types from `@outfitter/contracts/stream` as the CLI NDJSON adapter, keeping handlers transport-agnostic.
+
+**Programmatic usage** (for custom transport layers):
+
+```typescript
+import { createMcpProgressCallback } from "@outfitter/mcp/progress";
+
+const progress = createMcpProgressCallback("tok-123", (notification) =>
+  sdkServer.notification(notification)
+);
+```
+
 ## Core Tools
 
 Pre-built tools for common MCP patterns. These are marked with `deferLoading: false` for immediate availability.
@@ -372,7 +469,9 @@ const listTool = defineTool({
   description: "List all items",
   inputSchema: z.object({}),
   annotations: TOOL_ANNOTATIONS.readOnly,
-  handler: async (input, ctx) => { /* ... */ },
+  handler: async (input, ctx) => {
+    /* ... */
+  },
 });
 
 // Spread and override for edge cases
@@ -381,17 +480,19 @@ const searchTool = defineTool({
   description: "Search external APIs",
   inputSchema: z.object({ q: z.string() }),
   annotations: { ...TOOL_ANNOTATIONS.readOnly, openWorldHint: true },
-  handler: async (input, ctx) => { /* ... */ },
+  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 |
+| 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.
 
@@ -454,12 +555,12 @@ const { server: sdkServer, toolsList, callTool } = createSdkServer(mcpServer);
 
 Tools return Results with typed errors. The framework automatically translates `OutfitterError` categories to JSON-RPC error codes:
 
-| Category | JSON-RPC Code | Description |
-|----------|--------------|-------------|
-| `validation` | -32602 | Invalid params |
-| `not_found` | -32601 | Method not found |
-| `permission` | -32600 | Invalid request |
-| `internal` | -32603 | Internal error |
+| Category     | JSON-RPC Code | Description      |
+| ------------ | ------------- | ---------------- |
+| `validation` | -32602        | Invalid params   |
+| `not_found`  | -32601        | Method not found |
+| `permission` | -32600        | Invalid request  |
+| `internal`   | -32603        | Internal error   |
 
 ```typescript
 const result = await server.invokeTool("get-user", { userId: "123" });
@@ -523,6 +624,7 @@ Add your MCP server to Claude Desktop:
 ```
 
 Config location:
+
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/claude/claude_desktop_config.json`

package/dist/actions.d.ts

@@ -1,4 +1,9 @@
-import { BuildMcpToolsOptions, buildMcpTools } from "./shared/@outfitter/mcp-5jcgb033.js";
-import "./shared/@outfitter/mcp-fks4zt1z.js";
+import { BuildMcpToolsOptions, buildMcpTools } from "./shared/@outfitter/mcp-f67dnr72.js";
+import "./shared/@outfitter/mcp-qmdmgxa1.js";
+import "./shared/@outfitter/mcp-7btcghjj.js";
+import "./shared/@outfitter/mcp-knc1gq0g.js";
+import "./shared/@outfitter/mcp-9ry52yg3.js";
+import "./shared/@outfitter/mcp-dgwj3jna.js";
+import "./shared/@outfitter/mcp-q5hr7227.js";
 import "./shared/@outfitter/mcp-cqpyer9m.js";
 export { buildMcpTools, BuildMcpToolsOptions };

package/dist/actions.js

@@ -1,11 +1,58 @@
 // @bun
 import {
-  buildMcpTools
-} from "./shared/@outfitter/mcp-zmc7ht6z.js";
-import"./shared/@outfitter/mcp-hh12tqfg.js";
+  defineTool
+} from "./shared/@outfitter/mcp-yf1n85e9.js";
+import"./shared/@outfitter/mcp-n9vzcp37.js";
+import"./shared/@outfitter/mcp-zt2s3r38.js";
+import"./shared/@outfitter/mcp-q70dtfj6.js";
 import"./shared/@outfitter/mcp-fjtxsa0x.js";
-import"./shared/@outfitter/mcp-zy7b487d.js";
-import"./shared/@outfitter/mcp-9m5hs2z0.js";
+import"./shared/@outfitter/mcp-s2vnhzav.js";
+import"./shared/@outfitter/mcp-hw5wz4gb.js";
+
+// packages/mcp/src/actions.ts
+import { DEFAULT_REGISTRY_SURFACES } from "@outfitter/contracts";
+function isActionRegistry(source) {
+  return "list" in source;
+}
+function buildAnnotations(mcp) {
+  if (!mcp)
+    return;
+  const annotations = {};
+  let hasAnnotation = false;
+  if (mcp.readOnly === true) {
+    annotations["readOnlyHint"] = true;
+    hasAnnotation = true;
+  }
+  if (mcp.idempotent === true) {
+    annotations["idempotentHint"] = true;
+    hasAnnotation = true;
+  }
+  if (mcp.destructive === true) {
+    annotations["destructiveHint"] = true;
+    hasAnnotation = true;
+  }
+  return hasAnnotation ? annotations : undefined;
+}
+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) => {
+    const annotations = buildAnnotations(action.mcp);
+    return 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 } : {},
+      ...annotations ? { annotations } : {}
+    });
+  });
+}
 export {
   buildMcpTools
 };

package/dist/core-tools.d.ts

@@ -1,4 +1,9 @@
-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-zb3p61y9.js";
-import "./shared/@outfitter/mcp-fks4zt1z.js";
+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-4s22693j.js";
+import "./shared/@outfitter/mcp-qmdmgxa1.js";
+import "./shared/@outfitter/mcp-7btcghjj.js";
+import "./shared/@outfitter/mcp-knc1gq0g.js";
+import "./shared/@outfitter/mcp-9ry52yg3.js";
+import "./shared/@outfitter/mcp-dgwj3jna.js";
+import "./shared/@outfitter/mcp-q5hr7227.js";
 import "./shared/@outfitter/mcp-cqpyer9m.js";
 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

@@ -1,10 +1,144 @@
 // @bun
-import {
-  createCoreTools,
-  defineConfigTool,
-  defineDocsTool,
-  defineQueryTool
-} from "./shared/@outfitter/mcp-zv3ej45k.js";
+// packages/mcp/src/core-tools.ts
+import { Result, ValidationError } from "@outfitter/contracts";
+import { z } from "zod";
+var DEFAULT_DOCS = {
+  overview: "No documentation configured yet.",
+  tools: [],
+  examples: [],
+  schemas: {}
+};
+var docsSchema = z.object({
+  section: z.enum(["overview", "tools", "examples", "schemas"]).optional()
+});
+function pickDocsSection(payload, section) {
+  if (!section) {
+    return payload;
+  }
+  return {
+    [section]: payload[section]
+  };
+}
+function defineDocsTool(options = {}) {
+  return {
+    name: "docs",
+    description: options.description ?? "Documentation, usage patterns, and examples for this MCP server.",
+    deferLoading: false,
+    inputSchema: docsSchema,
+    handler: async (input) => {
+      const payload = options.getDocs ? await options.getDocs(input.section) : options.docs ?? DEFAULT_DOCS;
+      return Result.ok(pickDocsSection(payload, input.section));
+    }
+  };
+}
+var configSchema = z.object({
+  action: z.enum(["get", "set", "list"]),
+  key: z.string().optional(),
+  value: z.unknown().optional()
+});
+function createInMemoryStore(initial = {}) {
+  const store = new Map(Object.entries(initial));
+  return {
+    get(key) {
+      return { value: store.get(key), found: store.has(key) };
+    },
+    set(key, value) {
+      store.set(key, value);
+    },
+    list() {
+      return Object.fromEntries(store.entries());
+    }
+  };
+}
+function defineConfigTool(options = {}) {
+  const store = options.store ?? createInMemoryStore(options.initial);
+  return {
+    name: "config",
+    description: options.description ?? "Read or modify server configuration values.",
+    deferLoading: false,
+    inputSchema: configSchema,
+    handler: async (input) => {
+      switch (input.action) {
+        case "list": {
+          const config = await store.list();
+          return Result.ok({ action: "list", config });
+        }
+        case "get": {
+          if (!input.key) {
+            return Result.err(new ValidationError({
+              message: "Config key is required for action 'get'.",
+              field: "key"
+            }));
+          }
+          const { value, found } = await store.get(input.key);
+          return Result.ok({ action: "get", key: input.key, value, found });
+        }
+        case "set": {
+          if (!input.key) {
+            return Result.err(new ValidationError({
+              message: "Config key is required for action 'set'.",
+              field: "key"
+            }));
+          }
+          await store.set(input.key, input.value);
+          return Result.ok({
+            action: "set",
+            key: input.key,
+            value: input.value
+          });
+        }
+        default:
+          return Result.err(new ValidationError({
+            message: `Unknown action: ${input.action}`,
+            field: "action"
+          }));
+      }
+    }
+  };
+}
+var querySchema = z.object({
+  q: z.string().min(1).describe("Search query. Supports natural language or filter syntax.").optional(),
+  query: z.string().min(1).describe("Alias for q. Supports natural language or filter syntax.").optional(),
+  limit: z.number().int().positive().optional(),
+  cursor: z.string().optional(),
+  filters: z.record(z.string(), z.unknown()).optional()
+}).refine((value) => {
+  const queryValue = (value.q ?? value.query)?.trim();
+  return typeof queryValue === "string" && queryValue.length > 0;
+}, {
+  message: "Query is required.",
+  path: ["q"]
+});
+function defineQueryTool(options = {}) {
+  return {
+    name: "query",
+    description: options.description ?? "Search and discover resources with filters and pagination.",
+    deferLoading: false,
+    inputSchema: querySchema,
+    handler: (input, ctx) => {
+      const normalized = {
+        ...input,
+        q: (input.q ?? input.query ?? "").trim()
+      };
+      if (options.handler) {
+        return options.handler(normalized, ctx);
+      }
+      return Promise.resolve(Result.ok({
+        results: [],
+        _meta: {
+          note: "No query handler configured."
+        }
+      }));
+    }
+  };
+}
+function createCoreTools(options = {}) {
+  return [
+    defineDocsTool(options.docs),
+    defineConfigTool(options.config),
+    defineQueryTool(options.query)
+  ];
+}
 export {
   defineQueryTool,
   defineDocsTool,