MCP Tool Documentation

{
  "mcpServers": {
    "star-wars-name-generator": {
      "url": "https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp",
      "transport": "http"
    }
  }
}

curl "https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp/.mcp/list-tools"

# .env.example — env vars for openapi-typescript + orval.
# Copy to .env:  cp .env.example .env

# URL of the OpenAPI 3.1 spec (codegen input for BOTH tools).
MCP_OPENAPI_URL=https://starwarsnamegenerator.com/mcp-openapi.json

# Base URL of the live MCP endpoint (orval output.baseUrl + runtime client).
MCP_BASE_URL=https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp

# OAuth 2.1 Bearer token — OPTIONAL. Empty for the public server; set only when
# the spec is hosted behind an OAuth-protected server. Sent as:
#   Authorization: Bearer ${MCP_AUTH_TOKEN}
MCP_AUTH_TOKEN=

# ── package.json scripts (read $MCP_OPENAPI_URL) ─────────────────
# "mcp:types":  "openapi-typescript $MCP_OPENAPI_URL -o src/mcp-types.ts --enum"
# "mcp:client": "orval --config ./orval.config.ts"

# ── orval.config.ts (reads env, nothing hard-coded) ──────────────
# input:  { target: process.env.MCP_OPENAPI_URL! }
# output: { baseUrl: process.env.MCP_BASE_URL! }

# ── generated client at runtime (auth only if protected) ─────────
# fetch(`${process.env.MCP_BASE_URL}/.mcp/invoke-tool/${tool}`, {
#   method: "POST",
#   headers: {
#     "Content-Type": "application/json",
#     ...(process.env.MCP_AUTH_TOKEN
#       ? { Authorization: `Bearer ${process.env.MCP_AUTH_TOKEN}` }
#       : {}),
#   },
#   body: JSON.stringify(body),
# });

# openapi-typescript — emit a single .d.ts of typed request/response models.
npm i -D openapi-typescript

# Straight from the hosted spec:
npx openapi-typescript https://starwarsnamegenerator.com/mcp-openapi.json -o src/mcp-types.ts

# Use a generated type, e.g. the generate_star_wars_name request body:
#   import type { components } from "./mcp-types";
#   type GenerateStarWarsNameRequest =
#     components["schemas"]["GenerateStarWarsNameRequest"];

// orval.config.ts — typed client + models from the OpenAPI 3.1 spec.
import { defineConfig } from "orval";

export default defineConfig({
  mcp: {
    input: {
      target: "https://starwarsnamegenerator.com/mcp-openapi.json",
    },
    output: {
      mode: "tags-split",       // one folder per tag (Discovery, Tools)
      target: "src/mcp/client.ts",
      schemas: "src/mcp/model", // request/response models land here
      client: "fetch",          // dependency-free fetch client
      baseUrl: "https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp",
      clean: true,
      prettier: true,
    },
  },
});

# orval — typed fetch client + models from the same spec.
npm i -D orval

# Reads orval.config.ts above:
npx orval --config ./orval.config.ts

# Or one-off without a config file:
npx orval --input https://starwarsnamegenerator.com/mcp-openapi.json \
  --output src/mcp/client.ts --client fetch

# openapi-generator — typed client for any language.
npx @openapitools/openapi-generator-cli generate \
  -i https://starwarsnamegenerator.com/mcp-openapi.json \
  -g typescript-fetch \
  -o ./mcp-client

// mcp-client.ts — fully typed invoke-tool call using openapi-typescript output.
// Generated first with:
//   npx openapi-typescript https://starwarsnamegenerator.com/mcp-openapi.json -o src/mcp-types.ts
import type { components } from "./mcp-types";

type Schemas = components["schemas"];
type GenerateStarWarsNameRequest = Schemas["GenerateStarWarsNameRequest"];
type GenerateStarWarsNameResponse = Schemas["GenerateStarWarsNameResponse"];
type ToolError = Schemas["ToolError"];

const MCP_BASE = "https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp";

async function invokeTool<TReq, TRes>(tool: string, body: TReq): Promise<TRes> {
  const res = await fetch(`${MCP_BASE}/.mcp/invoke-tool/${tool}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = (await res.json()) as ToolError;
    throw new Error(err.error ?? `invoke-tool failed: ${res.status}`);
  }
  return (await res.json()) as TRes;
}

// Request body is checked against the generated schema — wrong fields won't compile.
const result = await invokeTool<GenerateStarWarsNameRequest, GenerateStarWarsNameResponse>(
  "generate_star_wars_name",
  { species: "twilek", gender: "female", count: 5 },
);

// Response is typed too: structuredContent.names is string[].
console.log(result.structuredContent?.names);

// mcp/openapi-client.ts — END-TO-END with openapi-typescript output.
// 1) Generate types:  openapi-typescript $MCP_OPENAPI_URL -o src/mcp-types.ts --enum
// 2) Env (see .env.example): MCP_BASE_URL, MCP_AUTH_TOKEN (optional)
import type { components } from "./mcp-types";

type Schemas = components["schemas"];
type GenerateStarWarsNameRequest = Schemas["GenerateStarWarsNameRequest"];
type GenerateStarWarsNameResponse = Schemas["GenerateStarWarsNameResponse"];
type ToolError = Schemas["ToolError"];

const MCP_BASE_URL = process.env.MCP_BASE_URL!;      // e.g. https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp
const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN;    // undefined on the public server

/** Build headers once — the ONLY correct auth format is Authorization: Bearer <token>. */
function authHeaders(): Record<string, string> {
  return {
    "Content-Type": "application/json",
    // Omit entirely when public; add the Bearer prefix when protected.
    ...(MCP_AUTH_TOKEN ? { Authorization: `Bearer ${MCP_AUTH_TOKEN}` } : {}),
  };
}

async function invokeTool<TReq, TRes>(tool: string, body: TReq): Promise<TRes> {
  const res = await fetch(`${MCP_BASE_URL}/.mcp/invoke-tool/${tool}`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = (await res.json()) as ToolError;
    throw new Error(err.error ?? `invoke-tool failed: ${res.status}`);
  }
  return (await res.json()) as TRes;
}

// Fully typed call — request body AND response are checked at compile time.
const result = await invokeTool<GenerateStarWarsNameRequest, GenerateStarWarsNameResponse>(
  "generate_star_wars_name",
  { species: "twilek", gender: "female", count: 5 },
);
console.log(result.structuredContent?.names); // string[]

// mcp/fetcher.ts — END-TO-END with orval output (custom fetch mutator).
// orval.config.ts:
//   output: {
//     baseUrl: process.env.MCP_BASE_URL!,
//     override: { mutator: { path: "src/mcp/fetcher.ts", name: "customFetch" } },
//   }
// Env (see .env.example): MCP_BASE_URL, MCP_AUTH_TOKEN (optional)

const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN; // undefined on the public server

/** orval calls this for every request; inject the correct Bearer header here. */
export const customFetch = async <T>(url: string, init?: RequestInit): Promise<T> => {
  const res = await fetch(url, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      ...init?.headers,
      // The server only reads Authorization: Bearer <token>; skip when public.
      ...(MCP_AUTH_TOKEN ? { Authorization: `Bearer ${MCP_AUTH_TOKEN}` } : {}),
    },
  });
  if (!res.ok) throw new Error(`invoke-tool failed: ${res.status}`);
  return (await res.json()) as T;
};

// ── Usage (mcp/usage.ts) — import the generated, typed operation ──
// The function name mirrors the spec's operationId; params/response are typed.
import { postMcpInvokeToolGenerateStarWarsName } from "./client";

const result = await postMcpInvokeToolGenerateStarWarsName({
  species: "twilek",
  gender: "female",
  count: 5,
});
console.log(result.structuredContent?.names); // string[]

// ── REQUEST — POST https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1/mcp/.mcp/invoke-tool/generate_star_wars_name
// Matches GenerateStarWarsNameRequest (openapi-typescript) and the generated
// body type for postMcpInvokeToolGenerateStarWarsName (orval). Both accept THIS
// exact JSON — species is required; gender/era/count are optional (count 1–50).
{
  "species": "twilek",
  "gender": "female",
  "era": "imperial",
  "count": 5
}

// ── RESPONSE (200) — matches GenerateStarWarsNameResponse
// content[] is required; structuredContent + isError are optional.
{
  "content": [
    {
      "type": "text",
      "text": "Aayla Secura\nNuala Deenan\nXiaan Amersu\nDrelliad Vao\nHera'toth Nal"
    }
  ],
  "structuredContent": {
    "species": "twilek",
    "gender": "female",
    "era": "imperial",
    "names": [
      "Aayla Secura",
      "Nuala Deenan",
      "Xiaan Amersu",
      "Drelliad Vao",
      "Hera'toth Nal"
    ]
  }
}

// ── ERROR RESPONSE (400/413/429) — matches ToolError
{
  "error": "species must be one of the supported ids"
}

# Mini FAQ — map the error you see to the exact config tweak.
# ("ot" = openapi-typescript, "orval" = orval.config.ts + mutator)

# Q: 401 Unauthorized on every invoke-tool call.
#    Cause: no token, or the header the server reads is missing.
#  ot   -> add the Bearer header to your fetch():
#            headers: { Authorization: `Bearer ${process.env.MCP_AUTH_TOKEN}` }
#  orval-> set the mutator + baseUrl so every request carries it:
#            output: { baseUrl: process.env.MCP_BASE_URL!,
#              override: { mutator: { path: "src/mcp/fetcher.ts", name: "customFetch" } } }

# Q: 403 Forbidden (token is present but rejected).
#    Cause: valid header shape, wrong/expired token or wrong audience.
#  ot   -> read a FRESH token at call time, don't cache a build-time literal:
#            const token = process.env.MCP_AUTH_TOKEN; // re-read per run
#  orval-> refresh inside the mutator so each call gets a live token:
#            headers: { Authorization: `Bearer ${await getToken()}` }

# Q: "invalid token" / malformed Authorization.
#    Cause: missing "Bearer " prefix, extra quotes, or a newline in the value.
#  ot   -> use a template literal, no quotes around the value:
#            Authorization: `Bearer ${token.trim()}`   // NOT "Bearer '${token}'"
#  orval-> same, inside customFetch: `Bearer ${token.trim()}`

# Q: "missing API key" from a client that expects x-api-key.
#    Cause: this server is OAuth-only; x-api-key is never read.
#  ot   -> delete the x-api-key header, send Authorization: Bearer instead.
#  orval-> in the mutator, replace { "api-key": key } with
#            { Authorization: `Bearer ${token}` }

# Q: Requests hit localhost / the wrong host (then 401/404).
#    Cause: tool used the spec's servers[] instead of your endpoint.
#  ot   -> you build the URL yourself: `${process.env.MCP_BASE_URL}/.mcp/invoke-tool/${tool}`
#  orval-> pin it: output: { baseUrl: process.env.MCP_BASE_URL! }

# Q: Header edits don't take effect after regenerating.
#    Cause: stale generated output.
#  orval-> add clean: true to output so it regenerates fresh.
#  ot   -> re-run: openapi-typescript $MCP_OPENAPI_URL -o src/mcp-types.ts --enum

# Generate types from a single tool's JSON Schema — no OpenAPI needed.
# TypeScript (json-schema-to-typescript):
npx json-schema-to-typescript \
  https://starwarsnamegenerator.com/mcp-schemas/generate_star_wars_name.request.json \
  -o GenerateStarWarsNameRequest.d.ts

# Any language (quicktype):
npx quicktype https://starwarsnamegenerator.com/mcp-schemas/generate_star_wars_name.response.json \
  -o GenerateStarWarsNameResponse.ts

# Validate a payload at runtime (ajv):
npx ajv validate \
  -s https://starwarsnamegenerator.com/mcp-schemas/generate_star_wars_name.request.json \
  -d payload.json