mcp-apps-builder

Build with mcp-use

Treat the installed mcp-use package, its exported types, generated declarations, and the project's existing code as the source of truth. Inspect the installed version before choosing APIs or changing code.

Workflow

1. Inspect package.json, the server entry, exported tool refs, mcp-env.d.ts, views/, skills/, and the installed mcp-use version.
2. Scaffold a new stable project with create-mcp-use-app@latest and the appropriate template. Match the package version or dist-tag when working on beta, canary, or an existing versioned project.
3. Read only the references needed for the task:

• [Server](references/server.md) for tools, resources, prompts, MCP middleware, request context, and result envelopes.
• [Views](references/views.md) for interactive MCP Apps, React hooks, model context, host capabilities, assets, and CSP.
• [Authentication](references/auth.md) for OAuth providers, verified identity, scopes, permissions, and authorization.
• [Skills over MCP](references/skills-over-mcp.md) when a server should ship reusable workflows alongside its tools.
• [Advanced features](references/advanced-features.md) for OpenAPI, proxying, notifications, subscriptions, and elicitation.
• [Migration](references/migration.md) only when retired or compatibility-only imports, helpers, registration shapes, UI patterns, or session assumptions are present.
• [Verification](references/verification.md) before reporting implementation work complete.

1. Implement against installed types. Prefer the framework's current conventions over copied examples or historical changelogs.
2. Validate the smallest real lifecycle that proves the changed behavior, then expand checks in proportion to risk.

Core invariants

• Import server APIs from mcp-use, React APIs from mcp-use/react, and OAuth provider adapters from their mcp-use/oauth/* subpaths.
• Define tool arguments with inputSchema. Add outputSchema for structured results and every View-bound tool.
• Return raw MCP result envelopes. A successful schema-backed tool must include matching structuredContent; an expected failure may return isError: true with model-readable content.
• Put each View at views/<name>/view.tsx and bind it with view: { name: "<name>" }.
• Export every statically declared tool ref consumed by a View. Default-export the server entry used by mcp-use dev, build, and start.
• Keep identity and mutable workflow state request-scoped or in an external store. Treat client-reported metadata as unverified.
• Consider Skills over MCP when a server exposes a repeatable, multi-step workflow that would otherwise inflate tool descriptions.

Guardrails

• Do not invent exports, configuration fields, or callback shapes. Confirm uncertain details in installed declarations or source.
• Do not preserve APIs that are absent from the installed version merely because they appear in an existing project.
• Do not return a plain domain object from a tool callback.
• Do not bind a View without a matching outputSchema and structuredContent result.
• Do not use module globals for cross-request identity, elicitation continuity, or durable business state.
• Do not claim success from a source build alone when types, package exports, authentication, or interactive behavior changed.
• Do not deploy or mutate external systems unless the user explicitly requests it.