@mcpmake/core 0.3.4 → 0.3.5

package/dist/emitter/python-annotations.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Map JSON Schema fragments onto precise Python type annotations + Pydantic
+ * models so the generated FastMCP server's inferred tool inputSchema regains
+ * full fidelity (A4-H2).
+ *
+ * FastMCP infers a tool's inputSchema from the handler function SIGNATURE, so
+ * the fidelity of the schema is exactly the fidelity of the annotations we emit:
+ *   - scalars → `str` / `int` / `float` / `bool`
+ *   - string enums → `Literal["a", "b", ...]`
+ *   - arrays → `list[<item>]`
+ *   - bounds (`minimum`/`maxLength`/…) → `Field(ge=.., max_length=.., ...)`
+ *   - a plain-object request body → a Pydantic `BaseModel` (nested objects
+ *     become nested models), which FastMCP expands into a nested object schema.
+ *
+ * Everything an OpenAPI schema can throw at us that we cannot model precisely
+ * (`$ref` left unresolved, `allOf`/`oneOf`/`anyOf`, free-form objects) degrades
+ * to a permissive but always-VALID annotation (`str`, `Any`, `dict`) — the
+ * emitter must never produce Python that fails to import.
+ */
+import type { JsonSchema } from '../types/index.js';
+/** A Python type annotation plus the `Field(...)` keyword args it needs. */
+export interface PyAnnotation {
+    /** The base Python type, e.g. `int`, `Literal["a", "b"]`, `list[str]`. */
+    annotation: string;
+    /** Ordered `Field(...)` kwargs, e.g. `['ge=1', 'le=100', 'description="..."']`. */
+    fieldArgs: string[];
+}
+/**
+ * Produce the base Python type + Field kwargs for a single path/query/header/
+ * cookie parameter (or a nested non-object body property). `optional` is handled
+ * by the caller (it wraps the base type in `| None` and appends `= None`).
+ */
+export declare function jsonSchemaToPyAnnotation(schema: JsonSchema | undefined): PyAnnotation;
+/**
+ * Render a complete parameter annotation (the text after the `:` in a function
+ * signature) for a base type + Field kwargs + optionality.
+ *
+ *   required, no args   → `int`
+ *   required, args      → `Annotated[int, Field(ge=1)]`
+ *   optional, no args   → `int | None = None`
+ *   optional, args      → `Annotated[int | None, Field(ge=1)] = None`
+ *
+ * Returns the full RHS so the template stays a dumb interpolation.
+ */
+export declare function renderParamAnnotation(base: string, fieldArgs: string[], optional: boolean): string;
+/** Whether a body schema is a plain object we can faithfully model as a Pydantic class. */
+export declare function isModellableObject(schema: JsonSchema | undefined): boolean;
+/** A generated Pydantic model: its class name and the full source of its `class` block. */
+export interface PydanticModel {
+    className: string;
+    source: string;
+}
+/**
+ * Allocates unique, valid, non-reserved Pydantic model class names. Seeded with
+ * Python/runtime names that already appear in server.py so a model can never
+ * shadow `BaseModel`, `Field`, `FastMCP`, etc.
+ */
+export declare class ModelNameAllocator {
+    private readonly used;
+    constructor(seed?: Iterable<string>);
+    allocate(hint: string): string;
+}
+/**
+ * Generate a Pydantic `BaseModel` class for a plain-object schema, recursing for
+ * nested object properties (each becomes its own nested model). Appends every
+ * model it creates to `models` (parent last is fine — Python resolves names
+ * lazily at runtime, but we emit children before parents so the source reads
+ * top-down). Returns the class name to reference for this object.
+ *
+ * Property keys that are not valid Python identifiers (e.g. `user-id`) use a
+ * sanitized field name plus `Field(alias="<wireKey>")`; the model carries
+ * `model_config = ConfigDict(populate_by_name=True)` so it accepts either name,
+ * and the handler serializes with `by_alias=True` to send the original wire key.
+ */
+export declare function buildPydanticModel(schema: JsonSchema, nameHint: string, alloc: ModelNameAllocator, models: PydanticModel[]): string;
+export declare function isPyKeyword(name: string): boolean;
+//# sourceMappingURL=python-annotations.d.ts.map

package/dist/emitter/python-annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-annotations.d.ts","sourceRoot":"","sources":["../../src/emitter/python-annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AA+FD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAOrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,OAAO,GAChB,MAAM,CAOR;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAO1E;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;gBAEvB,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAM;IAmBvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAiB/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,aAAa,EAAE,GACtB,MAAM,CAwER;AAuED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/emitter/python-annotations.js

@@ -0,0 +1,330 @@
+import { sanitizePyIdentifier } from '../utils/sanitize.js';
+/**
+ * Escape a string for a double-quoted Python literal. Kept local (rather than
+ * importing the Handlebars-bound `escapePyString`) so this module has no
+ * template-loader dependency and stays unit-testable in isolation.
+ */
+function pyStringLiteral(value) {
+    return `"${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')}"`;
+}
+/** A JSON-Schema `type` may be a string or an array of strings (OpenAPI 3.1). */
+function primaryType(schema) {
+    const t = schema.type;
+    if (typeof t === 'string')
+        return t;
+    if (Array.isArray(t)) {
+        // Prefer the first non-"null" member (nullable shorthand) for the base type.
+        const nonNull = t.find((x) => x !== 'null');
+        return typeof nonNull === 'string' ? nonNull : undefined;
+    }
+    return undefined;
+}
+/** Collect numeric/string-length/pattern bounds into `Field(...)` kwargs. */
+function boundsFieldArgs(schema) {
+    const args = [];
+    const numeric = (key, kw) => {
+        const v = schema[key];
+        if (typeof v === 'number' && Number.isFinite(v))
+            args.push(`${kw}=${v}`);
+    };
+    numeric('minimum', 'ge');
+    numeric('maximum', 'le');
+    // OpenAPI 3.0 boolean exclusiveMinimum/Maximum pairs with minimum/maximum;
+    // only the 3.1 numeric form maps cleanly to gt/lt, so guard on `typeof number`
+    // (the `numeric` helper already does). A boolean value is ignored.
+    numeric('exclusiveMinimum', 'gt');
+    numeric('exclusiveMaximum', 'lt');
+    numeric('minLength', 'min_length');
+    numeric('maxLength', 'max_length');
+    if (typeof schema.pattern === 'string' && schema.pattern.length > 0) {
+        args.push(`pattern=${pyStringLiteral(schema.pattern)}`);
+    }
+    return args;
+}
+/**
+ * Map a (non-body-root) schema to a Python base type. Body objects are handled
+ * separately as Pydantic models; here an `object` degrades to `dict`. Returns
+ * only the base type string — bounds/description are added by the caller.
+ */
+function baseTypeFor(schema) {
+    if (!schema || typeof schema !== 'object')
+        return 'Any';
+    // String enum → Literal[...]. Only a homogeneous all-string enum maps to a
+    // Literal; a mixed-type enum degrades to the base scalar type below.
+    const enumVals = schema.enum;
+    if (Array.isArray(enumVals) &&
+        enumVals.length > 0 &&
+        enumVals.every((v) => typeof v === 'string')) {
+        const members = enumVals.map(pyStringLiteral).join(', ');
+        return `Literal[${members}]`;
+    }
+    const t = primaryType(schema);
+    switch (t) {
+        case 'string':
+            return 'str';
+        case 'integer':
+            return 'int';
+        case 'number':
+            return 'float';
+        case 'boolean':
+            return 'bool';
+        case 'array': {
+            const items = schema.items;
+            if (items && typeof items === 'object' && !Array.isArray(items)) {
+                return `list[${baseTypeFor(items)}]`;
+            }
+            return 'list';
+        }
+        case 'object':
+            return 'dict';
+        default:
+            // Unknown / unresolved $ref / allOf|oneOf|anyOf with no `type`: stay
+            // permissive but valid. `Any` accepts anything and never breaks import.
+            return 'Any';
+    }
+}
+/**
+ * Produce the base Python type + Field kwargs for a single path/query/header/
+ * cookie parameter (or a nested non-object body property). `optional` is handled
+ * by the caller (it wraps the base type in `| None` and appends `= None`).
+ */
+export function jsonSchemaToPyAnnotation(schema) {
+    const annotation = baseTypeFor(schema);
+    const fieldArgs = schema ? boundsFieldArgs(schema) : [];
+    if (schema && typeof schema.description === 'string' && schema.description.length > 0) {
+        fieldArgs.push(`description=${pyStringLiteral(schema.description)}`);
+    }
+    return { annotation, fieldArgs };
+}
+/**
+ * Render a complete parameter annotation (the text after the `:` in a function
+ * signature) for a base type + Field kwargs + optionality.
+ *
+ *   required, no args   → `int`
+ *   required, args      → `Annotated[int, Field(ge=1)]`
+ *   optional, no args   → `int | None = None`
+ *   optional, args      → `Annotated[int | None, Field(ge=1)] = None`
+ *
+ * Returns the full RHS so the template stays a dumb interpolation.
+ */
+export function renderParamAnnotation(base, fieldArgs, optional) {
+    const typePart = optional ? `${base} | None` : base;
+    const suffix = optional ? ' = None' : '';
+    if (fieldArgs.length === 0) {
+        return `${typePart}${suffix}`;
+    }
+    return `Annotated[${typePart}, Field(${fieldArgs.join(', ')})]${suffix}`;
+}
+/** Whether a body schema is a plain object we can faithfully model as a Pydantic class. */
+export function isModellableObject(schema) {
+    if (!schema || typeof schema !== 'object')
+        return false;
+    if (primaryType(schema) !== 'object')
+        return false;
+    const props = schema.properties;
+    return (!!props && typeof props === 'object' && !Array.isArray(props) && Object.keys(props).length > 0);
+}
+/**
+ * Allocates unique, valid, non-reserved Pydantic model class names. Seeded with
+ * Python/runtime names that already appear in server.py so a model can never
+ * shadow `BaseModel`, `Field`, `FastMCP`, etc.
+ */
+export class ModelNameAllocator {
+    used;
+    constructor(seed = []) {
+        this.used = new Set([
+            // Imported / runtime names the model defs sit alongside in server.py.
+            'BaseModel',
+            'Field',
+            'ConfigDict',
+            'FastMCP',
+            'TextContent',
+            'Annotated',
+            'Literal',
+            'Optional',
+            'Any',
+            'BASE_URL',
+            'server',
+            'client',
+            ...seed,
+        ]);
+    }
+    allocate(hint) {
+        // PascalCase the hint, strip to identifier chars, prefix when it would start
+        // with a digit / be empty so the class name is always valid Python.
+        const cleaned = sanitizePyIdentifier(hint);
+        const pascal = cleaned
+            .split('_')
+            .filter(Boolean)
+            .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+            .join('');
+        let base = pascal && /^[A-Za-z]/.test(pascal) ? pascal : `Model${pascal}`;
+        if (!base)
+            base = 'Model';
+        let candidate = base;
+        let n = 1;
+        while (this.used.has(candidate))
+            candidate = `${base}${n++}`;
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+/**
+ * Generate a Pydantic `BaseModel` class for a plain-object schema, recursing for
+ * nested object properties (each becomes its own nested model). Appends every
+ * model it creates to `models` (parent last is fine — Python resolves names
+ * lazily at runtime, but we emit children before parents so the source reads
+ * top-down). Returns the class name to reference for this object.
+ *
+ * Property keys that are not valid Python identifiers (e.g. `user-id`) use a
+ * sanitized field name plus `Field(alias="<wireKey>")`; the model carries
+ * `model_config = ConfigDict(populate_by_name=True)` so it accepts either name,
+ * and the handler serializes with `by_alias=True` to send the original wire key.
+ */
+export function buildPydanticModel(schema, nameHint, alloc, models) {
+    const className = alloc.allocate(nameHint);
+    const props = (schema.properties ?? {});
+    const requiredList = Array.isArray(schema.required) ? schema.required : [];
+    const requiredSet = new Set(requiredList);
+    const fieldLines = [];
+    let needsAlias = false;
+    const usedFieldNames = new Set();
+    for (const [wireKey, propSchema] of Object.entries(props)) {
+        const isRequired = requiredSet.has(wireKey);
+        // Determine the python field name. Valid identifiers are used as-is; anything
+        // else is sanitized and aliased to the wire key. De-dupe sanitized names so
+        // two wire keys that sanitize to the same identifier don't collide.
+        // NOTE: a Pydantic v2 model field may NOT begin with `_` (those are treated
+        // as private attributes — `NameError: Fields must not use names with leading
+        // underscores`). So a leading-underscore wire key is NOT a valid field name
+        // here (unlike a function arg), and the sanitizer must never emit a leading
+        // `_`. sanitizePyFieldName prefixes `f_` instead.
+        const validIdent = /^[A-Za-z][A-Za-z0-9_]*$/.test(wireKey) &&
+            !isPyKeyword(wireKey) &&
+            !isReservedPydanticField(wireKey);
+        let fieldName = validIdent ? wireKey : sanitizePyFieldName(wireKey);
+        while (usedFieldNames.has(fieldName))
+            fieldName = `${fieldName}_`;
+        usedFieldNames.add(fieldName);
+        const aliased = fieldName !== wireKey;
+        if (aliased)
+            needsAlias = true;
+        // Nested plain-object property → its own model; otherwise a scalar/array.
+        let baseType;
+        let fieldArgs;
+        if (isModellableObject(propSchema)) {
+            baseType = buildPydanticModel(propSchema, `${className}_${fieldName}`, alloc, models);
+            fieldArgs = [];
+            if (typeof propSchema.description === 'string' && propSchema.description.length > 0) {
+                fieldArgs.push(`description=${pyStringLiteral(propSchema.description)}`);
+            }
+        }
+        else {
+            const ann = jsonSchemaToPyAnnotation(propSchema);
+            baseType = ann.annotation;
+            fieldArgs = ann.fieldArgs;
+        }
+        const typePart = isRequired ? baseType : `${baseType} | None`;
+        // Compose the Field(...) call. alias must come first for readability; the
+        // default sentinel for an optional field is `None` (passed as the Field
+        // default so the property is genuinely optional in the inferred schema).
+        const callArgs = [];
+        if (aliased)
+            callArgs.push(`alias=${pyStringLiteral(wireKey)}`);
+        if (!isRequired)
+            callArgs.push('default=None');
+        callArgs.push(...fieldArgs);
+        let rhs;
+        if (callArgs.length === 0) {
+            // Required, no metadata, valid identifier → bare typed field.
+            rhs = '';
+        }
+        else {
+            rhs = ` = Field(${callArgs.join(', ')})`;
+        }
+        fieldLines.push(`    ${fieldName}: ${typePart}${rhs}`);
+    }
+    const header = `class ${className}(BaseModel):`;
+    const configLine = needsAlias ? '    model_config = ConfigDict(populate_by_name=True)\n' : '';
+    const body = fieldLines.length > 0 ? fieldLines.join('\n') : '    pass';
+    const source = `${header}\n${configLine}${body}\n`;
+    models.push({ className, source });
+    return className;
+}
+/**
+ * Whether a wire key — even though it's a syntactically valid Python identifier —
+ * would be rejected by Pydantic v2 as a model field name. Pydantic reserves the
+ * `model_` namespace (`model_config` is the special class attribute; `model_dump`/
+ * `model_validate`/… are BaseModel methods), so a body property literally named
+ * `model_config`/`model_dump` (common in ML/AI API specs) would otherwise crash
+ * the generated server at import. Such keys are remapped to an `f_`-prefixed
+ * field with `Field(alias="<wireKey>")` preserving the wire name.
+ */
+function isReservedPydanticField(name) {
+    return name.startsWith('model_');
+}
+/**
+ * Sanitize a wire key into a legal Pydantic v2 model FIELD name. Like
+ * {@link sanitizePyIdentifier} but it never emits a leading underscore (Pydantic
+ * rejects `_`-leading field names) — a result that wouldn't start with a letter
+ * is prefixed with `f_`. A Python keyword or a Pydantic-reserved (`model_…`) name
+ * is also remapped. The original wire key is preserved via `Field(alias=…)`, so
+ * the on-the-wire name is unchanged.
+ */
+function sanitizePyFieldName(wireKey) {
+    let id = wireKey.replace(/[^A-Za-z0-9_]/g, '_');
+    if (!/^[A-Za-z]/.test(id))
+        id = `f_${id}`;
+    if (isPyKeyword(id))
+        id = `${id}_`;
+    if (isReservedPydanticField(id))
+        id = `f_${id}`;
+    return id;
+}
+const PY_KEYWORDS = new Set([
+    'False',
+    'None',
+    'True',
+    'and',
+    'as',
+    'assert',
+    'async',
+    'await',
+    'break',
+    'class',
+    'continue',
+    'def',
+    'del',
+    'elif',
+    'else',
+    'except',
+    'finally',
+    'for',
+    'from',
+    'global',
+    'if',
+    'import',
+    'in',
+    'is',
+    'lambda',
+    'nonlocal',
+    'not',
+    'or',
+    'pass',
+    'raise',
+    'return',
+    'try',
+    'while',
+    'with',
+    'yield',
+    'match',
+    'case',
+]);
+export function isPyKeyword(name) {
+    return PY_KEYWORDS.has(name);
+}
+//# sourceMappingURL=python-annotations.js.map

package/dist/emitter/python-annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-annotations.js","sourceRoot":"","sources":["../../src/emitter/python-annotations.ts"],"names":[],"mappings":"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"}

package/dist/emitter/python-templates/server.py.hbs

@@ -3,8 +3,10 @@
 import os
 import json
 import httpx
+from typing import Annotated, Literal, Optional, Any
 from urllib.parse import quote
 from dotenv import load_dotenv
+from pydantic import BaseModel, Field, ConfigDict
 from mcp.server.fastmcp import FastMCP
 from mcp.types import TextContent
 
@@ -91,9 +93,17 @@ def _auth_query_params() -> dict[str, str]:
     return params
 
 
+{{#if pydanticModels}}
+# Request-body models (A4-H2). Each plain-object request body is modelled as a
+# Pydantic BaseModel so FastMCP infers a full-fidelity nested-object input schema
+# (typed properties, required set, descriptions). Fields whose wire name is not a
+# valid Python identifier use Field(alias=...) + populate_by_name; the handler
+# serializes with by_alias=True to restore the original key on the wire.
+{{{pydanticModels}}}
+{{/if}}
 {{#each tools}}
 @server.tool(name="{{pyStr name}}")
-async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#each pyQueryParams}}{{pyName}}: str = "", {{/each}}{{#each pyHeaderParams}}{{pyName}}: str = "", {{/each}}{{#each pyCookieParams}}{{pyName}}: str = "", {{/each}}{{#if hasRequestBody}}body: dict | None = None{{/if}}) -> list[TextContent]:
+async def {{functionName}}({{{pySignature}}}) -> list[TextContent]:
     """{{pyDocstring description}}"""
     url = BASE_URL + "{{pyStr pathTemplate}}"
     {{#each pyPathParams}}
@@ -101,7 +111,8 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
     {{/each}}
     {{#if pyQueryParams.length}}
     params = { {{#each pyQueryParams}}"{{pyStr apiName}}": {{pyName}}, {{/each}} }
-    params = {k: v for k, v in params.items() if v}
+    # Drop only unset (None) optionals — a legitimate 0/false/"" must still be sent.
+    params = {k: v for k, v in params.items() if v is not None}
     {{#if @root.hasQueryApiKey}}
     params.update(_auth_query_params())
     {{/if}}
@@ -115,13 +126,13 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
     # names, merged over the auth headers. Empty values are omitted.
     req_headers = dict(_headers())
     {{#each pyHeaderParams}}
-    if {{pyName}}:
-        req_headers["{{pyStr wireName}}"] = {{pyName}}
+    if {{pyName}} is not None:
+        req_headers["{{pyStr wireName}}"] = str({{pyName}})
     {{/each}}
     {{#if pyCookieParams.length}}
     _cookie_parts = []
     {{#each pyCookieParams}}
-    if {{pyName}}:
+    if {{pyName}} is not None:
         _cookie_parts.append("{{pyStr wireName}}=" + quote(str({{pyName}}), safe=""))
     {{/each}}
     if _cookie_parts:
@@ -130,6 +141,16 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
         req_headers["Cookie"] = (_existing + "; " + _joined) if _existing else _joined
     {{/if}}
     {{/if}}
+    {{#if hasRequestBody}}
+    {{#if bodyIsModel}}
+    # Pydantic body → plain dict for httpx. by_alias restores any non-identifier
+    # wire keys; exclude_none drops unset optionals so they are omitted, not nulled.
+    _body = body.model_dump(exclude_none=True, by_alias=True) if body is not None else None
+    {{else}}
+    # Scalar / array / free-form body kept as the raw typed value.
+    _body = body
+    {{/if}}
+    {{/if}}
     try:
         async with client.stream(
             "{{method}}",
@@ -140,12 +161,12 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
             {{/if}}
             {{#if hasRequestBody}}
             {{#if (eq bodyEncoding "form")}}
-            data=body,
+            data=_body,
             {{else}}
             {{#if (eq bodyEncoding "multipart")}}
-            files=body,
+            files=_body,
             {{else}}
-            json=body,
+            json=_body,
             {{/if}}
             {{/if}}
             {{/if}}