tapimo 0.2.0 → 0.4.0

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, management, 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)
+})

package/src/apps/mcp.ts

@@ -0,0 +1,250 @@
+import { type Context, Hono } from 'hono'
+import { Cli as incur_Cli, type Openapi } from 'incur'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Metadata from './metadata.js'
+
+/** Document tag group whose operations surface as MCP tools (the data domain). */
+const tagGroup = 'Data API'
+
+/** Tags inside the group hidden from MCP: partner-shaped CoinGecko mirrors and the MCP endpoint itself. */
+const excludedTags = ['CoinGecko', 'MCP']
+
+/** Usage guidance surfaced to MCP clients on initialize. */
+const instructions =
+  "Tools mirror the Tempo API's data domain. Authenticated tools accept a Tempo API key: send it as an `Authorization: Bearer` header on the HTTP request, or pass the `authorization` tool input per call. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation."
+
+/** Zod schemas owned by the MCP endpoint's OpenAPI description. */
+export namespace schema {
+  /** JSON-RPC request identifier. */
+  export const Id = z
+    .union([z.string(), z.number(), z.null()])
+    .check(z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'))
+
+  /** JSON-RPC error payload. */
+  export const Error = z
+    .object({
+      code: z
+        .number()
+        .check(z.int(), z.describe('Numeric JSON-RPC error code returned by the MCP server.')),
+      data: z
+        .optional(z.unknown())
+        .check(z.describe('Optional extra error details returned by the MCP server.')),
+      message: z.string().check(z.describe('Human-readable JSON-RPC error message.')),
+    })
+    .check(z.describe('JSON-RPC error object returned when a message fails.'))
+
+  /** MCP JSON-RPC response payload. */
+  export const Response = z
+    .object({
+      error: z
+        .optional(Error)
+        .check(z.describe('JSON-RPC error object returned when a message fails.')),
+      id: z
+        .optional(Id)
+        .check(
+          z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
+        ),
+      jsonrpc: z.literal('2.0').check(z.describe('JSON-RPC protocol version; MCP uses `2.0`.')),
+      result: z.optional(z.unknown()).check(z.describe('Result returned by the MCP method.')),
+    })
+    .check(z.describe('One MCP JSON-RPC response returned by the server.'))
+}
+
+/**
+ * The MCP route group: a stateless streamable-HTTP MCP server at `/mcp` whose
+ * tools mirror the API's data domain (scoped via the OpenAPI document's
+ * `Data API` tag group), plus the remote Tempo docs tools. Mount alongside
+ * the other route groups:
+ *
+ * ```ts
+ * App.create(options).route('/', mcp({ fetch: (request) => getApp().fetch(request) }))
+ * ```
+ */
+export function mcp(options: mcp.Options) {
+  const { docs = 'https://mcp.tempo.xyz/mcp', fetch, name = 'tapimo', version = '0.0.0' } = options
+
+  // One incur instance per caller origin: the OpenAPI document is parsed once,
+  // and generated commands rebase onto the origin so tool results embed real
+  // absolute URLs (e.g. token asset URIs).
+  const clis = new Map<string, ReturnType<typeof build>>()
+
+  function resolve(origin: string) {
+    let cli = clis.get(origin)
+    if (!cli) {
+      cli = build(origin)
+      clis.set(origin, cli)
+      // A failed build (spec fetch or docs resolution) retries next request.
+      cli.catch(() => clis.delete(origin))
+    }
+    return cli
+  }
+
+  async function build(origin: string) {
+    const response = await fetch(new Request(new URL('/openapi.json', origin)))
+    if (!response.ok) throw new Error(`openapi.json request failed: ${response.status}`)
+    const document = (await response.json()) as Document
+    const cli = incur_Cli.create(name, {
+      description: 'Tempo API',
+      // Generated commands build requests against `http://localhost`; rebase
+      // them onto the caller origin and dispatch in-process.
+      fetch: (request) => {
+        const url = new URL(request.url)
+        return fetch(new Request(new URL(url.pathname + url.search, origin), request))
+      },
+      mcp: { instructions },
+      openapi: scope(document),
+      openapiConfig: { forwardHeaders: ['authorization'], mode: 'namespace' },
+      version,
+    })
+    if (docs !== false)
+      cli.command('docs', { description: 'Search the Tempo documentation.', mcp: docs })
+    return cli
+  }
+
+  async function handler(c: Context<App.Environment>) {
+    const cli = await resolve(new URL(c.req.url).origin)
+    // incur routes on the first path segment; pin the path to `/mcp` so a
+    // mount prefix never leaks into its router.
+    return cli.fetch(new Request(new URL('/mcp', c.req.url), c.req.raw))
+  }
+
+  // The documented POST carries the auth policy (described routes are
+  // default-closed); other methods fall through to the bare route and incur's 405.
+  const app = new Hono<App.Environment>()
+    .post(
+      '/mcp',
+      Auth.policy({ apiKey: { scopes: [] }, public: true }),
+      OpenApi.describeRoute({
+        description:
+          "A stateless streamable-HTTP MCP server: send JSON-RPC 2.0 messages as `POST` with `Accept: application/json, text/event-stream`. Tools mirror the API's data domain, plus `docs_*` documentation search. Anonymous requests use the public quota; send `Authorization: Bearer <api key>` for protected tools.",
+        operationId: 'mcpRequest',
+        // The JSON-RPC request envelope is protocol-owned (like `/rpc`), so the
+        // body documents an example rather than a schema.
+        requestBody: {
+          content: {
+            'application/json': {
+              example: { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} },
+            },
+          },
+          required: true,
+        },
+        responses: {
+          200: {
+            content: {
+              'application/json': {
+                example: {
+                  jsonrpc: '2.0',
+                  id: 1,
+                  result: { tools: [{ name: 'v1_tokens_get', description: 'List tokens' }] },
+                },
+                schema: OpenApi.resolver(schema.Response),
+              },
+            },
+            description: 'JSON-RPC response returned by the MCP server.',
+            headers: { ...OpenApi.successHeaders },
+          },
+          202: {
+            description:
+              'The message was a notification or client response; there is nothing to return.',
+          },
+          400: {
+            content: { 'application/json': { schema: OpenApi.resolver(schema.Response) } },
+            description:
+              'Malformed or invalid MCP message, returned as a JSON-RPC error response rather than the standard error envelope. A malformed API key returns the standard `400` envelope instead.',
+          },
+          401: OpenApi.standardError(
+            401,
+            'The presented API key is invalid. Anonymous requests are allowed under the public quota.',
+            ['api_key_invalid'],
+          ),
+          406: {
+            content: { 'application/json': { schema: OpenApi.resolver(schema.Response) } },
+            description:
+              'The `Accept` header must include both `application/json` and `text/event-stream`. Returned as a JSON-RPC error response.',
+          },
+          429: OpenApi.standardError(429, 'Rate limit exceeded.'),
+          500: OpenApi.standardError(500, 'Internal server error.'),
+        },
+        summary: 'Call MCP',
+        tags: ['MCP'],
+      }),
+      handler,
+    )
+    .all('/mcp', handler)
+  return Metadata.attach(app, openapi)
+}
+
+/** The OpenAPI metadata this group owns: the MCP endpoint's tag, surfaced under the `Data API` group. */
+const openapi = {
+  tags: [
+    {
+      name: 'MCP',
+      description:
+        'A hosted Model Context Protocol server: the data domain and Tempo docs exposed as tools.',
+    },
+  ],
+  'x-tagGroups': [{ name: tagGroup, tags: ['MCP'] }],
+} satisfies App.create.Metadata
+
+/** The slice of the OpenAPI document the domain filter reads. */
+type Document = Openapi.OpenAPISpec & {
+  paths: Record<string, Record<string, unknown>>
+  'x-tagGroups'?: readonly { name: string; tags: readonly string[] }[] | undefined
+}
+
+/** HTTP methods that carry operations in an OpenAPI path item. */
+const methods: readonly string[] = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'] // prettier-ignore
+
+/**
+ * Narrows the document to the data domain: operations tagged inside the
+ * `Data API` tag group, minus excluded tags. Management, relay, and session
+ * operations never surface as tools.
+ */
+function scope(document: Document): Openapi.OpenAPISpec {
+  const group = document['x-tagGroups']?.find((entry) => entry.name === tagGroup)
+  if (!group) throw new Error(`openapi.json is missing the "${tagGroup}" tag group`)
+  const tags = new Set(group.tags.filter((tag) => !excludedTags.includes(tag)))
+  const paths: Document['paths'] = {}
+  for (const [path, item] of Object.entries(document.paths)) {
+    // Keep in-domain operations; non-method keys (parameters, summary) ride along.
+    const entries = Object.entries(item).filter(([method, operation]) => {
+      if (!methods.includes(method)) return true
+      const tags_operation = (operation as { tags?: readonly string[] | undefined }).tags
+      return tags_operation?.some((tag) => tags.has(tag)) ?? false
+    })
+    if (entries.some(([method]) => methods.includes(method)))
+      paths[path] = Object.fromEntries(entries)
+  }
+  return { ...document, paths }
+}
+
+export declare namespace mcp {
+  /** Options for the MCP route group. */
+  type Options = {
+    /** Remote docs MCP source mounted as the `docs` tool group, or `false` to omit it. @default 'https://mcp.tempo.xyz/mcp' */
+    docs?: Source | false | undefined
+    /** In-process fetch handler for the composed app (e.g. `(request) => app.fetch(request)`). */
+    fetch: (request: Request) => Response | Promise<Response>
+    /** MCP server name. @default 'tapimo' */
+    name?: string | undefined
+    /** MCP server version. @default '0.0.0' */
+    version?: string | undefined
+  }
+
+  /** A remote streamable-HTTP MCP server endpoint. */
+  type Source =
+    | string
+    | URL
+    | {
+        /** Fetch handler used for MCP requests. Defaults to `globalThis.fetch`. */
+        fetch?: ((request: Request) => Response | Promise<Response>) | undefined
+        /** Headers merged into every MCP request. */
+        headers?: Record<string, string> | undefined
+        /** Streamable-HTTP MCP endpoint URL. */
+        url: string | URL
+      }
+}