feat(mcp): agent-first MCP surface, flow-spec DSL, capability discovery

.agents/skills/orpc-api/SKILL.md

@@ -217,6 +217,74 @@ guidance (valid values, example payloads, edge cases) an LLM needs to pick
 the right tool and fill it in correctly. A `findByCustomField`-style
 endpoint with ambiguous input shape should always set `description`.
 
+**Every DELETE (and any other body-less mutation) declares `successStatus:
+204`** — a handler with no `.output(...)` returns `undefined`, and without
+an explicit `successStatus` oRPC defaults to `200` with an empty body, which
+misrepresents the response. `apps/builder/__tests__/public-spec-operations.test.ts`
+enforces this across the whole public spec: every operation whose generated
+response has no declared body schema must document `successStatus: 204`
+(and nothing else in the 2xx range). If a mutation's handler actually
+`return`s data, add `.output(...)` instead of `successStatus: 204` — don't
+declare a body-less success status on a route that has a body.
+
+```typescript
+  delete: workspaceTokenAuthAPI
+    .route({
+      method: "DELETE",
+      path: "/v1/my-feature/{id}",
+      summary: "Delete item",
+      tags: ["MyFeature"],
+      successStatus: 204,
+    })
+    .input(z.object({ id: zodBigintAsString() }))
+    .errors(possibleErrorsOnDeletingResource)
+    .handler(async ({ context, input }) => {
+      await myFeatureService.delete({ id: input.id, workspaceId: context.workspace.id })
+    }),
+```
+
+**`mcpSpec`/`x-mcp` controls MCP-specific tool metadata** beyond what
+`summary`/`description`/`tags` cover — visibility in `tools/list`, whether a
+token-scope check can be bypassed so the tool is discoverable even when the
+caller lacks its scope, and the MCP read-only/destructive/idempotent hints.
+Import `mcpSpec` from `@/lib/orpc/mcp-annotations` and pass it as the
+function form of `.route({ spec: ... })` — **never a plain object**, which
+the OpenAPI generator treats as a full replacement of the generated
+operation (dropping `parameters`/`requestBody`/`responses`) rather than a
+merge:
+
+```typescript
+import { mcpSpec } from "@/lib/orpc/mcp-annotations"
+
+  list: workspaceTokenAuthAPI
+    .route({
+      method: "GET",
+      path: "/v1/my-feature",
+      summary: "List items",
+      tags: ["MyFeature"],
+      spec: mcpSpec({ visibility: "default" }),
+    })
+    // ...
+```
+
+- `visibility: "default"`** ships the tool in `tools/list` on every MCP
+  connection. The polarity is inverted from what you'd expect: **omitting
+  `spec` entirely (or `visibility` absent from it) means `"hidden"`** —
+  reachable only through the `search_tools`/`call_tool` meta-tools, not the
+  default connection payload. We cannot ask every one of the ~350 public
+  operations to opt out individually, so only the ~40 operations an agent
+  needs on every connection (list/get the most common resources, publish a
+  flow, etc.) opt IN.
+- `alwaysVisible: true` exempts an operation from scope-based `tools/list`
+  filtering — reserved for the small set of discovery endpoints
+  (`capabilities.get`, `token.get`) a token must be able to *see* even when
+  it lacks the scope those endpoints themselves require, so the caller gets
+  a 403 body instead of the tool silently disappearing.
+- `readOnlyHint`/`destructiveHint`/`idempotentHint` override the mcp-server
+  loader's HTTP-method-based inference (GET ⇒ read-only/idempotent, DELETE ⇒
+  destructive/idempotent, everything else ⇒ none) when an operation doesn't
+  fit that default.
+
 **`include`/`withCount` convention for list endpoints**: a public list
 endpoint whose row shape has optional relations or an expensive count query
 should accept `include?: string[]` (narrows the response payload — see

apps/builder/__tests__/__snapshots__/public-spec-mcp.test.ts.snap

@@ -0,0 +1,50 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`default tool set > operation ids match the curated snapshot 1`] = `
+[
+  "aiAgents.create",
+  "aiAgents.list",
+  "aiAgents.update",
+  "aiFiles.list",
+  "aiFunctions.list",
+  "analytics.blockedContactsPerDay",
+  "analytics.broadcastStats",
+  "analytics.flowStats",
+  "analytics.newContactCountsPerDay",
+  "analytics.sequenceStepStats",
+  "broadcasts.get",
+  "broadcasts.list",
+  "broadcasts.stop",
+  "capabilities.get",
+  "contacts.addTagsByName",
+  "contacts.create",
+  "contacts.get",
+  "contacts.list",
+  "contacts.listCustomFields",
+  "contacts.listMessages",
+  "contacts.listSequences",
+  "contacts.listTags",
+  "contacts.search",
+  "contacts.sendFlow",
+  "contacts.sendMessage",
+  "contacts.setCustomField",
+  "contacts.subscribeSequences",
+  "conversations.assign",
+  "conversations.get",
+  "conversations.list",
+  "errorLogs.list",
+  "flows.create",
+  "flows.get",
+  "flows.list",
+  "flows.publish",
+  "flows.updateDraft",
+  "flows.validate",
+  "keywords.list",
+  "messages.list",
+  "schemas.flowSpec",
+  "sequences.get",
+  "sequences.list",
+  "sequences.update",
+  "token.get",
+]
+`;

apps/builder/__tests__/__snapshots__/public-spec-operations.test.ts.snap

@@ -587,6 +587,11 @@ exports[`public API spec — operation naming guard > operation list (operationI
     "operationId": "broadcasts.updateDraft",
     "path": "/v1/broadcasts/{id}/draft",
   },
+  {
+    "method": "GET",
+    "operationId": "capabilities.get",
+    "path": "/v1/capabilities",
+  },
   {
     "method": "POST",
     "operationId": "channels.deliveryStatus",
@@ -1182,6 +1187,11 @@ exports[`public API spec — operation naming guard > operation list (operationI
     "operationId": "flows.updateDraft",
     "path": "/v1/flows/{id}/draft",
   },
+  {
+    "method": "POST",
+    "operationId": "flows.validate",
+    "path": "/v1/flows/validate",
+  },
   {
     "method": "GET",
     "operationId": "flows.versions",
@@ -1697,6 +1707,11 @@ exports[`public API spec — operation naming guard > operation list (operationI
     "operationId": "savedReplies.update",
     "path": "/v1/saved-replies/{id}",
   },
+  {
+    "method": "GET",
+    "operationId": "schemas.flowSpec",
+    "path": "/v1/schemas/flow-spec",
+  },
   {
     "method": "POST",
     "operationId": "sequences.create",
@@ -1827,6 +1842,11 @@ exports[`public API spec — operation naming guard > operation list (operationI
     "operationId": "templateMessages.list",
     "path": "/v1/template-messages",
   },
+  {
+    "method": "GET",
+    "operationId": "token.get",
+    "path": "/v1/token",
+  },
   {
     "method": "POST",
     "operationId": "triggers.create",

apps/builder/__tests__/capabilities-public-api.test.ts

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, test, vi } from "vitest"
+
+type RouteConfig = {
+  method: string
+  path: string
+  summary: string
+  tags: string[]
+}
+
+type CapturedProcedure = {
+  route: RouteConfig
+  handler?: (...args: any[]) => any
+}
+
+const { workspaceTokenAuthAPIForScope, capturedProcedures } = vi.hoisted(() => {
+  const capturedProcedures: CapturedProcedure[] = []
+
+  const makeProcedure = (route: RouteConfig) => {
+    const record: CapturedProcedure = { route }
+    capturedProcedures.push(record)
+
+    const chain = {
+      input: vi.fn(() => chain),
+      output: vi.fn(() => chain),
+      errors: vi.fn(() => chain),
+      handler: vi.fn((fn: (...args: any[]) => any) => {
+        record.handler = fn
+        return { handler: fn }
+      }),
+    }
+    return chain
+  }
+
+  const workspaceTokenAuthAPI = {
+    route: vi.fn((config: RouteConfig) => makeProcedure(config)),
+  }
+
+  return {
+    workspaceTokenAuthAPIForScope: vi.fn(
+      (_scope: string) => workspaceTokenAuthAPI,
+    ),
+    capturedProcedures,
+  }
+})
+
+vi.mock("@/orpc", () => ({ workspaceTokenAuthAPIForScope }))
+
+vi.mock("@chatbotx.io/business", () => ({
+  quotaEnforcementService: {},
+  userQuotaService: {},
+}))
+
+vi.mock("@chatbotx.io/business/errors", () => ({
+  ChatbotXException: class extends Error {},
+}))
+
+const getCapabilities = vi.fn()
+vi.mock("@chatbotx.io/business/capabilities", () => ({
+  CAPABILITIES_INCLUDES: [
+    "inboxes",
+    "templates",
+    "customFields",
+    "botFields",
+    "tags",
+    "aiAgents",
+    "sequences",
+    "flows",
+    "flowSpec",
+  ],
+  getCapabilities,
+}))
+
+await import("@/features/capabilities/api/public")
+
+const findProcedure = (method: string, path: string) => {
+  const found = capturedProcedures.find(
+    (p) => p.route.method === method && p.route.path === path,
+  )
+  if (!found) {
+    throw new Error(`No procedure registered for ${method} ${path}`)
+  }
+  return found
+}
+
+const scopeArgAtImport = workspaceTokenAuthAPIForScope.mock.calls[0]?.[0]
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+test("registers the capabilities public router under the contacts scope", () => {
+  expect(scopeArgAtImport).toBe("contacts")
+})
+
+describe("GET /v1/capabilities", () => {
+  const procedure = findProcedure("GET", "/v1/capabilities")
+
+  test("delegates to getCapabilities with the workspace id and no include by default", async () => {
+    getCapabilities.mockResolvedValueOnce({ tags: [{ id: "1", name: "VIP" }] })
+
+    const result = await procedure.handler?.({
+      context: { workspace: { id: "workspace-1" } },
+      input: {},
+    })
+
+    expect(getCapabilities).toHaveBeenCalledWith({
+      workspaceId: "workspace-1",
+      include: undefined,
+    })
+    expect(result).toEqual({ tags: [{ id: "1", name: "VIP" }] })
+  })
+
+  test("forwards a parsed include list", async () => {
+    getCapabilities.mockResolvedValueOnce({})
+
+    await procedure.handler?.({
+      context: { workspace: { id: "workspace-1" } },
+      input: { include: ["tags", "flows"] },
+    })
+
+    expect(getCapabilities).toHaveBeenCalledWith({
+      workspaceId: "workspace-1",
+      include: ["tags", "flows"],
+    })
+  })
+})
+
+describe("GET /v1/schemas/flow-spec", () => {
+  const procedure = findProcedure("GET", "/v1/schemas/flow-spec")
+
+  test("returns a JSON Schema object describing the flow-spec DSL", async () => {
+    const result = await procedure.handler?.({
+      context: { workspace: { id: "workspace-1" } },
+      input: {},
+    })
+
+    // A real JSON Schema for a discriminated union of 8 step kinds — assert
+    // it is genuinely derived from the zod schema (has the right shape),
+    // not that it equals some hand-maintained fixture that could drift.
+    expect(result).toHaveProperty("type")
+    expect(JSON.stringify(result)).toContain("formatVersion")
+    expect(JSON.stringify(result)).toContain("steps")
+  })
+})