mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
codex/a2ui-example
6 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Andrew Khadder
|
01208e052a |
Revert "docs: split TypeScript V1 and V2 documentation (#2010)" (#2036)
This reverts commit
|
||
|
Andrew Khadder
|
5b5fe96d28 |
docs: split TypeScript V1 and V2 documentation (#2010)
Preserve the V1 TypeScript docs, add independently navigable V2 beta documentation, and align shared documentation. Rename both V2 migration guides to “Migrating to v2”. |
||
|
Andrew Khadder
|
68afda5885 |
docs(typescript): review and rewrite TypeScript docs (MCP-2466) (#1780)
* docs: remove stale feedback block and orphaned anchor from docs.json * chore(docs): make Typescript more prominent * chore(docs): Update `welcome.mdx` * docs: rewrite TypeScript quickstart and welcome pages Refocus the quickstart on create-mcp-use-app (scaffold, run, and deploy a first MCP server) and drop the agent/client/server primer table and diagram. Convert the welcome page's server + widget example from Tabs to CodeGroup and tighten the intro wording. * docs: remove stale server templates page and fix its references Delete the typescript/server/templates page and repoint the home templates tip to the quickstart, which now covers create-mcp-use-app. * docs(typescript): fix dead example links to real example paths The 'see a full example' links pointed at GitHub folders that 404 or contain only a README. Corrected to the real runnable examples under libraries/typescript/packages/mcp-use/examples/, verified against origin/main (incl. matching cd commands): - installation: examples/server -> packages/.../examples/server - client-configuration: a .py link -> real TS multi-server example - code-mode: examples/client/* -> examples/agent/code-mode/* - elicitation, sampling, notifications: server/X -> server/features/X - supabase: server/supabase -> server/deployment/supabase - clerk: restore missing packages/mcp-use/ path segment Quickstart links were already fixed by the quickstart rewrite (e6903716). Part of the docs audit (MCP-2466). * docs(typescript): rewrite Agent and Client introduction pages Rewrite the Agent and Client intro pages to be task-oriented and scannable: concise feature lists with cross-links, runnable quick-start examples, and added API reference sections. Drop stale CodeSandbox embeds and outdated model names. * docs(typescript): fix MCPServer class name casing in server reference The API Reference heading, prose, and class signature used McpServer; the real SDK export is MCPServer. Corrected all three occurrences in server/index.mdx. * docs: add redirect for bare /typescript/server path Routes the bare /typescript/server path to its index page now that the server section has been restructured. Claude-Session: https://claude.ai/code/session_015uioJjKTAZXGQpbXHUHZWp * docs(typescript): fix broken code examples across MCP Server & Apps section Fix all 102 confirmed code defects found in the MCP Server & MCP Apps documentation audit (47 pages, 401 code blocks), verified against the mcp-use@1.32 SDK source. The recurring patterns that made copy-pasted examples fail to compile or run are now corrected everywhere they appeared: - server.start() -> await server.listen() (no start() method exists) - bare-object tool returns wrapped in object()/text() response helpers; catch blocks renamed so they no longer shadow the error() helper - prompt messages use role:"user" with typed { type:"text" } content instead of the invalid role:"system" + bare-string shape - auth reads ctx.auth.user.userId (not ctx.auth.userId); user fields live under ctx.auth.user, scopes/permissions stay top-level - security: remove verifyJwt: process.env.NODE_ENV === 'production' from all six OAuth provider pages (off-prod it skips signature verification and accepts forged tokens); rely on the secure default, with a warning never to disable it - correct import subpaths: Logger/MCPClient from mcp-use, response helpers and server symbols from mcp-use/server, MCPClient as BrowserMCPClient from mcp-use/browser; drop the unexported getMcpAppsBridge - useWidget generics use the real <TProps, TState, TOutput, ...> order; remove the non-existent notifyIntrinsicHeight (auto-size via McpUseProvider) - fix the deployment URL to <id>.run.mcp-use.com/mcp, add missing z/helper imports, add the --branch/--dockerfile CLI options, and clean up em dashes and bare/malformed code fences Each page was fixed and then independently re-verified against the SDK source, with a repo-wide pattern sweep confirming no instances remain. Structural IA changes (moving widget-components to /react/, orphan redirects) are intentionally deferred to the docs rewrite. * docs(typescript): restructure MCP Server & MCP Apps IA Promote MCP Apps to its own top-level section in the TypeScript SDK Docs tab and move the 9 React widget-component pages out of /server/widget-components/ into /typescript/react/. - Move 9 React component pages to typescript/react/ (git renames) with 9 redirects - Promote MCP Apps to a top-level group (Overview pages + React subgroup) - Remove the duplicate MCP Apps group from the Home product nav; rehome guides/chatgpt-apps-flow under MCP Apps so it no longer orphans - Move cli-reference out of MCP Server into a new Tooling group - Relocate response-helpers -> Core Components, openapi -> Advanced Features, nextjs-drop-in -> Deployment - Repoint all widget-components links to /typescript/react/ - Fix 3 broken anchor links (inspector CLI env var, mcp-apps metadata, auth providers) Structure-only change; no page content rewrites. Refs MCP-2466. * docs: refresh TypeScript server app docs * docs: add TypeScript API reference * docs: streamline TypeScript server navigation * docs: rewrite core TypeScript server guides * docs: rewrite advanced TypeScript server guides * docs: rewrite TypeScript server OAuth guides * docs: rewrite TypeScript server session storage guides * docs: rewrite MCP Apps section * docs: add TypeScript MCP client API reference * docs: add TypeScript MCP agent API reference * docs: reorder TypeScript API reference nav * docs: reorganize TypeScript tooling nav * docs: rewrite inspector guides * docs: rewrite MCP server tunneling guide * docs: rewrite CLI client and reference docs * docs: finalize TypeScript documentation rewrite * docs: move inspector updates under get started * Fix Mintlify validation errors * Fix Mintlify broken links * docs: update Manufact Cloud deployment guide * chore: retrigger Mintlify docs preview * Fix MDX comment syntax on home page * docs: rework TypeScript server examples * docs: fix server docs links * docs: restore SDK links in home sidebar * docs: move SDK links to end of home sidebar |
||
|
Enrico Toniato
|
806dbcaf50 |
Canary (#1401)
* fix(inspector): OAuth flow no longer leaves two tabs open (#1384) (#1391) * fix(inspector): OAuth flow no longer leaves two tabs open (#1384) Previously, the inspector opened the OAuth authorization page in a new tab (`target="_blank"` on the Authenticate anchor). After the auth server redirect to the callback URL, `Cross-Origin-Opener-Policy` typically stripped `window.opener`, so the callback took the `returnUrl` fallback branch and navigated the new tab back to the inspector — leaving the user with two inspector tabs. Changes: - Drop `target="_blank"` / `rel="noopener noreferrer"` on the Authenticate anchor so the click performs a same-tab navigation to the stored auth URL. - Set `useRedirectFlow: true` + `preventAutoAuth: true` on every server added from the inspector UI, so the stored OAuth state records `flowType: "redirect"` and the callback routes the current tab back to `returnUrl` instead of trying to close an already-navigated popup. - Propagate the same flags through every connection entry point (`handleAddConnection`, `Layout` adapter, and the `InspectorDashboard` adapter used by `handleUpdateConnection` URL edits and `useAutoConnect`) so the single-tab behavior holds across manual connect, URL edits, and shared-config auto-connect. The library primitives (`redirectToAuthorization`, `onMcpAuthorization`, `flowType`) already worked — this PR only wires the inspector to use them. Closes #1384 * chore: remove issue comments --------- Co-authored-by: Andrew Khadder <andrew@manufact.com> * chore: enter canary prerelease mode * docs(inspector): document --no-open CLI flag (#1397) * fix(inspector): hide free-tier upgrade UI when host app embeds ChatTab (#1399) ChatTab was deriving the Manufact free-tier "Model & usage" dialog from the mere presence of `managedLlmConfig`. The cloud dashboard embeds ChatTab with `managedLlmConfig` + `hideModelBadge=true`, but the badge and ConfigurationDialog treated the derived `freeTierInfo` as an override that forced the UI back on. Free-tier upgrade UI is now opt-in via a new `enableFreeTierUpgrade` prop on ChatTab (default false), plumbed through `EmbeddedConfig.chatEnableFreeTierUpgrade`. The hosted inspector auto-seeds it to true; host apps embedding ChatTab directly leave it off and their hide-* props are respected. * chore(typescript): version packages (canary) * fix(cli): keep mcp-use build non-fatal under bun runtime (#1382) * fix(cli): keep mcp-use build non-fatal under bun runtime `mcp-use build` was crashing during the tool-registry type-generation step on `oven/bun:alpine`. The step uses `tsx/esm/api`'s `tsImport`, which relies on Node's custom loader hooks that bun doesn't implement, so the exception killed the whole build. - Detect the bun runtime up front in `generateToolRegistryTypesForServer` and skip the `tsx/esm/api` path with a clear warning. - Wrap the build command's call in try/catch so any other import-time error is surfaced as a non-blocking warning rather than `exit 1`. - Invoke `tsc --noEmit` via `process.execPath` instead of hardcoding `node`, and drop `--max-old-space-size=4096` under bun (unsupported flag). `oven/bun:alpine` ships no `node` binary; bun runs tsc fine. Closes #1327 * fix(cli): distinguish skipped tool registry gen from errored Return "ok" | "failed" | "skipped" from generateToolRegistryTypesForServer so the bun-skip path no longer prints a misleading "had errors" warning after the "Skipping under bun runtime" notice. --------- Co-authored-by: Andrew Khadder <andrew@manufact.com> * chore(typescript): version packages (canary) * fix(inspector): stop MCP App widget from overlaying chat header (#1407) The sandboxed iframe wrappers in MCPAppsRenderer (relative z-20) and OpenAIComponentRenderer (relative z-10) created stacking contexts that painted above the chat header's absolute z-10, making the header unreachable when scrolling. Drop the explicit z-index classes so widgets stack under the header; spinner/skeleton overlays still work via DOM order. Closes MCP-1741 * chore(typescript): version packages (canary) * fix(inspector): improve handling of client-side and managed LLM configurations in ChatTab (#1418) Updated logic to determine `effectiveClientSide` and `hideModelBadge` based on host embed configurations. Introduced `hostUsesServerManagedStream` to ensure correct behavior when using managed LLM settings, preventing fallback to client-side streaming in hosted environments. Adjusted `hideModelBadge` and `hideConfigButton` properties to respect these configurations, enhancing the user experience in embedded scenarios. * chore(typescript): version packages (canary) * fix(cli): bundle server entries so extensionless imports work under Node ESM (#1357) * fix(cli): bundle server entries with esbuild to resolve extensionless imports Scaffolded apps run under plain Node ESM, which rejects extensionless relative imports with ERR_MODULE_NOT_FOUND. Flip `transpileWithEsbuild` to `bundle: true` + `packages: "external"`: relatives get inlined at build time while third-party packages (mcp-use, react, zod, etc.) stay as external imports resolved from node_modules at runtime. Users can keep writing idiomatic TypeScript imports without .js suffixes. * test(cli): regression test for MCP-1733 build import resolution Asserts that `mcp-use build` produces output where bare package imports stay external and relative extensionless imports are inlined. Uses a non-matching entry name (main.ts) to skip the tool-registry type gen step so the test does not depend on mcp-use being installed in the fixture. * chore(typescript): version packages (canary) * fix(auth): redirect OAuth errors back to inspector instead of showing raw error page (#1381) * fix(auth): redirect OAuth errors back to inspector instead of showing raw error page When the OAuth callback receives an error (e.g. access_denied), the handler previously threw immediately before looking up stored state, so it couldn't find the returnUrl to redirect. This resulted in a raw error page with stack traces rendered into the DOM. Move the error check after the state lookup so we have access to returnUrl and flowType. Now OAuth errors use the same redirect/postMessage patterns as successful auth: - Redirect flow: navigates to returnUrl with auth_error params - Popup flow: posts message to opener with success:false - Fallback with returnUrl: redirects with error params Fixes mcp-use/mcp-use#1362 * chore: add changeset for oauth error redirect fix * feat(inspector): show toast notification on OAuth error redirect * style: fix prettier formatting in callback.ts * fix(inspector): lift OAuth error toast to App level The auth_error toast was buried inside useAutoConnect, which fires before <Toaster /> subscribes to sonner — sonner only notifies current subscribers, so the toast was dropped on the floor. Lift it to App.tsx so the effect runs after Toaster mounts, and make it persistent (duration: Infinity, closeButton: true) so users can read the failure. * chore(inspector): tighten OAuth error toast comment and changeset * refactor(auth): simplify OAuth error redirect handling Collapse duplicated redirect/fallback branches in the OAuth callback error handler into a single redirectWithError helper, drop narration comments, and reuse the existing parsed URLSearchParams in the inspector App effect. --------- Co-authored-by: Andrew Khadder <andrew@manufact.com> * chore(typescript): version packages (canary) * fix(inspector): persist connection config in sessionStorage before OAuth redirect (#1404) Before this change, completing an OAuth flow without ?autoConnect in the URL left the inspector in a hanging state because useAutoConnect had no way to resume the connection on page reload. Now, clicking the Authenticate button writes the pending connection config to sessionStorage under INSPECTOR_RECONNECT_STORAGE_KEY — the same key already consumed by trySessionReconnect() in useAutoConnect. After the OAuth callback redirects back, the hook picks up the stored config and resumes the connection automatically. Inspector-only change; no library code modified. Closes #1389 * chore(typescript): version packages (canary) * fix(oauth): use OAuth 2.1 server endpoints for Supabase provider and clear up docs (#1422) Point getAuthEndpoint() and getTokenEndpoint() at /auth/v1/oauth/authorize and /auth/v1/oauth/token instead of the legacy /auth/v1/authorize and /auth/v1/token paths. Also restructure the Supabase provider docs around a Steps-based prerequisites block and link the new mcp-oauth-supabase-template. * chore(typescript): version packages (canary) * fix(cli): allow "." as project name to init in current directory (#1413) * fix(cli): allow "." as project name to init in current directory When running `npx create-mcp-use-app .` in an empty directory, the CLI now initializes the project in the current directory instead of erroring with "Directory already exists". - Detect "." as project name and resolve to cwd - Use basename(cwd) for package.json name and display output - Check that the directory is empty before proceeding - Update interactive input validator to accept "." Fixes #1406 * style: fix prettier formatting * fix(cli): address review feedback for dot-directory support - Sanitize basename for package.json name (lowercase, replace invalid chars, trim leading dots/dashes) - Allow known safe entries in empty-dir check (.git, .gitignore, LICENSE, README*, .DS_Store, .idea, .vscode, Thumbs.db) - Skip printing 'cd .' when useCurrentDir is true - Add unit tests for sanitizePackageName and isSafeEntry - Extract utils to separate module for testability * fix(cli): expand safe-entry allow list and improve clash error - Replace SAFE_DIR_ENTRIES with the create-next-app-style list (.claude, .cursor, .git*, .hg*, IDE dirs, CI configs, package-manager logs, docs, LICENSE, etc.). README is no longer auto-allowed since templates ship their own. - On clash, list the offending entries (one per line) instead of a generic "directory not empty" message, in both the non-interactive and interactive (Ink) paths. - Drop the unused sanitizePackageName re-export from index.tsx. - Update tests to match the new allow list. * refactor(cli): simplify dot-directory tests and rename trimmed var - Rename sanitizedProjectName -> trimmedProjectName at the call site; the variable is only .trim()'d, the npm-style sanitization happens inside deriveProjectInfo. - Trim isSafeEntry tests from 9 to 3 (the prior tests were enumerating the contents of SAFE_DIR_ENTRIES rather than the function's behavior). - Drop overlapping deriveProjectInfo cases already covered by the sanitizePackageName unit tests and the regression e2e test. - Switch the TS-string-literal sanitize test to property assertions so it stays resilient to regex-order tweaks. --------- Co-authored-by: Andrew Khadder <andrew@manufact.com> * chore(typescript): version packages (canary) * fix(inspector): detect Hono via duck-typing, not instanceof (#1417) * fix(inspector): detect Hono via duck-typing, not instanceof mountInspector(app) chose between a fast Hono-direct path and a slower Express-compat bridge based on app instanceof Hono. That check is unreliable across a published library boundary: when this package and the host (e.g. mcp-use) resolve different Hono constructors -- common in monorepos where workspace deps hoist their own hono, when Node loads Hono's dual CJS+ESM builds from the same on-disk copy as two separate module records, or under bundler dedup -- instanceof returns false even for a real Hono app. The Express bridge then runs against a Hono Context and crashes on every request trying to read req.headers.host. Switch to a duck-type check: Hono apps expose .fetch(Request) => Response; Express apps don't. The check is unambiguous for the documented input set and works regardless of which physical hono module produced the app. * Remove em dashes from comment and changeset * Drop redundant instanceof Hono fast-path; duck-type covers both shapes * Narrow app type via isHonoApp guard so Express bridge type-checks * Empty commit to refresh pkg.pr.new PR-tag alias for Deno preview * chore(typescript): version packages (canary) * docs: add v1.25.1 and inspector v3.0.1 changelog entries --------- Co-authored-by: Ayaan Gazali <ayaangazali@gmail.com> Co-authored-by: Andrew Khadder <andrew@manufact.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Andrew Khadder <54488379+khandrew1@users.noreply.github.com> Co-authored-by: Truffle <truffleagent@gmail.com> Co-authored-by: Kagura <kagura.agent.ai@gmail.com> Co-authored-by: Kagura <kagura.chen28@gmail.com> Co-authored-by: Pietro Zullo <62951181+pietrozullo@users.noreply.github.com> |
||
|
Enrico Toniato
|
3d787bab34 |
Canary (#970)
* feat(inspector): add environment variable for iframe embedding configuration (#965) * feat(inspector): add environment variable for iframe embedding configuration - Introduced `MCP_INSPECTOR_FRAME_ANCESTORS` environment variable to control which origins can embed the inspector widget in iframes, enhancing security and flexibility for both development and production environments. - Updated documentation to include usage examples and best practices for setting the variable, ensuring clarity for users embedding the inspector in their applications. - Refactored server routes and utilities to utilize the new environment variable for setting Content Security Policy (CSP) headers, improving security measures against unauthorized embedding. * feat(server): enhance tool and resource change handling - Added logic to ensure tool request handlers are registered on the SDK server, improving initialization for sessions with no tools. - Updated change detection for tools, prompts, resources, and templates to include removal events, ensuring accurate notifications for list changes. - Enhanced session server communication by sending updates when tools, prompts, resources, or templates are added or removed, improving responsiveness and user experience. * feat(server): pre-initialize request handlers for improved error handling - Added pre-initialization logic for tool, prompt, and resource request handlers on the SDK server to ensure they are available even when starting with zero registrations. - This change prevents -32601 "Method not found" errors on clients by ensuring that necessary handlers are set up during server initialization. * feat(inspector): implement localhost URL conversion for server-side fetches - Added a new utility function `toLocalhostUrl` to convert external proxy URLs to localhost for server-side fetches, ensuring correct content retrieval when running behind reverse proxies. - Updated the inspector's route handling to utilize the new function, improving reliability of widget content fetching. - Enhanced handling of asset URLs to ensure they are correctly rewritten for both external and localhost scenarios, addressing potential issues with proxy catch-all routes. - Configured Vite middleware to allow all hosts, facilitating smoother operation behind various reverse proxies. * feat(inspector): enhance widget URL handling and logging - Improved URL rewriting logic for widget assets to ensure correct resolution both locally and behind reverse proxies. - Added debug logging for fetching and processing widget HTML, aiding in troubleshooting and development. - Introduced a new global variable `__mcpServerUrl` for widgets to dynamically reference the server origin in API calls, enhancing flexibility. - Updated handling of asset paths to preserve query parameters, ensuring accurate resource fetching from the development server. * feat(server): enhance Vite HMR WebSocket support and MCP_URL handling - Updated MCP_URL assignment to only set if not provided by the user, allowing for external proxy configurations. - Implemented WebSocket proxy setup for Vite HMR, enabling hot module reloading through reverse proxies. - Added optional httpServer parameter in ServerConfig for Vite HMR WebSocket support. - Improved WebSocket upgrade request handling to ensure compatibility with various deployment scenarios. * feat(server): enhance HMR support for custom routes and widget management - Introduced a new `shouldRemove` predicate in the sync options to prevent the removal of specific items during HMR, protecting widget-registered tools. - Added a mutable `_customRoutes` registry in the MCP server to manage custom HTTP route handlers, enabling HMR for routes without re-registering. - Implemented a middleware to dispatch custom route handlers from the mutable map, ensuring compatibility with Hono's routing system. - Updated widget tool management to return a boolean indicating existence, allowing for fallback registration if tools are removed during HMR sync. - Enhanced resource directory handling in the widget mounting process to ensure directories are created dynamically for Vite file watching. * feat(inspector): enhance runtime configuration for inspector middleware - Added new configuration options to `mountInspector` for `devMode` and `sandboxOrigin`, allowing for improved handling of development environments and reverse proxy setups. - Updated `registerStaticRoutes` to inject runtime configuration into the HTML, enabling client-side components to access these settings. - Modified the inspector UI mounting process to utilize the new configuration options, enhancing flexibility and usability in various deployment scenarios. * fix(widget-handling): refine widget type determination logic - Updated widget type assignment to prioritize `appsSdk` when only `appsSdkMetadata` is present, ensuring accurate widget classification. - Enhanced metadata handling in widget registration to default to an empty object for `ui` when no metadata is available, improving robustness in widget rendering. * Enhance reverse proxy support and widget handling in inspector - Introduced `MCP_URL` environment variable to allow users to set an external proxy URL, ensuring correct widget asset URLs and HMR WebSocket connections. - Updated `mountInspector` configuration options to include `devMode` and `sandboxOrigin`, improving flexibility for development environments. - Added support for dynamic widget creation and improved HMR reliability, allowing for seamless integration behind reverse proxies. - Documented best practices for using `MCP_URL` and reverse proxy setups, ensuring clarity for users. * chore: enter canary prerelease mode * chore(typescript): version packages (canary) * feat(typescript): add completion support to resource templates and publish completion capabilities (#966) * add util for normalizing list callback completions for resource templates * add resource template completion and publish completion capabilites * add tests for toResourceTemplateCompleteCallbacks * add docs for resource templates completion * add changeset * update typescript conformance test server to include prompts and resource templates completion examples * revert default values for arg1 and arg2 and z.string().optional(), change to callback fn * run lint * chore(typescript): version packages (canary) * refactor(tests): remove serial mode configuration from E2E tests for UI widgets, chat, command palette, and setup * fix(inspector): update sandbox permissions for McpUIRenderer and MCPUIResource components (#974) - Removed 'allow-same-origin' and 'allow-popups-to-escape-sandbox' from sandbox permissions to enhance security and simplify iframe configurations. * chore(typescript): version packages (canary) * feat(inspector, typescript): release v0.18.5 and v1.17.0 with iframe embedding, reverse proxy support, and resource template completion - Introduced `MCP_INSPECTOR_FRAME_ANCESTORS` for iframe embedding control. - Enhanced `mountInspector` with `devMode` and `sandboxOrigin` options. - Added runtime config injection for improved deployment flexibility. - Improved server-side widget fetches and asset URL handling for reverse proxies. - Released v1.17.0 with resource template variable completion and custom route HMR support. - Updated dependencies to ensure compatibility with new features. * fix(tests): update hmr test prompts to use completable for default values --------- Co-authored-by: Joaquin Coromina <75667013+bjoaquinc@users.noreply.github.com> |
||
|
Enrico Toniato
|
a145cc7884 |
Docs/inspector (#492)
* refactor: reorganize documentation structure for Inspector and Dev Tools - Updated the docs.json file to consolidate Inspector and Tunneling pages under a new "Dev Tools" group. - Removed redundant entries for Inspector and Tunneling from the documentation structure. - Added a sidebar title for the Inspector page to enhance navigation. * docs: enhance Inspector documentation and add new CLI usage guides - Updated `docs.json` to include new pages for CLI usage, connection settings, keyboard shortcuts, command palette, integration, debugging ChatGPT apps, and development under the Inspector section. - Expanded the Inspector documentation to cover new features, including CLI usage and detailed guides for keyboard shortcuts and integration. - Improved the `self-hosting` documentation to reference the new CLI usage guide. - Enhanced the `apps-sdk-resources` documentation with additional details on widget state and testing procedures using the Inspector. * fix broken links |