Review, wire up, and release the generated SDK, docs, and MCP server.

TypeScript SDK

A buildable npm package with typed request/response models, one resource class per tag, an SDK error hierarchy, and a default fetch-based transport.

MCP server

A Node.js MCP server exposing one tool per operation, classified by safety bucket, with input validation derived from the spec.

Documentation site

A self-contained static HTML site — browse it live at /projects/<slug>/docs or download the zip and host it on any static host (Vercel, Netlify, S3, GitHub Pages).

text
my-api-sdk/
  package.json          # name + version derived from your spec
  tsconfig.json
  README.md             # quickstart for the consumer
  src/
    index.ts            # exports the client and types
    client.ts           # PetstoreClient — accepts baseUrl + auth + fetch
    errors.ts           # typed SDK error classes
    types.ts            # every component schema as a typed interface
    resources/
      pets.ts           # one file per tag, methods grouped by operationId
      owners.ts

• Open the SDK preview and confirm resource grouping (one resource per tag) matches your mental model of the API.
• Open src/client.ts and verify the default baseUrl matches the environment you intend to publish for.
• Verify the auth scheme: bearer token, API key header, or query parameter. The generator picks it from the first security requirement on each operation.
• Scan resource files for any operation whose response shape is `unknown` — that indicates the spec used additionalProperties: true or returned a $ref we couldn&rsquo;t resolve.
• Build the package locally before publishing.

bash
unzip my-api-typescript-sdk.zip -d my-api-sdk
cd my-api-sdk
npm install
npm run build
# inspect dist/ — should contain .d.ts files for every resource and type
npm pack

typescript
import { PetstoreClient, PetstoreError } from "petstore-sdk";

const client = new PetstoreClient({
  baseUrl: process.env.PETSTORE_BASE_URL!,
  apiKey: process.env.PETSTORE_API_KEY!,
  // Optional: bring your own fetch (e.g. for tracing or proxying)
  fetch: globalThis.fetch.bind(globalThis),
});

try {
  const pets = await client.pets.list({ limit: 50 });
  for (const pet of pets.items) {
    console.log(pet.id, pet.name);
  }
} catch (err) {
  if (err instanceof PetstoreError) {
    // err.status, err.code, err.message — all typed
    console.error("API failure", err.status, err.code);
  } else {
    throw err;
  }
}

text
my-api-mcp/
  package.json          # name derived from spec, depends on @modelcontextprotocol/sdk
  README.md             # client wiring snippets (Claude Desktop, Cursor, etc.)
  src/
    server.ts           # MCP stdio server entry point
    tools.ts            # one tool per operation, with input validation
    http-client.ts      # generated HTTP client (separate from the SDK package)
    env.ts              # required env vars: API_BASE_URL, auth credential names
    validate.ts         # input-schema validation per tool

Every tool is bucketed automatically. The MCP preview surfaces the counts so you can spot-check before release.

safe

GET / HEAD by default, or operations explicitly marked x-ajolla-safety: safe. Side-effect-free.

destructive

DELETE, or operations explicitly marked destructive. Permanent or hard-to-reverse.

admin

Operations gated by an admin security scope, or explicitly marked admin. Disabled by default in the generated server.

disabled

Operations the spec asked us to skip (x-ajolla-safety: disabled). Never registered as tools.

• Open the MCP preview and walk through every tool in the `destructive` and `admin` buckets. Confirm each one belongs there.
• Decide which buckets to enable in your runtime: most teams ship with `safe` only, and require explicit opt-in for the others.
• Provide least-privilege credentials. Do not reuse a token that can also reach unrelated systems.
• Configure logging in the host runtime so agent invocations are auditable.
• Pin the spec revision and the generated package version in your runbook so re-issuing a server is reproducible.

bash
unzip my-api-mcp-server.zip -d my-api-mcp
cd my-api-mcp
npm install
export API_BASE_URL="https://api.example.com"
export API_KEY="sk_…"
# Enable only the safe bucket initially
export MCP_ENABLED_BUCKETS="safe"
npm run start

Register the server as an MCP stdio command in the host client. The exact snippet is included in the generated README.md. A typical Claude Desktop config:

json
{
  "mcpServers": {
    "petstore": {
      "command": "node",
      "args": ["/absolute/path/to/my-api-mcp/dist/server.js"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "API_KEY": "sk_…",
        "MCP_ENABLED_BUCKETS": "safe"
      }
    }
  }
}

• Keep docs, SDK, and MCP releases tied to the same source spec revision. Track the SHA in the release notes for the consuming repo.
• Treat any change to a tool&rsquo;s safety bucket as a security-relevant event. Require a second reviewer.
• Add rollout gates for breaking API changes — downstream agents should not silently start invoking renamed tools.
• Run the regenerate flow after every spec change. Hand-patching generated files is not supported.
• Subscribe maintainers to the spec source so they hear about destructive-method additions before they appear in a release.

SDK methods named odd things

Add operationId to the spec — without it, Ajolla synthesizes method names from method + path.

MCP tool input is `any`

Replace inline objects with named components or remove additionalProperties: true. Both weaken input validation.

Auth not flowing through

Confirm the operation references the right securityScheme. Operations without security: [] inherit the document-level requirement.

Generation succeeded but the SDK, docs, or MCP zip 404s

Signed download URLs expire after 60 seconds. Click Download zip again to mint a fresh URL.

Destructive operation marked safe

Add x-ajolla-safety: destructive to the operation. The default classification is method-based and can&rsquo;t see business semantics.

• Getting started — Sign in to first generated zip in one session.
• OpenAPI readiness — Make the inputs better so these checklists get shorter.
• Using the CLI — Trigger regenerations and pull artifacts from CI.