feat(mcp): validate_expression tool — validate CEL against a schema before authoring (#1928)

[os-zhuang]

What

An agent-callable validate_expression MCP tool — the authoring-time surface the #1928 guardrail series always pointed at. It runs the same build-time checks as objectstack build, so an AI can validate a formula / predicate / flow condition while writing it instead of shipping one that silently evaluates to null.

Earlier PRs added the checks (tiers 1–4, #3178) and brought registerFlow to parity (#3190). This exposes them as a tool an agent can call directly. (The originally-floated validate_expression was scoped to the cloud service-ai package, which isn't in this repo; the MCP tool surface is the right in-repo home, and it reuses every primitive @objectstack/formula already exports.)

The tool

validate_expression({ objectName, expression, site? }) → resolves the object's real schema (field names + types) via the principal-bound describeObject bridge and returns:

• errors — bare field refs (amount → record.amount), unknown fields (did-you-mean), unknown functions
• warnings — text/boolean fields misused in arithmetic, date-equality pitfalls
• inScope — the fields, stdlib functions, and namespace roots available (so the model can self-correct)
• inferredType — for a formula site

site (formula | validation | flow_condition | template, default formula) maps to the validator's role + scope: flow_condition binds fields bare, the others bind record.<field>.

Security

Read-only (readOnlyHint), gated by the data:read OAuth scope, and fail-closed on sys_* objects — identical posture to describe_object. Runs entirely through the injected principal-bound bridge; no direct engine access. @objectstack/mcp gains a @objectstack/formula dependency (acyclic — formula's only dep is @objectstack/spec).

Testing

• @objectstack/mcp — 80 green (+8 tool cases: sound formula + inScope/inferredType; bare-ref error; unknown-field error; tier-4 text-in-arithmetic warning; flattened flow condition; object-not-found; sys_* refusal).
• Updated the 3 tool-surface assertions (scopes gating, HTTP tools/list) and the SKILL.md drift guard (src/skill.ts) to include the new tool.
• Build + DTS type-check clean.

Refs: #1928 (closed), #3178, #3190.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hnji7EEYR2mGt6pY53a8Bm

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Error		Jul 18, 2026 9:33am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/mcp.

9 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/actions-as-tools.mdx (via @objectstack/mcp)
• content/docs/ai/agents.mdx (via @objectstack/mcp)
• content/docs/ai/index.mdx (via @objectstack/mcp)
• content/docs/ai/natural-language-queries.mdx (via @objectstack/mcp)
• content/docs/api/index.mdx (via @objectstack/mcp)
• content/docs/deployment/environment-variables.mdx (via @objectstack/mcp)
• content/docs/plugins/packages.mdx (via @objectstack/mcp)
• content/docs/protocol/knowledge.mdx (via @objectstack/mcp)
• content/docs/releases/implementation-status.mdx (via @objectstack/mcp)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.