@ontrails/mcp 1.0.0-beta.14 → 1.0.0-beta.16

package/src/__tests__/progress.test.ts

@@ -1,136 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { McpExtra } from '../build.js';
-import { createMcpProgressCallback } from '../progress.js';
-
-describe('createMcpProgressCallback', () => {
-  test('returns undefined when no progressToken', () => {
-    const extra: McpExtra = {};
-    expect(createMcpProgressCallback(extra)).toBeUndefined();
-  });
-
-  test('returns undefined when no sendProgress function', () => {
-    const extra: McpExtra = { progressToken: 'tok-1' };
-    expect(createMcpProgressCallback(extra)).toBeUndefined();
-  });
-
-  test('sends 0/1 for start events', () => {
-    const calls: [number, number][] = [];
-    const extra: McpExtra = {
-      progressToken: 'tok-1',
-      sendProgress: (current, total) => {
-        calls.push([current, total]);
-        return Promise.resolve();
-      },
-    };
-
-    const cb = createMcpProgressCallback(extra);
-    expect(cb).toBeDefined();
-
-    const callback = cb as NonNullable<typeof cb>;
-    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
-    callback({
-      ts: new Date().toISOString(),
-      type: 'start',
-    });
-
-    expect(calls).toEqual([[0, 1]]);
-  });
-
-  test('sends progress notification for progress events', () => {
-    const calls: [number, number][] = [];
-    const extra: McpExtra = {
-      progressToken: 'tok-1',
-      sendProgress: (current, total) => {
-        calls.push([current, total]);
-        return Promise.resolve();
-      },
-    };
-
-    const cb = createMcpProgressCallback(extra);
-    expect(cb).toBeDefined();
-    const callback = cb as NonNullable<typeof cb>;
-
-    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
-    callback({
-      current: 5,
-      total: 10,
-      ts: new Date().toISOString(),
-      type: 'progress',
-    });
-
-    expect(calls).toEqual([[5, 10]]);
-  });
-
-  test('sends 1/1 for complete events', () => {
-    const calls: [number, number][] = [];
-    const extra: McpExtra = {
-      progressToken: 'tok-1',
-      sendProgress: (current, total) => {
-        calls.push([current, total]);
-        return Promise.resolve();
-      },
-    };
-
-    const cb = createMcpProgressCallback(extra);
-    expect(cb).toBeDefined();
-    const callback = cb as NonNullable<typeof cb>;
-
-    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
-    callback({
-      ts: new Date().toISOString(),
-      type: 'complete',
-    });
-
-    expect(calls).toEqual([[1, 1]]);
-  });
-
-  test('does not send for error events', () => {
-    const calls: [number, number][] = [];
-    const extra: McpExtra = {
-      progressToken: 'tok-1',
-      sendProgress: (current, total) => {
-        calls.push([current, total]);
-        return Promise.resolve();
-      },
-    };
-
-    const cb = createMcpProgressCallback(extra);
-    expect(cb).toBeDefined();
-    const callback = cb as NonNullable<typeof cb>;
-
-    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
-    callback({
-      message: 'something broke',
-      ts: new Date().toISOString(),
-      type: 'error',
-    });
-
-    expect(calls).toEqual([]);
-  });
-
-  test('handles missing total gracefully', () => {
-    const calls: [number, number][] = [];
-    const extra: McpExtra = {
-      progressToken: 'tok-1',
-      sendProgress: (current, total) => {
-        calls.push([current, total]);
-        return Promise.resolve();
-      },
-    };
-
-    const cb = createMcpProgressCallback(extra);
-    expect(cb).toBeDefined();
-    const callback = cb as NonNullable<typeof cb>;
-
-    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
-    callback({
-      current: 3,
-      ts: new Date().toISOString(),
-      type: 'progress',
-    });
-
-    // Sends current with 0 as indeterminate total
-    expect(calls).toEqual([[3, 0]]);
-  });
-});

package/src/__tests__/tool-name.test.ts

@@ -1,46 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { deriveToolName } from '../tool-name.js';
-
-describe('deriveToolName', () => {
-  test('replaces dots with underscores', () => {
-    expect(deriveToolName('myapp', 'entity.show')).toBe('myapp_entity_show');
-  });
-
-  test('prefixes with app name', () => {
-    expect(deriveToolName('myapp', 'search')).toBe('myapp_search');
-  });
-
-  test('handles multiple dots', () => {
-    expect(deriveToolName('myapp', 'entity.onboard')).toBe(
-      'myapp_entity_onboard'
-    );
-  });
-
-  test('replaces hyphens with underscores', () => {
-    expect(deriveToolName('my-app', 'some-trail')).toBe('my_app_some_trail');
-  });
-
-  test('lowercases everything', () => {
-    expect(deriveToolName('MyApp', 'Entity.Show')).toBe('myapp_entity_show');
-  });
-
-  test('handles single-segment trail IDs', () => {
-    expect(deriveToolName('dispatch', 'search')).toBe('dispatch_search');
-  });
-
-  test('handles dots in app name', () => {
-    expect(deriveToolName('my.app', 'trail')).toBe('my_app_trail');
-  });
-
-  test('matches spec examples', () => {
-    expect(deriveToolName('myapp', 'entity.show')).toBe('myapp_entity_show');
-    expect(deriveToolName('myapp', 'search')).toBe('myapp_search');
-    expect(deriveToolName('myapp', 'entity.onboard')).toBe(
-      'myapp_entity_onboard'
-    );
-    expect(deriveToolName('dispatch', 'patch.search')).toBe(
-      'dispatch_patch_search'
-    );
-  });
-});

package/src/__tests__/trailhead.test.ts

@@ -1,158 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { Result, trail, topo } from '@ontrails/core';
-import { z } from 'zod';
-
-import { trailhead, createMcpServer } from '../trailhead.js';
-import { buildMcpTools } from '../build.js';
-import type { McpToolDefinition } from '../build.js';
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-const requireTool = (tools: McpToolDefinition[], name: string) => {
-  const tool = tools.find((entry) => entry.name === name);
-  expect(tool).toBeDefined();
-  if (!tool) {
-    throw new Error(`Expected tool: ${name}`);
-  }
-  return tool;
-};
-
-/**
- * Unwrap buildMcpTools result, throwing on error so test failures show up clearly.
- */
-const buildTools = (
-  ...args: Parameters<typeof buildMcpTools>
-): McpToolDefinition[] => {
-  const result = buildMcpTools(...args);
-  if (result.isErr()) {
-    throw result.error;
-  }
-  return result.value;
-};
-
-const createIntegrationTools = () => {
-  const greetTrail = trail('greet', {
-    blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
-    description: 'Greet someone',
-    input: z.object({ name: z.string() }),
-    intent: 'read',
-  });
-
-  const deleteTrail = trail('item.delete', {
-    blaze: (_input) => Result.ok({ deleted: true }),
-    description: 'Delete an item',
-    input: z.object({ id: z.string() }),
-    intent: 'destroy',
-  });
-
-  return buildTools(topo('myapp', { deleteTrail, greetTrail }));
-};
-
-describe('trailhead', () => {
-  test('trailhead throws on invalid topo', async () => {
-    const t = trail('broken', {
-      blaze: () => Result.ok({}),
-      crosses: ['nonexistent.trail'],
-      input: z.object({}),
-      output: z.object({}),
-    });
-    const app = topo('test', { t });
-    await expect(trailhead(app)).rejects.toThrow(/validation/i);
-  });
-
-  test('trailhead skips validation when validate: false', async () => {
-    const t = trail('broken', {
-      blaze: () => Result.ok({}),
-      crosses: ['nonexistent.trail'],
-      input: z.object({}),
-      output: z.object({}),
-    });
-    const app = topo('test', { t });
-    const result = await Promise.race([
-      trailhead(app, { validate: false }).then(() => 'resolved' as const),
-      // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based timeout
-      new Promise<'timeout'>((resolve) => {
-        setTimeout(() => {
-          resolve('timeout');
-        }, 50);
-      }),
-    ]);
-    expect(['resolved', 'timeout']).toContain(result);
-  });
-
-  test('TrailheadMcpOptions accepts provision overrides', () => {
-    const opts: Parameters<typeof trailhead>[1] = {
-      provisions: {},
-      validate: false,
-    };
-    expect(opts.provisions).toEqual({});
-  });
-
-  test('createMcpServer registers tools that can be listed', () => {
-    const echoTrail = trail('echo', {
-      blaze: (input) => Result.ok({ reply: input.message }),
-      description: 'Echo',
-      input: z.object({ message: z.string() }),
-      intent: 'read',
-    });
-
-    const app = topo('testapp', { echoTrail });
-    const tools = buildTools(app);
-    const server = createMcpServer(tools, {
-      name: 'testapp',
-      version: '0.1.0',
-    });
-
-    // Server is created successfully
-    expect(server).toBeDefined();
-  });
-
-  test('createMcpServer handles multiple tools', () => {
-    const echoTrail = trail('echo', {
-      blaze: (input) => Result.ok({ reply: input.message }),
-      description: 'Echo',
-      input: z.object({ message: z.string() }),
-    });
-
-    const searchTrail = trail('search', {
-      blaze: (input) => Result.ok({ results: [input.query] }),
-      description: 'Search',
-      input: z.object({ query: z.string() }),
-      intent: 'read',
-    });
-
-    const app = topo('testapp', { echoTrail, searchTrail });
-    const tools = buildTools(app);
-
-    expect(tools).toHaveLength(2);
-
-    const server = createMcpServer(tools, {
-      name: 'testapp',
-      version: '0.1.0',
-    });
-    expect(server).toBeDefined();
-  });
-
-  test('buildMcpTools + createMcpServer integration', () => {
-    const tools = createIntegrationTools();
-    const names = tools.map((t) => t.name);
-    expect(names).toContain('myapp_greet');
-    expect(names).toContain('myapp_item_delete');
-
-    expect(requireTool(tools, 'myapp_greet').annotations?.readOnlyHint).toBe(
-      true
-    );
-    expect(
-      requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
-    ).toBe(true);
-
-    const server = createMcpServer(tools, {
-      name: 'myapp',
-      version: '1.0.0',
-    });
-    expect(server).toBeDefined();
-  });
-});

package/src/trailhead.ts

@@ -1,173 +0,0 @@
-/**
- * trailhead() -- the one-liner MCP server launcher.
- *
- * Three lines to expose trails as MCP tools:
- *
- * ```ts
- * const app = topo("myapp", entity);
- * await trailhead(app);
- * ```
- */
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
-import type {
-  Gate,
-  ProvisionOverrideMap,
-  Topo,
-  TrailContextInit,
-} from '@ontrails/core';
-import { validateEstablishedTopo } from '@ontrails/core';
-
-import type { McpToolDefinition } from './build.js';
-import { buildMcpTools } from './build.js';
-import { connectStdio } from './stdio.js';
-
-// ---------------------------------------------------------------------------
-// Options
-// ---------------------------------------------------------------------------
-
-export interface TrailheadMcpOptions {
-  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
-  readonly configValues?:
-    | Readonly<Record<string, Record<string, unknown>>>
-    | undefined;
-  readonly createContext?:
-    | (() => TrailContextInit | Promise<TrailContextInit>)
-    | undefined;
-  readonly excludeTrails?: readonly string[] | undefined;
-  readonly includeTrails?: readonly string[] | undefined;
-  readonly gates?: readonly Gate[] | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
-  readonly serverInfo?:
-    | {
-        readonly name?: string | undefined;
-        readonly version?: string | undefined;
-      }
-    | undefined;
-  readonly transport?: 'stdio' | undefined;
-  /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
-  readonly validate?: boolean | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Internal: create MCP server with tool handlers
-// ---------------------------------------------------------------------------
-
-/**
- * Create an MCP Server instance and register all tools.
- */
-export const createMcpServer = (
-  tools: McpToolDefinition[],
-  info: { readonly name: string; readonly version: string }
-): Server => {
-  const server = new Server(
-    { name: info.name, version: info.version },
-    { capabilities: { tools: {} } }
-  );
-
-  // Build a lookup map for tool dispatch
-  const toolMap = new Map<string, McpToolDefinition>();
-  for (const tool of tools) {
-    toolMap.set(tool.name, tool);
-  }
-
-  // Register tools/list handler
-  // oxlint-disable-next-line require-await -- MCP SDK requires async handler
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map((t) => ({
-      annotations: t.annotations,
-      description: t.description,
-      inputSchema: t.inputSchema,
-      name: t.name,
-    })),
-  }));
-
-  // Register tools/call handler
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const tool = toolMap.get(request.params.name);
-    if (tool === undefined) {
-      return {
-        content: [
-          {
-            text: `Unknown tool: ${request.params.name}`,
-            type: 'text' as const,
-          },
-        ],
-        isError: true,
-      } as Record<string, unknown>;
-    }
-
-    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
-    const progressToken = request.params._meta?.progressToken;
-
-    const sendProgress =
-      progressToken === undefined
-        ? undefined
-        : async (current: number, total: number) => {
-            await server.notification({
-              method: 'notifications/progress',
-              params: {
-                progress: current,
-                progressToken: progressToken,
-                total,
-              },
-            });
-          };
-
-    const extra = {
-      abortSignal: undefined as AbortSignal | undefined,
-      progressToken,
-      sendProgress,
-    };
-
-    const result = await tool.handler(args, extra);
-    // Spread to satisfy MCP SDK's index-signature requirement
-    return { ...result } as Record<string, unknown>;
-  });
-
-  return server;
-};
-
-// ---------------------------------------------------------------------------
-// trailhead
-// ---------------------------------------------------------------------------
-
-/**
- * Build MCP tools from an App, create a server, and connect via stdio.
- */
-export const trailhead = async (
-  app: Topo,
-  options: TrailheadMcpOptions = {}
-): Promise<void> => {
-  if (options.validate !== false) {
-    const validated = validateEstablishedTopo(app);
-    if (validated.isErr()) {
-      throw validated.error;
-    }
-  }
-
-  const toolsResult = buildMcpTools(app, {
-    configValues: options.configValues,
-    createContext: options.createContext,
-    excludeTrails: options.excludeTrails,
-    gates: options.gates,
-    includeTrails: options.includeTrails,
-    provisions: options.provisions,
-    validate: options.validate,
-  });
-
-  if (toolsResult.isErr()) {
-    throw toolsResult.error;
-  }
-
-  const server = createMcpServer(toolsResult.value, {
-    name: options.serverInfo?.name ?? app.name,
-    version: options.serverInfo?.version ?? '0.1.0',
-  });
-
-  await connectStdio(server);
-};

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/annotations.ts","./src/build.ts","./src/index.ts","./src/progress.ts","./src/stdio.ts","./src/tool-name.ts","./src/trailhead.ts"],"version":"5.9.3"}