@christopher_dondici/mcp-gen 2.1.2

package/dist/templates/typescript/server.hbs

@@ -0,0 +1,337 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { ApiClient } from "./client.js";
+
+// Auto-generated by mcp-gen v{{generatorVersion}}
+// Spec: {{info.title}} v{{info.version}}
+// Generated: {{generatedAt}}
+{{#if incremental}}
+// Incremental mode: edit code between @@mcp-gen markers — it will be preserved on re-generation.
+{{/if}}
+
+const BASE_URL = "{{baseUrl}}";
+const API_TOKEN = typeof process !== "undefined" ? process.env.TOKEN : undefined;
+const client = new ApiClient(BASE_URL, API_TOKEN);
+
+// ─── Logging ─────────────────────────────────────────────────────────────────
+// IMPORTANT: This server uses stdio transport. stdout is reserved for JSON-RPC.
+// Never use console.log() — it will corrupt the MCP stream.
+// Always use log() (writes to stderr) for any debug output.
+const log = (...args: unknown[]) => console.error("[{{serverName}}]", ...args);
+
+// ─── Serialization ───────────────────────────────────────────────────────────
+// Safely converts any handler return value to a string for the MCP text content.
+// Handles: objects, arrays, primitives, Buffers, Uint8Arrays (as base64), and
+// non-serializable values (circular refs, undefined, functions).
+function safeSerialize(value: unknown): string {
+  if (value === undefined || value === null) return String(value);
+  if (typeof value === "string") return value;
+  if (typeof value !== "object") return String(value);
+
+  // Binary data — encode as base64 instead of corrupting the stream
+  if (Buffer.isBuffer(value)) return value.toString("base64");
+  if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    // Circular references or non-serializable values
+    return String(value);
+  }
+}
+
+const server = new Server(
+  { name: "{{serverName}}", version: "{{serverVersion}}" },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+// ─── Security helpers (scoped resource policy by default) ───────────────────
+{{#if securitySchemes}}
+const securitySchemes = {{{json securitySchemes}}};
+{{else}}
+const securitySchemes: Record<string, unknown> = {};
+{{/if}}
+
+type ToolAuthContext = {
+  tokenId?: string;
+  principal?: string;
+  expiresAt?: string;
+  allowedTools?: string[];
+  endpointAllowlist?: string[];
+  spendLimitUsd?: number;
+  spendUsedUsd?: number;
+  revoked?: boolean;
+  requestId?: string;
+};
+
+type ToolPolicy = {
+  endpoint: string;
+  requiresTtl: boolean;
+  requiresSpendLimit: boolean;
+  requiresRequestLog: boolean;
+  requiresRevocationCheck: boolean;
+};
+
+const rawCredentialKeys = [
+  "authorization",
+  "token",
+  "access_token",
+  "api_key",
+  "apikey",
+  "x-api-key",
+  "client_secret",
+  "refresh_token",
+  "password",
+  "secret",
+];
+
+const toolPolicies: Record<string, ToolPolicy> = {
+  {{#each tools}}
+  "{{name}}": {
+    endpoint: "{{method}} {{path}}",
+    requiresTtl: true,
+    requiresSpendLimit: true,
+    requiresRequestLog: true,
+    requiresRevocationCheck: true,
+  },
+  {{/each}}
+};
+
+function hasRawCredentialKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const entries = Object.entries(value as Record<string, unknown>);
+  for (const [key, nested] of entries) {
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (rawCredentialKeys.some((candidate) => normalized === candidate.replace(/[^a-z0-9]/g, ""))) {
+      return true;
+    }
+    if (nested && typeof nested === "object" && hasRawCredentialKey(nested)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function extractCustomArgs(args: Record<string, unknown> | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!args) return out;
+  for (const [k, v] of Object.entries(args)) {
+    if (k === "authContext") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function getAuthContext(args: Record<string, unknown> | undefined): ToolAuthContext | undefined {
+  const ctx = args?.authContext;
+  if (!ctx || typeof ctx !== "object") return undefined;
+  return ctx as ToolAuthContext;
+}
+
+function ensureNoRawCredentials(args: Record<string, unknown> | undefined): void {
+  if (!args) return;
+  if (hasRawCredentialKey(args)) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      "Raw provider credentials are not allowed in tool arguments. Use scoped authContext metadata only."
+    );
+  }
+}
+
+function isExpired(expiresAt: string): boolean {
+  const ts = Date.parse(expiresAt);
+  if (Number.isNaN(ts)) return true;
+  return ts <= Date.now();
+}
+
+function requireSecurity(toolName: string, args: Record<string, unknown> | undefined, security: unknown): void {
+  ensureNoRawCredentials(args);
+  const policy = toolPolicies[toolName];
+  const authContext = getAuthContext(args);
+
+  if (!policy) {
+    throw new McpError(ErrorCode.InternalError, `Missing security policy for tool: ${toolName}`);
+  }
+
+  if (!authContext) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      "Missing authContext. Provide scoped metadata (tokenId, expiresAt, limits, requestId) from your gateway."
+    );
+  }
+
+  if (policy.requiresRevocationCheck && authContext.revoked) {
+    throw new McpError(ErrorCode.InvalidRequest, "Access revoked");
+  }
+
+  if (policy.requiresTtl && (!authContext.expiresAt || isExpired(authContext.expiresAt))) {
+    throw new McpError(ErrorCode.InvalidRequest, "Token expired or missing TTL");
+  }
+
+  if (policy.requiresRequestLog && !authContext.requestId) {
+    throw new McpError(ErrorCode.InvalidParams, "requestId is required for audit logging");
+  }
+
+  if (policy.requiresSpendLimit) {
+    const limit = authContext.spendLimitUsd;
+    const used = authContext.spendUsedUsd;
+    if (typeof limit !== "number" || typeof used !== "number") {
+      throw new McpError(ErrorCode.InvalidParams, "Spend limit metadata is required");
+    }
+    if (used > limit) {
+      throw new McpError(ErrorCode.InvalidRequest, "Spend limit exceeded");
+    }
+  }
+
+  if (authContext.allowedTools && !authContext.allowedTools.includes(toolName)) {
+    throw new McpError(ErrorCode.InvalidRequest, `Tool not allowed by scope: ${toolName}`);
+  }
+
+  if (authContext.endpointAllowlist && !authContext.endpointAllowlist.includes(policy.endpoint)) {
+    throw new McpError(ErrorCode.InvalidRequest, `Endpoint not allowed: ${policy.endpoint}`);
+  }
+
+  if (!security) return;
+  try {
+    const secArray = security as Array<Record<string, string[]>>;
+    if (!Array.isArray(secArray) || secArray.length === 0) return;
+    const req = secArray[0] ?? {};
+    const requiresScheme = Object.keys(req).length > 0;
+    if (!requiresScheme) return;
+    if (!authContext.tokenId) {
+      throw new McpError(ErrorCode.InvalidRequest, "Missing tokenId for secured operation");
+    }
+    const declaredScheme = Object.keys(req).some((schemeName) => {
+      const scheme = (securitySchemes as Record<string, unknown> | null)?.[schemeName];
+      return Boolean(scheme);
+    });
+    if (!declaredScheme) {
+      throw new McpError(ErrorCode.InvalidRequest, "Declared security scheme not found in OpenAPI components");
+    }
+  } catch {
+    throw new McpError(ErrorCode.InvalidRequest, "Unauthorized");
+  }
+}
+
+{{#if requiresAuth}}
+function requireApiAuth(): void {
+  if (!API_TOKEN) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      "This server uses an authenticated API. Set the TOKEN environment variable before starting."
+    );
+  }
+}
+{{/if}}
+
+// ─── Tool Definitions ────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {{#each tools}}
+    {
+      name: "{{name}}",
+      description: "{{escapeText description}}",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          {{#each params}}
+          {{name}}: { type: "{{type}}"{{#if (ne type "object")}}{{#if format}}, format: "{{format}}"{{/if}}{{#if enum}}, enum: {{{json enum}}}{{/if}}{{/if}}, description: "{{escapeText description}}" },
+          {{/each}}
+          authContext: {
+            type: "object" as const,
+            description: "Scoped auth metadata from a gateway (no raw provider credentials).",
+            properties: {
+              tokenId: { type: "string" as const },
+              principal: { type: "string" as const },
+              expiresAt: { type: "string" as const },
+              allowedTools: { type: "array" as const, items: { type: "string" as const } },
+              endpointAllowlist: { type: "array" as const, items: { type: "string" as const } },
+              spendLimitUsd: { type: "number" as const },
+              spendUsedUsd: { type: "number" as const },
+              revoked: { type: "boolean" as const },
+              requestId: { type: "string" as const },
+            },
+            additionalProperties: false,
+          },
+        },
+        required: [{{#each params}}{{#if required}}"{{name}}",{{/if}}{{/each}}],
+      },
+    },
+    {{/each}}
+  ],
+}));
+
+{{#if http}}
+// Exported helper so the client can assemble HTTP requests from a tool + params.
+function buildHttpArgs(args: Record<string, unknown> | undefined): Record<string, unknown> {
+  return extractCustomArgs(args);
+}
+{{/if}}
+
+// ─── Tool Handlers ───────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    {{#each tools}}
+    case "{{name}}": {
+      // {{method}} {{path}}
+      // @@mcp-gen:start:{{name}}
+      requireSecurity("{{name}}", args as Record<string, unknown> | undefined, {{#if security}}{{json security}}{{else}}null{{/if}});
+      {{#if ../http}}
+      {{#if ../requiresAuth}}requireApiAuth();{{/if}}
+      const out = await client.{{name}}(extractCustomArgs(args as Record<string, unknown> | undefined));
+      return { content: [{ type: "text" as const, text: safeSerialize(out) }] };
+      {{else}}
+      {{#if exampleResponse}}
+      return {
+        content: [{ type: "text" as const, text: safeSerialize({{json exampleResponse}}) }],
+      };
+      {{else}}
+      throw new McpError(ErrorCode.InternalError, "Handler not implemented: {{name}}");
+      {{/if}}
+      {{/if}}
+      // @@mcp-gen:end:{{name}}
+    }
+    {{/each}}
+    default:
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+  }
+});
+
+// ─── Resources (from OpenAPI parameter schemas) ────────────────────────────
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {{#each tools}}
+    {
+      uri: "{{path}}",
+      name: "{{escapeText description}}",
+      description: "{{method}} {{path}} — {{escapeText description}}",
+      mimeType: "application/json",
+    },
+    {{/each}}
+  ],
+}));
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log("running on stdio");
+}
+
+main().catch((err) => {
+  log("Fatal:", err);
+  process.exit(1);
+});

package/dist/templates/typescript/tsconfig.json.hbs

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/examples/petstore.json

@@ -0,0 +1,130 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Pet Store",
+    "description": "A sample Pet Store API to test mcp-gen",
+    "version": "1.0.0"
+  },
+  "servers": [{ "url": "https://petstore.example.com/v1" }],
+  "paths": {
+    "/pets": {
+      "get": {
+        "summary": "List all pets",
+        "operationId": "listPets",
+        "tags": ["pets"],
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Maximum number of pets to return",
+            "required": false,
+            "schema": { "type": "integer", "maximum": 100 }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of pets",
+            "content": {
+              "application/json": {
+                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } },
+                "example": [
+                  { "id": 1, "name": "Whiskers", "tag": "cat" },
+                  { "id": 2, "name": "Rex", "tag": "dog" }
+                ]
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a pet",
+        "operationId": "createPet",
+        "tags": ["pets"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/NewPet" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Pet created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Pet" },
+                "example": { "id": 3, "name": "Fluffy", "tag": "rabbit" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pets/{petId}": {
+      "get": {
+        "summary": "Get a pet by ID",
+        "operationId": "getPetById",
+        "tags": ["pets"],
+        "parameters": [
+          {
+            "name": "petId",
+            "in": "path",
+            "required": true,
+            "description": "The ID of the pet to retrieve",
+            "schema": { "type": "integer" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The pet",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Pet" },
+                "example": { "id": 1, "name": "Whiskers", "tag": "cat" }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a pet",
+        "operationId": "deletePet",
+        "tags": ["pets"],
+        "parameters": [
+          {
+            "name": "petId",
+            "in": "path",
+            "required": true,
+            "description": "The ID of the pet to delete",
+            "schema": { "type": "integer" }
+          }
+        ],
+        "responses": { "204": { "description": "Pet deleted" } }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pet": {
+        "type": "object",
+        "description": "A pet in the store",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "integer", "description": "Unique identifier" },
+          "name": { "type": "string", "description": "Name of the pet" },
+          "tag": { "type": "string", "description": "Type/species of the pet" }
+        }
+      },
+      "NewPet": {
+        "type": "object",
+        "description": "Payload for creating a new pet",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "description": "Name of the pet" },
+          "tag": { "type": "string", "description": "Type/species of the pet" }
+        }
+      }
+    }
+  }
+}

package/examples/petstore.yaml

@@ -0,0 +1,131 @@
+openapi: "3.0.3"
+info:
+  title: Pet Store
+  description: A sample Pet Store API to test mcp-gen YAML support
+  version: "1.0.0"
+servers:
+  - url: https://petstore.example.com/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of pets to return
+          required: false
+          schema:
+            type: integer
+            maximum: 100
+      responses:
+        "200":
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Pet"
+              example:
+                - id: 1
+                  name: Whiskers
+                  tag: cat
+                - id: 2
+                  name: Rex
+                  tag: dog
+    post:
+      summary: Create a pet
+      operationId: createPet
+      tags:
+        - pets
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NewPet"
+      responses:
+        "201":
+          description: Pet created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pet"
+              example:
+                id: 3
+                name: Fluffy
+                tag: rabbit
+  /pets/{petId}:
+    get:
+      summary: Get a pet by ID
+      operationId: getPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The ID of the pet to retrieve
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: The pet
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pet"
+              example:
+                id: 1
+                name: Whiskers
+                tag: cat
+        "404":
+          description: Pet not found
+    delete:
+      summary: Delete a pet
+      operationId: deletePet
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The ID of the pet to delete
+          schema:
+            type: integer
+      responses:
+        "204":
+          description: Pet deleted
+components:
+  schemas:
+    Pet:
+      type: object
+      description: A pet in the store
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          description: Unique identifier
+        name:
+          type: string
+          description: Name of the pet
+        tag:
+          type: string
+          description: Type/species of the pet
+    NewPet:
+      type: object
+      description: Payload for creating a new pet
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Name of the pet
+        tag:
+          type: string
+          description: Type/species of the pet

package/examples/week3.json

@@ -0,0 +1,47 @@
+{
+  "openapi": "3.0.1",
+  "info": { "title": "Week3 API", "version": "1.0.0" },
+  "servers": [{ "url": "https://api.week3.test" }],
+  "paths": {
+    "/items": {
+      "get": {
+        "summary": "List items",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ItemList" }
+              }
+            }
+          }
+        },
+        "security": [{ "ApiKeyAuth": [] }]
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" },
+      "BearerAuth": { "type": "http", "scheme": "bearer" }
+    },
+    "schemas": {
+      "A": {
+        "type": "object",
+        "properties": { "a": { "type": "string" } }
+      },
+      "B": {
+        "type": "object",
+        "properties": { "b": { "type": "number" } }
+      },
+      "Item": {
+        "oneOf": [ { "$ref": "#/components/schemas/A" }, { "$ref": "#/components/schemas/B" } ],
+        "discriminator": { "propertyName": "type" }
+      },
+      "ItemList": {
+        "type": "array",
+        "items": { "$ref": "#/components/schemas/Item" }
+      }
+    }
+  }
+}