Commit Graph

71 Commits

Author SHA1 Message Date
Ayaan Gazali 0c95e04db2 fix(docs): reword changelog heading that breaks mint broken-links with URIError (#1922)
The current mint CLI throws 'URIError: URI malformed' generating the anchor
slug for '### 100% Client Conformance (20/20)' (bare % followed by non-hex),
failing the 'Generate and validate API documentation' job on every PR.
Reworded to 'Full Client Conformance (20/20)'; mint broken-links now passes
across the whole docs tree.

Closes #1911

Co-authored-by: ayaanmacmini3 <ayaanmacmini3@ayaanmacmini3s-Mac-mini.local>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-18 09:25:53 -07:00
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
2026-06-29 10:05:13 -07:00
pietrozullo ad42b4bb3e docs: noindex auto-generated Python API reference instead of searchable flag
The searchable: false approach on the API Reference tab was inert on
visible tabs. Switch to per-page noindex: true frontmatter, which keeps
pages in the sidebar but excludes them from search indexing (search
engines, internal docs search, and AI context) so generic queries like
"CLI" surface curated guides instead of the generated reference.

Applied to all 73 existing reference pages and emitted by the generator
on every regeneration.

Closes MCP-2398
2026-06-29 10:23:42 +02:00
Andrew Khadder efa7fe78b2 Canary (#1719)
* fix(cli): update EnvVariable type to allow null values for sensitive rows (#1717)

- Modified the `value` property in the `EnvVariable` interface to accept `null`, indicating write-only sensitive rows where the stored value is withheld by the API.
- Adjusted the `printEnvVar` function to handle cases where `value` is `null`, ensuring proper display of sensitive information.

* chore: enter canary prerelease mode

* chore(typescript): version packages (canary)

* feat(server): add outgoing notification logging (#1674)

* chore(typescript): version packages (canary)

* fix(server): mount RFC 8414 canonical well-known paths for path-suffix issuers (#1684)

* fix(server): mount RFC 8414 canonical well-known paths for path-suffix issuers

Construct upstream OAuth/OIDC metadata URLs per RFC 8414 and OIDC
Discovery, and mount canonical path-suffixed routes on the MCP server
when the upstream issuer includes a path component.

Fixes #1576

Co-authored-by: Andrew Khadder <khandrew1@users.noreply.github.com>

* fix(server): mount OIDC discovery at root only; stop leaking error detail

Remove the unreachable, malformed OIDC path-suffix local mount (OIDC
Discovery appends the well-known segment to the issuer, so there is no
canonical form under the openid-configuration prefix, and no client flow
reaches a path-suffixed local route). Keep the RFC 8414 OAuth path-suffix
mount. Return a generic error_description to clients and log the raw
exception server-side instead of echoing it.

* style: apply prettier formatting

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Andrew Khadder <khandrew1@users.noreply.github.com>

* chore(typescript): version packages (canary)

* fix(server/oauth): broker upstream OAuth callback through /oauth/callback (#1728)

In proxy mode the server was forwarding each MCP client's redirect_uri
straight to the upstream provider, which forced every client's callback
(Claude, ChatGPT, the inspector, ...) to be pre-registered on the
provider. Instead, /authorize now sends the upstream the server's own
/oauth/callback and packs the client's redirect_uri + state into the
upstream `state` (base64url JSON, stateless). A new GET /oauth/callback
restores them and forwards the code (or upstream error) to the client's
original callback. /token rewrites redirect_uri to the brokered callback
so it matches the authorize request (RFC 6749 §4.1.3). PKCE passes
through untouched.

Also: jwksVerifier now rejects opaque (non-JWT) access tokens with an
actionable message pointing at the missing `audience`, instead of jose's
cryptic "Invalid Compact JWS".

Only `<server-domain>/oauth/callback` needs registering upstream now.

Closes MCP-2170

* fix(inspector): route localhost MCP servers through client-side chat (MCP-2419) (#1736)

* fix(inspector): route localhost MCP servers through client-side chat (MCP-2419)

In hosted mode the Chat tab streams through the managed cloud backend
(chatApiUrl), which connects to the MCP server server-side and cannot reach a
user's localhost server. The request 502s and, lacking CORS headers, surfaces
in the browser as an opaque "Failed to fetch" / CORS error.

Loopback server URLs now fall back to client-side (in-browser) chat streaming,
which already holds a direct session to the localhost server. The configure-key
empty state shows an explanatory notice telling the user the managed key can't
reach their machine and that a personal API key is needed — only in hosted mode;
the local inspector is unchanged.

The localhost check is extracted into a shared serverUrl util (with IPv6 [::1]
bracket handling) plus unit tests, and e2e tests cover the hosted+localhost
fallback, the no-cloud-call guarantee, and the notice's presence/absence.

* fix(inspector): address PR review on MCP-2419 localhost chat fix

- serverUrl: detect the full 127.0.0.0/8 loopback range (not just
  127.0.0.1), anchored so "127.example.com" is not a false positive
- serverUrl tests: cover 127.0.0.0/8 and near-loopback negatives
- e2e: stub the hosted `/api/auth/get-session` endpoint in
  enableHostedChatMode so HostedUserMenu never hits the real cloud
  backend (avoids CI flakiness/slowness)
- changeset: fix grammar

* style(inspector): prettier formatting for e2e test helpers

* chore(typescript): version packages (canary)

* fix(cli): use authoritative GitHub repo-access check for deploy (MCP-2467) (#1737)

The `mcp-use deploy` pre-flight repo-access check listed an installation's
repos and matched the target locally. That only inspected the first page, so
repos on later pages were wrongly reported inaccessible (MCP-2467); fully
paginating it (the prior behavior) hung on very large orgs.

Replace it with a single authoritative question per installation via the new
backend `GET /github/installations/:installationId/repos/:owner/:repo/access`
endpoint (a `repos.get` probe). The installation whose account matches the repo
owner is checked first, falling back to the others, preserving the
across-installations fix from MCP-2358 without paginating.

* chore(typescript): version packages (canary)

* chore(deps): bump esbuild from 0.27.1 to 0.28.1 in /libraries/typescript (#1734)

* chore(deps): bump esbuild from 0.27.1 to 0.28.1 in /libraries/typescript

Bumps [esbuild](https://github.com/evanw/esbuild) from 0.27.1 to 0.28.1.
- [Release notes](https://github.com/evanw/esbuild/releases)
- [Changelog](https://github.com/evanw/esbuild/blob/main/CHANGELOG-2025.md)
- [Commits](https://github.com/evanw/esbuild/compare/v0.27.1...v0.28.1)

---
updated-dependencies:
- dependency-name: esbuild
  dependency-version: 0.28.1
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

* chore: add changeset for dependabot updates

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* chore(typescript): version packages (canary)

* fix(typescript): silence dev widget logs when project has no widgets (#1730)

* chore(typescript): version packages (canary)

* feat : inspector add scroll-to-bottom button (#1538)

* inspector: add scroll-to-bottom button

* fix(inspector): center chat scroll button

---------

Co-authored-by: Andrew Khadder <andrew@manufact.com>

* chore(typescript): version packages (canary)

* fix(cli): cleanly unsubscribe on Ctrl+C (SIGINT) (#1687)

* fix(cli): add SIGINT handler to cleanly unsubscribe from resource

Addresses #1686

* chore: add cli changeset

---------

Co-authored-by: Andrew Khadder <andrew@manufact.com>

* chore(typescript): version packages (canary)

* fix(inspector): update emulate oauth callback (#1743)

* refactor: centralize screenshot handling and add REPL screenshot support (#1592)

* refactor: centralize screenshot handling and add REPL screenshot support

* chore: fix knip checks

* chore: drop knip version ignore

---------

Co-authored-by: Andrew Khadder <andrew@manufact.com>

* chore(typescript): version packages (canary)

* fix(api): update base URL for remote API calls to manufact.com (#1745)

* chore(config): add Langfuse Cloud API endpoints to exclusion list in lychee.toml

- Updated the `lychee.toml` configuration file to include Langfuse Cloud API endpoints in the exclusion list, preventing 403 errors from bot protection during CI processes. This change ensures valid defaults for API interactions.

* fix(workflow): remove unnecessary flag from pnpm install command in CI configuration

- Updated the `bump-mcp-use-reusable.yml` workflow file to remove the `--config.dangerously-allow-all-builds=true` flag from the `pnpm install` command, streamlining the installation process during CI runs.

* fix(api): update base URL for remote API calls to manufact.com

- Changed the default base URL from 'https://cloud.mcp-use.com' to 'https://cloud.manufact.com' across multiple files, including MCPAgent and RemoteAgent initializations, ensuring consistency in API endpoint references.

* chore(typescript): version packages (canary)

* feat(cli): add support for custom Dockerfile path in deployment options (#1746)

* chore(config): add Langfuse Cloud API endpoints to exclusion list in lychee.toml

- Updated the `lychee.toml` configuration file to include Langfuse Cloud API endpoints in the exclusion list, preventing 403 errors from bot protection during CI processes. This change ensures valid defaults for API interactions.

* fix(workflow): remove unnecessary flag from pnpm install command in CI configuration

- Updated the `bump-mcp-use-reusable.yml` workflow file to remove the `--config.dangerously-allow-all-builds=true` flag from the `pnpm install` command, streamlining the installation process during CI runs.

* feat(cli): add support for custom Dockerfile path in deployment options

- Introduced a new CLI option `--dockerfile` to specify a non-default Dockerfile path relative to the project root.
- Updated the `DeployOptions` interface to include the `dockerfile` property.
- Enhanced deployment command output to display the specified Dockerfile path, improving user feedback during deployment processes.

* refactor(cli): improve console log formatting for Dockerfile output

- Reformatted the console log statement for the Dockerfile option in the deploy command to enhance readability by breaking it into multiple lines. This change aims to maintain consistent code style and improve maintainability.

* chore(typescript): version packages (canary)

* Remove obsolete OAuth proxy callback changeset

* chore(typescript): version packages (canary)

* docs: update canary changelogs

* fix(cli): allow empty env var updates (#1750)

* chore(config): add Langfuse Cloud API endpoints to exclusion list in lychee.toml

- Updated the `lychee.toml` configuration file to include Langfuse Cloud API endpoints in the exclusion list, preventing 403 errors from bot protection during CI processes. This change ensures valid defaults for API interactions.

* fix(workflow): remove unnecessary flag from pnpm install command in CI configuration

- Updated the `bump-mcp-use-reusable.yml` workflow file to remove the `--config.dangerously-allow-all-builds=true` flag from the `pnpm install` command, streamlining the installation process during CI runs.

* fix(cli): allow empty env var updates

* Add changeset for empty env value updates

---------

Co-authored-by: Enrico <2827496+tonxxd@users.noreply.github.com>

* chore(typescript): version packages (canary)

* chore(deps): bump tar from 7.5.11 to 7.5.16 in /libraries/typescript (#1744)

* chore(config): add Langfuse Cloud API endpoints to exclusion list in lychee.toml

- Updated the `lychee.toml` configuration file to include Langfuse Cloud API endpoints in the exclusion list, preventing 403 errors from bot protection during CI processes. This change ensures valid defaults for API interactions.

* fix(workflow): remove unnecessary flag from pnpm install command in CI configuration

- Updated the `bump-mcp-use-reusable.yml` workflow file to remove the `--config.dangerously-allow-all-builds=true` flag from the `pnpm install` command, streamlining the installation process during CI runs.

* chore(deps): bump tar from 7.5.11 to 7.5.16 in /libraries/typescript

Bumps [tar](https://github.com/isaacs/node-tar) from 7.5.11 to 7.5.16.
- [Release notes](https://github.com/isaacs/node-tar/releases)
- [Changelog](https://github.com/isaacs/node-tar/blob/main/CHANGELOG.md)
- [Commits](https://github.com/isaacs/node-tar/compare/v7.5.11...v7.5.16)

---
updated-dependencies:
- dependency-name: tar
  dependency-version: 7.5.16
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

* chore: add changeset for dependabot updates

---------

Signed-off-by: dependabot[bot] <support@github.com>
Signed-off-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: Enrico <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* chore(typescript): version packages (canary)

---------

Signed-off-by: dependabot[bot] <support@github.com>
Signed-off-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Dhruv Tiwari <144548881+dhruvtiwari6@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Andrew Khadder <khandrew1@users.noreply.github.com>
Co-authored-by: Pietro Zullo <62951181+pietrozullo@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: kalpchaniyara <kalpchaniyara.2006@gmail.com>
Co-authored-by: Neha Prasad <nehaa9863pd@gmail.com>
Co-authored-by: Arpit Maurya <arpitbabu802@gmail.com>
Co-authored-by: 落尘 <cuidong111@gmail.com>
2026-06-16 09:41:20 -07:00
Pietro Zullo 8348c59a53 docs: reorganize, fix accuracy, and update for agent readability (#1502)
* docs: reorganize navigation and clean up content

- Remove 'Misc' group with misplaced blog posts
- Remove 'Libraries' redirect group from Home nav
- Simplify 'Dev Tools' group (flatten Inspector, CLI, Tunneling)
- Remove individual changelog versions from Python nav (keep summary)
- Remove changelog from TypeScript 'Get Started' group
- Remove tunneling duplicate from Python Development group
- Rewrite mcp101 as clean MCP concepts page (was pitch deck)
- Delete typescript/blog posts (not technical docs)
- Add redirects for deleted blog post URLs

* docs: fix content accuracy and remove sloppy language

- Fix broken python/server/mcp-apps link in home page
- Remove informal pitch-speak from python/server/index.mdx
- Fix grammar error in typescript/server/index.mdx
- Update typescript/client/logging.mdx: remove fake 'coming soon' API code
- Fix non-existent model name gpt-5.1 in typescript quickstart
- Fix mcp_use naming in development contributing guide

* docs: fix incorrect TypeScript server API calls in inspector docs

- Replace server.addTool() with server.tool() (correct mcp-use API)
- Add missing zod import to debugging-chatgpt-apps example

* docs: fix fake model names (gpt-5.1 → gpt-4o) in agent docs

* docs: update model names, fix APIs, and add agent visibility hints

- Replace all deprecated model names with latest: gpt-4.1, gpt-4.1-mini,
  claude-sonnet-4-6, claude-opus-4-7, gemini-2.5-flash across all docs
- Fix TypeScript server.tool() API in installation.mdx (old positional string form)
- Fix TypeScript agent.run() in quickstart.mdx (deprecated string form → object)
- Remove broken manufact.com/docs/llms.txt hidden hints from 5 pages
- Add <Visibility for="agents"> block to mcp101.mdx with install commands,
  key classes, and API signatures for agent-oriented navigation
- Add LangChain provider install note to Python quickstart (mcp-use agent
  requires a separate langchain-* provider package)
- Update model name cards in Python llm-integration.mdx

* docs: clean up remaining stale model names and improve accuracy

- Update supported model lists in Python and TypeScript llm-integration pages
- Fix cost optimization table to use current model IDs
- Update TypeScript agent overview supported providers list

* docs: add LangChain provider install to TypeScript quickstart agent section

The MCPAgent requires a separate @langchain/* provider package; this was
not mentioned before the code example that imports from @langchain/openai.

* docs: update to latest flagship model IDs (May 2026)

- OpenAI: gpt-4.1 → gpt-5.5, gpt-4.1-mini → gpt-5.5-mini
- Google: gemini-2.5-flash → gemini-3.1-flash, gemini-2.5-pro → gemini-3.1-pro
- Groq: llama-3.1-* → llama-4-scout-17b-16e-instruct
- Anthropic (claude-opus-4-7, claude-sonnet-4-6) already current, no change

* docs: replace all em dashes with hyphens

* docs: restore llms.txt hints using Visibility component

* docs: simplify TypeScript logging page to unsupported notice only

* docs: rewrite mcp101 to explain MCP protocol with mcp-use examples and doc links

* docs: remove goal.md

* docs: revert nav changes, keep only Misc group removal and blog redirects

* docs: reorder mcp101 to Server/App -> Client/Inspector -> Agent, restore title

* docs: add code examples for Resources and Prompts in mcp101

* docs: remove em dashes from mcp101

* docs: add MCPClient code examples to mcp101

* docs: add React client example to mcp101

* docs: add agent code examples to mcp101

* docs: expand MCP Apps section in mcp101 with example and links

* docs: restore Contacts, Socials, and Founders sections to mcp101

* docs: add context-setting intro paragraph to mcp101 for new readers

* docs: add MCP stores section to mcp101 intro with Claude, ChatGPT, Cursor

* docs: fix Claude store link

* docs: fix ChatGPT store link

* docs: fix Cursor store link

* docs: replace store Cards with linked image grid

* docs: add captions to store images

* docs: add Notifications to client primitives table in mcp101

* docs: add lead-in paragraph before resource cards at bottom of mcp101

* docs: move resource cards to end of page after Contacts/Socials/Founders

* docs: demote Contacts/Socials/Founders to bold text to remove from TOC

* docs: move Contacts/Socials/Founders to very end of mcp101

* docs: add Resources and Contacts section headers, link official MCP docs

* chore(docs): update site metadata, footer links, and rename mcp_use to mcp-use

* update docs metadata + images

* docs: enhance MCP section by highlighting the reach of MCP stores with 1 billion weekly active users

* api ref
2026-05-14 18:49:06 +02:00
Luigi Pederzani 6b2db4a2b0 docs: reorganize docs and examples around MCP Servers + MCP Apps (#1363)
Reshape docs, examples, and indexes to mirror the README narrative:
MCP Servers + MCP Apps are primary; MCP Agent and MCP Client are
present but secondary. Remove duplicated concepts, deprecated pages,
and stale examples; add redirects for removed paths.

Docs
- Rewrite home/index.mdx: tagline + MCP Server / MCP App split cards,
  quickstart tabs, MCP Apps widget snippet, Templates teaser, Inspector,
  Deploy, Agent+Client in a collapsed accordion.
- New home/templates.mdx gallery (Chart Builder, Diagram Builder, Slide
  Deck, Maps Explorer, Widget Gallery, and more) with demo URLs and
  deploy buttons, mirroring the README.
- Simplify python/typescript welcome.mdx: drop duplicated "What is MCP?"
  / "Why mcp-use?" (single pointer to home/mcp101); server-first Next
  Steps; fix broken Python links.
- docs.json: Home product reshaped (Welcome, MCP Apps, Templates, Dev
  Tools + CLI reference, Concepts, Libraries, Misc). Python
  Integrations collapsed into MCP Agents → LLM Adapters.
  fastapi_mount added to Python MCP Server Overview. TS MCP Apps adds
  creating-mcp-apps-server; OAuth Providers gets keycloak + custom.
  Empty API Reference, misrouted Community, and Blog tabs removed from
  TS SDK.
- Delete: ui-widgets.mdx, mcp-ui-resources.mdx,
  comparison-with-other-implementations.mdx, api-reference.mdx (empty),
  typescript/development/security.mdx, python/blog/middleware.mdx,
  python/server/auth/index.mdx.
- Redirects: old paths → current equivalents.
- CLI reference: new "What's New" card group (HMR, --tunnel, skills
  add, generate-types); cross-link from `start` to Tunneling guide.

Examples
- Rewrite libraries/typescript/.../examples/server/ui/mcp-ui/ as a
  programmatic MCP Apps widget gallery (welcome-card, quick-poll,
  task-card) using server.uiResource({ type: "mcpApps", htmlTemplate }).
  Removes deprecated UIResource / rawHtml / remoteDom patterns.
- Delete empty server/ui/apps-sdk/.
- Fix stale docs URL in server/ui/mcp-apps/apps-sdk/index.ts.
- Update examples/README.md and TS examples README: add Templates
  pointer (github.com/mcp-use/mcp-use#templates + docs/home/templates),
  list previously-missing examples (mcp-apps, files, model-context,
  middleware, session-management, better-auth, Python orphans), flag
  apps-sdk as legacy.
2026-05-03 22:57:45 +02:00
Pietro Zullo b056f72e06 docs: add llms.txt directive to landing pages for agent readiness (#1419)
* docs: add llms.txt directive blockquote to landing pages

Adds a blockquote pointing to /llms.txt at the top of the main landing
pages so agents have a clear, page-level pointer to the documentation
index. Addresses the LLMS TXT Directive check in agent-readiness audits.

* docs: hide llms.txt directive from human readers via display:none

The directive is for agents (which still see it in DOM/markdown export),
not humans, so wrap each blockquote in a hidden div to remove visual
noise from landing pages.

* docs: use absolute URL for llms.txt directive

Mintlify's broken-link checker validates relative paths against pages
in docs.json, and /llms.txt is an auto-generated artifact at host root,
not a navigation page. Switch to the absolute URL so CI passes; agents
still see a same-host link.

* docs: point llms.txt directive at canonical manufact.com URL

Skips the 2 cross-host 301 hops from docs.mcp-use.com so agents reach
the index in one request.

* docs: remove redirect-audit.md from PR

This was an internal diagnostic file accidentally bundled into the
llms.txt directive PR. Keeping it locally for reference, not for
shipping in docs.
2026-04-27 17:47:29 +02:00
Pietro Zullo 95b99d0859 docs: fix integration adapter imports and update Anthropic model (#1385)
- Use mcp_use.agents.adapters for OpenAI/Anthropic/Google adapters
  (the top-level mcp_use.adapters only re-exports Base/LangChain)
- Bump Anthropic examples from claude-3-opus-20240229 to claude-opus-4-7
- Drop stale "New" tag from the Anthropic integration page
2026-04-22 10:37:44 +02:00
Alberto Farah Blair 3f6dafc306 fix: update deprecated claude-3-5-sonnet-20241022 model to claude-sonnet-4-6 (#1266)
Model claude-3-5-sonnet-20241022 was retired on 2025-10-28 per Anthropic
deprecations page. Updated default model and documentation examples to use
claude-sonnet-4-6 as recommended replacement.

Fixes #1258

Co-authored-by: Flocky (GitHub Agent) <flocky@silhouette.ai>
2026-04-09 02:55:59 -04:00
pietrozullo fc918e5bc7 python/release/1.7.0 2026-03-17 14:42:18 +01:00
Pietro Zullo 30b23271d5 fix(python): respect configured inspector path (#1176)
* fix(python): respect configured inspector path

* fix(python): treat inspector path as a base prefix

* fix(python): format inspector fixes for ruff

* fix(ci): run conformance with node 22

* fix(ci): fail conformance runs with empty results

* chore(ci): drop inline conformance result validation

* docs(python): clarify inspector path behavior
2026-03-09 14:24:53 +01:00
Pietro Zullo 0ac1c60a60 feat(python): add mcp_logs_only option to hide non-MCP HTTP access logs (#1164)
* feat(python/server): add mcp_logs_only option to suppress HTTP access logs

When mcp_logs_only=True, all uvicorn access logs are suppressed. MCP
protocol logs (printed directly by MCPLoggingMiddleware) continue to
show. This eliminates the duplicate INFO: lines for MCP requests and
hides non-MCP HTTP traffic (/docs, /inspector, static files).

The implementation is simple: MCPAccessFormatter returns an empty string
when the flag is set, since the middleware already handles MCP logging
via direct stdout prints.

Closes #1162

* fix(python/server): use filter instead of empty string to suppress access logs

Replace the formatter returning "" (which still outputs a blank line)
with a proper MCPLogsOnlyFilter that drops log records entirely.

* docs: update

* docs(python): document mcp_logs_only option in server logging docs
2026-03-06 14:39:21 +01:00
Pietro Zullo 1a3dcfd632 feat(python): auto-retry next available port when default is in use (#1163)
* feat(python/server): auto-retry next available port when default is in use

Add port availability checking before starting uvicorn. When the
requested port is occupied, the server automatically tries the next
port (up to 10 retries) instead of crashing.

Refs #1161

* test(python/server): add unit tests for port retry helpers

Tests for _is_port_available and _find_available_port covering:
- Port available/unavailable detection
- Skipping to next port when current is in use
- RuntimeError when all ports exhausted

* docs(python): document automatic port retry in server running docs
2026-03-06 14:39:11 +01:00
Vincenzo Reina d344233c50 feat(python): add create-mcp-use CLI with rich UI and dependency install (#1097)
* Add uvx create-mcp-use command

* Update docs

* Add docs

* feat(python/cli): improve create-mcp-use with rich UI, dependency install, and telemetry

- Use rich for colored output, spinner, and panel for get-started instructions
- Add ASCII logo matching the TypeScript CLI
- Prompt user to install dependencies after scaffolding (detects uv/pip)
- Add --install and --no-install flags for non-interactive use
- Capture install output to keep terminal clean
- Add CreateMCPUseEvent telemetry to track CLI usage
- Fix starter template pyproject.toml hatch build config for installability

* feat(python/server): auto-retry next available port when default is in use

Add port availability checking before starting uvicorn. When the
requested port is occupied, the server automatically tries the next
port (up to 10 retries) instead of crashing.

Refs #1161

* fix(python/cli): fix linting errors in create-mcp-use CLI

* Revert "feat(python/server): auto-retry next available port when default is in use"

This reverts commit baf3d3233e.

* fix(python/cli): address PR review feedback

- Fix ruff format issues in cli.py
- Fix "Cli" → "CLI" in docs title
- Fix "a MCP" → "an MCP" grammar in quickstart

* docs(python): regenerate API docs for CLI module

* docs: update

---------

Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
2026-03-06 12:25:19 +01:00
Pietro Zullo e935514fc7 feat(python): add icons parameter to MCPServer constructor (#1147)
* fix(python/server): simplify tool JSON Schema for Optional parameters

Pydantic generates {"anyOf": [{"type": "T"}, {"type": "null"}]} for
Optional[T] tool parameters. While valid JSON Schema 2020-12, this
pattern breaks description rendering in the MCP Inspector UI and fails
Gemini API validation (requires top-level type field). MCP signals
optionality via the required array, making the anyOf/null wrapper
redundant.

- Add simplify_optional_schema() utility that collapses nullable anyOf
  into flat {"type": "T"} while preserving description, default, title
- Override MCPServer.add_tool() to apply simplification after Pydantic
  generates the schema
- Add 12 unit tests for the schema simplifier (test_json_schema.py)
- Add 23 unit tests for tool schema output (test_list_tool_format.py)
- Update server_example.py with representative parameter patterns
  including Literal enum types

* docs(python/server): add parameter types and JSON Schema section to tools docs

Document the Python-to-JSON-Schema type mapping, required/optional/nullable
parameter patterns, and Literal enum usage. Includes a note explaining the
anyOf/null simplification that mcp-use applies automatically.

* feat(python/server): add icons parameter to MCPServer constructor

Pass through the icons parameter to FastMCP so server-level icons can
be set directly in the MCPServer constructor.

* docs(python/server): document icons parameter in server overview

* docs(python): update server example with icons and Literal enum params

* style: format server_example.py

* test(python): add unit tests for icons constructor parameter

* docs: regenerate API reference for icons param
2026-03-05 10:17:58 +01:00
Pietro Zullo ccfb07a8ee fix(python): simplify tool JSON Schema for Optional parameters (#1141)
* fix(python/server): simplify tool JSON Schema for Optional parameters

Pydantic generates {"anyOf": [{"type": "T"}, {"type": "null"}]} for
Optional[T] tool parameters. While valid JSON Schema 2020-12, this
pattern breaks description rendering in the MCP Inspector UI and fails
Gemini API validation (requires top-level type field). MCP signals
optionality via the required array, making the anyOf/null wrapper
redundant.

- Add simplify_optional_schema() utility that collapses nullable anyOf
  into flat {"type": "T"} while preserving description, default, title
- Override MCPServer.add_tool() to apply simplification after Pydantic
  generates the schema
- Add 12 unit tests for the schema simplifier (test_json_schema.py)
- Add 23 unit tests for tool schema output (test_list_tool_format.py)
- Update server_example.py with representative parameter patterns
  including Literal enum types

* docs(python/server): add parameter types and JSON Schema section to tools docs

Document the Python-to-JSON-Schema type mapping, required/optional/nullable
parameter patterns, and Literal enum usage. Includes a note explaining the
anyOf/null simplification that mcp-use applies automatically.

* fix(python/server): address PR review comments on json_schema.py

- Fix _simplify_property docstring: says "in place" but returns new dict
- Fix simplify_optional_schema docstring: document fast-path return when
  no properties exist (returns original, not a copy)
- Wrap dict comprehension for line length

* style: format server_example.py

* docs: regenerate API reference for json_schema module
2026-03-05 09:24:46 +01:00
Pietro Zullo 869e56fcf4 fix(python): register debug routes when debug=True passed to run() (#1114)
* fix(python): register debug routes when debug=True passed to run()

When MCPServer was created with debug=False (default) and run(debug=True)
was called, debug routes (/docs, /inspector, /openmcp.json) were never
registered because _add_dev_routes() only ran during __init__.

Now run(debug=True) calls _add_dev_routes() and rebuilds the Starlette
app so routes are available. Also removes dead code in ServerRunner that
could never execute due to the same ordering issue.

Closes #1099

* docs: regenerate API reference after removing debug from ServerRunner.run()

The debug parameter was removed from ServerRunner.run() since debug mode
is now fully handled in MCPServer.run() before the runner is invoked.
2026-02-27 15:32:04 +01:00
Yuuki 8ce409948d docs(python): fix incorrect parameter name in quickstart server example (#1108)
Changed 'description' to 'instructions' in MCPServer constructor to match the actual API signature.
2026-02-27 12:40:21 +01:00
pietrozullo 7c3b6c2e1f feat(docs): enhance Python server documentation with examples for tools, prompts, and resources
- Added detailed examples for defining tools, prompts, and resources in Python, showcasing their usage with annotations and context.
- Updated README to include a Python server example for weather information retrieval.
- Improved clarity on prompt and resource definitions, including argument descriptions and JSON-RPC responses.
- Enhanced documentation for better understanding of dynamic resources and tool functionalities.
2026-02-18 11:16:16 -08:00
Pietro Zullo cfeb41e3ea docs(python): update LangChain examples to use 1.0+ API (#1022)
Replace deprecated AgentExecutor/create_tool_calling_agent with the
modern create_agent/init_chat_model API, matching the existing
LangChain integration page and examples.
2026-02-15 19:04:25 -08:00
Pietro Zullo a9bc4db3ae feat(python): add protocol handlers for logging, completions, subscriptions, and DNS protection (#1004)
* feat(python): add protocol handlers for logging, completions, subscriptions, and DNS protection

Server SDK changes:
- logging/setLevel: stores client level, Context.log() filters by RFC 5424 severity
- completion/complete: default empty handler, overridable via mcp.completion()
- resources/subscribe + unsubscribe: tracks per-session subscriptions
- notify_resource_updated(): broadcasts to all subscribed sessions via WeakSet
- dns_rebinding_protection: explicit constructor parameter (default: False)
- Capabilities patch for subscribe=True

Middleware:
- Added hooks: on_set_logging_level, on_subscribe_resource, on_unsubscribe_resource, on_complete

Tests:
- 9 unit tests for log level filtering (RFC 5424)
- Updated DNS protection tests for explicit flag

Docs:
- logging.mdx: MCP protocol logging section with level filtering
- resources.mdx: subscription section with example
- middleware.mdx: new hooks documented

Refs:
- https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging
- https://modelcontextprotocol.io/specification/2025-11-25/server/resources#subscriptions

* style: format adapter files for ruff 0.15
2026-02-14 18:53:30 -08:00
pietrozullo 36e1ac012d docs(python): document mcpclient constructor 2026-01-29 15:50:39 +01:00
pietrozullo 49926b7bbf chore(docs): linking does not work in docs and results in 404 page. remove updates page from main navigation 2026-01-25 11:46:01 +01:00
Enrico Toniato e463f68bf7 fix(docs): update GitHub Issues link for telemetry documentation 2026-01-22 15:10:28 +01:00
pietrozullo 6f5b47b21d chore(docs): fixes and logo update 2026-01-22 14:05:54 +01:00
pietrozullo cd6408069f docs(python): revamp getting started pages to match TypeScript style
- Add welcome page with py_welcome.png image
- Rewrite quickstart with Agent/Client/Server sections and mermaid diagram
- Simplify installation page (single package, no separate sections)
- Add updates symlink to changelog in getting-started
- Remove configuration overview page, update broken links to specific pages
- Update changelog title to "Updates"
2026-01-22 13:38:01 +01:00
pietrozullo be5f4d7490 python/release1.6.0 2026-01-22 12:58:01 +01:00
Pietro Zullo d789a92b4b feat(server): Bearer Token authentication for Python MCP server (#841)
* Fix DNS rebinding protection for cloud/proxy deployments

- Add host/port parameters to MCPServer.__init__() and pass to FastMCP
- Default host to "0.0.0.0" (cloud-friendly, disables DNS protection)
- "127.0.0.1" auto-enables DNS protection (handled by FastMCP)
- run() can override host/port, falls back to __init__ values
- Add comprehensive docstring to __init__() explaining parameters
- Update documentation

This fixes 421 Misdirected Request errors when running behind reverse
proxies (Cloudflare, nginx, etc.) where the Host header doesn't match
the auto-configured allowed_hosts for localhost.

* Fix DNS rebinding protection for cloud/proxy deployments

- Add host/port parameters to MCPServer.__init__() and pass to FastMCP
- Default host to "0.0.0.0" (cloud-friendly, disables DNS protection)
- "127.0.0.1" auto-enables DNS protection (handled by FastMCP)
- run() can override host/port and reconfigures DNS protection accordingly
- Rebuild app when host changes in run() to apply new security settings
- Add comprehensive docstring to __init__() explaining parameters
- Add unit tests for host/port configuration and run() overrides
- Update documentation

This fixes 421 Misdirected Request errors when running behind reverse
proxies (Cloudflare, nginx, etc.) where the Host header doesn't match
the auto-configured allowed_hosts for localhost.

* ruff lint

* Bump mcp minimum version to 1.23.0

Required for TransportSecuritySettings and DNS rebinding protection
auto-configuration feature that was added in v1.23.0.

* feat(server): add bearer token authentication for Python MCP server

Add HTTP-layer bearer token authentication that returns proper 401 responses.

- BearerAuthProvider: abstract base class with verify_token() method
- AccessToken: model with token, claims, and scopes fields
- AuthMiddleware: Starlette middleware returning HTTP 401 for invalid tokens
- get_access_token() / require_auth(): context helpers for tools

Usage:
```python
class MyAuth(BearerAuthProvider):
    async def verify_token(self, token: str) -> AccessToken | None:
        if token != "secret":
            return None
        return AccessToken(token=token, claims={"user": "alice"})

server = MCPServer(name="my-server", auth=MyAuth())
```

Closes #840

* autogenerate docs

* test(server): add unit and integration tests for bearer token auth

Unit tests:
- AccessToken model creation and serialization
- BearerAuthProvider abstract class and subclassing
- get_access_token/require_auth context helpers
- AuthMiddleware 401 responses, path exclusion, CORS

Integration tests:
- MCPClient connecting to bearer auth server with valid token
- Connection failure with invalid/missing token
- Tool access to user claims and scopes

* fix(server): address code review feedback for bearer auth

- Fix CORS security: allow_credentials=False with allow_origins=["*"]
- Remove dead try/except import for auth module
- Remove PII (email) from debug logs
- Add comment explaining broad exception handling in verify_token
- Add /openmcp.json to docs excluded paths list
- Remove set_access_token from public API (internal only)
- Create AuthenticationError instead of using ValueError
- Skip middleware tests on older httpx versions (TestClient compat)

* docs: update API documentation for auth module

* fix(server): address Copilot review feedback

- Fix bearer.mdx: require_auth raises AuthenticationError, not ValueError
- Fix API docs: claims and scopes are optional with defaults, not required
- Remove deprecated SSE transport from bearer_auth_server.py test server

* autogenerate docs

* fix(server): address renvins review feedback

- Improve bearer.mdx claims documentation with explanation and examples
- Remove unnecessary cast() for AuthMiddleware in server.py
- Refactor auth tests to use pytest fixtures for cleaner setup/teardown

* docs(auth): clarify that all MCP endpoints are automatically protected

- Add "What Gets Protected" section explaining automatic protection
- Clarify that get_access_token/require_auth are for accessing token data, not protection
- Update examples to show proper usage pattern
- Improve Note at bottom to be clearer

* fix(auth): prevent path prefix bypass in auth middleware

Security fix: Use exact path matching or segment-based prefix matching
instead of simple startswith() to prevent auth bypass attacks.

Before: /docs-secret would bypass auth because it starts with /docs
After: Only /docs and /docs/* bypass auth, /docs-secret requires auth

Added tests for path matching security edge cases.

* refactor(auth): update import paths for authentication components

- Changed import statements in multiple documentation files and source files to reflect the new structure, moving authentication-related imports to the `auth` submodule.
- Updated examples to ensure clarity and consistency in usage patterns for `BearerAuthProvider`, `AccessToken`, `get_access_token`, and `require_auth`.
2026-01-21 17:53:38 +01:00
Pietro Zullo 79d017bdc2 fix(python): DNS rebinding protection for cloud/proxy deployments (#825)
* Fix DNS rebinding protection for cloud/proxy deployments

- Add host/port parameters to MCPServer.__init__() and pass to FastMCP
- Default host to "0.0.0.0" (cloud-friendly, disables DNS protection)
- "127.0.0.1" auto-enables DNS protection (handled by FastMCP)
- run() can override host/port, falls back to __init__ values
- Add comprehensive docstring to __init__() explaining parameters
- Update documentation

This fixes 421 Misdirected Request errors when running behind reverse
proxies (Cloudflare, nginx, etc.) where the Host header doesn't match
the auto-configured allowed_hosts for localhost.

* Fix DNS rebinding protection for cloud/proxy deployments

- Add host/port parameters to MCPServer.__init__() and pass to FastMCP
- Default host to "0.0.0.0" (cloud-friendly, disables DNS protection)
- "127.0.0.1" auto-enables DNS protection (handled by FastMCP)
- run() can override host/port and reconfigures DNS protection accordingly
- Rebuild app when host changes in run() to apply new security settings
- Add comprehensive docstring to __init__() explaining parameters
- Add unit tests for host/port configuration and run() overrides
- Update documentation

This fixes 421 Misdirected Request errors when running behind reverse
proxies (Cloudflare, nginx, etc.) where the Host header doesn't match
the auto-configured allowed_hosts for localhost.

* ruff lint

* Bump mcp minimum version to 1.23.0

Required for TransportSecuritySettings and DNS rebinding protection
auto-configuration feature that was added in v1.23.0.
2026-01-19 15:32:58 +01:00
Pietro Zullo d8d319c940 fix(python/server): improve debug and pretty_print_jsonrpc behavior (#814)
* fix(python/server): improve debug and pretty_print_jsonrpc behavior

- Make pretty_print_jsonrpc work independently of debug_level
  (previously required DEBUG=2 environment variable)
- Rename run_debug to debug in server.run() for consistency
- Make run(debug=True) override server's debug_level if it was 0
- Remove aggressive signal handlers that broke thread compatibility
  (uvicorn handles SIGINT/SIGTERM gracefully)
- Update all documentation to use new debug parameter name

* refactor(python/server): remove unused lupo_tool function from server_example.py

* docs: update signals API reference after simplification

* refactor: remove unused signals.py module

uvicorn already handles SIGINT/SIGTERM gracefully, so custom signal
handlers are unnecessary. Removed the signals.py file and all references
to setup_signal_handlers().

* chore: remove analysis files
2026-01-14 18:43:25 +01:00
Vincenzo Reina 4997674559 feat(python): Intercept MCP handshake with on_initialize middleware (#769)
* Wrap server session from MCP

* Update server and middleware

* Update middleware example

* Fix formatting and linting

* Update docs

* Fix monkeypatch for tests

* Update docs and remove comment

* feat(python): add tests, docs, and docstrings for on_initialize middleware

- Add 13 unit tests covering dispatch, chain order, rejection, and context enrichment
- Rewrite middleware.mdx documentation with Mintlify components (Tabs, Tips, Cards)
- Add comprehensive docstring to MiddlewareServerSession documenting single-server-per-process limitation
- Add docs/CLAUDE.md with documentation improvement guidelines
- Regenerate API documentation

* docs: highlight typed context feature in middleware docs

* example: add ClientCapabilitiesGuard demonstrating typed context

* style: fix linting in middleware example

* docs(examples): add comprehensive docstrings to middleware_example.py

- Add module docstring explaining key concepts and middleware hooks
- Document each middleware class with typed context details
- Organize code with section headers (CONNECTION, REQUEST, TOOL-SPECIFIC)
- Add ClientCapabilitiesGuard example showing typed context usage

---------

Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
2026-01-14 16:47:57 +01:00
pietrozullo 00d7599bfb fix(docs): update image links in changelog to use CDN URLs
Replaced local image paths with CDN links for releases 1.3.11, 1.3.12, 1.4.0, 1.4.1, 1.5.0, and 1.5.2 in the changelog files.
2026-01-13 09:23:04 +01:00
Inchara J c990faf76b fix(python): add timeout mechanism to ConnectionManager.stop() (#726)
* fix(python): add timeout mechanism to ConnectionManager.stop()

Add timeout parameter (default: 30s) to stop() method to prevent infinite hangs
during application shutdown. Resolves issue #562.

Changes:
- Add timeout parameter to stop() with 30 second default
- Wrap task wait with asyncio.wait_for() to enforce timeout
- Wrap cleanup event wait with asyncio.wait_for() to enforce timeout
- Force cleanup on timeout by clearing connection and setting done event
- Add appropriate warning/error logging on timeout

Tests:
- Add 10 comprehensive unit tests for timeout scenarios
- All 158 unit tests pass
- Manual end-to-end testing verified

This ensures graceful shutdown even when cleanup hangs in production.

* updated with copilot suggested edits

* ruff checks passed

* Improve timeout handling in ConnectionManager.stop()

- Move 'import time' to module level
- Use CancelledError consistently (Python 3.11+ style)
- Treat timeout <= 0 or None as infinite wait (no timeout)
- Add elapsed time to timeout warning logs
- Add tests for negative/zero/None timeout behavior

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: update ConnectionManager.stop() API reference with timeout parameter

---------

Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 18:04:08 +01:00
pietrozullo 96cec626e5 chore(docs): update image links in changelog files to use CDN URLs
- Replaced local image paths with CDN links for releases 1.3.11, 1.3.12, 1.4.0, 1.4.1, 1.5.0, and 1.5.2 in the changelog files.
- Updated the changelog entries to ensure consistent image sourcing and improve loading performance.
2026-01-12 16:37:42 +01:00
pietrozullo 6d04f70106 release/python1.5.2 2026-01-12 13:50:07 +01:00
pietrozullo 043931dad9 feat(docs): add Contributors component to changelog files
- Introduced a new Contributors component in the changelog files for releases 1.3.11, 1.3.12, 1.4.1, and 1.5.0 to acknowledge contributors in a consistent format.
- Updated the changelog entries to include a list of contributors for each release, enhancing visibility and appreciation for their contributions.
2026-01-12 13:47:41 +01:00
Pietro Zullo 2c8a3f7d88 chore(python): docs update (#795)
* chore(docs): remove Blog section from documentation

- Eliminated the Blog tab and its associated group from the documentation structure, streamlining the content for better clarity and focus on relevant topics.

* chore(docs): update image links in changelog and remove obsolete images

- Replaced local image paths with CDN links for releases 1.3.11, 1.3.12, 1.4.0, 1.4.1, and 1.5.0 in the changelog files.
- Deleted outdated image files for releases 1.3.11 and 1.3.12 to streamline documentation and reduce clutter.

* fix(docs): update documentation link for logo reference

- Changed the logo href from the main site to the documentation page for better navigation and user experience.
2026-01-12 12:09:47 +01:00
Luigi Pederzani b45d9663ec feat(python): introduce roots support in MCPClient and Server (#751)
* fix(python): expose client capabilities to MCP servers

Add list_roots_callback support to Python connectors to properly
advertise the roots capability during MCP initialization handshake.

Previously, the Python library was not exposing any client capabilities
because the list_roots_callback was not being passed to ClientSession.
This fix ensures the roots capability is always advertised, bringing
the Python library in line with the TypeScript implementation.

Changes:
- Add roots and list_roots_callback params to BaseConnector
- Add get_roots() and set_roots() methods for managing roots
- Pass list_roots_callback to ClientSession in all connectors
- Export Root type from connectors module
- Update unit tests to expect list_roots_callback parameter

Closes MCP-1063

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(python): add roots and list_roots_callback params to connectors

- Add roots and list_roots_callback parameters to StdioConnector,
  HttpConnector, and SandboxConnector constructors
- Add comprehensive unit tests for client capabilities exposure
- Tests verify roots capability, get_roots(), set_roots(), and
  that all callbacks are correctly passed to ClientSession

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: fix import sorting and update API documentation

- Fix import sorting in test_client_capabilities.py (ruff)
- Regenerate API documentation for updated connector classes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(python): add list_roots() method to server Context

Allow MCP servers to request the list of roots from connected clients
via ctx.list_roots(). This follows the same pattern as ctx.sample()
and ctx.elicit() for server-to-client requests.

* feat(python): add roots params to MCPClient and config

- Add roots and list_roots_callback parameters to MCPClient.__init__,
  from_dict(), and from_config_file() methods
- Update create_connector_from_config() to pass roots params to all
  connector types (Stdio, HTTP, Sandbox)
- Allows clients to configure roots at the MCPClient level and have
  them propagate to all sessions

* test(python): add get_client_roots tool to primitive server

Add a tool that demonstrates the roots capability by requesting and
returning the list of roots from the connected client. Used for
integration testing of the roots feature.

* test(python): add integration tests for roots capability

Add comprehensive integration tests for the roots feature:
- test_roots_capability: Verify server can request/receive roots
- test_roots_empty_by_default: Verify empty roots when not provided
- test_roots_with_custom_callback: Verify custom callback precedence
- test_set_roots_updates_server_view: Verify dynamic root updates

* test(python): update unit tests for roots parameters

Update mock assertions in test_client.py to expect the new roots
and list_roots_callback parameters in create_connector_from_config
calls.

* ci(python): add roots to primitive tests and README badge

- Add roots to CI workflow primitive test matrix
- Add roots to PR comment report primitives list
- Add Roots badge to README Primitives row

* feat(docs): enhance MCP client and server documentation for roots feature

- Added `roots` and `list_roots_callback` parameters to MCP client initialization documentation.
- Updated `create_connector_from_config` documentation to include new parameters.
- Introduced `list_roots` method documentation in server context, detailing its usage and return values.
- Improved overall clarity and completeness of API reference for better developer guidance.

* feat(python): add get_client_roots tool to context example

- Introduced a new tool, `get_client_roots`, to the context example, demonstrating how to retrieve and display the list of roots exposed by the client.
- Updated documentation to include the new tool and its functionality, enhancing the example's coverage of context features.

* feat(docs): add roots documentation for client and server

- Introduced new documentation for the `roots` feature, detailing how clients can expose file system roots to MCP servers and how servers can access these roots.
- Added examples for configuring roots in the MCP client and using the `list_roots()` method in the server context.
- Enhanced overall clarity and usability of the documentation to support developers in implementing the roots functionality.

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
2026-01-12 11:16:09 +01:00
Vincenzo Reina aca5f9c040 feat(python): Adapt OAuth to 2.1 version from new MCP spec (#518)
* feat: Add PRM in the metadata discovery

* fix: fallback anyway to PRM

* feat: Implement complete discovery logic

* feat: Final implementation of CIMD

* feat: Implement PKCE

* feat: Add scope from WWW-Authenticate

* feat: Add all URLs possible styles

* feat: Update tests and example

* docs: Update docs

* fix: linting

* docs: update API documentation

* fix: correct typos in OAuth metadata and error messages

- Updated the comment in ProtectedResourceMetadata to use the correct abbreviation (PRM).
- Fixed a typo in the OAuthAuthenticationError message regarding code challenge support.
- Corrected the comment for legacy client paths to use "pre-registered" instead of "pre-reggistered".

* feat: restructure authentication documentation and add new methods

- Updated the authentication section in  to group authentication methods under a new Authentication category with an icon.
- Removed the old  file and replaced it with new documentation files for Bearer Token, Custom Auth, and OAuth 2.1.
- Introduced an overview page for authentication methods, detailing usage and configuration for each method.
- Enhanced security best practices and examples for each authentication type to improve clarity and usability.

* refactor: improve debug logging for OAuth metadata discovery

- Updated debug messages to provide clearer context by specifying the issuer or host being queried during OAuth and OpenID Connect metadata discovery.
- Enhanced error logging to remove redundant information, focusing on the failure reason without repeating the URL.

* fix: correct abbreviation in ProtectedResourceMetadata documentation

- Updated the abbreviation from PRC to PRM in the ProtectedResourceMetadata section to ensure accuracy in the documentation.

* fix(oauth): correct RFC 8414 well-known URL construction for path-based issuers

  The OAuth metadata discovery was incorrectly constructing .well-known URLs
  by appending to the issuer instead of inserting between host and path.

  RFC 8414 specifies that for an issuer like https://github.com/login/oauth,
  the .well-known URL should be:
    https://github.com/.well-known/oauth-authorization-server/login/oauth

  We were incorrectly building:
    https://github.com/login/oauth/.well-known/oauth-authorization-server

  This fix:
  - Implements correct RFC 8414 URL construction (insert between host/path)
  - Supports OpenID Connect style as fallback (append to issuer)
  - Removes GitHub-specific hardcode since discovery now works correctly
  - Adds documentation comments explaining the two standards

  Ref: https://www.rfc-editor.org/rfc/rfc8414.html#section-3

* chore: oauth examples

* docs: enhance OAuth endpoint discovery documentation

- Updated the OAuth documentation to clarify how `mcp-use` discovers OAuth endpoints using both OAuth 2.0 and OpenID Connect standards.
- Added a table detailing the URL construction methods for each standard.
- Included examples for better understanding and a note on fallback behavior when the issuer has no path.

* response to bs codeql

* fix: update API URL Updated the GitHub API URL in the configuration to the correct endpoint for OAuth operations.

---------

Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
2026-01-11 18:09:34 +01:00
pietrozullo 824ca31c9c fix(docs): move local images to cdn links 2026-01-11 13:26:24 +01:00
nktrk 3c45e9dcc7 Change debug flag to run_debug in server example (#718)
* Change debug flag to run_debug in server example

Signed-off-by: nktrk <nktrk@users.noreply.github.com>

* Change additional debug flags to run_debug in server example setup

Signed-off-by: nktrk <nktrk@users.noreply.github.com>

* Update server documentation to replace 'debug' with 'run_debug' for consistency across examples

---------

Signed-off-by: nktrk <nktrk@users.noreply.github.com>
Co-authored-by: Enrico Toniato <2827496+tonxxd@users.noreply.github.com>
2026-01-11 08:37:54 +01:00
Pietro Zullo 4889c49821 fix(python): update docs (#774) 2026-01-10 16:40:27 +01:00
nktrk 96ab98b8d2 Refactor imports in agent docs to use langchain_core module (#723)
Updated import statements to use langchain_core for any reference to prompts

Signed-off-by: nktrk <nktrk@users.noreply.github.com>
2026-01-08 11:21:38 +01:00
pietrozullo 1055cabe72 remove useless files 2025-12-15 18:15:09 +01:00
Salvatore Gabriele Karra 39e85c8c25 feat(python): pass files to agent (prompt_files) (#428)
* feat(python): accept HumanMessage queries and move file input into messages

* use image as example

* restore remote.py

Signed-off-by: Salvatore Gabriele Karra <86735558+gabrielekarra@users.noreply.github.com>

* lint

* fix example in docs - create example

* update docs

* remove tests

---------

Signed-off-by: Salvatore Gabriele Karra <86735558+gabrielekarra@users.noreply.github.com>
Co-authored-by: pietrozullo <pietro.zullo@gmail.com>
2025-12-15 14:58:21 +01:00
Enrico Toniato 0cc3c1cbf0 fix(docs): update Cloudflare links in Code Mode documentation
- Corrected the Cloudflare link in the Code Mode section to point to the appropriate resource.
- Ensured consistency in references to enhance user navigation and information accuracy.
2025-12-12 09:08:52 +01:00
Pietro Zullo ebef017114 python/server/middleware&tel (#650)
* chore: add example server pretty print JSON RPC for transparency

* updated telemetry module

* chore: agent side tel - langchain adapter - client tel

* server side tel:

* update API reference

* python transports and primitive reports are publishes only if not skipped

* remove wrongly generate files

* properly typed middleware

* remove examples

* feat(docs): add middleware and session management documentation

- Introduced new documentation for middleware, detailing hooks, minimal examples, and best practices for integrating middleware in MCP servers.
- Added a session management guide explaining session ID handling, usage patterns, and examples for managing per-client state in MCP servers.
- Updated  to include links to the new middleware and session management pages.

* generate docs

* remove few events

* adapter tel

* adapter tel

* api ref docs update

* google adapter fix

* fix version

* fix event naming

* server example is streamable and echo tool fix

* removed initialize middleware hook, initialize requests are not passed thorugh normal handlers

* api ref

* beta on middleware
2025-12-10 17:02:08 +01:00
pietrozullo 8a84554e64 fix broken link 2025-12-01 16:47:13 +01:00
pietrozullo 67041ca575 python/release-1.5.0 2025-12-01 16:44:20 +01:00
Pietro Zullo be9942a4d4 feat/python/server (#559)
* feat: server first implementation

* docs: docs for server and images

* chore: locked langchain dependencies in pyproject.toml (#321)

* python/release/1.3.13

* catch uvicorn logs && log session id

* fix debug logic

* docs: logging update

* fix: icon of elicitation

* fix installation paths for local clones

* docs: minor restructuring

* docs: reorganization, killed non existing pages

* docs: beta tag on server

* chore: example servers

* feat: inspector autopopulated and client only

* feat: enhance MCP logging system with customizable formats and improved middleware

* feat: implement weather alert and forecast tools in FastMCP example server

* mcp path configurable

* fix inspector

* export as FastMCP too

* chore: update fastmcp migration example

* lock inspector version

* type runner

* unhide docs and remove dangers

* migration diff

* docs and context example

* export context

* logging improvement

* pretty JSON RPC

* autoConnect url param in inspecotr

* move logging

* type check

* Server Router

* show response logs

* fallback tool name to function name in router registration

* compatibility export

* Introduced ty and prek as type checker and precommit engine respectively - moved ruff config in pyproject toml

* add ty check

* ty runs only on staged files

* ty configuration fix

* move startup info in logging

* remove bug from action

* update claude rules

* fix resource serialization

* comments on inspector errors

* abstracted runner transports

* remove redunant call for network

* fix ip getter

* add inspector mcp path

* response limit logging

* disable ty check in action

* moved transport type to types

* support sse

* show transport type in logs

* change default transport

* refactored tests to use mcp server

* removed fastmcp

* file restructuring

* test table

* sampling, elicitation, tool disabling enabling

* deprecte sse server side

* simplified report

* fix action

* remove sse deprecated test

* move tests files to allow for server integration tests

* docs

* reorg integration test files

* api-reference-doxs

* fix broken links

* telemetry

* remove feature useage from scarf
2025-12-01 14:12:16 +01:00