Repository navigation
feat(docs,api,marketing): docs MCP server, /mcp alias, agent_auth identity types, reinstated OpenAPI spec - #5912
Conversation
…rd is the real catalog" This reverts commit d9a66fa.
…/mcp alias, agent_auth identity types - docs.superset.sh/mcp now speaks MCP (docs_search + docs_read over the fumadocs source); the docs page moves to /mcp-server with a 308 for browser GETs. Fixes the 'docs MCP unhealthy' multi-surface finding with a real learn-surface server. - api.superset.sh/mcp aliases the v2 MCP endpoint; superset.sh/mcp redirects to it (307 preserves POST for MCP clients). - agent_auth gains identity_types_supported: [anonymous] + per-type block — accurately describes anonymous DCR claimed via browser consent. - /api/llms.txt scoped index (+robots carve-out); .md twins and Accept negotiation extended to changelog; applicationSubCategory added. - Reinstated /openapi.json (previous commit): the rescan hangs ~16 pts on it (scoped-permissions/schema/function-calling read the spec). Claude-Session: https://claude.ai/code/session_01GbjRvApZBmhsSkfHzihp6x
📝 WalkthroughWalkthroughThe changes expand Superset’s agent-readiness surfaces with MCP documentation and aliases, an OpenAPI specification, anonymous authentication metadata, updated discovery descriptors, agent-readable markdown resources, changelog markdown routing, and related documentation. ChangesAPI protocol and discovery
Documentation MCP server
Marketing discovery and resource surfaces
Markdown content surfaces
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant MCPClient
participant SupersetAPI
participant DocsMCP
participant DiscoveryMetadata
MCPClient->>DiscoveryMetadata: Read MCP and OpenAPI descriptors
DiscoveryMetadata-->>MCPClient: MCP endpoint and API specification URLs
MCPClient->>SupersetAPI: Use API or MCP endpoint
MCPClient->>DocsMCP: Search or read documentation
DocsMCP-->>MCPClient: Documentation results or markdown
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🧹 Preview Cleanup CompleteThe following preview resources have been cleaned up:
Thank you for your contribution! 🎉 |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
apps/api/src/app/openapi.json/route.ts (1)
1-3: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winHardcoded production origin instead of request-derived origin.
API_URL/MARKETING_URL/DOCS_URLare literalhttps://...strings baked into the spec (servers: [{ url: API_URL }], contact/terms links, etc.), unlike the sibling discovery routes added in this same PR (e.g..well-known/mcp/route.ts,.well-known/mcp/server-card.json/route.ts) which derive the origin viagetRequestOrigin(request). On any non-production origin (preview/staging deployment), this spec will still advertise the production API as theserversentry, so agents/tools consuming/openapi.jsonthere would be pointed at the wrong host.♻️ Suggested direction
-const API_URL = "https://api.superset.sh"; -const MARKETING_URL = "https://superset.sh"; -const DOCS_URL = "https://docs.superset.sh"; +import { getRequestOrigin } from "`@/lib/oauth-metadata`"; +// derive API_URL from request origin inside GET(), keep MARKETING_URL/DOCS_URL as constants if they never vary by environmentAlso applies to: 90-91, 116-116, 592-599
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/api/src/app/openapi.json/route.ts` around lines 1 - 3, Update the OpenAPI route handler to derive the request origin with the existing getRequestOrigin(request) helper instead of using hardcoded API_URL, MARKETING_URL, and DOCS_URL values. Build the servers, contact, terms, and related links from that request-derived origin so preview and staging specifications advertise their own host; remove or replace the affected constants while preserving the existing OpenAPI structure.apps/docs/src/app/mcp/route.ts (1)
92-97: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winAdd CORS handling to the MCP transport endpoint.
handleMcp()returnstransport.handleRequest(request)directly, and the route only changesGETfor human redirects.WebStandardStreamableHTTPServerTransportdoes not add CORS headers automatically, so anonymous browser-based MCP clients callingdocs.superset.sh/mcpcan be blocked by same-origin policy. Wrap the transport responses with the requiredAccess-Control-Allow-*headers and handle theOPTIONSpreflight explicitly.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/src/app/mcp/route.ts` around lines 92 - 97, Update handleMcp to explicitly respond to OPTIONS preflight requests and add the required Access-Control-Allow-* headers to transport responses, including responses returned by transport.handleRequest(request). Preserve the existing MCP server connection and request handling behavior for non-preflight requests.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/marketing/next.config.ts`:
- Around line 59-63: Update the `/mcp` redirect configuration in the Next.js
redirects list to set `permanent` to true, producing the required permanent 308
redirect while preserving the existing source and destination.
---
Nitpick comments:
In `@apps/api/src/app/openapi.json/route.ts`:
- Around line 1-3: Update the OpenAPI route handler to derive the request origin
with the existing getRequestOrigin(request) helper instead of using hardcoded
API_URL, MARKETING_URL, and DOCS_URL values. Build the servers, contact, terms,
and related links from that request-derived origin so preview and staging
specifications advertise their own host; remove or replace the affected
constants while preserving the existing OpenAPI structure.
In `@apps/docs/src/app/mcp/route.ts`:
- Around line 92-97: Update handleMcp to explicitly respond to OPTIONS preflight
requests and add the required Access-Control-Allow-* headers to transport
responses, including responses returned by transport.handleRequest(request).
Preserve the existing MCP server connection and request handling behavior for
non-preflight requests.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: d9fa0af1-28ba-4a22-8b47-b4a74bfca9c3
⛔ Files ignored due to path filters (1)
bun.lockis excluded by!**/*.lock
📒 Files selected for processing (24)
apps/api/src/app/.well-known/mcp/route.tsapps/api/src/app/.well-known/mcp/server-card.json/route.tsapps/api/src/app/api/[...unmatched]/route.tsapps/api/src/app/api/route.tsapps/api/src/app/mcp/route.tsapps/api/src/app/openapi.json/route.tsapps/api/src/lib/agent-auth-metadata.tsapps/docs/content/docs/mcp-server.mdxapps/docs/content/docs/meta.jsonapps/docs/package.jsonapps/docs/src/app/mcp/route.tsapps/marketing/next.config.tsapps/marketing/src/app/.well-known/agent-card.json/route.tsapps/marketing/src/app/.well-known/api-catalog/route.tsapps/marketing/src/app/.well-known/mcp/route.tsapps/marketing/src/app/.well-known/mcp/server-card.json/route.tsapps/marketing/src/app/agents.md/route.tsapps/marketing/src/app/api/llms.txt/route.tsapps/marketing/src/app/md/[...path]/route.tsapps/marketing/src/app/robots.txt/route.tsapps/marketing/src/components/JsonLd/JsonLd.tsxapps/marketing/src/lib/llms.tsapps/marketing/src/proxy.tsplans/done/20260722-agent-readiness.md
| { | ||
| source: "/mcp", | ||
| destination: "https://api.superset.sh/mcp", | ||
| permanent: false, | ||
| }, |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
BASE_URL="${BASE_URL:-https://superset.sh}"
curl -sS -D - "$BASE_URL/mcp" -o /dev/null | sed -n '1p;/^[Ll]ocation:/p'
# Expect an HTTP 308 response.Repository: superset-sh/superset
Length of output: 175
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== next config excerpt =="
if [ -f apps/marketing/next.config.ts ]; then
nl -ba apps/marketing/next.config.ts | sed -n '1,120p'
else
echo "apps/marketing/next.config.ts not found"
fd -a 'next\.config\.(ts|js|mjs|cjs)' . | sed -n '1,20p'
fi
echo
echo "== mcp redirect mentions =="
rg -n '"source":\s*"/mcp"|source:\s*["'\'']\s*/mcp\s*["'\'']|permanent:\s*(true|false)' apps/marketing/next.config.ts apps 2>/dev/null || true
echo
echo "== repo diff/stat summary =="
git diff --stat || true
git diff -- apps/marketing/next.config.ts | sed -n '1,160p' || trueRepository: superset-sh/superset
Length of output: 224
🌐 Web query:
Next.js redirects permanent false true 307 308 next.config.js documentation
💡 Result:
In Next.js, the redirects configuration in next.config.js uses the permanent property to determine the HTTP status code for a redirect [1][2]. When you define a redirect, you set the permanent property to either true or false: - permanent: true: Uses a 308 status code. This informs clients and search engines that the redirect is permanent and should be cached [1][3]. - permanent: false: Uses a 307 status code. This indicates a temporary redirect, which is not cached by clients [1][4]. Next.js uses 307 and 308 status codes specifically to preserve the original HTTP request method [1][3]. Traditionally, 301 (permanent) and 302 (temporary) status codes were used, but these often caused browsers to change the request method to GET regardless of the original method (e.g., turning a POST into a GET). By using 307 and 308, Next.js ensures the original request method is maintained [1][4]. In rare cases where you need a different status code for legacy HTTP client compatibility, you can use the statusCode property instead of permanent, but you cannot use both simultaneously [1][3]. Additionally, when permanent: true is used, Next.js automatically adds a Refresh header to ensure IE11 compatibility [3][4].
Citations:
- 1: https://nextjs.org/docs/app/api-reference/config/next-config-js/redirects
- 2: https://nextjs.org/docs/app/guides/redirecting
- 3: https://nextjs.org/docs/15/app/api-reference/config/next-config-js/redirects
- 4: https://nextjs.org/docs/pages/api-reference/config/next-config-js/redirects
🌐 Web query:
Next.js permanent redirect 308 Next.js redirects next.config.js permanent
💡 Result:
In Next.js, a permanent redirect is configured in your next.config.js file using the redirects function [1][2]. By setting the permanent property to true within a redirect object, Next.js will automatically use the 308 HTTP status code [1][2][3]. Configuration Example: module.exports = { async redirects { return [ { source: '/old-path', destination: '/new-path', permanent: true, // Triggers a 308 status code }, ]; }, }; Key Details: - 308 Status Code: Next.js uses 308 for permanent redirects and 307 for temporary redirects [1][2]. These status codes are preferred over the older 301/302 because they explicitly preserve the request method (e.g., ensuring a POST request remains a POST request after the redirect) [1][2][4]. - Caching: Setting permanent: true instructs browsers and search engines to cache the redirect permanently [1][2]. - Alternative Methods: For redirects based on logic within your application (rather than path matching), you can use the permanentRedirect function in Server Components, Route Handlers, or Server Actions, which also defaults to a 308 status code [5][6]. - Custom Status Codes: If you require a different status code (such as for compatibility with older clients), you can use the statusCode property instead of the permanent property, though you cannot use both at the same time [1][2][3].
Citations:
- 1: https://nextjs.org/docs/app/api-reference/config/next-config-js/redirects
- 2: https://nextjs.org/docs/pages/api-reference/config/next-config-js/redirects
- 3: https://vercel.com/kb/guide/does-vercel-support-permanent-redirects
- 4: https://nextjs.org/learn/seo/status-codes
- 5: https://nextjs.org/docs/app/guides/redirecting
- 6: https://nextjs.org/docs/app/api-reference/functions/redirect
🌐 Web query:
Superset official mcp URL 308 permanent
💡 Result:
There is no single "official MCP URL" for Apache Superset; instead, the MCP service URL is determined by your specific deployment configuration [1][2]. For most production environments, the MCP service is accessed via your main Superset base URL with an added /mcp suffix (e.g., https://your-superset-instance.com/mcp) [1][3][4]. In development environments, it is typically available at http://localhost:5008 [3][2]. Regarding 308 Permanent Redirects: 1. URL Handling: If you are encountering a 308 error when accessing Superset endpoints, it is often due to missing trailing slashes in the URL requested by the client [5][6]. Flask, which powers Superset, may issue a 308 redirect to append the slash to match the defined route [5]. 2. Proxy Configuration: A 308 error can also occur if your reverse proxy (e.g., Nginx, Apache) is misconfigured or if there is a mismatch between your environment's base URL settings and the actual traffic routing [1][7][6]. 3. Troubleshooting: - Ensure your Superset configuration (superset_config.py) explicitly sets WEBDRIVER_BASEURL_USER_FRIENDLY to the correct public-facing URL of your instance [1][3]. - If behind a proxy, verify that your ingress or proxy rules correctly route /mcp/* traffic to the MCP service port (default 5008) without improper redirects [8][7]. - For AI clients (like Claude Desktop or ChatGPT), ensure you are providing the full, correct URL including the /mcp path as configured by your administrator [9][4]. For definitive setup instructions for your specific instance, consult your organization's internal documentation or the official Apache Superset MCP administration guide [2][4].
Citations:
- 1: fix(mcp): Use config-based URL for MCP service instead of request auto-detection apache/superset#36460
- 2: https://superset.apache.org/admin-docs/configuration/mcp-server/
- 3: https://github.com/apache/superset/blob/d23b0cad/superset/mcp_service/utils/url_utils.py
- 4: https://superset.apache.org/user-docs/using-superset/using-ai-with-superset/
- 5: fix(dashboard): Remove 308 redirect when creating new dashboards apache/superset#28754
- 6: 308 http error when creating new dashboard apache/superset#30912
- 7: https://github.com/apache/superset/blob/master/superset/mcp_service/PRODUCTION.md
- 8: https://github.com/apache/superset/blob/master/superset/mcp_service/README.md
- 9: https://docs.superset.sh/mcp
Make the /mcp redirect permanent.
permanent: false maps to a temporary 307 redirect in Next.js. permanent: true preserves the request method while using the 308 status expected for a stable legacy URL.
Proposed fix
source: "/mcp",
destination: "https://api.superset.sh/mcp",
- permanent: false,
+ permanent: true,📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| { | |
| source: "/mcp", | |
| destination: "https://api.superset.sh/mcp", | |
| permanent: false, | |
| }, | |
| { | |
| source: "/mcp", | |
| destination: "https://api.superset.sh/mcp", | |
| permanent: true, | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/marketing/next.config.ts` around lines 59 - 63, Update the `/mcp`
redirect configuration in the Next.js redirects list to set `permanent` to true,
producing the required permanent 308 redirect while preserving the existing
source and destination.
Links
plans/done/20260722-agent-readiness.mdSummary
docs.superset.sh/mcpnow speaks MCP —docs_search+docs_readtools over the live fumadocs source (stateless Streamable HTTP, no auth, read-only public content). The docs page moves to/mcp-server; browser GETs get a 308 so old links keep working. This turns the scanner's "docs MCP detected but unhealthy" into a real learn-surface over the same protocol agents act with./openapi.json(revert of the drop merged in feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata #5910): the rescan added a 5-pt "scoped permissions" check on top of the spec/schema/function-calling checks — ~16 pts total read securitySchemes and operations from an API spec. Same deliberately narrow scope: MCP transport, RFC-shaped OAuth endpoints, discovery docs; the 27 tools remain self-described viatools/listand the live server card, never hand-listed.agent_authcompleted withidentity_types_supported: ["anonymous"]+ per-type block. "Anonymous RFC 7591 registration, user claims via browser consent (PKCE)" is an accurate description of our flow, and the rescan confirmed the block is being read (register_uri was detected)./mcpalias on api.superset.sh (re-export of the v2 handler, ownmaxDuration) and asuperset.sh/mcp307 redirect (preserves POST for MCP clients)./api/llms.txtscoped index + robots carve-out;.mdtwins and Accept negotiation extended to changelog pages;applicationSubCategory: "Developer Tools"in SoftwareApplication JSON-LD (nudges category classifiers away from "AI & ML").Manual QA Checklist
initialize,tools/list,tools/call(docs_search + docs_read) verified against local dev server; stateless per-request transport (same pattern as the api v2 route)GET /mcpwithoutAccept: text/event-stream→ 308 to/mcp-server;/mcp-serverpage renders; nav updated (meta.json)api /mcpalias returns 401 +WWW-Authenticate: Bearer resource_metadata=...unauthenticatedagent_authblock (skill, register_uri, revocation_uri, identity_types_supported, anonymous.credential_types_supported)/api/llms.txtserves; robots.txt allows it while still disallowing/api//changelog/<slug>.mdreturns text/markdown; drafts excludedTesting
bun run typecheck(marketing, api, docs — re-run on this branch after cherry-picking onto latest main)bun run lint(exits 0)bun run build(docs)Design Decisions
/mcpentirely, so the page had to move; a 308 for browser GETs preserves every existing link.Known Limitations
npx skills add, ChatGPT directory, PyPI SDK) or a real product feature (MCP Appsui://, ~6 pts) — documented in the plan doc.Risks / Rollout
docs.superset.sh/mcpURL changes meaning (page → MCP endpoint). Mitigated by the 308 redirect for browsers; all internal links updated to/mcp-server.Summary by cubic
Adds a public docs MCP server, restores
/openapi.json, and completesagent_authmetadata. Also adds an/mcpalias and small discoverability updates.New Features
https://docs.superset.sh/mcpwithdocs_searchanddocs_read(Streamable HTTP, no auth). The docs page moved to/mcp-server;GET /mcpredirects (308) for browsers.https://api.superset.sh/openapi.json(OpenAPI 3.1) covering MCP transport and OAuth/discovery endpoints; tools remain self-described viatools/list.agent_authnow includesidentity_types_supported: ["anonymous"]with a per-type block describing anonymous DCR + PKCE consent./mcpalias onapi.superset.shto the v2 MCP handler;https://superset.sh/mcp307-redirects to it (preserves POST).GET /api/llms.txtadded and allowed inrobots.txt;.mdtwins + Accept negotiation extended to changelog pages.service-descto the OpenAPI spec; docs and server-card URLs updated to/mcp-server.applicationSubCategory: "Developer Tools"added to SoftwareApplication JSON‑LD.Dependencies
@modelcontextprotocol/sdkto docs.Written for commit 86eb8bf. Summary will update on new commits.
Summary by CodeRabbit
New Features
/api/llms.txtfor machine-readable developer resources.Documentation
Bug Fixes