callspec 0.1.0

package/dist/mcpTools.d.ts

@@ -0,0 +1,14 @@
+import type { McpRouteConfig, Registry, RouteDef } from './types';
+export declare function isMcpEnabled(route: RouteDef<any, any, any>): boolean;
+export declare function routeMcpName(routeKey: string, route: RouteDef<any, any, any>): string;
+export declare function mcpAnnotations(route: RouteDef<any, any, any>): Record<string, unknown> | undefined;
+export type McpToolListEntry = {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+};
+export declare function listMcpTools(registry: Registry<any>): McpToolListEntry[];
+export type { McpRouteConfig };

package/dist/mcpTools.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMcpEnabled = isMcpEnabled;
+exports.routeMcpName = routeMcpName;
+exports.mcpAnnotations = mcpAnnotations;
+exports.listMcpTools = listMcpTools;
+const runtyp_1 = require("runtyp");
+function isMcpEnabled(route) {
+    return route.mcp !== undefined;
+}
+function routeMcpName(routeKey, route) {
+    if (route.mcp && typeof route.mcp === 'object' && route.mcp.name) {
+        return route.mcp.name;
+    }
+    return routeKey;
+}
+function mcpAnnotations(route) {
+    if (route.mcp && typeof route.mcp === 'object') {
+        return route.mcp.annotations;
+    }
+    return undefined;
+}
+function listMcpTools(registry) {
+    return Object.entries(registry)
+        .filter(([, route]) => isMcpEnabled(route))
+        .map(([key, route]) => {
+        const entry = {
+            name: routeMcpName(key, route),
+            title: route.meta.summary,
+            description: route.meta.description,
+            inputSchema: (0, runtyp_1.toJsonSchema)(route.input),
+        };
+        if (route.output) {
+            entry.outputSchema = (0, runtyp_1.toJsonSchema)(route.output);
+        }
+        const annotations = mcpAnnotations(route);
+        if (annotations)
+            entry.annotations = annotations;
+        return entry;
+    });
+}

package/dist/mountMcp.d.ts

@@ -0,0 +1,13 @@
+import type { Router } from 'express';
+import type { ContextResolver, Registry } from './types';
+export type MountMcpOptions<Ctx> = {
+    path?: string;
+    contextResolver?: ContextResolver<Ctx>;
+    expose?: boolean;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    instructions?: string;
+};
+export declare function mountMcp<Ctx>(router: Router, registry: Registry<Ctx>, options: MountMcpOptions<Ctx>): void;

package/dist/mountMcp.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountMcp = mountMcp;
+const errors_1 = require("./errors");
+const executeRoute_1 = require("./executeRoute");
+const mcpTools_1 = require("./mcpTools");
+function toolError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function mountMcp(router, registry, options) {
+    if (options.expose === false)
+        return;
+    const mcpPath = options.path ?? '/mcp';
+    router.all(mcpPath, (async (req, res) => {
+        const body = req.body;
+        const respond = (result) => {
+            res.json({
+                jsonrpc: '2.0',
+                id: body?.id ?? null,
+                result,
+            });
+        };
+        const respondError = (code, message) => {
+            res.status(code >= 400 ? code : 500).json({
+                jsonrpc: '2.0',
+                id: body?.id ?? null,
+                error: { code, message },
+            });
+        };
+        try {
+            if (body?.method === 'initialize') {
+                respond({
+                    protocolVersion: '2024-11-05',
+                    capabilities: { tools: {} },
+                    serverInfo: options.serverInfo,
+                    instructions: options.instructions,
+                });
+                return;
+            }
+            if (body?.method === 'tools/list') {
+                respond({ tools: (0, mcpTools_1.listMcpTools)(registry) });
+                return;
+            }
+            if (body?.method === 'tools/call') {
+                const toolName = body.params?.name;
+                if (!toolName) {
+                    respond(toolError('Missing tool name'));
+                    return;
+                }
+                const routeEntry = Object.entries(registry).find(([key, route]) => (0, mcpTools_1.routeMcpName)(key, route) === toolName);
+                if (!routeEntry) {
+                    respond(toolError(`Unknown tool: ${toolName}`));
+                    return;
+                }
+                const [, route] = routeEntry;
+                if (!(0, mcpTools_1.isMcpEnabled)(route)) {
+                    respond(toolError(`Tool not exposed: ${toolName}`));
+                    return;
+                }
+                const ctx = options.contextResolver
+                    ? await options.contextResolver(req)
+                    : undefined;
+                try {
+                    const result = await (0, executeRoute_1.executeRoute)(route, body.params?.arguments ?? {}, ctx);
+                    respond({
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        structuredContent: result,
+                    });
+                    return;
+                }
+                catch (err) {
+                    if (err instanceof errors_1.CallspecUnauthorizedError) {
+                        respond(toolError('Unauthorized — Bearer token required'));
+                        return;
+                    }
+                    if (err instanceof errors_1.CallspecValidationError) {
+                        respond(toolError(JSON.stringify(err.errors)));
+                        return;
+                    }
+                    throw err;
+                }
+            }
+            if (body?.method === 'notifications/initialized') {
+                res.status(204).end();
+                return;
+            }
+            respondError(400, `Unsupported method: ${body?.method ?? 'unknown'}`);
+        }
+        catch (err) {
+            if (err instanceof errors_1.CallspecNotFoundError) {
+                respondError(404, err.message);
+                return;
+            }
+            respondError(500, err instanceof Error ? err.message : 'Internal error');
+        }
+    }));
+}

package/dist/mountRegistry.d.ts

@@ -0,0 +1,32 @@
+import type { Router } from 'express';
+import { type OpenApiOptions } from './openapi';
+import type { ContextResolver, Registry } from './types';
+import { type MountCallsheetOptions } from './callsheet/mountCallsheet';
+export type MountRegistryDocsOptions = {
+    /** OpenAPI document metadata. Required to expose docs. */
+    openApi?: OpenApiOptions;
+    /** Serve GET …/openapi.json. Default: true when docs are enabled. */
+    exposeOpenApi?: boolean;
+    /** Serve the callsheet UI at `/docs`. Default: true when docs are enabled. */
+    exposeUi?: boolean;
+    /** OpenAPI JSON path on this router. Default `/openapi.json`. */
+    openApiPath?: string;
+    /** callsheet UI mount path. Default `/docs`. */
+    uiPath?: string;
+    /** Options passed to callsheet (rpcBase override, branding, MCP, etc.). */
+    callsheet?: Pick<MountCallsheetOptions, 'rpcBase' | 'branding' | 'mcpPath' | 'mcp' | 'brandAssetsDir'>;
+};
+export type MountRegistryOptions<Ctx> = {
+    contextResolver?: ContextResolver<Ctx>;
+    /**
+     * @deprecated Use `docs.openApi` with `docs.exposeOpenApi` / `docs.exposeUi`.
+     * When true and `openApi` or `docs.openApi` is set, enables docs surfaces.
+     */
+    exposeDocs?: boolean;
+    /** @deprecated Use `docs.openApi`. */
+    openApi?: OpenApiOptions;
+    /** Docs configuration — OpenAPI spec and/or callsheet UI, each toggled independently. */
+    docs?: MountRegistryDocsOptions | false;
+    basePath?: string;
+};
+export declare function mountRegistry<Ctx>(router: Router, registry: Registry<Ctx>, options?: MountRegistryOptions<Ctx>): void;

package/dist/mountRegistry.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountRegistry = mountRegistry;
+const errors_1 = require("./errors");
+const executeRoute_1 = require("./executeRoute");
+const openapi_1 = require("./openapi");
+const mountCallsheet_1 = require("./callsheet/mountCallsheet");
+function sendError(res, err) {
+    if (err instanceof errors_1.CallspecValidationError) {
+        res.status(400).json({ error: err.message, errors: err.errors });
+        return;
+    }
+    if (err instanceof errors_1.CallspecUnauthorizedError) {
+        res.status(401).send('Unauthorized');
+        return;
+    }
+    throw err;
+}
+function resolveDocsOptions(options) {
+    if (options.docs === false)
+        return false;
+    const legacyEnabled = options.exposeDocs === true;
+    const merged = options.docs ?? {};
+    const openApi = merged.openApi ?? options.openApi;
+    if (!openApi)
+        return false;
+    if (!legacyEnabled && options.docs === undefined && options.exposeDocs === undefined) {
+        return false;
+    }
+    const docsEnabled = legacyEnabled || options.docs !== undefined;
+    return {
+        openApi,
+        exposeOpenApi: merged.exposeOpenApi ?? (docsEnabled ? true : false),
+        exposeUi: merged.exposeUi ?? (docsEnabled ? true : false),
+        openApiPath: merged.openApiPath ?? '/openapi.json',
+        uiPath: merged.uiPath ?? '/docs',
+        callsheet: merged.callsheet,
+    };
+}
+function mountRegistry(router, registry, options = {}) {
+    const basePath = options.basePath ?? '';
+    const docs = resolveDocsOptions(options);
+    if (docs && docs.openApi && docs.exposeOpenApi !== false) {
+        const openApiPath = docs.openApiPath ?? '/openapi.json';
+        router.get(`${basePath}${openApiPath}`, (_req, res) => {
+            res.json((0, openapi_1.emitOpenApi)(registry, {
+                ...docs.openApi,
+                basePath,
+            }));
+        });
+    }
+    if (docs && docs.exposeUi !== false) {
+        const uiPath = docs.uiPath ?? '/docs';
+        const openApiPath = docs.openApiPath ?? '/openapi.json';
+        const specPath = openApiPath.startsWith('/')
+            ? `..${openApiPath}`
+            : openApiPath;
+        (0, mountCallsheet_1.mountCallsheet)(router, {
+            path: `${basePath}${uiPath}`.replace(/\/{2,}/g, '/') || '/docs',
+            specPath,
+            rpcBase: docs.callsheet?.rpcBase ?? '..',
+            title: docs.openApi?.title,
+            branding: docs.callsheet?.branding,
+            mcpPath: docs.callsheet?.mcpPath,
+            mcp: docs.callsheet?.mcp,
+            brandAssetsDir: docs.callsheet?.brandAssetsDir,
+        });
+    }
+    for (const [name, route] of Object.entries(registry)) {
+        router.post(`${basePath}/${name}`, (async (req, res, next) => {
+            try {
+                const ctx = options.contextResolver
+                    ? await options.contextResolver(req)
+                    : undefined;
+                const response = await (0, executeRoute_1.executeRoute)(route, req.body, ctx);
+                res.json(response);
+            }
+            catch (err) {
+                try {
+                    sendError(res, err);
+                }
+                catch (rethrow) {
+                    next(rethrow);
+                }
+            }
+        }));
+    }
+}

package/dist/openapi.d.ts

@@ -0,0 +1,8 @@
+import type { Registry } from './types';
+export type OpenApiOptions = {
+    title: string;
+    version: string;
+    basePath?: string;
+    security?: Array<Record<string, string[]>>;
+};
+export declare function emitOpenApi(registry: Registry<any>, options: OpenApiOptions): Record<string, unknown>;

package/dist/openapi.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitOpenApi = emitOpenApi;
+const runtyp_1 = require("runtyp");
+function routePath(basePath, name) {
+    return `${basePath}/${name}`.replace(/\/{2,}/g, '/');
+}
+function emitOpenApi(registry, options) {
+    const paths = {};
+    const basePath = options.basePath ?? '';
+    for (const [name, route] of Object.entries(registry)) {
+        paths[routePath(basePath, name)] = {
+            post: {
+                operationId: name,
+                summary: route.meta.summary,
+                description: route.meta.description,
+                tags: [...route.meta.tags],
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: (0, runtyp_1.toJsonSchema)(route.input),
+                        },
+                    },
+                },
+                responses: {
+                    200: {
+                        description: 'Success',
+                        content: route.output ? {
+                            'application/json': {
+                                schema: (0, runtyp_1.toJsonSchema)(route.output),
+                            },
+                        } : {
+                            'application/json': {
+                                schema: { type: 'object' },
+                            },
+                        },
+                    },
+                    401: { description: 'Unauthorized' },
+                    400: { description: 'Validation error' },
+                },
+                ...(route.access === 'private' && options.security ? { security: options.security } : {}),
+                'x-callspec-access': route.access,
+                ...(route.mcp ? { 'x-callspec-mcp': true } : {}),
+            },
+        };
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: options.title,
+            version: options.version,
+        },
+        paths,
+    };
+}

package/dist/serializer.d.ts

@@ -0,0 +1,2 @@
+export declare function serializeResponse(data: unknown): unknown;
+export declare function deserializeResponse(data: unknown): unknown;

package/dist/serializer.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeResponse = serializeResponse;
+exports.deserializeResponse = deserializeResponse;
+function serializeResponse(data) {
+    if (data === null || data === undefined)
+        return data;
+    if (data instanceof Date) {
+        return {
+            __type: 'Date',
+            value: data.toISOString(),
+        };
+    }
+    if (Array.isArray(data))
+        return data.map(serializeResponse);
+    if (typeof data === 'object') {
+        const serialized = {};
+        for (const [key, value] of Object.entries(data)) {
+            serialized[key] = serializeResponse(value);
+        }
+        return serialized;
+    }
+    return data;
+}
+function deserializeResponse(data) {
+    if (data === null || data === undefined)
+        return data;
+    if (typeof data === 'object'
+        && data !== null
+        && '__type' in data
+        && data.__type === 'Date'
+        && 'value' in data) {
+        return new Date(data.value);
+    }
+    if (Array.isArray(data))
+        return data.map(deserializeResponse);
+    if (typeof data === 'object') {
+        const deserialized = {};
+        for (const [key, value] of Object.entries(data)) {
+            deserialized[key] = deserializeResponse(value);
+        }
+        return deserialized;
+    }
+    return data;
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+import type { Request } from 'express';
+import type { Pred } from 'runtyp';
+export type RouteMeta = {
+    summary: string;
+    description: string;
+    tags: readonly string[];
+};
+export type McpRouteConfig = true | {
+    name?: string;
+    annotations?: Record<string, unknown>;
+};
+export type RouteAccess = 'public' | 'private';
+export type RouteHandler<TInput, TOutput, Ctx> = (input: TInput, ctx: Ctx) => Promise<TOutput> | TOutput;
+export type RouteDef<TInput = unknown, TOutput = unknown, Ctx = unknown> = {
+    input: Pred<TInput>;
+    output?: Pred<TOutput>;
+    meta: RouteMeta;
+    access: RouteAccess;
+    mcp?: McpRouteConfig;
+    handler: RouteHandler<TInput, TOutput, Ctx>;
+};
+export type Registry<Ctx = unknown> = Record<string, RouteDef<any, any, Ctx>>;
+export type ContextResolver<Ctx> = (req: Request) => Ctx | Promise<Ctx | undefined> | Ctx | undefined;
+export type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+export type InferRouteInput<R extends RouteDef<any, any, any>> = R extends RouteDef<infer I, any, any> ? I : never;
+export type InferRouteOutput<R extends RouteDef<any, any, any>> = R extends {
+    output: Pred<infer O>;
+} ? O : UnwrapPromise<ReturnType<R['handler']>>;
+export type InferRegistry<T extends Registry<any>> = {
+    [K in keyof T]: {
+        name: K & string;
+        input: InferRouteInput<T[K]>;
+        output: InferRouteOutput<T[K]>;
+    };
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "callspec",
+  "version": "0.1.0",
+  "description": "Registry-first RPC: HTTP, OpenAPI docs, MCP, and typed client from one defineRoute registry",
+  "keywords": [
+    "rpc",
+    "openapi",
+    "mcp",
+    "express",
+    "typescript",
+    "api",
+    "registry"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/logfoxai/callspec.git"
+  },
+  "homepage": "https://github.com/logfoxai/callspec",
+  "license": "MIT",
+  "author": "Marc H. Weiner <mhweiner234@gmail.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "assets",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "npm run build:server && npm run build:ui",
+    "build:server": "tsc",
+    "build:ui": "node scripts/build-callsheet-ui.mjs",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "test": "kizu 'src/**/*.spec.ts'",
+    "dev:docs": "node scripts/dev-docs.cjs",
+    "validate": "npm run check:package-json && npm run build && npm run lint && npm test",
+    "check:package-json": "node scripts/check-no-file-deps.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "highlight.js": "11.11.1",
+    "runtyp": "2.5.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.17",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.0.0",
+    "express": "^4.18.2",
+    "kizu": "^4.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^8.0.0"
+  }
+}