webmcp-codegen 0.0.1 → 0.1.0

package/dist/sources/index.js

@@ -0,0 +1,139 @@
+import {
+  nameFromRoute,
+  toToolName
+} from "../chunk-BIKKPCRT.js";
+import {
+  deepDeref,
+  deref,
+  pascalCase
+} from "../chunk-5L4KN6F4.js";
+
+// src/sources/openapi.ts
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { parse as parseYaml } from "yaml";
+var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+function openapi(options) {
+  return {
+    kind: "openapi",
+    async collect() {
+      const specPath = resolve(process.cwd(), options.spec);
+      const spec = await readSpec(specPath);
+      return operationsFromSpec(spec);
+    }
+  };
+}
+async function readSpec(specPath) {
+  let text;
+  try {
+    text = await readFile(specPath, "utf8");
+  } catch {
+    throw new Error(
+      `Could not read the OpenAPI spec at "${specPath}". Check the "spec" path in codegen.config.`
+    );
+  }
+  return parseYaml(text);
+}
+function operationsFromSpec(spec) {
+  const root = spec;
+  const paths = root.paths ?? {};
+  const rootSecurity = Array.isArray(root.security) && root.security.length > 0;
+  const candidates = [];
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const sharedParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const upperMethod = method.toUpperCase();
+      const ref = `${upperMethod} ${path}`;
+      const name = typeof operation.operationId === "string" && operation.operationId.length > 0 ? toToolName(operation.operationId) : nameFromRoute(method, path);
+      const opSecurity = operation.security;
+      const requiresAuth = Array.isArray(opSecurity) ? opSecurity.length > 0 : rootSecurity;
+      candidates.push({
+        id: ref,
+        name,
+        source: { kind: "openapi", ref },
+        inputSchema: buildInputSchema(operation, sharedParams, spec),
+        outputSchema: findOutputSchema(operation, spec),
+        inputTypeName: `${pascalCase(name)}Input`,
+        httpMethod: upperMethod,
+        // The safety layer refines this — the source only reports the verb.
+        sideEffect: "unknown",
+        requiresAuth,
+        description: pickDescription(operation, upperMethod ?? method.toUpperCase(), path),
+        descriptionSource: typeof operation.summary === "string" || typeof operation.description === "string" ? "openapi-summary" : "generated-template"
+      });
+    }
+  }
+  if (candidates.length === 0) {
+    throw new Error('The OpenAPI spec has no operations under "paths". Nothing to generate.');
+  }
+  return candidates;
+}
+function buildInputSchema(operation, sharedParams, spec) {
+  const properties = {};
+  const required = /* @__PURE__ */ new Set();
+  const parameters = [
+    ...sharedParams,
+    ...Array.isArray(operation.parameters) ? operation.parameters : []
+  ];
+  for (const rawParam of parameters) {
+    const param = deref(rawParam, spec);
+    if (param.in !== "path" && param.in !== "query") continue;
+    if (typeof param.name !== "string") continue;
+    const fieldSchema = param.schema ? deepDeref(param.schema, spec) : { type: "string" };
+    properties[param.name] = typeof param.description === "string" ? { ...fieldSchema, description: param.description } : fieldSchema;
+    if (param.in === "path" || param.required === true) required.add(param.name);
+  }
+  const body = extractJsonBody(operation.requestBody, spec);
+  if (body) {
+    if (body.schema.type === "object" || body.schema.properties) {
+      for (const [key, value] of Object.entries(body.schema.properties ?? {})) {
+        properties[key] = value;
+      }
+      if (body.required) {
+        for (const key of body.schema.required ?? []) required.add(key);
+      }
+    } else {
+      properties.body = body.schema;
+      if (body.required) required.add("body");
+    }
+  }
+  return { type: "object", properties, required: [...required] };
+}
+function extractJsonBody(requestBody, spec) {
+  if (!requestBody || typeof requestBody !== "object") return void 0;
+  const body = deref(requestBody, spec);
+  const content = body.content;
+  const jsonEntry = content?.["application/json"] ?? Object.entries(content ?? {}).find(([mediaType]) => mediaType.endsWith("+json"))?.[1];
+  if (!jsonEntry?.schema) return void 0;
+  return {
+    schema: deepDeref(jsonEntry.schema, spec),
+    required: body.required === true
+  };
+}
+function findOutputSchema(operation, spec) {
+  const responses = operation.responses;
+  if (!responses) return void 0;
+  for (const [status, rawResponse] of Object.entries(responses)) {
+    if (!status.startsWith("2")) continue;
+    const response = deref(rawResponse, spec);
+    const content = response.content;
+    const jsonEntry = content?.["application/json"] ?? Object.entries(content ?? {}).find(([mediaType]) => mediaType.endsWith("+json"))?.[1];
+    if (jsonEntry?.schema) return deepDeref(jsonEntry.schema, spec);
+  }
+  return void 0;
+}
+function pickDescription(operation, method, path) {
+  if (typeof operation.summary === "string" && operation.summary.trim().length > 0) {
+    return operation.summary.trim();
+  }
+  if (typeof operation.description === "string" && operation.description.trim().length > 0) {
+    return operation.description.trim().split("\n")[0];
+  }
+  return `${method} ${path}`;
+}
+export {
+  openapi
+};
+//# sourceMappingURL=index.js.map

package/dist/sources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sources/openapi.ts"],"sourcesContent":["/**\n * The OpenAPI source.\n *\n * Reads an OpenAPI 3.x document (YAML or JSON) and turns every operation\n * into a CandidateTool. This is the highest-reach source: most backend\n * frameworks can already emit an OpenAPI spec, so teams get value without\n * changing any application code.\n *\n * What we read from each operation:\n *   - name        ← operationId, slugified (falls back to method + path)\n *   - description ← summary, else the first line of description, else a template\n *   - inputSchema ← path + query parameters merged with the JSON request body\n *   - outputSchema ← the first 2xx response's JSON schema, when present\n *\n * Header and cookie parameters are skipped on purpose: agents should not be\n * setting those by hand, and auth headers are the app's job, not the tool's.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { parse as parseYaml } from \"yaml\";\nimport { nameFromRoute, toToolName } from \"../naming.js\";\nimport { deepDeref, deref, pascalCase } from \"../schema.js\";\nimport type { CandidateTool, JsonSchema, Source } from \"../types.js\";\n\nexport interface OpenApiSourceOptions {\n  /** Path to the OpenAPI document, relative to the project root. */\n  spec: string;\n}\n\nconst HTTP_METHODS = [\"get\", \"post\", \"put\", \"patch\", \"delete\", \"head\", \"options\"] as const;\n\n/** Create an OpenAPI source for the config's `sources` array. */\nexport function openapi(options: OpenApiSourceOptions): Source {\n  return {\n    kind: \"openapi\",\n    async collect() {\n      const specPath = resolve(process.cwd(), options.spec);\n      const spec = await readSpec(specPath);\n      return operationsFromSpec(spec);\n    },\n  };\n}\n\nasync function readSpec(specPath: string): Promise<unknown> {\n  let text: string;\n  try {\n    text = await readFile(specPath, \"utf8\");\n  } catch {\n    throw new Error(\n      `Could not read the OpenAPI spec at \"${specPath}\". Check the \"spec\" path in codegen.config.`,\n    );\n  }\n  // YAML is a superset of JSON, so one parser handles both file types.\n  return parseYaml(text);\n}\n\nfunction operationsFromSpec(spec: unknown): CandidateTool[] {\n  const root = spec as Record<string, unknown>;\n  const paths = (root.paths ?? {}) as Record<string, Record<string, unknown>>;\n  const rootSecurity = Array.isArray(root.security) && root.security.length > 0;\n  const candidates: CandidateTool[] = [];\n\n  for (const [path, pathItem] of Object.entries(paths)) {\n    // Parameters declared on the path item apply to every operation under it.\n    const sharedParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];\n\n    for (const method of HTTP_METHODS) {\n      const operation = pathItem[method] as Record<string, unknown> | undefined;\n      if (!operation) continue;\n\n      const upperMethod = method.toUpperCase() as CandidateTool[\"httpMethod\"];\n      const ref = `${upperMethod} ${path}`;\n      const name =\n        typeof operation.operationId === \"string\" && operation.operationId.length > 0\n          ? toToolName(operation.operationId)\n          : nameFromRoute(method, path);\n\n      const opSecurity = operation.security;\n      const requiresAuth = Array.isArray(opSecurity) ? opSecurity.length > 0 : rootSecurity;\n\n      candidates.push({\n        id: ref,\n        name,\n        source: { kind: \"openapi\", ref },\n        inputSchema: buildInputSchema(operation, sharedParams, spec),\n        outputSchema: findOutputSchema(operation, spec),\n        inputTypeName: `${pascalCase(name)}Input`,\n        httpMethod: upperMethod,\n        // The safety layer refines this — the source only reports the verb.\n        sideEffect: \"unknown\",\n        requiresAuth,\n        description: pickDescription(operation, upperMethod ?? method.toUpperCase(), path),\n        descriptionSource:\n          typeof operation.summary === \"string\" || typeof operation.description === \"string\"\n            ? \"openapi-summary\"\n            : \"generated-template\",\n      });\n    }\n  }\n\n  if (candidates.length === 0) {\n    throw new Error('The OpenAPI spec has no operations under \"paths\". Nothing to generate.');\n  }\n  return candidates;\n}\n\n/**\n * Merge path + query parameters and the JSON request body into one object\n * schema — that single object is what the agent fills in when calling the tool.\n */\nfunction buildInputSchema(\n  operation: Record<string, unknown>,\n  sharedParams: unknown[],\n  spec: unknown,\n): JsonSchema {\n  const properties: Record<string, JsonSchema> = {};\n  const required = new Set<string>();\n\n  const parameters = [\n    ...sharedParams,\n    ...(Array.isArray(operation.parameters) ? operation.parameters : []),\n  ];\n\n  for (const rawParam of parameters) {\n    const param = deref(rawParam as JsonSchema, spec) as Record<string, unknown>;\n    // Headers and cookies are transport concerns, not tool inputs.\n    if (param.in !== \"path\" && param.in !== \"query\") continue;\n    if (typeof param.name !== \"string\") continue;\n\n    const fieldSchema = param.schema\n      ? deepDeref(param.schema as JsonSchema, spec)\n      : { type: \"string\" };\n    properties[param.name] =\n      typeof param.description === \"string\"\n        ? { ...fieldSchema, description: param.description }\n        : fieldSchema;\n    // Path params are always required by definition; query params say so.\n    if (param.in === \"path\" || param.required === true) required.add(param.name);\n  }\n\n  const body = extractJsonBody(operation.requestBody, spec);\n  if (body) {\n    if (body.schema.type === \"object\" || body.schema.properties) {\n      // The common case: an object body flattens into the tool input.\n      for (const [key, value] of Object.entries(body.schema.properties ?? {})) {\n        properties[key] = value;\n      }\n      if (body.required) {\n        for (const key of body.schema.required ?? []) required.add(key);\n      }\n    } else {\n      // A non-object body (array, raw string, …) goes under a \"body\" field.\n      properties.body = body.schema;\n      if (body.required) required.add(\"body\");\n    }\n  }\n\n  return { type: \"object\", properties, required: [...required] };\n}\n\n/** Find the operation's JSON request body schema, if it declares one. */\nfunction extractJsonBody(\n  requestBody: unknown,\n  spec: unknown,\n): { schema: JsonSchema; required: boolean } | undefined {\n  if (!requestBody || typeof requestBody !== \"object\") return undefined;\n  const body = deref(requestBody as JsonSchema, spec) as Record<string, unknown>;\n  const content = body.content as Record<string, { schema?: JsonSchema }> | undefined;\n  // Prefer application/json; accept any \"+json\" media type as a fallback.\n  const jsonEntry =\n    content?.[\"application/json\"] ??\n    Object.entries(content ?? {}).find(([mediaType]) => mediaType.endsWith(\"+json\"))?.[1];\n  if (!jsonEntry?.schema) return undefined;\n  return {\n    schema: deepDeref(jsonEntry.schema, spec),\n    required: body.required === true,\n  };\n}\n\n/** The response contract, used by the safety layer's PII scan (and later, docs). */\nfunction findOutputSchema(\n  operation: Record<string, unknown>,\n  spec: unknown,\n): JsonSchema | undefined {\n  const responses = operation.responses as Record<string, unknown> | undefined;\n  if (!responses) return undefined;\n  // The first 2xx response with a JSON schema wins.\n  for (const [status, rawResponse] of Object.entries(responses)) {\n    if (!status.startsWith(\"2\")) continue;\n    const response = deref(rawResponse as JsonSchema, spec) as Record<string, unknown>;\n    const content = response.content as Record<string, { schema?: JsonSchema }> | undefined;\n    const jsonEntry =\n      content?.[\"application/json\"] ??\n      Object.entries(content ?? {}).find(([mediaType]) => mediaType.endsWith(\"+json\"))?.[1];\n    if (jsonEntry?.schema) return deepDeref(jsonEntry.schema, spec);\n  }\n  return undefined;\n}\n\n/**\n * The description is part of the agent's prompt, so we take the spec's own\n * words when they exist and only fall back to a plain template. Both paths\n * are marked so the audit report shows which descriptions need human love.\n */\nfunction pickDescription(operation: Record<string, unknown>, method: string, path: string): string {\n  if (typeof operation.summary === \"string\" && operation.summary.trim().length > 0) {\n    return operation.summary.trim();\n  }\n  if (typeof operation.description === \"string\" && operation.description.trim().length > 0) {\n    // Use the first line only — long prose belongs in docs, not in a prompt.\n    return operation.description.trim().split(\"\\n\")[0] as string;\n  }\n  return `${method} ${path}`;\n}\n"],"mappings":"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","names":[]}

package/dist/types-Bf5MxWeH.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The shared shapes that flow through the codegen pipeline.
+ *
+ * Every stage of the pipeline speaks in these types:
+ *
+ *   Source → CandidateTool → (safety review) → ReviewedTool → Generator → GeneratedFile
+ *
+ * A source (OpenAPI today, tRPC/Zod later) only has to produce CandidateTools.
+ * A generator only has to turn ReviewedTools into files. Everything in between
+ * lives here so the stages stay independent.
+ */
+/**
+ * A relaxed JSON Schema type. Real-world schemas (especially from OpenAPI)
+ * carry keywords we don't model individually, so unknown keywords are allowed
+ * through untouched instead of being rejected.
+ */
+interface JsonSchema {
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    description?: string;
+    format?: string;
+    nullable?: boolean;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    additionalProperties?: boolean | JsonSchema;
+    [keyword: string]: unknown;
+}
+/** Which source a candidate came from. Grows as new sources are added. */
+type SourceKind = "openapi" | "trpc" | "zod" | "prisma" | "graphql" | "manual";
+/**
+ * What the tool does to the world. The safety layer derives this from the
+ * HTTP method plus naming heuristics; it drives both the MCP hints and the
+ * risk tier.
+ */
+type SideEffect = "read" | "write" | "destructive" | "unknown";
+/** How dangerous the tool is to expose to an agent. */
+type RiskTier = "safe-read" | "write-confirm" | "destructive-confirm";
+/**
+ * A tool being considered for generation. Sources produce these; nothing is
+ * written to disk until the safety layer has reviewed every candidate.
+ */
+interface CandidateTool {
+    /** Stable id used for diffing across regenerations. */
+    id: string;
+    /** The final tool name an agent will see (validated, de-duplicated). */
+    name: string;
+    /** Where this candidate came from, e.g. `{ kind: "openapi", ref: "GET /orders/{id}" }`. */
+    source: {
+        kind: SourceKind;
+        ref: string;
+    };
+    /** Always derived from the source contract, never hand-typed. */
+    inputSchema: JsonSchema;
+    /** Present when the source has response typing. */
+    outputSchema?: JsonSchema;
+    /** Name of the generated TypeScript input type, e.g. "GetOrderStatusInput". */
+    inputTypeName: string;
+    httpMethod?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    sideEffect: SideEffect;
+    requiresAuth: boolean;
+    /** Where the description text came from — always reviewable before commit. */
+    description: string;
+    descriptionSource: "openapi-summary" | "generated-template";
+}
+/** The MCP hints the spec defines for a tool, computed by the safety layer. */
+interface ToolHints {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+}
+/** A candidate after safety review: classified, hinted, and linted. */
+interface ReviewedTool extends CandidateTool {
+    riskTier: RiskTier;
+    hints: ToolHints;
+    /**
+     * Output field paths the PII heuristics flagged (e.g. "user.email").
+     * These are fields that would leave the page and reach the agent.
+     */
+    piiInOutput: string[];
+}
+/** One audit finding. Errors block generation (unless --force); warnings don't. */
+interface AuditFinding {
+    level: "error" | "warning";
+    /** Tool name this finding is about, or undefined for project-level findings. */
+    tool?: string;
+    message: string;
+}
+/** A file the generator wants to write. */
+interface GeneratedFile {
+    /** Absolute path on disk. */
+    path: string;
+    /** Full new contents. */
+    contents: string;
+    /** What writing this file would do — used for the report and --dry-run. */
+    action: "create" | "update" | "unchanged";
+    /**
+     * Present when an existing file was edited by hand in the generated region,
+     * so we refused to touch it. The new contents go to a `.new` sibling instead.
+     */
+    conflict?: string;
+}
+/**
+ * A source reads an existing contract and produces candidate tools.
+ * Create one with a helper like `openapi({ spec: "./openapi.yaml" })`.
+ */
+interface Source {
+    readonly kind: SourceKind;
+    collect(): Promise<CandidateTool[]>;
+}
+/**
+ * A generator turns reviewed tools into files.
+ * Named after what lands in your repo: `js`, `html`, `react`, `manifest`.
+ */
+interface ToolGenerator {
+    readonly kind: string;
+    generate(tools: ReviewedTool[], cwd: string): Promise<GeneratedFile[]>;
+}
+/** Safety knobs. Everything here extends defaults; nothing is required. */
+interface SafetyOptions {
+    /** Extra field names to treat as PII, on top of the built-in list. */
+    piiFields?: string[];
+    /** Tool names or source refs to skip entirely (substrings, case-insensitive). */
+    exclude?: string[];
+}
+/** The config file shape. Create it with `defineConfig` for type checking. */
+interface CodegenConfig {
+    sources: Source[];
+    generate: ToolGenerator[];
+    safety?: SafetyOptions;
+}
+
+export type { AuditFinding as A, CodegenConfig as C, GeneratedFile as G, JsonSchema as J, ReviewedTool as R, Source as S, ToolGenerator as T, CandidateTool as a, RiskTier as b, SafetyOptions as c, SideEffect as d, SourceKind as e, ToolHints as f };

package/package.json

@@ -1,17 +1,37 @@
 {
   "name": "webmcp-codegen",
-  "version": "0.0.1",
-  "description": "Generate safe, typed, human-reviewed WebMCP tools from the API contracts you already have (OpenAPI, tRPC, Zod). Under active development.",
+  "version": "0.1.0",
+  "description": "Generate safe, typed, human-reviewed WebMCP tools from the API contracts you already have (OpenAPI, tRPC, Zod).",
+  "license": "MIT",
   "type": "module",
-  "main": "./src/index.js",
+  "sideEffects": false,
+  "bin": {
+    "webmcp-codegen": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sources": {
+      "types": "./dist/sources/index.d.ts",
+      "import": "./dist/sources/index.js"
+    },
+    "./generators": {
+      "types": "./dist/generators/index.d.ts",
+      "import": "./dist/generators/index.js"
+    }
   },
   "files": [
-    "src"
+    "dist"
   ],
-  "engines": {
-    "node": ">=20"
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/sources/index.ts src/generators/index.ts --format esm --dts --sourcemap --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/sources/index.ts src/generators/index.ts --format esm --dts --sourcemap --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "webmcp",
@@ -22,10 +42,18 @@
     "zod",
     "model-context-protocol"
   ],
-  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SouravInsights/groundstate.git",
     "directory": "packages/codegen"
+  },
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1"
   }
 }

package/src/index.js

@@ -1,4 +0,0 @@
-// webmcp-codegen — under active development.
-// This placeholder claims the npm name; the codegen pipeline (sources, safety
-// layer, emitters, CLI) lands here. See notes/webmcp-codegen-design.md.
-export {};