tapimo 0.1.0 → 0.3.0

package/src/apps/{webhooks.test.ts → data/routes/webhooks.test.ts}

@@ -1,11 +1,11 @@
 import { type Db, Webhooks as Core } from 'tapimo'
 
-import * as Tidx from '../internal/Tidx.js'
-import * as Viem from '../internal/Viem.js'
-import * as TestApp from '../../test/App.js'
-import * as Mppx from '../../test/Mppx.js'
-import * as Runtime from '../../test/runtime.js'
-import * as Tempo from '../../test/Tempo.js'
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as TestApp from '../../../../test/App.js'
+import * as Mppx from '../../../../test/Mppx.js'
+import * as Runtime from '../../../../test/runtime.js'
+import * as Tempo from '../../../../test/Tempo.js'
 import * as Webhooks from './webhooks.js'
 
 /** API key with both webhook scopes, owned by `org_test`. */
@@ -1151,7 +1151,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
   // the real keyset/`toBlock` SQL and decode path end to end — no fabricated rows.
   const realTidx = Tidx.getClient({
     chainId: 42431,
-    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.VITE_TIDX_BASIC_AUTH },
+    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.TIDX_BASIC_AUTH },
   })
   // The monitoring scanners (`log:emitted`/`block:created`/`transaction:included`)
   // read the same immutable historical window over real RPC (chain 42431 →

package/src/apps/{webhooks.ts → data/routes/webhooks.ts}

@@ -2,20 +2,20 @@ import { type Context, Hono } from 'hono'
 import { type AbiEvent, parseAbiItem } from 'viem'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as Cursor from '../internal/Cursor.js'
-import * as Db from '../db/Db.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
-import type * as Viem from '../internal/Viem.js'
-import * as Webhooks from '../internal/Webhooks.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as Db from '../../../db/Db.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import type * as Viem from '../../../internal/Viem.js'
+import * as Webhooks from '../../../internal/Webhooks.js'
 import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
@@ -378,7 +378,7 @@ export namespace schema {
           .record(z.string(), z.unknown())
           .check(
             z.describe(
-              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or an operator object.',
+              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or a super admin object.',
             ),
             z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }),
           ),
@@ -533,7 +533,7 @@ export namespace schema {
         .string()
         .check(
           z.describe('Webhook subscription ID (`wh_…`).'),
-          z.meta({ examples: ['wh_abc123'] }),
+          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
         ),
       lastDeliveryAt: z
         .optional(z.iso.datetime())
@@ -594,7 +594,10 @@ export namespace schema {
         ),
       id: z
         .string()
-        .check(z.describe('Webhook delivery ID (`whd_…`).'), z.meta({ examples: ['whd_abc123'] })),
+        .check(
+          z.describe('Webhook delivery ID (`whd_…`).'),
+          z.meta({ examples: ['whd_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
+        ),
       requestUrl: z
         .string()
         .check(
@@ -620,7 +623,7 @@ export namespace schema {
         .string()
         .check(
           z.describe('Subscription ID (`wh_…`) this delivery belongs to.'),
-          z.meta({ examples: ['wh_abc123'] }),
+          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
         ),
     })
     .check(z.describe('One attempt by Tempo to deliver an event to your webhook URL.'))
@@ -901,7 +904,7 @@ export namespace schema {
       .string()
       .check(
         z.describe('Subscription ID (`wh_…`) that produced this delivery.'),
-        z.meta({ examples: ['wh_abc123'] }),
+        z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
       ),
   }
 
@@ -1075,7 +1078,7 @@ export namespace schema {
           .string()
           .check(
             z.describe('Webhook subscription ID (`wh_…`).'),
-            z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Path parameters for a webhook subscription request.'))
@@ -1158,13 +1161,13 @@ export namespace schema {
           .string()
           .check(
             z.describe('Delivery ID (`whd_…`) you want Tempo to replay.'),
-            z.meta({ examples: ['whd_001718668800000_8oQ2pVmZ4kKxWnLcRfTbN'] }),
+            z.meta({ examples: ['whd_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
           ),
         id: z
           .string()
           .check(
             z.describe('Webhook subscription ID (`wh_…`).'),
-            z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Path parameters for retrying a webhook delivery.'))
@@ -1209,7 +1212,7 @@ export namespace schema {
           .string()
           .check(
             z.describe('ID of the webhook subscription that was deleted.'),
-            z.meta({ examples: ['wh_abc123'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Confirmation that the webhook subscription was deleted.'))
@@ -1225,21 +1228,25 @@ export namespace schema {
  */
 export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
-  return (
-    new Hono<App.Environment>()
-      .use('*', async (c, next) => {
-        // Gate the whole resource on a configured state store. Without it the
-        // outbound-HTTP surface is disabled (read-only deployment).
-        if (!c.get('webhook')) return notEnabled(c) as never
+  // Gate the whole resource on a configured state store. Without it the
+  // outbound-HTTP surface is disabled (read-only deployment).
+  const gate = async (c: Context<App.Environment>, next: () => Promise<void>) => {
+    if (!c.get('webhook')) return notEnabled(c) as never
 
-        await next()
+    await next()
 
-        // Subscriptions are principal-scoped, mutating, and stateful: never cache.
-        if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
-        return
-      })
+    // Subscriptions are principal-scoped, mutating, and stateful: never cache.
+    if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
+    return
+  }
+  return (
+    new Hono<App.Environment>()
+      // `/v1/webhooks/*` does not match the collection root, so it gets its
+      // own registration.
+      .use('/v1/webhooks', gate)
+      .use('/v1/webhooks/*', gate)
       .get(
-        '/event-types',
+        '/v1/webhooks/event-types',
         Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
         OpenApi.describeRoute({
           description: 'See which onchain event types Tempo can POST to your webhook URL.',
@@ -1275,7 +1282,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('json', schema.createWebhook.Body, {
           code: 'body_invalid',
@@ -1338,7 +1345,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('query', schema.listWebhooks.Query, {
           code: 'query_invalid',
@@ -1412,7 +1419,7 @@ export function webhooks(options: webhooks.Options = {}) {
       // constraint, this API-key-only route's policy would be collected for the
       // event-types request and override its (intentionally public) access.
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.getWebhook.Params, {
           code: 'param_invalid',
@@ -1464,7 +1471,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.listWebhookDeliveries.Params, {
           code: 'param_invalid',
@@ -1555,7 +1562,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/ping',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/ping',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.pingWebhook.Params, {
           code: 'param_invalid',
@@ -1620,7 +1627,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.retryWebhookDelivery.Params, {
           code: 'param_invalid',
@@ -1691,7 +1698,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .patch(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.updateWebhook.Params, {
           code: 'param_invalid',
@@ -1763,7 +1770,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .delete(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.deleteWebhook.Params, {
           code: 'param_invalid',

package/src/apps/docs/App.ts

@@ -0,0 +1,65 @@
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import type { Handler as vocs_Handler } from 'vocs/server'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+
+/**
+ * The docs route group: the Vocs API reference served at the app root.
+ *
+ * ```ts
+ * import { docs } from 'tapimo/docs'
+ * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * ```
+ *
+ * The group registers no routes itself: it carries a reference factory (via
+ * {@link Metadata}) that `App.create` mounts on finalize, after every group and
+ * the OpenAPI/OpenRPC documents — so the reference always renders the full
+ * composed surface and its catch-all stays behind API routes, wherever the
+ * group sits in the composition chain.
+ *
+ * Lives in the `tapimo/docs` subpath (never re-exported from `tapimo/apps`) so
+ * the Vocs renderer and its multi-MB icon/font data are bundled only by
+ * deployments that actually serve docs. Even then the renderer loads lazily on
+ * the first docs request (see `reference.ts`), so API traffic and isolate
+ * startup never pay for it.
+ */
+export function docs(options: docs.Options = {}) {
+  return Metadata.attach(new Hono<App.Environment>(), {
+    docs: ({ spec }) => {
+      // Memoized across requests: all docs traffic shares one handler.
+      let handler: Promise<Hono> | undefined
+      return new Hono<App.Environment>().get('*', async (c, next) => {
+        handler ??= import('./reference.js').then((m) =>
+          m.create({ mount: mountFromRoutePath(c.req.routePath), spec, vocs: options }),
+        )
+        const response = await (await handler).fetch(c.req.raw, c.env, executionCtx(c))
+        // Inner 404 means "not a docs route" (`fallback: 'next'` semantics):
+        // defer to the host app's later routes / JSON `notFound`.
+        if (response.status === 404) return next()
+        return response
+      })
+    },
+  })
+}
+
+export declare namespace docs {
+  /** Vocs API reference options (theme, top navigation, logo, socials, …). */
+  type Options = NonNullable<Parameters<typeof vocs_Handler.openApi>[0]['vocs']>
+}
+
+/** Derives the host mount prefix from Hono's matched `routePath` (`/api/*` → `/api`, `/*` → ``). */
+function mountFromRoutePath(routePath: string) {
+  return routePath.replace(/\*+$/, '').replace(/\/+$/, '')
+}
+
+// `c.executionCtx` throws outside Workers (tests, Node); docs rendering never
+// uses `waitUntil`, so absence is fine.
+function executionCtx(c: Context) {
+  try {
+    return c.executionCtx
+  } catch {
+    return undefined
+  }
+}

package/src/apps/docs/index.ts

@@ -0,0 +1 @@
+export { docs } from './App.js'

package/src/apps/docs/reference.ts

@@ -0,0 +1,132 @@
+import { Hono } from 'hono'
+import { Handler as vocs_Handler } from 'vocs/server'
+
+import type * as App from '../../App.js'
+import openrpcSpec from '../../openrpc.json' with { type: 'json' }
+import type { docs } from './App.js'
+import { pilatFontFaces } from './fonts.js'
+import { logoUrl } from './logo.js'
+
+/**
+ * Builds the Vocs reference handler. Loaded via dynamic import on the first
+ * docs request (see `docs()` in `App.ts`), keeping the multi-MB renderer off
+ * isolate startup.
+ */
+export function create(options: create.Options): Hono {
+  const { mount, spec, vocs } = options
+  const handler = vocs_Handler.openApi(
+    {
+      // Inline the OpenRPC doc so vocs expands it without a self-subrequest
+      // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
+      spec: () => spec().then(inlineOpenrpc),
+      sidebar: { collapsed: true },
+      vocs: { logoUrl, title: 'Tempo API Reference', ...vocs },
+    },
+    { css, fallback: 'next' },
+  )
+  if (!mount) return handler
+  // Re-mount under the host prefix so the handler's `routePath`-derived mount
+  // (asset link bases, known-route checks) matches a direct `.route()` mount.
+  return new Hono().route(mount, handler)
+}
+
+export declare namespace create {
+  /** Options for building the reference handler. */
+  type Options = {
+    /** Host mount prefix derived from the wrapper's matched `routePath` (`''` at root). */
+    mount: string
+    /** Memoized OpenAPI document builder — the same document served at `/openapi.json`. */
+    spec: App.create.DocsContext['spec']
+    /** Vocs reference options (theme, top navigation, logo, socials, …). */
+    vocs: docs.Options
+  }
+}
+
+/**
+ * Custom CSS injected into the standalone reference's shell `<head>` (via
+ * `Handler.openApi(_, { css })`), after the Vocs design-system styles so it
+ * overrides them:
+ *
+ * - Page/surface backgrounds use Tempo's near-black dark palette and pure-white
+ *   light palette via `light-dark(<light>, <dark>)`.
+ * - The dark border color is darkened (the light theme keeps its default).
+ * - Every corner is squared. The universal `!important` rule beats hard-coded
+ *   `border-radius` values and inline styles (e.g. the Scalar playground), which
+ *   overriding the radius scale variables alone would miss.
+ * - The default sans/body font is Pilat (Vocs reads `--vocs-font-family`); the
+ *   webfont is embedded via {@link pilatFontFaces}. Body stays at the default
+ *   weight (400); headings are pinned to 500, which renders Pilat Demi (the
+ *   family has no 500 cut, so Demi covers the 500-600 range — see
+ *   {@link pilatFontFaces}).
+ */
+const css = `${pilatFontFaces}
+
+:root {
+  --vocs-font-family: "Pilat", Arial, Helvetica, sans-serif;
+  --vocs-background-color-primary: light-dark(#fafafa, #0a0a0a);
+  --vocs-background-color-surface: light-dark(#fff, #121212);
+}
+
+:is(h1, h2, h3, h4, h5, h6)[data-v] {
+  font-weight: 500;
+}
+
+/* Nudge the header logo a touch larger than the default max-h-7 (1.75rem). */
+[data-v-logo-image] {
+  max-height: 2rem;
+}
+
+/* Sidebar leaf items render Regular (the nav's 450 default otherwise resolves to
+ * Demi via the 500-600 range). Group labels ([data-v-sidebar-section-header])
+ * keep their heavier weight. */
+[data-v-sidebar-item] {
+  font-weight: 400;
+}
+
+[data-vocs-theme='dark'] {
+  --vocs-color-gray4: oklch(20% 0 0);
+  --vocs-color-gray5: oklch(0.23 0 0);
+  --vocs-border-color-primary: oklch(0.25 0 0);
+  --vocs-border-color-secondary: oklch(0.25 0 0);
+}
+
+*,
+*::before,
+*::after {
+  border-radius: 0 !important;
+}`
+
+/**
+ * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
+ * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
+ *
+ * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
+ * public `/openapi.json` by `App.create`'s `applyOpenrpcLink`) would make the
+ * docs worker fetch its own `/openrpc.json` — a self-subrequest that is
+ * unreliable on Cloudflare Workers and silently falls back to a single,
+ * unexpanded operation. Inlining the committed artifact keeps expansion
+ * deterministic across local and deployed environments, without bloating the
+ * public spec. Only the affected path/op are cloned; the rest of the (large)
+ * document is shared by reference.
+ */
+function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
+  const paths: Record<string, unknown> = {}
+  for (const [pathname, item] of Object.entries(spec.paths)) {
+    let next = item
+    if (isRecord(item))
+      for (const [method, op] of Object.entries(item))
+        if (isRpcOperation(op)) next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
+    paths[pathname] = next
+  }
+  return { ...spec, paths }
+}
+
+// The JSON-RPC passthrough's operation id, set by its route definition and
+// targeted by `App.create`'s `applyOpenrpcLink`.
+function isRpcOperation(op: unknown): op is Record<string, unknown> {
+  return isRecord(op) && op['operationId'] === 'rpcRequest'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}

package/src/apps/index.ts

@@ -0,0 +1,4 @@
+export { data } from './data/index.js'
+export { mcp } from './mcp.js'
+export { platform } from './platform/index.js'
+export { relay } from './relay/index.js'

package/src/apps/mcp.test.ts

@@ -0,0 +1,206 @@
+import { Cli as incur_Cli, z } from 'incur'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import { mcp } from './mcp.js'
+
+const origin = 'https://api.tempo-api.test'
+
+/** API key with read-only webhook scope, used to prove header forwarding. */
+const reader = {
+  id: 'key_reader',
+  orgId: 'org_test',
+  scopes: ['webhooks:read'],
+  token: 'secret_reader',
+} satisfies TestApp.kvStore.Key
+
+/** Composes a test app with the MCP group mounted, dispatching in-process. */
+function createHost(
+  options: {
+    app?: ReturnType<typeof TestApp.create> | undefined
+    docs?: mcp.Options['docs'] | undefined
+  } = {},
+) {
+  const app = options.app ?? TestApp.create()
+  const host = mcp({ docs: options.docs ?? false, fetch: (request) => app.fetch(request) })
+  return { app, host }
+}
+
+/** Stub remote docs MCP server: an in-process incur CLI serving `/mcp`. */
+function docsStub() {
+  const remote = incur_Cli.create('docs-remote', { version: '1.0.0' }).command('search', {
+    description: 'Search docs',
+    options: z.object({ query: z.string().describe('Search query') }),
+    run: (context) => ({ hits: [context.options.query] }),
+  })
+  return { fetch: (request: Request) => remote.fetch(request), url: 'http://docs.local/mcp' }
+}
+
+/** Anything serving `/mcp`: the group host, or a composed app it is mounted into. */
+type Host = { fetch: (request: Request) => Response | Promise<Response> }
+
+async function request(host: Host, body: unknown, headers: Record<string, string> = {}) {
+  const response = await host.fetch(
+    new Request(new URL('/mcp', origin), {
+      body: JSON.stringify(body),
+      headers: {
+        accept: 'application/json, text/event-stream',
+        'content-type': 'application/json',
+        ...headers,
+      },
+      method: 'POST',
+    }),
+  )
+  expect(response.status).toBe(200)
+  return (await response.json()) as { result: any }
+}
+
+function initialize(host: Host) {
+  return request(host, {
+    id: 1,
+    jsonrpc: '2.0',
+    method: 'initialize',
+    params: {
+      capabilities: {},
+      clientInfo: { name: 'test-client', version: '1.0.0' },
+      protocolVersion: '2025-03-26',
+    },
+  })
+}
+
+async function toolsList(host: Host) {
+  const body = await request(host, { id: 2, jsonrpc: '2.0', method: 'tools/list', params: {} })
+  return (body.result.tools as { name: string }[]).map((tool) => tool.name)
+}
+
+async function toolsCall(
+  host: Host,
+  name: string,
+  args: Record<string, unknown>,
+  headers: Record<string, string> = {},
+) {
+  const body = await request(
+    host,
+    { id: 3, jsonrpc: '2.0', method: 'tools/call', params: { arguments: args, name } },
+    headers,
+  )
+  return body.result as {
+    content: { text: string; type: string }[]
+    isError?: boolean
+    structuredContent?: Record<string, unknown>
+  }
+}
+
+/** Parses a tool result: structured content when present, else the JSON text item. */
+function resultJson(result: Awaited<ReturnType<typeof toolsCall>>) {
+  return result.structuredContent ?? JSON.parse(result.content[0]!.text)
+}
+
+test('scopes tools to the data domain', async () => {
+  const { app, host } = createHost({ docs: docsStub() })
+
+  // The domain filter must drop paths that actually exist in the spec.
+  const spec = (await (await app.fetch(new Request(new URL('/openapi.json', origin)))).json()) as {
+    paths: Record<string, unknown>
+  }
+  expect(Object.keys(spec.paths).some((path) => path.startsWith('/gecko/'))).toBe(true)
+  expect(Object.keys(spec.paths).some((path) => path.startsWith('/v1/auth/'))).toBe(true)
+  expect(Object.keys(spec.paths).some((path) => path.startsWith('/v1/orgs'))).toBe(true)
+
+  await initialize(host)
+  const tools = await toolsList(host)
+
+  expect(tools).toContain('v1_tokens_get')
+  expect(tools).toContain('docs_search')
+  // RPC is part of the data domain tag group.
+  expect(tools.some((name) => name.startsWith('rpc'))).toBe(true)
+  // Out of domain: CoinGecko mirrors, session auth, platform, relay.
+  expect(tools.some((name) => name.startsWith('gecko_'))).toBe(false)
+  expect(tools.some((name) => name.startsWith('v1_auth_'))).toBe(false)
+  expect(tools.some((name) => name.startsWith('v1_orgs'))).toBe(false)
+  expect(tools.some((name) => name.startsWith('v1_me'))).toBe(false)
+})
+
+test('executes generated tools against the composed app', async () => {
+  // Verified tokens are database-backed, so seed the default chain.
+  const db = TestApp.database()
+  await TestApp.verifiedSeed(db, Runtime.get().chainId)
+  const { host } = createHost({ app: TestApp.create({ db }) })
+
+  await initialize(host)
+  const result = await toolsCall(host, 'v1_tokens_get', { verified: true })
+
+  expect(result.isError).toBeFalsy()
+  const body = resultJson(result) as { data: { verified: boolean }[]; nextCursor: unknown }
+  expect(body.data.length).toBeGreaterThan(0)
+  expect(body.data.every((token) => token.verified === true)).toBe(true)
+})
+
+test('forwards the caller Authorization header to authenticated tools', async () => {
+  const { host } = createHost({ app: TestApp.create({ auth: { keys: [reader] } }) })
+  await initialize(host)
+
+  const denied = await toolsCall(host, 'v1_webhooks_get', {})
+  expect(denied.isError).toBe(true)
+
+  const allowed = await toolsCall(
+    host,
+    'v1_webhooks_get',
+    {},
+    { authorization: `Bearer ${reader.token}` },
+  )
+  expect(allowed.isError).toBeFalsy()
+  expect(resultJson(allowed)).toMatchObject({ data: [] })
+})
+
+test('proxies docs tool calls to the remote MCP source', async () => {
+  const { host } = createHost({ docs: docsStub() })
+  await initialize(host)
+
+  const result = await toolsCall(host, 'docs_search', { query: 'fees' })
+
+  expect(result.isError).toBeFalsy()
+  expect(resultJson(result)).toMatchObject({ hits: ['fees'] })
+})
+
+test('documents POST /mcp and keeps it open under auth enforcement', async () => {
+  // Worker-style composition: the group mounted into the app it dispatches to.
+  const app = TestApp.create()
+  app.route('/', mcp({ docs: false, fetch: (request) => app.fetch(request) }))
+
+  const spec = (await (await app.fetch(new Request(new URL('/openapi.json', origin)))).json()) as {
+    paths: Record<string, { post?: { operationId?: string; security?: unknown; tags?: string[] } }>
+    'x-tagGroups': { name: string; tags: string[] }[]
+  }
+  const operation = spec.paths['/mcp']?.post
+  expect(operation?.operationId).toBe('mcpRequest')
+  expect(operation?.tags).toEqual(['MCP'])
+  // Anonymous and any-valid-key access; no required scopes.
+  expect(operation?.security).toEqual([{ apiKey: [] }, { bearerAuth: [] }, {}])
+
+  // Surfaces under `Data API` in the reference, but the tool filter excludes the `MCP` tag.
+  const groups = Object.fromEntries(spec['x-tagGroups'].map((group) => [group.name, group.tags]))
+  expect(groups['MCP']).toBeUndefined()
+  expect(groups['Data API']).toContain('MCP')
+
+  // Documenting the route makes it auth-enforced; the public lane keeps it
+  // anonymously reachable, and the endpoint never surfaces itself as a tool.
+  await initialize(app)
+  const tools = await toolsList(app)
+  expect(tools.length).toBeGreaterThan(0)
+  expect(tools.some((name) => name.startsWith('mcp'))).toBe(false)
+
+  // A presented-but-invalid key is rejected at the transport.
+  const rejected = await app.fetch(
+    new Request(new URL('/mcp', origin), {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'tools/list', params: {} }),
+      headers: {
+        accept: 'application/json, text/event-stream',
+        authorization: 'Bearer not-a-key',
+        'content-type': 'application/json',
+      },
+      method: 'POST',
+    }),
+  )
+  expect(rejected.status).toBe(401)
+})