Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

8.6 KB
Raw Blame
// the Model Context Protocol's JSON-RPC envelope over Streamable HTTP, for a stateless, tools-only server that serves
// the handshake-based revisions Claude's hosted apps speak and the per-request revision 2026-07-28 on one endpoint

export const MODERN_VERSION = '2026-07-28';
// newest first; initialize answers with the client's version when it is one of these, otherwise the newest
export const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'] as const;
export const SUPPORTED_VERSIONS: readonly string[] = [MODERN_VERSION, ...LEGACY_VERSIONS];
// the transport spec says a request with no version header comes from a 2025-03-26 client
const UNNAMED_LEGACY_VERSION = '2025-03-26';

const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';

// JSON-RPC's own codes, then the two the MCP transport adds
export const RPC_ERROR = {
    parse: -32700,
    invalidRequest: -32600,
    methodNotFound: -32601,
    invalidParams: -32602,
    internal: -32603,
    headerMismatch: -32020,
    unsupportedVersion: -32022,
} as const;

export type JsonRpcId = string | number;
export type JsonObject = Record<string, unknown>;

// a request has an id and expects a reply; a notification has none and gets 202
export interface RpcMessage {
    id: JsonRpcId | null;
    method: string;
    params: JsonObject;
}

export interface RpcError {
    code: number;
    message: string;
    data?: unknown;
}

export type RpcResponse =
    | { jsonrpc: '2.0'; id: JsonRpcId | null; result: unknown }
    | { jsonrpc: '2.0'; id: JsonRpcId | null; error: RpcError };

// what the endpoint sends back: the HTTP status and a JSON body, or none for an accepted notification
export interface McpReply {
    status: number;
    body: RpcResponse | null;
}

// legacy requests follow the initialize handshake's rules; modern ones carry their version in _meta and in headers
export type Era = { kind: 'legacy'; version: string } | { kind: 'modern'; version: string };

// the request headers the transport reads, already looked up by name; undefined when absent
export interface McpHeaders {
    protocolVersion?: string;
    method?: string;
    name?: string;
}

export interface ServerIdentity {
    name: string;
    title: string;
    version: string;
    instructions: string;
}

function isObject(value: unknown): value is JsonObject {
    return typeof value === 'object' && value !== null && !Array.isArray(value);
}

export function resultReply(id: JsonRpcId | null, result: unknown, status = 200): McpReply {
    return { status, body: { jsonrpc: '2.0', id, result } };
}

export function errorReply(id: JsonRpcId | null, code: number, message: string, status: number, data?: unknown): McpReply {
    return { status, body: { jsonrpc: '2.0', id, error: data === undefined ? { code, message } : { code, message, data } } };
}

// one message per POST; batches were removed from the protocol in 2025-06-18, and clients never send responses
export function parseMessage(body: unknown): RpcMessage | McpReply {
    if (!isObject(body) || body.jsonrpc !== '2.0') {
        return errorReply(null, RPC_ERROR.invalidRequest, 'Send one JSON-RPC 2.0 request or notification per POST.', 400);
    }
    const { id, method, params } = body;
    const validId = id === undefined || typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id));
    if (typeof method !== 'string' || method === '' || !validId) {
        return errorReply(null, RPC_ERROR.invalidRequest, 'A JSON-RPC request needs a method name and a string or number id.', 400);
    }
    if (params !== undefined && !isObject(params)) {
        return errorReply(id ?? null, RPC_ERROR.invalidParams, 'params must be an object.', 400);
    }
    return { id: id ?? null, method, params: params ?? {} };
}

export function isReply(value: RpcMessage | McpReply): value is McpReply {
    return 'status' in value;
}

// a value the client could not send as a plain header arrives as =?base64?<value>?=
export function decodeHeaderValue(value: string): string | null {
    const encoded = /^=\?base64\?([A-Za-z0-9+/]*={0,2})\?=$/i.exec(value);
    if (!encoded) return value;
    try {
        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(Uint8Array.from(atob(encoded[1]), char => char.charCodeAt(0)));
    } catch {
        // not base64 or not UTF-8, so it cannot match anything in the body
        return null;
    }
}

// a request carrying the version in _meta is modern; anything else follows the version its header names
export function requestEra(message: RpcMessage, headers: McpHeaders): Era {
    const meta = isObject(message.params._meta) ? message.params._meta : {};
    const metaVersion = meta[META_VERSION];
    if (typeof metaVersion === 'string') return { kind: 'modern', version: metaVersion };
    return { kind: 'legacy', version: headers.protocolVersion ?? UNNAMED_LEGACY_VERSION };
}

// what makes a request unusable before its method runs: an unknown version, or headers that disagree with the body
export function checkEnvelope(message: RpcMessage, era: Era, headers: McpHeaders): McpReply | null {
    if (era.kind === 'legacy') {
        // initialize names its version in the body and is answered with one we support, so only later requests are checked
        if (message.method === 'initialize' || (LEGACY_VERSIONS as readonly string[]).includes(era.version)) return null;
        return unsupportedVersion(message.id, era.version);
    }
    if (era.version !== MODERN_VERSION) return unsupportedVersion(message.id, era.version);
    if (headers.protocolVersion !== era.version) return headerMismatch(message.id, 'MCP-Protocol-Version', headers.protocolVersion, era.version);
    if (message.id !== null && headers.method !== message.method) return headerMismatch(message.id, 'Mcp-Method', headers.method, message.method);
    if (message.method === 'tools/call') {
        const name = typeof message.params.name === 'string' ? message.params.name : undefined;
        const sent = headers.name === undefined ? undefined : decodeHeaderValue(headers.name) ?? undefined;
        if (sent !== name) return headerMismatch(message.id, 'Mcp-Name', headers.name, name);
    }
    return null;
}

function unsupportedVersion(id: JsonRpcId | null, requested: string): McpReply {
    return errorReply(id, RPC_ERROR.unsupportedVersion, 'Unsupported protocol version', 400, { supported: SUPPORTED_VERSIONS, requested });
}

function headerMismatch(id: JsonRpcId | null, header: string, sent: string | undefined, expected: string | undefined): McpReply {
    const message = sent === undefined
        ? `Header mismatch: the ${header} header is missing`
        : `Header mismatch: ${header} header value '${sent}' does not match body value '${expected ?? ''}'`;
    return errorReply(id, RPC_ERROR.headerMismatch, message, 400);
}

// modern servers answer an unknown method with 404 so intermediaries can tell it apart from a bad request
export function methodNotFound(message: RpcMessage, era: Era): McpReply {
    return errorReply(message.id, RPC_ERROR.methodNotFound, `Unknown method: ${message.method}`, era.kind === 'modern' ? 404 : 200);
}

export function negotiateLegacyVersion(requested: unknown): string {
    return typeof requested === 'string' && (LEGACY_VERSIONS as readonly string[]).includes(requested) ? requested : LEGACY_VERSIONS[0];
}

export function initializeResult(params: JsonObject, server: ServerIdentity): JsonObject {
    return {
        protocolVersion: negotiateLegacyVersion(params.protocolVersion),
        capabilities: { tools: { listChanged: false } },
        serverInfo: { name: server.name, title: server.title, version: server.version },
        instructions: server.instructions,
    };
}

// cached privately per client for an hour: the tool list depends on what the caller is allowed to do
const DISCOVERY_TTL_MS = 60 * 60 * 1000;

export function discoverResult(server: ServerIdentity): JsonObject {
    return {
        resultType: 'complete',
        supportedVersions: SUPPORTED_VERSIONS,
        capabilities: { tools: {} },
        _meta: { [META_SERVER_INFO]: { name: server.name, title: server.title, version: server.version } },
        instructions: server.instructions,
        ttlMs: DISCOVERY_TTL_MS,
        cacheScope: 'private',
    };
}

// modern results say they are complete, and list results say how long and for whom they may be cached
export function eraResult(era: Era, result: JsonObject, cacheable = false): JsonObject {
    if (era.kind === 'legacy') return result;
    return cacheable ? { resultType: 'complete', ...result, ttlMs: DISCOVERY_TTL_MS, cacheScope: 'private' } : { resultType: 'complete', ...result };
}