Skip to content

Add a read-only webjs MCP server and webjs check --json #262

@vivek7405

Description

@vivek7405

Problem

No MCP server exposes webjs's own introspection. An agent cannot query the running dev server for the live route table (buildRouteTable), registered server actions + RPC hashes (buildActionIndex), registered custom-element tags (registry.allTags), or structured webjs check violations. The scaffolded .claude.json wires a Playwright MCP for browser debugging but nothing surfaces webjs state, so agents work blind against the live app. The same structured data is also locked behind human-formatted CLI output: checkConventions returns {rule,file,message,fix} objects but the CLI only pretty-prints them (only --rules is read, no --json), so an agent running webjs check in a loop must regex-scrape stdout to recover data the function already produced structured.

Design / approach

Expose the already-computed artifacts (route table, action index, registered tags, check violations) over a small read-only MCP server, and add webjs check --json printing the structured result the function already returns. Both are thin read-only surfaces over existing data, mutating nothing.

Web-standards fit: Read-only projections of data the framework already computes; the additions are small adapters, not new analysis.

Prior art: Next.js next-devtools-mcp (get_routes / get_server_action_by_id / get_errors).

Acceptance criteria

  • A webjs MCP server exposes read-only tools for the live route table, registered actions (with RPC hashes), and registered tags
  • A tool returns structured webjs check violations for the app
  • It reads the already-computed artifacts and mutates nothing
  • Scaffolds wire the webjs MCP into the agent config alongside the existing Playwright entry
  • A smoke test asserts the introspection tools return expected shapes against a scaffolded app
  • webjs check --json emits the raw structured violations + a summary count (non-zero exit preserved), asserted to parse as JSON matching checkConventions
  • Tests cover the new behaviour at the applicable layer(s)
  • Docs / AGENTS.md / CONVENTIONS.md updated if the public surface changed

Filed from the production-readiness audit (webjs vs Next.js / Remix / Rails / Turbo / Lit). Theme: ai-dx. Priority: P1. Kept to webjs identity: no-build, progressive enhancement, web-components-first, AI-first, batteries-included, close to web standards.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type
No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions