tapimo 0.1.0 → 0.3.0

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. Platform, 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
+      }
+}

package/src/apps/metadata.ts

@@ -0,0 +1,23 @@
+import type { Hono } from 'hono'
+
+import type * as App from '../App.js'
+
+// Hono's `.route()` drops sub-app metadata, so a group's OpenAPI metadata can't
+// ride the instance through it. Each group attaches its metadata here and
+// `App.create` reads it back on mount. The `WeakMap` keeps the association off
+// the app's type, so `testClient`/`hc` inference is untouched.
+const registry = new WeakMap<Hono<any, any>, App.create.Metadata>()
+
+/** Attaches a group's OpenAPI metadata to its app instance for `create` to collect on mount. */
+export function attach<const app extends Hono<any, any>>(
+  app: app,
+  metadata: App.create.Metadata,
+): app {
+  registry.set(app, metadata)
+  return app
+}
+
+/** Reads the OpenAPI metadata attached to an app instance, if any. */
+export function read(app: Hono<any, any>): App.create.Metadata | undefined {
+  return registry.get(app)
+}

package/src/apps/platform/App.ts

@@ -0,0 +1,169 @@
+import { Hono } from 'hono'
+import type Stripe from 'stripe'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+
+import { apiKeys } from './routes/api-keys.js'
+import { billing } from './routes/billing.js'
+import { invitations } from './routes/invitations.js'
+import { me } from './routes/me.js'
+import { members } from './routes/members.js'
+import { orgs } from './routes/orgs.js'
+import { projects } from './routes/projects.js'
+import { scopes } from './routes/scopes.js'
+import { usage } from './routes/usage.js'
+
+/**
+ * Minimal transactional email sender. Cloudflare deployments wrap the Email
+ * Service binding (`{ from, send: (m) => env.EMAIL.send(m) }`); other hosts
+ * pass any compatible sender. Dispatch is always best-effort.
+ */
+export type Email = {
+  /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
+  consoleUrl?: string | undefined
+  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  from: string
+  /** Sends one message. */
+  send: (message: Email.Message) => Promise<unknown>
+}
+
+export declare namespace Email {
+  /** One transactional message. */
+  type Message = {
+    /** Sender address. */
+    from: string
+    /** HTML body. */
+    html?: string | undefined
+    /** Subject line. */
+    subject: string
+    /** Plain-text body. */
+    text: string
+    /** Recipient address. */
+    to: string
+  }
+}
+
+/** Billing capability, one bag per billing source; Stripe is the sole source today. */
+export type Billing = {
+  /**
+   * Stripe billing source.
+   */
+  stripe: {
+    /** Constructed Stripe client. */
+    client: Stripe
+    /** Console URL for Checkout/portal return links when the request carries no `Origin`. Defaults to the hosted console. */
+    consoleUrl?: string | undefined
+    /** Test-mode Stripe backing sandbox billing; omit to keep sandbox billing 501. */
+    sandbox?:
+      | {
+          /** Constructed test-mode Stripe client. */
+          client: Stripe
+          /** Test-mode webhook endpoint signing secret (`whsec_…`). */
+          webhookSecret: string
+        }
+      | undefined
+    /** Webhook endpoint signing secret (`whsec_…`). */
+    webhookSecret: string
+  }
+}
+
+/**
+ * Request environment for platform routes: the shared app environment plus the
+ * capabilities this group publishes on context (`billing`, `email`). Owned
+ * here, not in core `App.Environment`, since these are platform concerns.
+ */
+export type Environment = {
+  Variables: App.Environment['Variables'] & {
+    /** Stripe billing capability; undefined when billing is unconfigured. */
+    billing: Billing | undefined
+    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    email: Email | undefined
+  }
+}
+
+/**
+ * The tenant-platform route group: the current user, orgs, projects, members,
+ * invitations, and API-key management. Every route reads its dependencies from
+ * request context set by {@link App.create}.
+ *
+ * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
+ * {@link App.create}, so platform routes gate on a session without owning it.
+ *
+ * ```ts
+ * App.create(options).route('/', platform())
+ * ```
+ */
+export function platform(options: platform.Options = {}) {
+  const app = new Hono<Environment>()
+    // Publish this group's capabilities for handlers; undefined disables each.
+    .use('*', async (c, next) => {
+      c.set('billing', options.billing)
+      c.set('email', options.email)
+      await next()
+    })
+    .route('/', apiKeys({ enabled: options.apiKeys !== false }))
+    .route('/', billing())
+    .route('/', invitations())
+    .route('/', me())
+    .route('/', members())
+    .route('/', orgs())
+    .route('/', projects())
+    .route('/', scopes())
+    .route('/', usage())
+  return Metadata.attach(app, openapi)
+}
+
+export declare namespace platform {
+  /** Options for the platform route group. */
+  type Options = {
+    /** Expose the API-key management routes in the OpenAPI document. @default true */
+    apiKeys?: boolean | undefined
+    /** Stripe billing capability; omit to disable billing routes (501) and keep production sponsorship closed. */
+    billing?: Billing | undefined
+    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    email?: Email | undefined
+  }
+}
+
+/**
+ * The OpenAPI metadata this group owns: platform operation tags and the
+ * `session` security scheme. Tagged onto the {@link platform} instance so
+ * `App.create` collects it.
+ */
+const openapi = {
+  securitySchemes: {
+    session: {
+      description: 'Cookie session established by sign-in (`POST /v1/auth/siwe`). Clients may also send the session token as `Authorization: Bearer <token>`.', // prettier-ignore
+      in: 'cookie',
+      name: 'accounts_auth',
+      type: 'apiKey',
+    },
+  },
+  tags: [
+    { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
+    { name: 'Billing', description: 'Organization billing backed by Stripe.' },
+    { name: 'Invitations', description: 'Pending organization invitations.' },
+    { name: 'Members', description: 'Organization team membership.' },
+    { name: 'Organizations', description: 'Teams that own application workspaces and members.' },
+    { name: 'Projects', description: 'Application workspaces within an organization.' },
+    { name: 'Usage', description: 'Request and sponsorship usage for organizations.' },
+    { name: 'Users', description: 'Users on the Tempo Platform.' },
+  ],
+  'x-tagGroups': [
+    {
+      name: 'Platform API',
+      tags: [
+        'API Keys',
+        'Authentication',
+        'Billing',
+        'Invitations',
+        'Members',
+        'Organizations',
+        'Projects',
+        'Usage',
+        'Users',
+      ],
+    },
+  ],
+} satisfies App.create.Metadata