Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

narrative.ts

37 lines1.8 KB

1/**
2 * Narrative API root (PLAN.md task 11.2). A JSON-accepting GET / returns
3 * what an MCP `initialize` instructions field carries: narrative
4 * description, workflow, inline examples, and HAL links. The instructions
5 * text IS the llms.txt source, so the three surfaces (root narrative, MCP
6 * initialize, llms.txt) cannot drift.
7 */
8import { serviceIndex } from '#/routes/v1/index.ts'
9import { llmsTxt } from '#/server/llms-txt.ts'
10​
11/** The MCP initialize `instructions` text — shared with GET / (json). */
12export const NARRATIVE_INSTRUCTIONS = llmsTxt
13​
14export function narrativeRoot(origin: string): Record<string, unknown> {
15 return {
16 service: 'modelschemas',
17 description:
18 'Live AI model schemas: which models exist right now, and what their request/response payloads look like — model lists refresh every 15 minutes, full provider specs daily.',
19 instructions: NARRATIVE_INSTRUCTIONS,
20 quickstart: [
21 `GET ${origin}/v1/models?activity=chat&q=claude — what can I call right now`,
22 `GET ${origin}/v1/schemas/anthropic/chat/v1%2Fmessages?kind=input — exact request shape`,
23 `POST ${origin}/v1/validate — check a payload before spending tokens`,
24 `POST ${origin}/v1/estimate — amount and currency from the stored rate card`,
25 `GET ${origin}/v1/changes?limit=20 — what changed since I last looked`,
26 ],
27 mcp: { endpoint: `${origin}/mcp`, transport: 'streamable-http' },
28 _links: serviceIndex._links,
29 }
31​
32/** True for GET/HEAD requests that explicitly prefer JSON over HTML. */
33export function wantsJsonRoot(request: Request): boolean {
34 if (request.method !== 'GET' && request.method !== 'HEAD') return false
35 const accept = request.headers.get('accept') ?? ''
36 return accept.includes('application/json') && !accept.includes('text/html')