@outfitter/mcp 0.1.0-rc.1

package/dist/index.js

@@ -0,0 +1,787 @@
+// src/actions.ts
+import { DEFAULT_REGISTRY_SURFACES } from "@outfitter/contracts";
+
+// src/server.ts
+import { generateRequestId, Result } from "@outfitter/contracts";
+
+// src/schema.ts
+function zodToJsonSchema(schema) {
+  return convertZodType(schema);
+}
+function getDef(schemaOrDef) {
+  if (!schemaOrDef) {
+    return;
+  }
+  if (schemaOrDef._def) {
+    return schemaOrDef._def;
+  }
+  if (schemaOrDef.def) {
+    return schemaOrDef.def;
+  }
+  return schemaOrDef;
+}
+function getDescription(schema, def) {
+  if (typeof schema?.description === "string") {
+    return schema.description;
+  }
+  if (typeof def?.description === "string") {
+    return def.description;
+  }
+  return;
+}
+function convertZodType(schema) {
+  const def = getDef(schema);
+  if (!def) {
+    return {};
+  }
+  const typeName = def.typeName ?? def.type;
+  let jsonSchema;
+  switch (typeName) {
+    case "ZodString":
+    case "string":
+      jsonSchema = convertString(def);
+      break;
+    case "ZodNumber":
+    case "number":
+      jsonSchema = convertNumber(def);
+      break;
+    case "ZodBoolean":
+    case "boolean":
+      jsonSchema = { type: "boolean" };
+      break;
+    case "ZodNull":
+    case "null":
+      jsonSchema = { type: "null" };
+      break;
+    case "ZodUndefined":
+    case "undefined":
+      jsonSchema = {};
+      break;
+    case "ZodArray":
+    case "array":
+      jsonSchema = convertArray(def);
+      break;
+    case "ZodObject":
+    case "object":
+      jsonSchema = convertObject(def);
+      break;
+    case "ZodOptional":
+    case "optional":
+      jsonSchema = convertZodType(def.innerType);
+      break;
+    case "ZodNullable":
+    case "nullable":
+      jsonSchema = {
+        anyOf: [convertZodType(def.innerType), { type: "null" }]
+      };
+      break;
+    case "ZodDefault":
+    case "default": {
+      const defaultValue = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+      jsonSchema = {
+        ...convertZodType(def.innerType),
+        default: defaultValue
+      };
+      break;
+    }
+    case "ZodEnum":
+    case "enum": {
+      const values = def.values ?? Object.values(def.entries ?? {});
+      jsonSchema = {
+        type: "string",
+        enum: values
+      };
+      break;
+    }
+    case "ZodNativeEnum":
+      jsonSchema = {
+        enum: Object.values(def.values ?? def.entries ?? {})
+      };
+      break;
+    case "ZodLiteral":
+    case "literal": {
+      const literalValues = Array.isArray(def.values) ? def.values : [def.value].filter((value) => value !== undefined);
+      if (literalValues.length > 1) {
+        jsonSchema = {
+          enum: literalValues
+        };
+        break;
+      }
+      jsonSchema = literalValues.length ? {
+        const: literalValues[0]
+      } : {};
+      break;
+    }
+    case "ZodUnion":
+    case "union":
+      jsonSchema = {
+        anyOf: def.options.map(convertZodType)
+      };
+      break;
+    case "ZodIntersection":
+    case "intersection":
+      jsonSchema = {
+        allOf: [convertZodType(def.left), convertZodType(def.right)]
+      };
+      break;
+    case "ZodRecord":
+    case "record":
+      jsonSchema = {
+        type: "object",
+        additionalProperties: def.valueType ? convertZodType(def.valueType) : {}
+      };
+      break;
+    case "ZodTuple":
+    case "tuple":
+      jsonSchema = {
+        type: "array",
+        items: def.items.map(convertZodType)
+      };
+      break;
+    case "ZodAny":
+    case "any":
+      jsonSchema = {};
+      break;
+    case "ZodUnknown":
+    case "unknown":
+      jsonSchema = {};
+      break;
+    case "ZodVoid":
+    case "void":
+      jsonSchema = {};
+      break;
+    case "ZodNever":
+    case "never":
+      jsonSchema = { not: {} };
+      break;
+    case "ZodEffects":
+      jsonSchema = convertZodType(def.schema);
+      break;
+    case "ZodPipeline":
+    case "pipe": {
+      const outputDef = getDef(def.out);
+      const outputType = outputDef?.typeName ?? outputDef?.type;
+      jsonSchema = outputType === "transform" ? convertZodType(def.in) : convertZodType(def.out);
+      break;
+    }
+    case "ZodLazy":
+    case "lazy":
+      jsonSchema = {};
+      break;
+    default:
+      jsonSchema = {};
+      break;
+  }
+  const description = getDescription(schema, def);
+  if (description && !jsonSchema.description) {
+    jsonSchema.description = description;
+  }
+  return jsonSchema;
+}
+function convertString(def) {
+  const schema = { type: "string" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
+      if (normalizedCheck?.kind) {
+        switch (normalizedCheck.kind) {
+          case "min":
+            schema.minLength = normalizedCheck.value;
+            break;
+          case "max":
+            schema.maxLength = normalizedCheck.value;
+            break;
+          case "length":
+            schema.minLength = normalizedCheck.value;
+            schema.maxLength = normalizedCheck.value;
+            break;
+          case "email":
+            schema.pattern = "^[^@]+@[^@]+\\.[^@]+$";
+            break;
+          case "url":
+            schema.pattern = "^https?://";
+            break;
+          case "uuid":
+            schema.pattern = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
+            break;
+          case "regex":
+            schema.pattern = normalizedCheck.regex?.source ?? normalizedCheck.pattern?.source ?? (typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : undefined);
+            break;
+          default:
+            break;
+        }
+        continue;
+      }
+      if (!normalizedCheck?.check) {
+        continue;
+      }
+      switch (normalizedCheck.check) {
+        case "min_length":
+          schema.minLength = normalizedCheck.minimum;
+          break;
+        case "max_length":
+          schema.maxLength = normalizedCheck.maximum;
+          break;
+        case "string_format":
+          if (normalizedCheck.pattern) {
+            schema.pattern = typeof normalizedCheck.pattern === "string" ? normalizedCheck.pattern : normalizedCheck.pattern.source;
+          }
+          if (normalizedCheck.format && normalizedCheck.format !== "regex") {
+            schema.format = normalizedCheck.format;
+          }
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return schema;
+}
+function convertNumber(def) {
+  const schema = { type: "number" };
+  if (def.checks) {
+    for (const check of def.checks) {
+      const normalizedCheck = check?._zod?.def ?? check?.def ?? check;
+      if (normalizedCheck?.kind) {
+        switch (normalizedCheck.kind) {
+          case "min":
+            schema.minimum = normalizedCheck.value;
+            break;
+          case "max":
+            schema.maximum = normalizedCheck.value;
+            break;
+          case "int":
+            schema.type = "integer";
+            break;
+          default:
+            break;
+        }
+        continue;
+      }
+      if (!normalizedCheck?.check) {
+        continue;
+      }
+      switch (normalizedCheck.check) {
+        case "greater_than":
+          if (normalizedCheck.inclusive) {
+            schema.minimum = normalizedCheck.value;
+          } else {
+            schema.exclusiveMinimum = normalizedCheck.value;
+          }
+          break;
+        case "less_than":
+          if (normalizedCheck.inclusive) {
+            schema.maximum = normalizedCheck.value;
+          } else {
+            schema.exclusiveMaximum = normalizedCheck.value;
+          }
+          break;
+        case "number_format":
+          if (normalizedCheck.format === "int" || normalizedCheck.format === "safeint") {
+            schema.type = "integer";
+          }
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  return schema;
+}
+function convertArray(def) {
+  const element = def.element ?? def.type;
+  const schema = {
+    type: "array",
+    items: element ? convertZodType(element) : {}
+  };
+  return schema;
+}
+function isFieldOptional(fieldDef) {
+  if (!(fieldDef?.typeName || fieldDef?.type)) {
+    return false;
+  }
+  const typeName = fieldDef.typeName ?? fieldDef.type;
+  if (typeName === "ZodOptional" || typeName === "ZodDefault" || typeName === "optional" || typeName === "default") {
+    return true;
+  }
+  if (typeName === "ZodEffects") {
+    return isFieldOptional(getDef(fieldDef.schema));
+  }
+  if (typeName === "ZodPipeline" || typeName === "pipe") {
+    const inputOptional = isFieldOptional(getDef(fieldDef.in));
+    const outputDef = getDef(fieldDef.out);
+    const outputType = outputDef?.typeName ?? outputDef?.type;
+    if (outputType === "transform") {
+      return inputOptional;
+    }
+    const outputOptional = isFieldOptional(outputDef);
+    return inputOptional && outputOptional;
+  }
+  if (typeName === "ZodNullable" || typeName === "nullable") {
+    return isFieldOptional(getDef(fieldDef.innerType));
+  }
+  return false;
+}
+function convertObject(def) {
+  const properties = {};
+  const required = [];
+  const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+  for (const [key, value] of Object.entries(shape ?? {})) {
+    properties[key] = convertZodType(value);
+    const fieldDef = getDef(value);
+    if (!isFieldOptional(fieldDef)) {
+      required.push(key);
+    }
+  }
+  const schema = {
+    type: "object",
+    properties
+  };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+// src/types.ts
+import {
+  TaggedError as TaggedErrorImpl
+} from "@outfitter/contracts";
+import { TaggedError } from "@outfitter/contracts";
+var TaggedError2 = TaggedErrorImpl;
+var McpErrorBase = TaggedError2("McpError")();
+
+class McpError extends McpErrorBase {
+  category = "internal";
+}
+
+// src/server.ts
+function createNoOpLogger() {
+  const noop = () => {};
+  return {
+    trace: noop,
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    child: () => createNoOpLogger()
+  };
+}
+function createMcpServer(options) {
+  const { name, version, logger: providedLogger } = options;
+  const logger = providedLogger ?? createNoOpLogger();
+  const tools = new Map;
+  const resources = [];
+  function createHandlerContext(toolName, requestId, signal) {
+    const ctx = {
+      requestId,
+      logger: logger.child({ tool: toolName, requestId }),
+      cwd: process.cwd(),
+      env: process.env
+    };
+    if (signal !== undefined) {
+      ctx.signal = signal;
+    }
+    return ctx;
+  }
+  function translateError(error) {
+    const codeMap = {
+      validation: -32602,
+      not_found: -32601,
+      permission: -32600,
+      internal: -32603,
+      timeout: -32603,
+      network: -32603,
+      rate_limit: -32603,
+      auth: -32600,
+      conflict: -32603,
+      cancelled: -32603
+    };
+    const code = codeMap[error.category] ?? -32603;
+    return new McpError({
+      message: error.message,
+      code,
+      context: {
+        originalTag: error._tag,
+        category: error.category
+      }
+    });
+  }
+  const server = {
+    name,
+    version,
+    registerTool(tool) {
+      logger.debug("Registering tool", { name: tool.name });
+      const description = tool.description?.trim() ?? "";
+      if (description.length < 8) {
+        logger.warn("Tool description may be too short for search discovery", {
+          name: tool.name,
+          description
+        });
+      }
+      const jsonSchema = zodToJsonSchema(tool.inputSchema);
+      const handler = (input, ctx) => tool.handler(input, ctx);
+      const deferLoading = tool.deferLoading ?? true;
+      tools.set(tool.name, {
+        name: tool.name,
+        description,
+        inputSchema: jsonSchema,
+        deferLoading,
+        handler,
+        zodSchema: tool.inputSchema
+      });
+      logger.info("Tool registered", { name: tool.name });
+    },
+    registerResource(resource) {
+      logger.debug("Registering resource", {
+        uri: resource.uri,
+        name: resource.name
+      });
+      resources.push(resource);
+      logger.info("Resource registered", { uri: resource.uri });
+    },
+    getTools() {
+      return Array.from(tools.values()).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        defer_loading: tool.deferLoading
+      }));
+    },
+    getResources() {
+      return [...resources];
+    },
+    async invokeTool(toolName, input, invokeOptions) {
+      const requestId = invokeOptions?.requestId ?? generateRequestId();
+      logger.debug("Invoking tool", { tool: toolName, requestId });
+      const tool = tools.get(toolName);
+      if (!tool) {
+        logger.warn("Tool not found", { tool: toolName, requestId });
+        return Result.err(new McpError({
+          message: `Tool not found: ${toolName}`,
+          code: -32601,
+          context: { tool: toolName }
+        }));
+      }
+      const parseResult = tool.zodSchema.safeParse(input);
+      if (!parseResult.success) {
+        const errorMessages = parseResult.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+        logger.warn("Input validation failed", {
+          tool: toolName,
+          requestId,
+          errors: errorMessages
+        });
+        return Result.err(new McpError({
+          message: `Invalid input: ${errorMessages}`,
+          code: -32602,
+          context: {
+            tool: toolName,
+            validationErrors: parseResult.error.issues
+          }
+        }));
+      }
+      const ctx = createHandlerContext(toolName, requestId, invokeOptions?.signal);
+      try {
+        const result = await tool.handler(parseResult.data, ctx);
+        if (result.isErr()) {
+          logger.debug("Tool returned error", {
+            tool: toolName,
+            requestId,
+            error: result.error._tag
+          });
+          return Result.err(translateError(result.error));
+        }
+        logger.debug("Tool completed successfully", {
+          tool: toolName,
+          requestId
+        });
+        return Result.ok(result.value);
+      } catch (error) {
+        logger.error("Tool threw exception", {
+          tool: toolName,
+          requestId,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return Result.err(new McpError({
+          message: error instanceof Error ? error.message : "Unknown error",
+          code: -32603,
+          context: {
+            tool: toolName,
+            thrown: true
+          }
+        }));
+      }
+    },
+    async start() {
+      logger.info("MCP server starting", { name, version, tools: tools.size });
+    },
+    async stop() {
+      logger.info("MCP server stopping", { name, version });
+    }
+  };
+  return server;
+}
+function defineTool(definition) {
+  return definition;
+}
+function defineResource(definition) {
+  return definition;
+}
+
+// src/actions.ts
+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 } : {}
+  }));
+}
+// src/core-tools.ts
+import { Result as Result2, 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 Result2.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 Result2.ok({ action: "list", config });
+        }
+        case "get": {
+          if (!input.key) {
+            return Result2.err(new ValidationError({
+              message: "Config key is required for action 'get'.",
+              field: "key"
+            }));
+          }
+          const { value, found } = await store.get(input.key);
+          return Result2.ok({ action: "get", key: input.key, value, found });
+        }
+        case "set": {
+          if (!input.key) {
+            return Result2.err(new ValidationError({
+              message: "Config key is required for action 'set'.",
+              field: "key"
+            }));
+          }
+          await store.set(input.key, input.value);
+          return Result2.ok({
+            action: "set",
+            key: input.key,
+            value: input.value
+          });
+        }
+        default:
+          return Result2.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(Result2.ok({
+        results: [],
+        _meta: {
+          note: "No query handler configured."
+        }
+      }));
+    }
+  };
+}
+function createCoreTools(options = {}) {
+  return [
+    defineDocsTool(options.docs),
+    defineConfigTool(options.config),
+    defineQueryTool(options.query)
+  ];
+}
+// src/transport.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { safeStringify } from "@outfitter/contracts";
+function isMcpToolResponse(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const content = value.content;
+  return Array.isArray(content);
+}
+function toTextPayload(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  return safeStringify(value);
+}
+function serializeError(error) {
+  if (error && typeof error === "object") {
+    const record = error;
+    return {
+      _tag: record._tag ?? "McpError",
+      message: record.message ?? "Unknown error",
+      code: record.code,
+      context: record.context
+    };
+  }
+  return {
+    _tag: "McpError",
+    message: String(error)
+  };
+}
+function wrapToolResult(value) {
+  if (isMcpToolResponse(value)) {
+    return value;
+  }
+  const structuredContent = value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+  return {
+    content: [
+      {
+        type: "text",
+        text: toTextPayload(value)
+      }
+    ],
+    ...structuredContent ? { structuredContent } : {}
+  };
+}
+function wrapToolError(error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: toTextPayload(serializeError(error))
+      }
+    ],
+    isError: true
+  };
+}
+function createSdkServer(server) {
+  const sdkServer = new Server({ name: server.name, version: server.version }, { capabilities: { tools: {} } });
+  sdkServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: server.getTools()
+  }));
+  sdkServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await server.invokeTool(name, args ?? {});
+    if (result.isErr()) {
+      return wrapToolError(result.error);
+    }
+    return wrapToolResult(result.value);
+  });
+  return sdkServer;
+}
+async function connectStdio(server, transport = new StdioServerTransport) {
+  const sdkServer = createSdkServer(server);
+  await sdkServer.connect(transport);
+  return sdkServer;
+}
+export {
+  zodToJsonSchema,
+  defineTool,
+  defineResource,
+  defineQueryTool,
+  defineDocsTool,
+  defineConfigTool,
+  createSdkServer,
+  createMcpServer,
+  createCoreTools,
+  connectStdio,
+  buildMcpTools,
+  McpError
+};