okengine 0.18.4 → 0.19.0

package/site/content/docs/elements/ai/mcp.mdx

@@ -0,0 +1,275 @@
+---
+title: "MCP"
+description: "Two directions — expose Flows as gated mcp.tool endpoints on :6535, and consume external servers with ai.mcpServer allowlists."
+icon: "Plug"
+source: "docs/spec/unified-theory.md"
+---
+
+Model Context Protocol (MCP) connects OKE to Cursor, Claude Desktop, and other agents in
+**two directions**: your app exposes selected Flows as tools, and your Flows call tools on
+external MCP servers.
+
+For developers wiring Cursor to a backend or letting an agent open a GitHub issue — opt-in
+gates inbound; allowlists outbound.
+
+<Callout title="The one rule">
+  Inbound: `on(mcp.tool("name").gate(...), flow)` — ungated tools are not exposed. Outbound:
+  `ai.mcpServer` with a required `tools` allowlist — the runtime never trusts raw `tools/list`.
+</Callout>
+
+## Smallest Example — expose a Flow
+
+<Steps>
+
+<Step>
+### Bind a gated MCP tool
+
+```typescript title="src/flows/bookings/create.ts"
+import { on, flow, mcp } from "okengine";
+import { z } from "zod";
+import { member } from "@/core/gate";
+
+export const create = on(
+  mcp
+    .tool("bookings.create", {
+      in: z.object({
+        guest: z.string().min(1),
+        night: z.string(),
+      }),
+      out: z.object({ id: z.string(), guest: z.string(), night: z.string() }),
+    })
+    .gate(member),
+  flow({
+    do: async (input, fx) => {
+      return { id: fx.id(), ...input };
+    },
+  }),
+);
+```
+
+Deny-by-default: `on(mcp.tool("…"), flow)` without `.gate(...)` fails gate posture at boot.
+
+</Step>
+
+<Step>
+### Connect a client
+
+App MCP listens on port **6535**, path **`/mcp`** (not the backend `:6530` HTTP port). Bearer
+auth is required.
+
+```json
+{
+  "mcpServers": {
+    "notes": {
+      "url": "http://127.0.0.1:6535/mcp",
+      "headers": {
+        "Authorization": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+`GET /health` on the same port probes liveness. Override with `ports.mcp` in config when needed.
+
+</Step>
+
+<Step>
+### Call the tool
+
+The client lists `bookings.create` (and other gated tools). Invocations run the Flow under the
+same gate chain as HTTP.
+
+</Step>
+
+</Steps>
+
+## Smallest Example — consume a server
+
+<Steps>
+
+<Step>
+### Declare an outbound server
+
+```typescript title="src/core/mcp.ts"
+import { ai, vault } from "okengine";
+
+const githubToken = vault.secret("GITHUB_MCP_TOKEN");
+
+export const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: githubToken },
+  tools: ["create_issue", "list_repos"],
+});
+
+export const createIssue = github.tool("create_issue"); // mcp:github/create_issue
+```
+
+Exactly one of `url` (Streamable HTTP) or `command` (+ optional `args` for stdio). Bearer must
+be a `vault.secret` handle or contract name — never a token literal in source.
+
+</Step>
+
+<Step>
+### Use in ask / agent tools
+
+```typescript
+await fx.ask(triage, input, {
+  tools: [github.tool("create_issue")],
+  maxSteps: 2,
+});
+```
+
+Capability ref is `mcp:github/create_issue`. Model-facing names use `server__tool`
+(`github__create_issue`).
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Inbound gate", "stdio server", "Agent bag", "Docs MCP"]}>
+
+<Tab value="Inbound gate">
+
+Chain policies like HTTP — first denial wins:
+
+```typescript
+on(
+  mcp.tool("admin.wipe").gate(member, gate.scope("admin")),
+  flow({ do: async (_input, fx) => fx.json.empty() }),
+);
+```
+
+</Tab>
+
+<Tab value="stdio server">
+
+Local executable transport:
+
+```typescript
+export const localTools = ai.mcpServer("local", {
+  command: "npx",
+  args: ["-y", "some-mcp-server"],
+  tools: ["lookup"],
+});
+```
+
+</Tab>
+
+<Tab value="Agent bag">
+
+Mix Flows and MCP refs on one agent:
+
+```typescript
+ai.agent("planner", {
+  model: "smart",
+  tools: ["tasks.create", github.tool("create_issue")],
+  maxSteps: 8,
+  budget: { maxCostPerRun: 0.25 },
+});
+```
+
+</Tab>
+
+<Tab value="Docs MCP">
+
+Read-only docs MCP is a **separate** process on port **6536** — not your app’s `:6535` tool
+server. Use it for documentation search, not business Flows.
+
+</Tab>
+
+</Tabs>
+
+## Inbound reference
+
+| Piece   | Detail                                                 |
+| ------- | ------------------------------------------------------ |
+| Trigger | `mcp.tool(name, { in, out, errors? })` from `okengine` |
+| Gates   | `.gate(...)` required for exposure                     |
+| Port    | **6535** (`ports.mcp`)                                 |
+| Path    | `POST /mcp` · `GET /health`                            |
+| Auth    | Bearer required (`Bearer token required`)              |
+
+Empty name throws `TypeError: mcp.tool(name): name is required`.
+
+## Outbound reference — `ai.mcpServer`
+
+| Option        | Type          | Required      | Meaning                            |
+| ------------- | ------------- | ------------- | ---------------------------------- |
+| `url`         | `string`      | XOR `command` | Streamable HTTP endpoint           |
+| `command`     | `string`      | XOR `url`     | stdio executable (no shell string) |
+| `args`        | `string[]`    | no            | Arguments for `command`            |
+| `auth.bearer` | secret / name | no            | Vault contract for Bearer          |
+| `tools`       | `string[]`    | **yes**       | Allowlist — never raw `tools/list` |
+
+| Method              | Returns                       | Meaning                                    |
+| ------------------- | ----------------------------- | ------------------------------------------ |
+| `server.tool(name)` | `{ name: "mcp:server/tool" }` | Capability ref for ask / agent / `fx.call` |
+
+### Declare errors
+
+| Message                                 | Fix                                         |
+| --------------------------------------- | ------------------------------------------- |
+| `ai.mcpServer: name is required`        | Pass a non-empty server id                  |
+| `name "…" must not contain "/" or "__"` | Use a simple id (`github`, not `org/repo`)  |
+| `tools allowlist is required`           | Pass `tools: ["…"]`                         |
+| `declare exactly one of url or command` | Pick HTTP **or** stdio                      |
+| `tool "…" is not in the allowlist`      | Add the name to `tools` before `.tool(...)` |
+
+## Ports
+
+| Port     | Surface                  |
+| -------- | ------------------------ |
+| **6530** | Backend HTTP             |
+| **6535** | App MCP (Flows as tools) |
+| **6536** | Docs MCP (read-only)     |
+
+Mnemonic: O·K·E = 6·5·3.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Bearer token required">
+  Clients must send `Authorization: Bearer …`. Missing or invalid Bearer is rejected before tool
+  dispatch.
+</Accordion>
+
+<Accordion title="Tool missing from Cursor / client list">
+  The Flow is not bound with `mcp.tool(…).gate(…)`, gates deny the identity, or the client points at
+  `:6530` instead of `:6535/mcp`.
+</Accordion>
+
+<Accordion title="Ungated mcp.tool fails at boot">
+  Deny-by-default posture: attach at least one gate. Public-style exposure still needs an explicit
+  gate policy you intend (there is no `.public()` on MCP triggers).
+</Accordion>
+
+<Accordion title="ai.mcpServer allowlist / transport errors">
+  See the declare-error table above. Runtime `ai.mcp: …` covers unknown server, non-allowlisted
+  tool, and unsupported HITL prompts from the remote.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Agents](/docs/elements/ai/agents) — MCP refs in tool bags
+- [Gate](/docs/elements/gate) — policies on `mcp.tool`
+- [Vault](/docs/elements/vault) — bearer secret contracts
+- [AI](/docs/elements/ai) — element overview
+- [Security](/docs/reference/security) — ports 6530 · 6533 · 6535 · 6536
+
+## Next
+
+<Cards>
+  <Card
+    title="Agents"
+    description="Run bounded agents that call MCP tools."
+    href="/docs/elements/ai/agents"
+  />
+  <Card title="AI" description="Models, prompts, and fx.ask." href="/docs/elements/ai" />
+  <Card title="Flow" description="Flows are the tools MCP exposes." href="/docs/elements/flow" />
+</Cards>

package/site/content/docs/elements/ai/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "AI",
+  "icon": "Sparkles",
+  "pages": ["index", "models", "prompts", "agents", "mcp"]
+}

package/site/content/docs/elements/ai/models.mdx

@@ -0,0 +1,283 @@
+---
+title: "Models"
+description: "Declare ai.model bindings — known providers auto-resolve baseUrl; Anthropic and Google OpenAI-compat have documented limits."
+icon: "Cpu"
+source: "docs/spec/unified-theory.md"
+---
+
+An `ai.model` binding names a logical model (`smart`, `local`, …), the wire `model` id, and how
+to reach it (`provider`, optional `baseUrl` / `apiKey` / `driverId`).
+
+For developers swapping OpenRouter for a self-hosted OpenAI-compatible `/v1` — one logical
+name, different bindings per environment.
+
+<Callout title="The one rule">
+  Known OpenAI-compatible `provider` names resolve `baseUrl` automatically. Explicit `baseUrl`
+  always wins. Unknown providers require `baseUrl` — they fail loud. Per-binding `apiKey` isolates
+  tokens when several providers run together.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare cloud + BYO bindings
+
+```typescript title="src/core/ai.ts"
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const local = ai.model("local", {
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_MODEL ?? "your-model-id",
+  ...(process.env.OKE_AI_URL?.trim() ? { baseUrl: process.env.OKE_AI_URL.trim() } : {}),
+});
+```
+
+OpenRouter fills `https://openrouter.ai/api/v1` without typing it. Any
+OpenAI-compatible `/v1` uses the same driver — set `OKE_AI_URL` yourself;
+Compose does not manage inference.
+
+</Step>
+
+<Step>
+### Attach a versioned prompt
+
+```typescript
+export const triage = smart.prompt("ticket-triage", {
+  version: 1,
+  via: ["smart", "local"],
+});
+```
+
+</Step>
+
+<Step>
+### Ask from a Flow
+
+```typescript title="src/flows/support/triage.ts"
+import { on, flow, http } from "okengine";
+import { triage } from "@/core/ai";
+
+export const classify = on(
+  http.post(),
+  flow({
+    do: async (input, fx) => await fx.ask(triage, input),
+  }),
+);
+```
+
+`fx.ask` uses the prompt’s model chain. Recovery via `via` opens a **separate** client per
+binding — keys and base URLs do not mix.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["OpenRouter", "BYO /v1", "Native Anthropic", "Multi-key"]}>
+
+<Tab value="OpenRouter">
+
+Zero Docker — registry fills the URL:
+
+```typescript
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+See [OpenRouter](/docs/recipes/openrouter) for router aliases (`openrouter/auto`, fusion, …).
+
+</Tab>
+
+<Tab value="BYO /v1">
+
+Same `openai-compatible` driver — you supply the base URL (no Compose AI recipe):
+
+```typescript
+export const local = ai.model("local", {
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_MODEL ?? "your-model-id",
+  baseUrl: process.env.OKE_AI_URL, // must end in /v1
+});
+```
+
+Pin `drivers.ai.dev: "openai-compatible"`. Set `OKE_AI_URL` / `OKE_AI_MODEL`
+in env, or pass `baseUrl` on the binding.
+
+</Tab>
+
+<Tab value="Native Anthropic">
+
+Production Claude — native Messages API, not the OpenAI-compat shim:
+
+```typescript
+export const claude = ai.model("claude", {
+  provider: "anthropic",
+  model: "claude-sonnet-4-20250514",
+  driverId: "anthropic",
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+```
+
+</Tab>
+
+<Tab value="Multi-key">
+
+One binding per provider so tokens never collide:
+
+```typescript
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/auto",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const gpt = ai.model("gpt", {
+  provider: "openai",
+  model: "gpt-4.1-mini",
+  apiKey: process.env.OPENAI_API_KEY,
+});
+```
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option     | Type     | Default     | Meaning                                                       |
+| ---------- | -------- | ----------- | ------------------------------------------------------------- |
+| `provider` | `string` | —           | Registry name or exempt/local label                           |
+| `model`    | `string` | —           | Wire model id sent to the provider                            |
+| `baseUrl`  | `string` | auto / omit | Override (always wins over registry)                          |
+| `apiKey`   | `string` | —           | Per-binding key (isolates multi-provider apps)                |
+| `driverId` | `string` | app default | Protocol driver (`openai-compatible`, `anthropic`, `mock`, …) |
+| `tier`     | `string` | —           | Optional app label (not the registry status below)            |
+
+Empty name throws `TypeError: ai.model: name is required`.
+
+## Verified providers
+
+These names auto-resolve a verified OpenAI-compatible `baseUrl`:
+
+| Provider     | Base URL (auto)                       |
+| ------------ | ------------------------------------- |
+| `openai`     | `https://api.openai.com/v1`           |
+| `openrouter` | `https://openrouter.ai/api/v1`        |
+| `groq`       | `https://api.groq.com/openai/v1`      |
+| `together`   | `https://api.together.ai/v1`          |
+| `deepinfra`  | `https://api.deepinfra.com/v1/openai` |
+| `xai`        | `https://api.x.ai/v1`                 |
+| `mistral`    | `https://api.mistral.ai/v1`           |
+| `deepseek`   | `https://api.deepseek.com`            |
+| `vercel`     | `https://ai-gateway.vercel.sh/v1`     |
+
+**Not** registered (pass `baseUrl` if you still need them): Cloudflare Workers AI
+(account-scoped URL); Meta (retired Llama OpenAI-compat API / unverified Muse Spark
+host — do not guess a URL).
+
+Exempt labels (no registry URL): `mock`, `local`, `openai-compatible`.
+
+## Limited compatibility
+
+`anthropic`, `google`, and alias `gemini` also auto-resolve a URL, with documented limits.
+Prefer native Anthropic for production Claude.
+
+| Provider            | Base URL (auto)                                           |
+| ------------------- | --------------------------------------------------------- |
+| `anthropic`         | `https://api.anthropic.com/v1`                            |
+| `google` / `gemini` | `https://generativelanguage.googleapis.com/v1beta/openai` |
+
+<Callout type="warn" title="Anthropic OpenAI-compat is evaluation-only">
+  Anthropic’s OpenAI-compatible endpoint is for testing/comparison only. `tools[].function.strict`
+  is ignored; `n` must be 1; no embeddings here. **Production:** `driverId: "anthropic"` (native
+  Messages API).
+</Callout>
+
+<Callout type="warn" title="Google OpenAI-compat tool schemas">
+  Tool/parameter schemas are not full OpenAI JSON Schema fidelity. Complex Flow-as-tool schemas can
+  fail — do not rely on this path for agent tool calling in production.
+</Callout>
+
+Declare-time and `oke extract` both warn when these providers auto-resolve.
+
+## Native vs OpenAI-compat Anthropic
+
+| Path                                          | When                                            |
+| --------------------------------------------- | ----------------------------------------------- |
+| `driverId: "anthropic"`                       | Production Claude — native Messages API         |
+| `provider: "anthropic"` without native driver | Quick eval via openai-compatible + registry URL |
+
+They are not interchangeable for agents that depend on reliable tool calling.
+
+## Streaming
+
+`fx.stream(model, { prompt, data?, via? })` records `asks` and yields token chunks. Drivers
+that do not support stream throw
+`ai: model "…" (driver …) does not support stream`.
+
+```typescript
+for await (const chunk of fx.stream(smart, { prompt: "Say hello" })) {
+  // chunk is a string token
+}
+```
+
+## Per-environment drivers
+
+See [AI Overview](/docs/elements/ai#per-environment-drivers). create-oke does **not** pin
+`drivers.ai` by default — unset dev/test → `mock`; prod must declare.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='ai.model: unknown provider "…" requires an explicit baseUrl'>
+  The name is not in the registry (and not an exempt local label). Pass `baseUrl`, or use a known
+  provider id from the tables above. Exact message lists known providers and notes that Cloudflare
+  and Meta always need `baseUrl`.
+</Accordion>
+
+<Accordion title="Limited-compatibility warn on extract / declare">
+  Expected for `anthropic` / `google` / `gemini` when auto-resolving the OpenAI-compat URL. Switch
+  to native `driverId: "anthropic"` for production Claude.
+</Accordion>
+
+<Accordion title='ai: no client for model "…" and no defaultDriver'>
+  The binding has no resolvable client and boot has no default AI driver. Pin `drivers.ai` or set
+  `OKE_AI_DRIVER` / `OKE_AI_URL` for the active environment.
+</Accordion>
+
+<Accordion title="TypeError: ai.model: name is required">
+  Pass a non-empty logical name (`"smart"`, `"local"`, …).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [OpenRouter](/docs/recipes/openrouter) — free / auto / fusion routers
+- [Prompts](/docs/elements/ai/prompts) — `model.prompt` and `via`
+- [AI](/docs/elements/ai) — element overview and `fx` surface
+
+## Next
+
+<Cards>
+  <Card
+    title="Prompts"
+    description="Versioned prompts and via chains."
+    href="/docs/elements/ai/prompts"
+  />
+  <Card title="OpenRouter" description="Zero-cost cloud default." href="/docs/recipes/openrouter" />
+  <Card title="AI" description="Element overview." href="/docs/elements/ai" />
+</Cards>