refactor(mcp): convert via native Standard JSON Schema; drop standard-json + quansync

Replace @standard-community/standard-json with the schema's own Standard
JSON Schema converter (~standard.jsonSchema from @standard-schema/spec,
implemented by e.g. zod 4). This keeps JSON-schema generation
vendor-neutral and precise for validators that ship a converter, while
removing the @standard-community/standard-json + quansync dependencies and
reverting the async conversion back to synchronous.

Validators without a native converter degrade to a permissive object
schema. The inspect plugin additionally keeps @valibot/to-json-schema as a
fallback so it still converts valibot schemas precisely.

Technique adapted from PR #155.

Author: antfubot

AGENTS.md

@@ -36,7 +36,7 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 ## Conventions
 
 - RPC functions must use `defineRpcFunction`; always namespace IDs `devframes:plugin:<slug>:<fn-name>` (matching the plugin's `@devframes/plugin-<slug>` package name).
-- **Stay validator-neutral.** `devframe` and every `@devframes/*` package must not introduce a preferred schema validator dependency — no `valibot`, `zod`, `arktype`, etc. in their runtime `dependencies`. `args`/`returns`/flag schemas are typed against [Standard Schema](https://standardschema.dev/) (`@standard-schema/spec`, types-only); first-party code that needs to author a schema uses the built-in zero-dep `devframe/utils/simple-schema` builder (deliberately minimal — not a general validator). JSON-schema conversion goes through `@standard-community/standard-json`, whose per-vendor converters are optional peers, so no validator is forced. Docs, by contrast, should point *users* at a real validator for their own integrations — recommend **valibot** (lightest) or **zod** (worth reusing if they already pull it via the JSON-render or MCP integrations).
+- **Stay validator-neutral.** `devframe` and every `@devframes/*` package must not introduce a preferred schema validator dependency — no `valibot`, `zod`, `arktype`, etc. in their runtime `dependencies`. `args`/`returns`/flag schemas are typed against [Standard Schema](https://standardschema.dev/) (`@standard-schema/spec`, types-only); first-party code that needs to author a schema uses the built-in zero-dep `devframe/utils/simple-schema` builder (deliberately minimal — not a general validator). JSON-schema conversion uses each schema's own Standard JSON Schema converter (`~standard.jsonSchema`, implemented by e.g. zod 4) when present and degrades to a permissive object otherwise — no converter library and no vendor dependency is required. Docs, by contrast, should point *users* at a real validator for their own integrations — recommend **valibot** (lightest) or **zod** (worth reusing if they already pull it via the JSON-render or MCP integrations).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
 - Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) — add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.

packages/devframe/package.json

@@ -83,7 +83,6 @@
     }
   },
   "dependencies": {
-    "@standard-community/standard-json": "catalog:deps",
     "@standard-schema/spec": "catalog:deps",
     "birpc": "catalog:deps",
     "crossws": "catalog:deps",
@@ -92,7 +91,6 @@
     "mrmime": "catalog:deps",
     "nostics": "catalog:deps",
     "pathe": "catalog:deps",
-    "quansync": "catalog:deps",
     "ufo": "catalog:deps"
   },
   "devDependencies": {

packages/devframe/src/adapters/mcp/__tests__/to-json-schema.test.ts

@@ -1,47 +1,56 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import * as v from 'valibot'
 import { describe, expect, it } from 'vitest'
 import { argsToJsonSchema, returnToJsonSchema } from '../to-json-schema'
 
 const PERMISSIVE = { type: 'object', additionalProperties: true }
 
+/** A Standard Schema that also implements the Standard JSON Schema converter (like zod 4). */
+function withJsonSchema(json: Record<string, unknown>): StandardSchemaV1 {
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'test',
+      validate: (value: unknown) => ({ value }),
+      jsonSchema: {
+        input: () => json,
+        output: () => json,
+      },
+    } as StandardSchemaV1['~standard'],
+  }
+}
+
 describe('argsToJsonSchema', () => {
-  it('returns an empty object schema when no args', async () => {
-    const { schema, unwrapped } = await argsToJsonSchema(undefined)
+  it('returns an empty object schema when no args', () => {
+    const { schema, unwrapped } = argsToJsonSchema(undefined)
     expect(unwrapped).toBe(false)
     expect(schema).toEqual({ type: 'object', properties: {} })
   })
 
-  it('advertises each positional arg under arg0/arg1/... with precise per-vendor conversion', async () => {
-    const { schema, unwrapped } = await argsToJsonSchema([v.string(), v.number()])
-    expect(unwrapped).toBe(false)
-    expect(schema).toMatchObject({
-      type: 'object',
-      required: ['arg0', 'arg1'],
-      additionalProperties: false,
-    })
-    const props = (schema as any).properties
-    // valibot vendor → precise conversion via @standard-community/standard-json.
-    expect(props.arg0).toMatchObject({ type: 'string' })
-    expect(props.arg1).toMatchObject({ type: 'number' })
+  it('uses the schema\'s own Standard JSON Schema converter when present', () => {
+    const { schema } = argsToJsonSchema([withJsonSchema({ type: 'string' })])
+    expect((schema as any).properties.arg0).toEqual({ type: 'string' })
   })
 
-  it('falls back to a permissive object for vendors without a converter', async () => {
-    const foreign = {
-      '~standard': { version: 1 as const, vendor: 'acme', validate: (value: unknown) => ({ value }) },
-    }
-    const { schema } = await argsToJsonSchema([foreign])
+  it('falls back to a permissive object for validators without a native converter (valibot)', () => {
+    const { schema } = argsToJsonSchema([v.string(), v.number()])
     expect((schema as any).properties.arg0).toEqual(PERMISSIVE)
+    expect((schema as any).properties.arg1).toEqual(PERMISSIVE)
+    expect(schema).toMatchObject({ type: 'object', required: ['arg0', 'arg1'], additionalProperties: false })
   })
 })
 
 describe('returnToJsonSchema', () => {
-  it('returns undefined when no schema is provided', async () => {
-    expect(await returnToJsonSchema(undefined)).toBeUndefined()
+  it('returns undefined when no schema is provided', () => {
+    expect(returnToJsonSchema(undefined)).toBeUndefined()
+  })
+
+  it('uses the native converter when present', () => {
+    expect(returnToJsonSchema(withJsonSchema({ type: 'object', properties: { ok: { type: 'boolean' } } })))
+      .toEqual({ type: 'object', properties: { ok: { type: 'boolean' } } })
   })
 
-  it('converts a declared return schema precisely for known vendors', async () => {
-    const schema = await returnToJsonSchema(v.object({ ok: v.boolean() }))
-    expect((schema as any).type).toBe('object')
-    expect((schema as any).properties.ok).toMatchObject({ type: 'boolean' })
+  it('falls back to permissive for validators without a native converter', () => {
+    expect(returnToJsonSchema(v.object({ ok: v.boolean() }))).toEqual(PERMISSIVE)
   })
 })

packages/devframe/src/adapters/mcp/build-server.ts

@@ -148,7 +148,7 @@ export async function createMcpServer(
 
 function registerToolHandlers(server: Server, ctx: DevframeNodeContext): void {
   server.setRequestHandler('tools/list', async () => {
-    const tools = await Promise.all(ctx.agent.list().tools.map(tool => projectTool(tool, ctx)))
+    const tools = ctx.agent.list().tools.map(tool => projectTool(tool, ctx))
     return { tools }
   })
 
@@ -157,7 +157,7 @@ function registerToolHandlers(server: Server, ctx: DevframeNodeContext): void {
     try {
       const tool = ctx.agent.getTool(name)
       const outputSchema = tool
-        ? tool.outputSchema ?? await computeOutputSchema(tool, ctx)
+        ? tool.outputSchema ?? computeOutputSchema(tool, ctx)
         : undefined
       const result = await ctx.agent.invoke(name, args ?? {})
       return {
@@ -248,9 +248,9 @@ function registerResourceHandlers(
   })
 }
 
-async function projectTool(tool: AgentTool, ctx: DevframeNodeContext): Promise<Tool> {
-  const inputSchema = tool.inputSchema ?? await computeInputSchema(tool, ctx)
-  const outputSchema = tool.outputSchema ?? await computeOutputSchema(tool, ctx)
+function projectTool(tool: AgentTool, ctx: DevframeNodeContext): Tool {
+  const inputSchema = tool.inputSchema ?? computeInputSchema(tool, ctx)
+  const outputSchema = tool.outputSchema ?? computeOutputSchema(tool, ctx)
   return {
     name: tool.id,
     title: tool.title,
@@ -265,17 +265,17 @@ async function projectTool(tool: AgentTool, ctx: DevframeNodeContext): Promise<T
   } as Tool
 }
 
-async function computeInputSchema(tool: AgentTool, ctx: DevframeNodeContext): Promise<unknown> {
+function computeInputSchema(tool: AgentTool, ctx: DevframeNodeContext): unknown {
   if (tool.kind !== 'rpc' || !tool.rpcName)
     return { type: 'object', properties: {} }
   const def = ctx.rpc.definitions.get(tool.rpcName) as RpcFunctionDefinitionAnyWithContext<DevframeNodeContext> | undefined
   if (!def)
     return { type: 'object', properties: {} }
   const args = def.args as readonly StandardSchemaV1[] | undefined
-  return (await argsToJsonSchema(args)).schema
+  return argsToJsonSchema(args).schema
 }
 
-async function computeOutputSchema(tool: AgentTool, ctx: DevframeNodeContext): Promise<unknown> {
+function computeOutputSchema(tool: AgentTool, ctx: DevframeNodeContext): unknown {
   if (tool.kind !== 'rpc' || !tool.rpcName)
     return undefined
   const def = ctx.rpc.definitions.get(tool.rpcName) as RpcFunctionDefinitionAnyWithContext<DevframeNodeContext> | undefined

packages/devframe/src/adapters/mcp/to-json-schema.ts

@@ -1,33 +1,37 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import { toJsonSchema } from '@standard-community/standard-json'
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec'
 
 const FALLBACK_OBJECT_SCHEMA = Object.freeze({ type: 'object', additionalProperties: true })
 
+/** A `~standard` prop that may also carry the Standard JSON Schema converter. */
+type MaybeJsonSchema = StandardSchemaV1['~standard'] & Partial<StandardJSONSchemaV1['~standard']>
+
 /**
  * Convert a Standard Schema to JSON Schema for the agent/MCP surface.
  *
- * `@standard-community/standard-json` dispatches on the schema's
- * `~standard` vendor (valibot, zod, arktype, …) and lazily loads that
- * vendor's converter, so precise schemas require the matching converter
- * to be installed (e.g. `@valibot/to-json-schema`, `zod-to-json-schema`).
- * When no converter is available — or conversion fails — we degrade to a
- * permissive object schema so the surface never throws and no validator is
- * forced.
+ * Devframe stays validator-neutral, so conversion uses the schema's own
+ * [Standard JSON Schema](https://standardschema.dev/) converter
+ * (`~standard.jsonSchema`) when the validator provides one — zod 4 does,
+ * for example. Validators without a native converter (e.g. valibot) degrade
+ * to a permissive object schema rather than pulling in a converter library.
  */
-async function safeToJsonSchema(schema: StandardSchemaV1): Promise<unknown> {
-  try {
-    return await toJsonSchema(schema)
-  }
-  catch {
-    return FALLBACK_OBJECT_SCHEMA
+function safeToJsonSchema(schema: StandardSchemaV1): unknown {
+  const standard = schema['~standard'] as MaybeJsonSchema
+  if (standard.jsonSchema) {
+    try {
+      return standard.jsonSchema.input({ target: 'draft-2020-12' })
+    }
+    catch {
+      return FALLBACK_OBJECT_SCHEMA
+    }
   }
+  return FALLBACK_OBJECT_SCHEMA
 }
 
 /**
  * JSON Schema for an RPC return value on the agent/MCP surface.
  * @internal
  */
-export async function returnToJsonSchema(schema: StandardSchemaV1 | undefined): Promise<unknown> {
+export function returnToJsonSchema(schema: StandardSchemaV1 | undefined): unknown {
   if (!schema)
     return undefined
   return safeToJsonSchema(schema)
@@ -42,17 +46,17 @@ export async function returnToJsonSchema(schema: StandardSchemaV1 | undefined):
  * Returns `{ type: 'object', properties: {} }` when there are no args.
  * @internal
  */
-export async function argsToJsonSchema(
+export function argsToJsonSchema(
   args: readonly StandardSchemaV1[] | undefined,
-): Promise<{ schema: unknown, unwrapped: boolean }> {
+): { schema: unknown, unwrapped: boolean } {
   if (!args || args.length === 0)
     return { schema: { type: 'object', properties: {} }, unwrapped: false }
 
   const properties: Record<string, unknown> = {}
   const required: string[] = []
   for (let i = 0; i < args.length; i++) {
     const key = `arg${i}`
-    properties[key] = await safeToJsonSchema(args[i]!)
+    properties[key] = safeToJsonSchema(args[i]!)
     required.push(key)
   }
 

plugins/inspect/package.json

@@ -56,10 +56,9 @@
     }
   },
   "dependencies": {
-    "@standard-community/standard-json": "catalog:deps",
+    "@valibot/to-json-schema": "catalog:deps",
     "cac": "catalog:deps",
-    "nostics": "catalog:deps",
-    "quansync": "catalog:deps"
+    "nostics": "catalog:deps"
   },
   "devDependencies": {
     "@antfu/design": "catalog:frontend",

plugins/inspect/src/rpc/functions/_schema.ts

@@ -1,11 +1,25 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import { toJsonSchema } from '@standard-community/standard-json'
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec'
+import { toJsonSchema } from '@valibot/to-json-schema'
 
 const FALLBACK_SCHEMA = Object.freeze({ type: 'object', additionalProperties: true })
 
-async function convert(schema: unknown): Promise<unknown> {
+/** A `~standard` prop that may also carry the Standard JSON Schema converter. */
+type MaybeJsonSchema = StandardSchemaV1['~standard'] & Partial<StandardJSONSchemaV1['~standard']>
+
+/**
+ * Convert a schema to JSON Schema for the inspector, vendor-neutrally.
+ *
+ * Prefers the schema's own Standard JSON Schema converter
+ * (`~standard.jsonSchema`, implemented by e.g. zod 4), then falls back to
+ * valibot's converter, then to a permissive object — so introspection never
+ * throws regardless of which validator produced the schema.
+ */
+function convert(schema: unknown): unknown {
+  const standard = (schema as StandardSchemaV1)['~standard'] as MaybeJsonSchema
   try {
-    return await toJsonSchema(schema as StandardSchemaV1)
+    if (standard.jsonSchema)
+      return standard.jsonSchema.input({ target: 'draft-2020-12' })
+    return toJsonSchema(schema as never)
   }
   catch {
     return FALLBACK_SCHEMA
@@ -14,14 +28,9 @@ async function convert(schema: unknown): Promise<unknown> {
 
 /**
  * Convert an RPC return schema to JSON Schema, swallowing conversion
- * failures (unsupported vendor / missing converter) into a permissive
- * fallback so introspection never throws.
- *
- * Conversion is vendor-neutral via `@standard-community/standard-json`,
- * which loads the matching per-vendor converter on demand (valibot, zod,
- * arktype, …) — install the converter for the vendor you inspect.
+ * failures into a permissive fallback so introspection never throws.
  */
-export async function returnSchemaToJson(schema: unknown): Promise<unknown> {
+export function returnSchemaToJson(schema: unknown): unknown {
   if (!schema)
     return undefined
   return convert(schema)
@@ -32,11 +41,11 @@ export async function returnSchemaToJson(schema: unknown): Promise<unknown> {
  * (`type: 'array'` + `prefixItems`). Returns `undefined` when the function
  * declares no args.
  */
-export async function argsSchemaToJson(args: readonly unknown[] | undefined): Promise<unknown> {
+export function argsSchemaToJson(args: readonly unknown[] | undefined): unknown {
   if (!args || args.length === 0)
     return undefined
   return {
     type: 'array',
-    prefixItems: await Promise.all(args.map(arg => convert(arg))),
+    prefixItems: args.map(arg => convert(arg)),
   }
 }

plugins/inspect/src/rpc/functions/list-functions.ts

@@ -46,8 +46,8 @@ export const listFunctions = defineInspectRpc({
           hasHandler: !!fn.handler,
           invokable: INVOKABLE_TYPES.has(type),
           agent,
-          argsSchema: await argsSchemaToJson(fn.args as readonly unknown[] | undefined),
-          returnsSchema: await returnSchemaToJson(fn.returns),
+          argsSchema: argsSchemaToJson(fn.args as readonly unknown[] | undefined),
+          returnsSchema: returnSchemaToJson(fn.returns),
         })
       }
       out.sort((a, b) => a.name.localeCompare(b.name))