@pepys/api 0.0.1 → 0.1.0

package/README.md

@@ -13,7 +13,7 @@
 
 The pepys API, for Bun: typed queries over the store that the host writes.
 
-A deployment serves the core queries and each plug-in's queries over oRPC.
+A deployment serves the core queries and each plug-in's queries over oRPC and as MCP tools.
 
 ## Install
 
@@ -23,7 +23,8 @@ bun add @pepys/api
 
 ## Features
 
-- The oRPC router and the app that serves it.
+- `serveAPI`, which serves a deployment's queries at `/rpc` and as MCP tools at `/mcp`.
+- `DeploymentClient`, the type of a typed client of a deployment's queries.
 - The store reader over the host's Turso files.
 
 ## Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pepys/api",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "The pepys API: typed queries over the store",
   "license": "MIT",
   "repository": {
@@ -19,12 +19,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@orpc/contract": "1.16.1",
-    "@orpc/server": "1.16.1",
-    "@pepys/contract": "0.0.1",
-    "@pepys/kit": "0.0.1",
-    "@pepys/kysely-turso": "0.0.1",
-    "@pepys/schema": "0.0.1",
+    "@modelcontextprotocol/server": "2.4.0",
+    "@orpc/contract": "2.0.0-beta.50",
+    "@orpc/mcp": "2.0.0-beta.50",
+    "@orpc/openapi": "2.0.0-beta.50",
+    "@orpc/server": "2.0.0-beta.50",
+    "@pepys/contract": "0.1.0",
+    "@pepys/kit": "0.1.0",
+    "@pepys/kysely-turso": "0.1.0",
+    "@pepys/schema": "0.1.0",
     "@tursodatabase/database": "0.8.3",
     "elysia": "2.0.0-rc.1",
     "exact-mirror": "1.2.7",
@@ -32,12 +35,13 @@
     "openapi-types": "12.1.3",
     "tiny-invariant": "1.3.3",
     "ts-pattern": "5.9.2",
+    "type-fest": "5.10.0",
     "typebox": "1.4.4",
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@orpc/client": "1.16.1",
-    "@pepys/ingest": "0.0.1",
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/testing": "0.1.0",
     "@zgeoff/std": "0.4.3"
   }
 }

package/src/app/create-app.ts

@@ -1,14 +1,37 @@
+import { McpServer, createMcpHandler } from '@modelcontextprotocol/server';
+import { McpRegistrar } from '@orpc/mcp';
+import { COMMON_ERROR_STATUS_MAP } from '@orpc/server';
 import { RPCHandler } from '@orpc/server/fetch';
 import { Elysia } from 'elysia';
 import type { QueryContext } from '../queries/types.ts';
 import { createRouter } from './create-router.ts';
 
+// The router at /rpc, and each of its procedures as an MCP tool at /mcp.
 export function createApp(context: QueryContext) {
-  const handler = new RPCHandler(createRouter());
+  const router = createRouter(context.deployment.queries);
 
-  return new Elysia().all('/rpc/*', { parse: 'none' }, async (route) => {
-    const result = await handler.handle(route.request, { prefix: '/rpc', context });
+  // A contract's own status has no effect in oRPC v2: the handler's map gives each code its HTTP
+  // status, and a code the map lacks gets 400. The map sets 503 itself, so it rests on no default.
+  const rpc = new RPCHandler(router, {
+    errorStatusMap: { ...COMMON_ERROR_STATUS_MAP, SERVICE_UNAVAILABLE: 503 },
+  });
+
+  const registrar = new McpRegistrar(router);
+
+  // stateless: one server per request, with the tools of the one router
+  const mcp = createMcpHandler(async () => {
+    const server = new McpServer({ name: `pepys-${context.deployment.name}`, version: '1.0.0' });
 
-    return result.matched ? result.response : new Response('not found', { status: 404 });
+    await registrar.register(server, { context });
+
+    return server;
   });
+
+  return new Elysia()
+    .all('/rpc/*', { parse: 'none' }, async (route) => {
+      const result = await rpc.handle(route.request, { prefix: '/rpc', context });
+
+      return result.matched ? result.response : new Response('not found', { status: 404 });
+    })
+    .all('/mcp', { parse: 'none' }, (route) => mcp.fetch(route.request));
 }

package/src/app/create-router.ts

@@ -1,68 +1,85 @@
-import type { ContractRouterClient } from '@orpc/contract';
-import { ORPCError, ValidationError, implement } from '@orpc/server';
+import { oc } from '@orpc/contract';
+import { openapi } from '@orpc/openapi';
+import { implement } from '@orpc/server';
+import type { Router } from '@orpc/server';
 import { coreContract } from '@pepys/contract';
-import type { CoreContract } from '@pepys/contract';
+import type { AnyQueryDefinition } from '@pepys/kit';
+import { z } from 'zod';
 import { readEntity } from '../queries/get-entity/read-entity.ts';
+import { walkNeighbourhood } from '../queries/neighbourhood/walk-neighbourhood.ts';
 import type { QueryContext } from '../queries/types.ts';
+import { runPluginQuery } from './run-plugin-query.ts';
 
-export function createRouter() {
-  // oRPC validates the input before a procedure's own middleware by default, so a middleware
-  // could not turn an input failure into the procedure's typed error.
-  const api = implement(coreContract, {
-    initialInputValidationIndex: Number.POSITIVE_INFINITY,
-  }).$context<QueryContext>();
+// One flat router: the two core procedures and each plug-in query, by its snake case name, which
+// is also its MCP tool name. The deployment check refuses a query named as a core procedure.
+export function createRouter(queries: readonly AnyQueryDefinition[]): Router<QueryContext> {
+  const core = implement(coreContract).$context<QueryContext>();
 
-  return api.router({
-    get_entity: api.get_entity.handler(async (options) => {
+  const router: Record<string, Router<QueryContext>> = {
+    get_entity: core.get_entity.handler(async (options) => {
       const result = await readEntity(options.context, options.input.id);
 
-      const buildNotFound = options.errors.NOT_FOUND;
+      if (!result.ok) {
+        const buildError = options.errors[result.failure.code];
+
+        throw buildError({ message: result.failure.message });
+      }
+
+      return result.value;
+    }),
+    neighbourhood: core.neighbourhood.handler(async (options) => {
+      const result = await walkNeighbourhood(options.context, options.input);
 
       if (!result.ok) {
-        throw buildNotFound({ message: result.failure.message });
+        const buildError = options.errors[result.failure.code];
+
+        throw buildError({ message: result.failure.message });
       }
 
       return result.value;
     }),
-    neighbourhood: api.neighbourhood.handler(throwNotImplemented),
-    search: api.search.handler(throwNotImplemented),
-    entity_history: api.entity_history.handler(throwNotImplemented),
-    assert_link: api.assert_link
-      .use(async (options) => {
-        const buildUnprocessable = options.errors.UNPROCESSABLE_CONTENT;
-
-        try {
-          return await options.next();
-        } catch (error) {
-          if (isMissingEvidence(error)) {
-            throw buildUnprocessable({ cause: error });
-          }
-
-          throw error;
-        }
-      })
-      .handler(throwNotImplemented),
-    retract_link: api.retract_link.handler(throwNotImplemented),
-    correct_label: api.correct_label.handler(throwNotImplemented),
-  });
-}
+  };
 
-export type APIClient = ContractRouterClient<CoreContract>;
+  for (const query of queries) {
+    if (hasTransform(query)) {
+      throw new Error(
+        `the query ${query.name} has a zod transform, which an MCP tool schema cannot carry`,
+      );
+    }
 
-interface NotImplementedCall {
-  errors: { NOT_IMPLEMENTED: () => Error };
-}
+    const contract = oc
+      .errors({ SERVICE_UNAVAILABLE: {} })
+      .meta(openapi({ description: query.description }))
+      .input(query.input)
+      .output(query.output);
 
-function throwNotImplemented(options: NotImplementedCall): never {
-  const buildNotImplemented = options.errors.NOT_IMPLEMENTED;
+    router[query.name] = implement(contract)
+      .$context<QueryContext>()
+      .handler(async (options) => {
+        const result = await runPluginQuery(options.context.store, query, options.input);
 
-  throw buildNotImplemented();
+        if (!result.ok) {
+          const buildUnavailable = options.errors.SERVICE_UNAVAILABLE;
+          const consumers = result.failure.consumers.join(', ');
+
+          throw buildUnavailable({ message: `the consumers ${consumers} have no current version` });
+        }
+
+        return result.value;
+      });
+  }
+
+  return router;
 }
 
-function isMissingEvidence(error: unknown): boolean {
-  return (
-    error instanceof ORPCError &&
-    error.cause instanceof ValidationError &&
-    error.cause.issues.some((issue) => issue.path?.[0] === 'evidence')
-  );
+// zod writes no JSON Schema for the output of a transform, and throws instead.
+function hasTransform(query: AnyQueryDefinition): boolean {
+  try {
+    z.toJSONSchema(query.input, { io: 'output' });
+    z.toJSONSchema(query.output, { io: 'output' });
+
+    return false;
+  } catch {
+    return true;
+  }
 }

package/src/app/run-plugin-query.ts

@@ -0,0 +1,31 @@
+import type {
+  AnyQueryDefinition,
+  QueryDefinition,
+  Result,
+  StoreReader,
+  StoreReaderFailure,
+} from '@pepys/kit';
+
+// Runs one plug-in query's handler on the files of the consumers it reads. The router has parsed
+// `input` with the query's own input schema, and parses the answer with its output schema.
+export async function runPluginQuery(
+  store: StoreReader,
+  query: AnyQueryDefinition,
+  input: unknown,
+): Promise<Result<unknown, StoreReaderFailure>> {
+  const handler: unknown = query.handler;
+
+  if (!isQueryHandler(handler)) {
+    throw new TypeError(`the query ${query.name} has no handler`);
+  }
+
+  const result = await store.withConsumers(query.reads, (db) => handler({ input, db }));
+
+  return result;
+}
+
+// A list of queries types each handler's call as `never`, since no one call type fits every
+// handler. Each handler takes the call that its own input schema parses, which the router gives.
+function isQueryHandler(handler: unknown): handler is QueryDefinition['handler'] {
+  return typeof handler === 'function';
+}

package/src/client/deployment-client.ts

@@ -0,0 +1,9 @@
+import type { ContractRouterClient } from '@orpc/contract';
+import type { CoreContract } from '@pepys/contract';
+import type { Deployment, PluginClient } from '@pepys/kit';
+import type { UnionToIntersection } from 'type-fest';
+
+// The typed client of one deployment: the core procedures, then each plug-in query by its name. A
+// caller that needs one plug-in's queries alone uses the kit's PluginClient.
+export type DeploymentClient<Target extends Deployment> = ContractRouterClient<CoreContract> &
+  UnionToIntersection<PluginClient<Target['plugins'][number]>>;

package/src/config/read-api-config.ts

@@ -3,6 +3,9 @@ import { parsePort } from '@pepys/schema';
 
 export interface APIConfig {
   storeDirectory: string;
+
+  // the listen address; 127.0.0.1 unless the deployment sets another
+  host: string;
   port: number;
 }
 
@@ -10,6 +13,7 @@ export function readAPIConfig(
   environment: Readonly<Record<string, string | undefined>>,
 ): Result<APIConfig, string[]> {
   const storeDirectory = environment['PEPYS_STORE_DIR'] ?? '';
+  const host = environment['PEPYS_API_HOST'] ?? '';
   const portText = environment['PEPYS_API_PORT'] ?? '';
   const port = portText === '' ? ({ ok: true, value: 8081 } as const) : parsePort(portText);
 
@@ -22,5 +26,8 @@ export function readAPIConfig(
     return { ok: false, failure: problems };
   }
 
-  return { ok: true, value: { storeDirectory, port: port.value } };
+  return {
+    ok: true,
+    value: { storeDirectory, host: host === '' ? '127.0.0.1' : host, port: port.value },
+  };
 }

package/src/index.ts

@@ -1,11 +1,10 @@
-export { createRouter } from './app/create-router.ts';
-export type { APIClient } from './app/create-router.ts';
 export { createApp } from './app/create-app.ts';
-export type * from './change-feed/change-feed.ts';
-export type * from './principal/principal.ts';
+export { createRouter } from './app/create-router.ts';
+export type { DeploymentClient } from './client/deployment-client.ts';
 export { readAPIConfig } from './config/read-api-config.ts';
+export { buildQueryContext } from './queries/build-query-context.ts';
+export type { QueryContext } from './queries/types.ts';
+export { serveAPI } from './serve/serve-api.ts';
 export { createStoreReader } from './store-reader/create-store-reader.ts';
-export { openConsumerDatabase } from './store-reader/open-consumer-database.ts';
 export { readChangeOperations } from './store-reader/read-change-operations.ts';
 export { readOffsets } from './store-reader/read-offsets.ts';
-export { readPullRequests } from './store-reader/read-pull-requests.ts';

package/src/queries/build-query-context.ts

@@ -0,0 +1,13 @@
+import { buildLinkRegistry } from '@pepys/kit';
+import type { CheckedDeployment, StoreReader } from '@pepys/kit';
+import { buildEntityKindIndex } from './entity-kinds/build-entity-kind-index.ts';
+import type { QueryContext } from './types.ts';
+
+export function buildQueryContext(store: StoreReader, deployment: CheckedDeployment): QueryContext {
+  return {
+    store,
+    deployment,
+    entityKinds: buildEntityKindIndex(deployment.consumers),
+    linkRegistry: buildLinkRegistry(deployment.linkTypes),
+  };
+}

package/src/queries/entity-kinds/build-entity-kind-index.ts

@@ -0,0 +1,17 @@
+import type { ConsumerDeclaration, EntityKind, EntityViewDeclaration } from '@pepys/kit';
+
+interface EntityOwner {
+  consumer: ConsumerDeclaration;
+  view: EntityViewDeclaration;
+}
+
+// Which consumer and table hold each kind. The deployment check refuses two views of one kind.
+export type EntityKindIndex = ReadonlyMap<string, EntityOwner>;
+
+export function buildEntityKindIndex(consumers: readonly ConsumerDeclaration[]): EntityKindIndex {
+  return new Map<EntityKind, EntityOwner>(
+    consumers.flatMap((consumer) =>
+      consumer.entityViews.map((view) => [view.kind, { consumer, view }] as const),
+    ),
+  );
+}

package/src/queries/get-entity/read-entity.ts

@@ -1,70 +1,86 @@
 import type { CoreOutputs } from '@pepys/contract';
-import type { EntityID, EntityIDParts, Result } from '@pepys/kit';
+import { parseEntityID } from '@pepys/kit';
+import type { Result } from '@pepys/kit';
 import { sql } from 'kysely';
 import invariant from 'tiny-invariant';
 import { z } from 'zod';
 import type { QueryContext, QueryFailure } from '../types.ts';
 import { buildEntityRow } from './build-entity-row.ts';
-import { findEntityConsumer } from './find-entity-consumer.ts';
 
 const storedRowSchema = z.record(z.string(), z.unknown());
 const storedRowsSchema = z.object({ rows: z.array(storedRowSchema) });
 
-interface ParsedEntityID {
-  id: EntityID;
-  parts: EntityIDParts;
-}
+type EntityOutput = CoreOutputs['get_entity'];
 
+// The kind in the ID names the owning consumer, so the call attaches that one file.
 export async function readEntity(
   context: QueryContext,
-  parsed: ParsedEntityID,
-): Promise<Result<CoreOutputs['get_entity'], QueryFailure>> {
-  const id = parsed.id;
+  id: string,
+): Promise<Result<EntityOutput, QueryFailure>> {
+  const parsed = parseEntityID(id);
+
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      failure: {
+        code: 'BAD_REQUEST',
+        message: `${id} is not an entity ID: ${parsed.failure.reason}`,
+      },
+    };
+  }
 
   const notFound = {
     ok: false,
     failure: { code: 'NOT_FOUND', message: `no entity ${id}` },
   } as const;
 
-  const found = findEntityConsumer(context.consumers, parsed.parts);
+  const owner = context.entityKinds.get(`${parsed.value.source}:${parsed.value.kind}`);
 
-  if (found === undefined) {
+  if (owner === undefined) {
     return notFound;
   }
 
-  const read = await context.store.withConsumer(found.consumer.name, async (transaction) => {
-    const entity = await transaction
+  const read = await context.store.withConsumers([owner.consumer], async (db) => {
+    const entity = await db
       .selectFrom('entity')
       .selectAll()
       .where('id', '=', id)
       .executeTakeFirst();
 
     if (entity === undefined) {
-      return notFound;
+      return null;
     }
 
-    const table = sql.table(found.entityView.table);
-    const idColumn = sql.ref(found.entityView.id);
-    const query = sql`select * from ${table} where ${idColumn} = ${id}`;
+    // the names come from the declaration, never from the input
+    const table = sql.table(owner.view.table);
+    const idColumn = sql.ref(owner.view.id);
 
-    const result = await query.execute(transaction);
+    const result = await sql`select * from ${table} where ${idColumn} = ${id}`.execute(db);
 
     const [stored] = storedRowsSchema.parse(result).rows;
-    const declaration = found.consumer.tables[found.entityView.table];
+    const declaration = owner.consumer.tables[owner.view.table];
 
-    invariant(
-      stored !== undefined && declaration !== undefined,
-      'an entity view row has a table row',
-    );
+    invariant(stored !== undefined && declaration !== undefined, 'an entity row has a table row');
 
-    const value: CoreOutputs['get_entity'] = {
+    const value: EntityOutput = {
       entity,
+      consumer: owner.consumer.name,
+      table: owner.view.table,
       row: buildEntityRow(declaration, stored),
-      aliases: [],
     };
 
-    return { ok: true, value } as const;
+    return value;
   });
 
-  return read.ok ? read.value : notFound;
+  if (!read.ok) {
+    return {
+      ok: false,
+      failure: {
+        code: 'SERVICE_UNAVAILABLE',
+        message: `the consumer ${read.failure.consumers.join(', ')} has no current version`,
+      },
+    };
+  }
+
+  return read.value === null ? notFound : { ok: true, value: read.value };
 }

package/src/queries/neighbourhood/pick-link-types.ts

@@ -0,0 +1,30 @@
+import type { LinkRegistry, Result } from '@pepys/kit';
+
+interface LinkTypeChoice {
+  linkTypes: readonly string[] | null;
+  includeHubs: boolean;
+}
+
+interface UnknownLinkTypes {
+  unknown: readonly string[];
+  known: readonly string[];
+}
+
+// The link types a walk follows: the named ones, or every one, with a hub type only when the
+// caller includes hubs.
+export function pickLinkTypes(
+  registry: LinkRegistry,
+  choice: LinkTypeChoice,
+): Result<readonly string[], UnknownLinkTypes> {
+  const known = [...registry.keys()].toSorted();
+  const named = choice.linkTypes ?? known;
+  const unknown = [...new Set(named.filter((name) => !registry.has(name)))].toSorted();
+
+  if (unknown.length > 0) {
+    return { ok: false, failure: { unknown, known } };
+  }
+
+  const followed = named.filter((name) => choice.includeHubs || registry.get(name)?.hub === false);
+
+  return { ok: true, value: [...new Set(followed)].toSorted() };
+}

package/src/queries/neighbourhood/take-hop.ts

@@ -0,0 +1,97 @@
+import type { LinkRow } from '@pepys/kit';
+import { compareText } from '../../utils/compare-text.ts';
+
+interface WalkLink {
+  type: string;
+  from: string;
+  to: string;
+  direction: 'outgoing' | 'incoming';
+  origin: string;
+  confidence: number;
+  depth: number;
+}
+
+export interface WalkState {
+  // every ID seen, with the depth it was first seen at; the cycle guard
+  depths: ReadonlyMap<string, number>;
+  links: readonly WalkLink[];
+
+  // the IDs the next hop expands
+  frontier: readonly string[];
+  isTruncated: boolean;
+}
+
+interface Hop {
+  depth: number;
+  entityLimit: number;
+  linkReadLimit: number;
+}
+
+// One hop, from the link rows that touch the frontier in read order. Two origins of one link merge
+// at the highest confidence; new IDs join in ID order while the entity limit has room.
+export function takeHop(state: WalkState, rows: readonly LinkRow[], hop: Hop): WalkState {
+  const frontier = new Set(state.frontier);
+  const followed = new Set(state.links.map((link) => toLinkKey(link.type, link.from, link.to)));
+  const merged = new Map<string, LinkRow>();
+
+  for (const row of rows.slice(0, hop.linkReadLimit)) {
+    const key = toLinkKey(row.type, row.from_id, row.to_id);
+    const held = merged.get(key);
+
+    if (!followed.has(key) && (held === undefined || row.confidence > held.confidence)) {
+      merged.set(key, row);
+    }
+  }
+
+  const candidates = [...merged.values()].map((row) => {
+    const isOutgoing = frontier.has(row.from_id);
+
+    return {
+      link: {
+        type: row.type,
+        from: row.from_id,
+        to: row.to_id,
+        direction: isOutgoing ? 'outgoing' : 'incoming',
+        origin: row.origin,
+        confidence: row.confidence,
+        depth: hop.depth,
+      } satisfies WalkLink,
+      reached: isOutgoing ? row.to_id : row.from_id,
+    };
+  });
+
+  const newIDs = [
+    ...new Set(
+      candidates.map((candidate) => candidate.reached).filter((id) => !state.depths.has(id)),
+    ),
+  ].toSorted();
+
+  const room = Math.max(0, hop.entityLimit - state.depths.size);
+  const admitted = newIDs.slice(0, room);
+
+  const depths = new Map([...state.depths, ...admitted.map((id) => [id, hop.depth] as const)]);
+
+  const links = candidates
+    .filter((candidate) => depths.has(candidate.reached))
+    .map((candidate) => candidate.link)
+    .toSorted(compareLinks);
+
+  return {
+    depths,
+    links: [...state.links, ...links],
+    frontier: admitted,
+    isTruncated: state.isTruncated || rows.length > hop.linkReadLimit || newIDs.length > room,
+  };
+}
+
+function toLinkKey(type: string, from: string, to: string): string {
+  return JSON.stringify([type, from, to]);
+}
+
+function compareLinks(first: WalkLink, second: WalkLink): number {
+  return (
+    compareText(first.type, second.type) ||
+    compareText(first.from, second.from) ||
+    compareText(first.to, second.to)
+  );
+}