typescript-sdk/scripts/fetch-spec-types.ts

import { writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import * as prettier from 'prettier';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const PROJECT_ROOT = join(__dirname, '..');

/**
 * The protocol revisions the SDK keeps reference types for:
 * - `2025-11-25`: the frozen, released schema.
 * - `2026-07-28`: the upcoming protocol revision.
 *
 * Each is written to `packages/core-internal/src/types/spec.types.<version>.ts`.
 */
const SUPPORTED_VERSIONS = ['2025-11-25', '2026-07-28'] as const;
type SpecVersion = (typeof SUPPORTED_VERSIONS)[number];

/**
 * Upstream schema directory per revision. Until the 2026-07-28 revision is
 * published, its schema lives in the spec repository's draft directory; this
 * mapping drops once `schema/2026-07-28/` exists upstream.
 */
const UPSTREAM_SCHEMA_DIRS: Record<SpecVersion, string> = {
    '2025-11-25': '2025-11-25',
    '2026-07-28': 'draft'
};

/**
 * Generation pin per released revision. Released revisions are frozen: without
 * an explicit SHA argument, their types are regenerated from the pinned spec
 * commit below — never from the latest upstream commit — so a released anchor
 * can only change through a deliberate, reviewed repin. Moving a pin (or
 * freezing a newly released revision) must land in the same commit that
 * retargets `.github/workflows/update-spec-types.yml`.
 *
 * Draft-tracking revisions have no entry and float to the latest upstream
 * commit via the nightly workflow's refresh PRs.
 *
 * See `packages/core-internal/src/types/README.md` for the full lifecycle policy.
 */
const RELEASED_REVISION_PINS: Partial<Record<SpecVersion, string>> = {
    '2025-11-25': '0168c57fc74aba6e6dcf8f0b7191db3caaa5ad65'
};

interface GitHubCommit {
    sha: string;
}

async function fetchLatestSHA(version: SpecVersion): Promise<string> {
    const url = `https://api.github.com/repos/modelcontextprotocol/modelcontextprotocol/commits?path=schema/${UPSTREAM_SCHEMA_DIRS[version]}/schema.ts&per_page=1`;

    const response = await fetch(url);
    if (!response.ok) {
        throw new Error(`Failed to fetch commit info: ${response.status} ${response.statusText}`);
    }

    const commits = (await response.json()) as GitHubCommit[];
    if (!commits || commits.length === 0) {
        throw new Error('No commits found');
    }

    return commits[0].sha;
}

async function fetchSpecTypes(version: SpecVersion, sha: string): Promise<string> {
    const url = `https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/${sha}/schema/${UPSTREAM_SCHEMA_DIRS[version]}/schema.ts`;

    const response = await fetch(url);
    if (!response.ok) {
        throw new Error(`Failed to fetch spec types: ${response.status} ${response.statusText}`);
    }

    return await response.text();
}

async function updateSpecTypes(version: SpecVersion, providedSHA?: string): Promise<void> {
    const pinnedSHA = RELEASED_REVISION_PINS[version];
    let sha: string;
    if (providedSHA) {
        console.log(`[${version}] Using provided SHA: ${providedSHA}`);
        sha = providedSHA;
    } else if (pinnedSHA) {
        console.log(`[${version}] Using pinned SHA for released revision: ${pinnedSHA}`);
        sha = pinnedSHA;
    } else {
        console.log(`[${version}] Fetching latest commit SHA...`);
        sha = await fetchLatestSHA(version);
    }

    console.log(`[${version}] Fetching schema.ts from commit: ${sha}`);

    const specContent = await fetchSpecTypes(version, sha);

    // Read header template
    const headerTemplate = `/**
 * This file is automatically generated from the Model Context Protocol specification.
 *
 * Source: https://github.com/modelcontextprotocol/modelcontextprotocol
 * Pulled from: https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/{SCHEMA_DIR}/schema.ts
 * Last updated from commit: {SHA}
 *
 * DO NOT EDIT THIS FILE MANUALLY. Changes will be overwritten by automated updates.
 * To update this file, run: pnpm run fetch:spec-types {VERSION}
 */`;

    const header = headerTemplate.replaceAll('{VERSION}', version).replaceAll('{SCHEMA_DIR}', UPSTREAM_SCHEMA_DIRS[version]).replace('{SHA}', sha);

    // Combine header and content
    const fullContent = header + specContent;

    // Format with prettier using the project's config so the output passes lint
    const outputPath = join(PROJECT_ROOT, 'packages', 'core-internal', 'src', 'types', `spec.types.${version}.ts`);
    const prettierConfig = await prettier.resolveConfig(outputPath);
    const formatted = await prettier.format(fullContent, { ...prettierConfig, filepath: outputPath });

    writeFileSync(outputPath, formatted, 'utf-8');

    console.log(`[${version}] Successfully updated packages/core-internal/src/types/spec.types.${version}.ts`);
}

function isSupportedVersion(value: string): value is SpecVersion {
    return (SUPPORTED_VERSIONS as readonly string[]).includes(value);
}

async function main() {
    try {
        // Usage: fetch-spec-types.ts [version] [sha]
        // With no version, all supported versions are fetched at their latest upstream SHA.
        const providedVersion = process.argv[2];
        const providedSHA = process.argv[3];

        if (providedVersion === undefined) {
            for (const version of SUPPORTED_VERSIONS) {
                await updateSpecTypes(version);
            }
            return;
        }

        if (!isSupportedVersion(providedVersion)) {
            throw new Error(`Unsupported version "${providedVersion}". Supported versions: ${SUPPORTED_VERSIONS.join(', ')}`);
        }

        await updateSpecTypes(providedVersion, providedSHA);
    } catch (error) {
        console.error('Error:', error instanceof Error ? error.message : String(error));
        process.exit(1);
    }
}

main();