@outfitter/mcp 0.4.1 → 0.4.3

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
 }
 
@@ -255,7 +256,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,7 +274,7 @@ 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
 }
 ```
 
@@ -372,7 +377,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 +388,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 +463,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,13 +532,14 @@ 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`
 
 ## 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.
+Run `outfitter upgrade --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
 

package/dist/actions.d.ts

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

package/dist/actions.js

@@ -1,11 +1,32 @@
 // @bun
 import {
-  buildMcpTools
-} from "./shared/@outfitter/mcp-ktapzh9d.js";
-import"./shared/@outfitter/mcp-nmp5wf0w.js";
+  defineTool
+} from "./shared/@outfitter/mcp-b502y16n.js";
 import"./shared/@outfitter/mcp-fjtxsa0x.js";
 import"./shared/@outfitter/mcp-9m5hs2z0.js";
-import"./shared/@outfitter/mcp-zy7b487d.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 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/core-tools.d.ts

@@ -1,4 +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";
+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-s6afm4ff.js";
+import "./shared/@outfitter/mcp-gqjg15f5.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,