Repository navigation
feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata - #5910
Conversation
…MCP discovery, agent auth metadata, OpenAPI spec Addresses orank agent-readiness gaps for superset.sh: Marketing (superset.sh): - llms.txt: when-to-use guidance + developer-resource index; shared builder in lib/llms.ts - Markdown surfaces: /index.md, /llms.md, /agents.md, /auth.md (WorkOS auth.md convention), .md twins for blog/compare pages, Accept: text/markdown negotiation + ?mode=agent via new proxy.ts - robots.txt: explicit AI-crawler tiers (allow AI search/user agents, block CCBot/Bytespider) + Content-Signal - .well-known: A2A agent-card.json, MCP discovery + server card, RFC 9727 api-catalog - JSON-LD: Organization contactPoint/address/sameAs, WebPage speakable, Service schema - Contact page: direct channels prose; Link headers (RFC 8288) on homepage API (api.superset.sh): - /openapi.json: OpenAPI 3.1 spec for the protocol-stable surface (MCP transport, OAuth, discovery) - AS metadata: agent_auth block (skill/register_uri/revocation_uri); PRM resource_documentation - /.well-known/mcp + server-card.json with live tool introspection via in-memory MCP client - JSON errors: 401 + WWW-Authenticate at /api root, JSON 404 catch-all for unmatched /api/* paths Docs (docs.superset.sh): - /llms.txt page index (llms-full.txt and per-page /llms.mdx already existed) Claude-Session: https://claude.ai/code/session_01GbjRvApZBmhsSkfHzihp6x
…e real catalog An OpenAPI spec for a JSON-RPC-over-one-endpoint API reduces to a single generic operation no function-calling framework can use. Point service-desc links, error hints, llms.txt, and agents.md at the live MCP server card instead. Rationale recorded in plans/done/20260722-agent-readiness.md. Claude-Session: https://claude.ai/code/session_01GbjRvApZBmhsSkfHzihp6x
📝 WalkthroughWalkthroughAdds agent-oriented discovery and authentication metadata, machine-readable Markdown routes and content negotiation, API error responses, crawler directives, structured JSON-LD, and linked documentation/catalog surfaces across the API, docs, and marketing applications. ChangesAPI discovery and authentication
Marketing discovery and content surfaces
Site metadata and documentation
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Agent
participant MarketingServerCard
participant ApiServerCard
participant MCPClient
participant MCPServer
Agent->>MarketingServerCard: Request MCP server card
MarketingServerCard->>ApiServerCard: Fetch live card
ApiServerCard->>MCPClient: List available tools
MCPClient->>MCPServer: Connect over linked transport
MCPServer-->>MCPClient: Return tool definitions
MCPClient-->>ApiServerCard: Return simplified tools
ApiServerCard-->>MarketingServerCard: Return populated card
MarketingServerCard-->>Agent: Return card or fallback
🚥 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: 13
🧹 Nitpick comments (1)
apps/marketing/src/app/.well-known/agent-card.json/route.ts (1)
34-39: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winKeep advertised OAuth scopes synchronized.
apps/api/src/app/.well-known/oauth-protected-resource/route.tsderivesscopes_supportedfrom the live auth configuration, while this card hardcodes four scopes. Reuse a shared source so discovery cannot advertise scopes the authorization server no longer supports.🤖 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/src/app/.well-known/agent-card.json/route.ts` around lines 34 - 39, Update the agent-card route’s scopes configuration to reuse the shared live OAuth scope source used by the protected-resource route instead of hardcoding values in the scopes object. Ensure the advertised scopes remain synchronized with the authorization server’s supported configuration.
🤖 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/api/src/app/.well-known/mcp/server-card.json/route.ts`:
- Around line 7-10: Move the await server.connect(serverTransport) call into the
existing try block in the route handler, ensuring any setup rejection still
reaches the cleanup path and invokes server.close(). Keep the server creation
and transport pairing unchanged.
- Around line 14-15: Update the MCP server-card route’s client.listTools() flow
to iterate through all paginated responses, passing each response’s nextCursor
as the subsequent cursor until no cursor remains. Accumulate tools from every
page before applying the existing map serialization, preserving the current
output shape.
In `@apps/docs/src/app/llms.txt/route.ts`:
- Around line 11-20: Update the page links generated in the source.getPages()
mapping so each href prefixes page.url with /llms.mdx, matching the advertised
Markdown endpoint while preserving the existing title and description rendering.
In `@apps/marketing/src/app/.well-known/agent-card.json/route.ts`:
- Around line 7-23: Update the agent-card response built in the route’s card
object so it no longer presents the MCP_SERVER_URL as an A2A 0.3.0 endpoint.
Either point url and its transport/capabilities to a genuine A2A endpoint, or
replace this A2A-shaped card with the existing MCP server-card document; do not
advertise MCP as A2A.
- Around line 25-43: Update the Agent Card object containing securitySchemes to
also declare its MCP authentication requirement through the appropriate security
field. Reference the existing oauth2 scheme and preserve the current
authorizationCode flow and scope definitions.
In `@apps/marketing/src/app/.well-known/api-catalog/route.ts`:
- Around line 13-15: Update the live tool catalog service-desc link in the
api-catalog route to use API_URL and reference the API-origin server-card
endpoint. In the mcp route, update serverCard to the same API-origin server-card
endpoint instead of the marketing fallback document; apply these changes at
apps/marketing/src/app/.well-known/api-catalog/route.ts lines 13-15 and
apps/marketing/src/app/.well-known/mcp/route.ts lines 12-14.
In `@apps/marketing/src/app/.well-known/mcp/server-card.json/route.ts`:
- Around line 19-28: Update GET so the parsed upstream response is validated
against the expected server-card shape before replacing FALLBACK_CARD. Reject
null, arrays, and malformed objects by retaining the fallback, and preserve type
safety without introducing any.
In `@apps/marketing/src/app/robots.txt/route.ts`:
- Around line 6-29: Update the robots.txt content in the route handler so every
named crawler group, including GoogleOther, ChatGPT-User, and Claude-SearchBot,
also contains Disallow rules for /api/ and /_next/. Preserve Allow: / and the
existing crawler groups while applying the same exclusions consistently.
In `@apps/marketing/src/components/JsonLd/JsonLd.tsx`:
- Around line 210-254: Move HomeWebPageJsonLd and ServiceJsonLd out of
JsonLd.tsx into separate HomeWebPageJsonLd/HomeWebPageJsonLd.tsx and
ServiceJsonLd/ServiceJsonLd.tsx component files, adding colocated index.ts files
for each. Preserve their existing schemas and behavior, and update the existing
barrel exports so both components remain publicly available.
- Around line 37-41: Align the structured-data claims with
HERO_COPY.control.subheadline by replacing the hardcoded “10+” wording in the
Organization description and new WebPage name with the approved “100+” claim or
a shared source-of-truth value. Update the JsonLd component’s relevant fields
while preserving the existing schema structure and other metadata.
In `@apps/marketing/src/lib/llms.ts`:
- Around line 15-16: Update the component-removal logic in the LLM text
transformation chain to strip MDX wrapper opening and closing tags while
preserving their inner text, instead of deleting the entire matched body. Keep
the existing self-closing component removal behavior, and ensure nested or
multiline wrapper content remains available in the generated outputs.
In `@apps/marketing/src/proxy.ts`:
- Around line 5-8: Update acceptsMarkdown to parse the Accept header’s media
ranges and reject text/markdown entries with q=0, including parameterized values
such as text/markdown;q=0. Preserve Markdown acceptance for entries with a
positive or unspecified quality value, while continuing to return false when
Markdown is not accepted.
In `@plans/done/20260722-agent-readiness.md`:
- Line 11: Update the llms.txt row in the completed plan to remove the stale
OpenAPI reference and describe only the currently exposed API docs/MCP
resources, matching the resource list in llms.ts. Preserve the row’s existing
scope and formatting.
---
Nitpick comments:
In `@apps/marketing/src/app/.well-known/agent-card.json/route.ts`:
- Around line 34-39: Update the agent-card route’s scopes configuration to reuse
the shared live OAuth scope source used by the protected-resource route instead
of hardcoding values in the scopes object. Ensure the advertised scopes remain
synchronized with the authorization server’s supported configuration.
🪄 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: 66bd4f6e-895d-4216-b9f8-c9dc36387012
📒 Files selected for processing (34)
apps/api/src/app/.well-known/mcp/route.tsapps/api/src/app/.well-known/mcp/server-card.json/route.tsapps/api/src/app/.well-known/oauth-authorization-server/[...path]/route.tsapps/api/src/app/.well-known/oauth-authorization-server/route.tsapps/api/src/app/.well-known/oauth-protected-resource/[...path]/route.tsapps/api/src/app/.well-known/oauth-protected-resource/route.tsapps/api/src/app/api/[...unmatched]/route.tsapps/api/src/app/api/route.tsapps/api/src/lib/agent-auth-metadata.tsapps/docs/src/app/llms.txt/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/auth.md/route.tsapps/marketing/src/app/blog/llms.txt/route.tsapps/marketing/src/app/compare/llms.txt/route.tsapps/marketing/src/app/components/HeroSection/HeroSection.tsxapps/marketing/src/app/contact/page.tsxapps/marketing/src/app/index.md/route.tsapps/marketing/src/app/llms-full.txt/route.tsapps/marketing/src/app/llms.md/route.tsapps/marketing/src/app/llms.txt/route.tsapps/marketing/src/app/md/[...path]/route.tsapps/marketing/src/app/page.tsxapps/marketing/src/app/robots.tsapps/marketing/src/app/robots.txt/route.tsapps/marketing/src/components/JsonLd/JsonLd.tsxapps/marketing/src/components/JsonLd/index.tsapps/marketing/src/lib/llms.tsapps/marketing/src/proxy.tsplans/done/20260722-agent-readiness.md
💤 Files with no reviewable changes (1)
- apps/marketing/src/app/robots.ts
| const server = createMcpServer(); | ||
| const [serverTransport, clientTransport] = | ||
| InMemoryTransport.createLinkedPair(); | ||
| await server.connect(serverTransport); |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Keep server cleanup on setup failures.
server.connect() runs before the try; if it rejects, server.close() is never reached. Move the connection into the existing try so every created server is closed.
🤖 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/.well-known/mcp/server-card.json/route.ts` around lines 7 -
10, Move the await server.connect(serverTransport) call into the existing try
block in the route handler, ensuring any setup rejection still reaches the
cleanup path and invokes server.close(). Keep the server creation and transport
pairing unchanged.
| const { tools } = await client.listTools(); | ||
| return tools.map((tool) => ({ |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
npm pack --silent --ignore-scripts --pack-destination "$tmp" \
"`@modelcontextprotocol/sdk`@1.28.0" >/dev/null
tar -xzf "$tmp"/*.tgz -C "$tmp"
rg -n 'listTools|nextCursor' "$tmp/package"Repository: superset-sh/superset
Length of output: 10477
🏁 Script executed:
#!/bin/bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
npm pack --silent --ignore-scripts --pack-_destination "$tmp" \
"`@modelcontextprotocol/sdk`@1.28.0" >/dev/null
tar -xzf "$tmp"/*.tgz -C "$tmp"
printf '\n--- listTools examples pagination snippets ---\n'
sed -n '70,125p' "$tmp/package/dist/esm/examples/client/streamableHttpWithSseFallbackClient.js"
printf '\n--- simple client examples ---\n'
sed -n '84,100p' "$tmp/package/dist/esm/examples/client/simpleTaskInteractiveClient.js"
sed -n '500,520p' "$tmp/package/dist/esm/examples/client/simpleStreamableHttp.js"
sed -n '104,120p' "$tmp/package/dist/esm/examples/client/parallelToolCallsClient.js"
printf '\n--- server-card route ---\n'
wc -l apps/api/src/app/.well-known/mcp/server-card.json/route.ts
cat -n apps/api/src/app/.well-known/mcp/server-card.json/route.ts
printf '\n--- deterministic shape model ---\n'
node - <<'JS'
const example = `{
"tools": [ { "name": "a" }, { "name": "b" } ],
"nextCursor": "cursor-1"
}`;
const page = JSON.parse(example);
console.log('current implementation returns', page.tools.length, 'tools', JSON.stringify(page.tools.map(t=>t.name)));
console.log('has nextCursor', page.nextCursor !== undefined);
JSRepository: superset-sh/superset
Length of output: 162
🏁 Script executed:
#!/bin/bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
npm pack --silent --ignore-scripts --pack-destination "$tmp" \
"`@modelcontextprotocol/sdk`@1.28.0" >/dev/null
tar -xzf "$tmp"/*.tg 2>/dev/null || tar -xzf "$tmp"/*.tgz -C "$tmp"
printf '\n--- listTools examples pagination snippets ---\n'
sed -n '70,125p' "$tmp/package/dist/esm/examples/client/streamableHttpWithSseFallbackClient.js"
printf '\n--- simple client examples ---\n'
sed -n '84,100p' "$tmp/package/dist/esm/examples/client/simpleTaskInteractiveClient.js"
sed -n '500,520p' "$tmp/package/dist/esm/examples/client/simpleStreamableHttp.js"
sed -n '104,120p' "$tmp/package/dist/esm/examples/client/parallelToolCallsClient.js"
printf '\n--- server-card route ---\n'
wc -l apps/api/src/app/.well-known/mcp/server-card.json/route.ts
cat -n apps/api/src/app/.well-known/mcp/server-card.json/route.ts
printf '\n--- deterministic shape model ---\n'
node - <<'JS'
const page = {"tools":[{"name":"a"},{"name":"b"}],"nextCursor":"cursor-1"};
console.log('current implementation returns', page.tools.length, 'tools', JSON.stringify(page.tools.map(t=>t.name)));
console.log('has nextCursor', page.nextCursor !== undefined);
JSRepository: superset-sh/superset
Length of output: 6843
🌐 Web query:
modelcontextprotocol typescript-sdk docs/client.md listTools nextCursor loop
💡 Result:
As of the latest updates to the Model Context Protocol (MCP) TypeScript SDK (version 2.0.0 and later), the listTools method now automatically handles pagination by default [1]. When you call client.listTools() without arguments, the SDK walks every page of results on your behalf, aggregates them, and returns the complete list [2][3][1]. This behavior also applies to listPrompts, listResources, and listResourceTemplates [2][1]. If you require fine-grained control, such as fetching only a specific page, you can pass an explicit cursor object: const page = await client.listTools({ cursor: heldCursor }); console.log(page.tools, page.nextCursor); Legacy manual pagination loops—where you previously had to manually check for nextCursor and request subsequent pages in a do...while loop—are no longer necessary for most use cases, though they will still function (the first call will simply return all items and an undefined nextCursor, causing the loop to exit immediately) [1]. The SDK includes a default listMaxPages limit (set to 64) to prevent infinite loops or excessive memory usage during auto-aggregation [2][1]. If a server's pagination does not terminate, the call will throw an SdkError with code LIST_PAGINATION_EXCEEDED [2][1]. You can customize this limit via ClientOptions.listMaxPages or set it to 0 to remove the cap entirely [2].
Citations:
- 1: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/client%402.0.0-alpha.4
- 2: https://ts.sdk.modelcontextprotocol.io/v2/clients/calling.html
- 3: https://github.com/modelcontextprotocol/TypeScript-sdk/blob/main/docs/client.md
🌐 Web query:
"@modelcontextprotocol/sdk@1.28.0" "docs/client.md" "listTools" "nextCursor"
💡 Result:
In the Model Context Protocol (MCP) TypeScript SDK, the listTools method (along with listPrompts, listResources, and listResourceTemplates) supports cursor-based pagination [1][2][3]. As of recent SDK updates (e.g., version 2.0.0-alpha.4 and later), the behavior for listTools has been streamlined: 1. Auto-Aggregation: When called without a cursor argument, the Client automatically walks through all available pages by following the nextCursor values returned by the server [2][4]. It returns a single, fully aggregated list of results, with the final nextCursor set to undefined [2][4]. 2. Manual Pagination: If you need to fetch specific pages individually, you can pass an explicit cursor string to the listTools({ cursor }) call [2][4]. This returns exactly that page of results and the corresponding nextCursor for the subsequent page [2][4]. The nextCursor value is an opaque string provided by the server, which clients can store and pass back in subsequent requests to retrieve the next segment of a paginated list [5][3][6]. For developers implementing custom pagination logic, a common pattern looks like this [1][7]: let cursor: string | undefined; const allTools: Tool[] = []; do { const result = await client.listTools({ cursor }); allTools.push(...result.tools); cursor = result.nextCursor; } while (cursor); Note that the SDK includes safety mechanisms, such as ClientOptions.listMaxPages (defaulting to 64), to cap auto-aggregation and prevent issues with servers that might have infinite or excessively long pagination sequences [2][4]. If this limit is exceeded, the SDK throws an SdkError with the code LIST_PAGINATION_EXCEEDED [2][4].
Citations:
- 1: https://ts.sdk.modelcontextprotocol.io/documents/protocol.html
- 2: https://ts.sdk.modelcontextprotocol.io/v2/clients/calling.html
- 3: https://py.sdk.modelcontextprotocol.io/v2/advanced/pagination/
- 4: https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/client%402.0.0-alpha.4
- 5: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
- 6: https://modelcontextprotocol.io/specification/2025-06-18/server/tools.md
- 7: https://github.com/microsoft/mcp-for-beginners/blob/HEAD/04-PracticalImplementation/pagination/README.md
🌐 Web query:
"@modelcontextprotocol/sdk@1.28.0" listTools implementation nextCursor
💡 Result:
In the Model Context Protocol (MCP) TypeScript SDK, including version 1.28.0, the listTools method supports cursor-based pagination using a nextCursor field [1][2]. ### Implementation Details The listTools method is an asynchronous operation provided by the high-level Client class [3][4]. When a server returns a list of tools, the response includes a nextCursor if additional results are available [1][5]. To implement pagination in your client, you should pass the cursor value from the previous response's nextCursor into the params of the subsequent listTools call [1][2]. ### Recommended Pagination Pattern You can implement a loop to fetch all available tools by checking for the existence of nextCursor [2]: typescript let cursor: string | undefined; const allTools: Tool[] = []; do { // Pass the cursor from the previous response const result = await client.listTools({ cursor }); allTools.push(...result.tools); // Update cursor for the next iteration; // it will be undefined when there are no more pages cursor = result.nextCursor; } while (cursor); ### Key Guidelines - Treat cursors as opaque tokens [1][6]. Clients must not attempt to parse, modify, or assume a specific format for the cursor [1]. - A missing or undefined nextCursor indicates that you have reached the end of the result set [1][6]. - Clients should support both paginated and non-paginated flows, as servers may return all results at once if the list is short [1]. For more information on the protocol specification regarding pagination, refer to the official Model Context Protocol documentation [1][6].
Citations:
- 1: https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/pagination
- 2: modelcontextprotocol/typescript-sdk@v1.26.0...v1.29.0
- 3: https://npmx.dev/package/@modelcontextprotocol/sdk/v/~1.28.0
- 4: https://www.npmjs.com/package/@modelcontextprotocol/sdk
- 5: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
- 6: https://github.com/modelcontextprotocol/kotlin-sdk
🌐 Web query:
github.com modelcontextprotocol typescript-sdk @modelcontextprotocol/sdk@1.28.0 src client listTools nextCursor
💡 Result:
In the Model Context Protocol (MCP) TypeScript SDK, the listTools method supports cursor-based pagination to handle cases where a server returns a large number of tools [1][2]. When calling listTools(), you can pass an optional cursor in the parameters [3]. If the server has more tools to return, the response will include a nextCursor property [3][4]. To retrieve all tools, you should implement a loop that passes the nextCursor from the current response into the cursor parameter of the next listTools request [1][5]. The following pattern is the standard approach for collecting all tools: typescript let cursor: string | undefined; const allTools: Tool[] = []; do { const result = await client.listTools({ cursor }); allTools.push(...result.tools); cursor = result.nextCursor; } while (cursor !== undefined); Key points regarding this pattern: - The nextCursor value is provided by the server in the response object [1][4]. - When nextCursor is undefined, it indicates that all pages have been retrieved [4]. - The Client class also provides an auto-aggregating version of listTools() that fetches all pages automatically if you call it without a cursor argument [6][7]. This internal walk is capped at a default of 64 pages to prevent infinite loops with misbehaving servers, though this can be configured via listMaxPages [7]. Explicitly using a cursor in your own loop bypasses this automatic aggregation cap [7].
Citations:
- 1: https://modelcontextprotocol.github.io/typescript-sdk/documents/protocol.html
- 2: https://ts.sdk.modelcontextprotocol.io/protocol.html
- 3: https://context7.com/websites/ts_sdk_modelcontextprotocol_io/llms.txt
- 4: https://github.com/modelcontextprotocol/typescript-sdk/blob/e4227d13/packages/client/src/client/client.examples.ts
- 5: https://github.com/modelcontextprotocol/typescript-sdk/blob/e4227d13/docs/client.md
- 6: https://github.com/modelcontextprotocol/TypeScript-sdk/blob/main/docs/client.md
- 7: https://github.com/modelcontextprotocol/typescript-sdk/blob/95d28cbae98e57df1b987b656a555777de976545/packages/client/src/client/client.ts
🏁 Script executed:
#!/bin/bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
echo "npm pack version:"
npm pack --silent --ignore-scripts \
--pack-destination "$tmp" "`@modelcontextprotocol/sdk`@1.28.0" |& sed -n '1,20p'
echo
echo "tarballs in tmp:"
ls -l "$tmp"
echo
echo "tarball names and listTools implementation:"
for f in "$tmp"/*.tgz "$tmp"/*.tg 2>/dev/null; do
[ -f "$f" ] || continue
echo "--- $f ---"
mkdir -p "$tmp/pkg"
tar -xzf "$f" -C "$tmp/pkg"
sed -n '520,590p' "$tmp/pkg/package/dist/esm/client/index.js"
doneRepository: superset-sh/superset
Length of output: 426
🏁 Script executed:
#!/bin/bash
set -euo pipefail
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
echo "npm pack version:"
npm pack --silent --ignore-scripts \
--pack-destination "$tmp" "`@modelcontextprotocol/sdk`@1.28.0" |& sed -n '1,20p'
echo
echo "tarballs in tmp:"
ls -l "$tmp"
echo
echo "listTools implementation:"
mkdir -p "$tmp/pkg"
tar -xzf "$tmp"/modelcontextprotocol-sdk-1.28.0.tgz -C "$tmp/pkg"
sed -n '520,590p' "$tmp/pkg/package/dist/esm/client/index.js"
sed -n '104,130p' "$tmp/pkg/package/dist/esm/client/index.js"
sed -n '1,40p' "$tmp/pkg/package/dist/esm/client/index.js"Repository: superset-sh/superset
Length of output: 7231
Collect every page from tools/list.
In @modelcontextprotocol/sdk@1.28.0, client.listTools() returns only the response for the requested cursor and does not auto-iterate nextCursor. This route then serializes only the first page, so any tools behind pagination are omitted from the server card. Use a loop that passes nextCursor into the next cursor parameter until it is absent.
🤖 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/.well-known/mcp/server-card.json/route.ts` around lines 14 -
15, Update the MCP server-card route’s client.listTools() flow to iterate
through all paginated responses, passing each response’s nextCursor as the
subsequent cursor until no cursor remains. Accumulate tools from every page
before applying the existing map serialization, preserving the current output
shape.
| "Each page is available as markdown at /llms.mdx/<path>. The full corpus is at /llms-full.txt.", | ||
| "", | ||
| "## Pages", | ||
| "", | ||
| ...source.getPages().map((page) => { | ||
| const description = | ||
| typeof page.data.description === "string" && page.data.description | ||
| ? `: ${page.data.description}` | ||
| : ""; | ||
| return `- [${page.data.title}](https://docs.superset.sh${page.url})${description}`; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Point the index at the advertised Markdown twins.
Line 11 tells agents to use /llms.mdx/<path>, but Line 20 links every entry to the HTML page URL. Prefix page.url with /llms.mdx so the index actually returns machine-readable content.
Proposed fix
- return `- [${page.data.title}](https://docs.superset.sh${page.url})${description}`;
+ return `- [${page.data.title}](https://docs.superset.sh/llms.mdx${page.url})${description}`;📝 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.
| "Each page is available as markdown at /llms.mdx/<path>. The full corpus is at /llms-full.txt.", | |
| "", | |
| "## Pages", | |
| "", | |
| ...source.getPages().map((page) => { | |
| const description = | |
| typeof page.data.description === "string" && page.data.description | |
| ? `: ${page.data.description}` | |
| : ""; | |
| return `- [${page.data.title}](https://docs.superset.sh${page.url})${description}`; | |
| "Each page is available as markdown at /llms.mdx/<path>. The full corpus is at /llms-full.txt.", | |
| "", | |
| "## Pages", | |
| "", | |
| ...source.getPages().map((page) => { | |
| const description = | |
| typeof page.data.description === "string" && page.data.description | |
| ? `: ${page.data.description}` | |
| : ""; | |
| return `- [${page.data.title}](https://docs.superset.sh/llms.mdx${page.url})${description}`; |
🤖 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/llms.txt/route.ts` around lines 11 - 20, Update the page
links generated in the source.getPages() mapping so each href prefixes page.url
with /llms.mdx, matching the advertised Markdown endpoint while preserving the
existing title and description rendering.
| const card = { | ||
| protocolVersion: "0.3.0", | ||
| name: "Superset", | ||
| description: | ||
| "Superset runs parallel AI coding agents in isolated Git worktrees. This service speaks the Model Context Protocol (JSON-RPC over Streamable HTTP) rather than the A2A message protocol — connect an MCP client to the URL below to create workspaces, launch coding agents, schedule automations, and manage tasks on behalf of a Superset user.", | ||
| url: MCP_SERVER_URL, | ||
| preferredTransport: "JSONRPC", | ||
| provider: { | ||
| organization: COMPANY.NAME, | ||
| url: baseUrl, | ||
| }, | ||
| version: "1.0.0", | ||
| documentationUrl: `${COMPANY.DOCS_URL}/mcp`, | ||
| capabilities: { | ||
| streaming: true, | ||
| pushNotifications: false, | ||
| stateTransitionHistory: false, |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate route and related files =="
git ls-files | rg '(^|/)agent-card\.json/route\.ts$|agent|card|mcp|a2a|Agent Card|agent-card|well-known|well-known' || true
echo
echo "== inspect target route =="
target="$(git ls-files | rg '(^|/)apps/marketing/src/app/\.well-known/agent-card\.json/route\.ts$' | head -1 || true)"
if [ -n "${target:-}" ]; then
wc -l "$target"
sed -n '1,140p' "$target"
fi
echo
echo "== search A2A/mcp references =="
rg -n "preferredTransport|protocolVersion|agent card|Agent Card|a2a|A2A|model-context|mcp|MCP_SERVER_URL|MCP|JSONRPC" -S . \
-g '!node_modules' -g '!dist' -g '!build' -g '!coverage' | head -200Repository: superset-sh/superset
Length of output: 50376
🌐 Web query:
A2A protocol v0.3.0 Agent Card preferredTransport JSONRPC url protocolVersion
💡 Result:
In the A2A Protocol v0.3.0, the Agent Card is a core metadata structure that facilitates agent discovery and interaction [1][2]. The specific fields requested are defined as follows: preferredTransport This field is REQUIRED in the Agent Card [1][3]. It specifies the transport protocol used for the agent's primary endpoint (the main url field) [1][4]. While it allows for various transport types, it commonly defaults to "JSONRPC" if not explicitly specified by some implementations, though strict compliance requires explicit declaration [4][3][5]. The transport declared here MUST be supported at the main url provided in the card [1][4]. url This is the REQUIRED base URL for the agent's A2A service [6][2]. It represents the primary endpoint where the agent expects to receive requests using the protocol specified in preferredTransport [1][4]. For HTTP-based transports, this must be an absolute URL [6][7]. protocolVersion This is a REQUIRED string field in the Agent Card that indicates the version of the A2A protocol supported by the agent (e.g., "0.3.0") [6][8]. It ensures that clients can verify compatibility before attempting to interact with the agent [9][7]. Note: These fields (url and preferredTransport) were utilized in v0.x versions of the protocol [10]. In v1.0.0, the architecture evolved; the top-level url and preferredTransport fields were replaced by a more flexible supportedInterfaces array, which allows agents to declare multiple protocol bindings and URLs [8][10].
Citations:
- 1: https://a2a-protocol.org/v0.3.0/specification/
- 2: https://stacka2a.dev/learn/agent-card-spec
- 3: fix: Agent card PreferredTransport MUST list supported transports a2aproject/a2a-dotnet#189
- 4: https://a2a-protocol.org/latest/sdk/python/api/a2a.compat.v0_3.types.html
- 5: http://a2a-registry.dev/documentation/examples/agent-registration/
- 6: https://a2a-protocol.org/v0.2.5/specification/
- 7: https://a2a-protocol.org/dev/specification/
- 8: https://a2a-protocol.org/v1.0.0/specification/
- 9: https://github.com/a2aproject/A2A/blob/main/docs/specification.md
- 10: https://www.agentcard.net/agent-card-schema
Do not advertise the MCP endpoint as an A2A JSON-RPC endpoint.
This card uses the A2A 0.3.0 Agent Card shape, but url points to the MCP server while preferredTransport: "JSONRPC" and A2A capabilities describe A2A behavior. A2A clients will select this URL and send A2A requests to an MCP handler. Point the card to a real A2A endpoint, or publish only the existing MCP server-card document.
🤖 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/src/app/.well-known/agent-card.json/route.ts` around lines 7 -
23, Update the agent-card response built in the route’s card object so it no
longer presents the MCP_SERVER_URL as an A2A 0.3.0 endpoint. Either point url
and its transport/capabilities to a genuine A2A endpoint, or replace this
A2A-shaped card with the existing MCP server-card document; do not advertise MCP
as A2A.
| securitySchemes: { | ||
| oauth2: { | ||
| type: "oauth2", | ||
| description: | ||
| "OAuth 2.1 authorization code + PKCE with RFC 7591 dynamic client registration. Discovery via RFC 9728 protected resource metadata.", | ||
| flows: { | ||
| authorizationCode: { | ||
| authorizationUrl: `${API_URL}/api/auth/oauth2/authorize`, | ||
| tokenUrl: `${API_URL}/api/auth/oauth2/token`, | ||
| scopes: { | ||
| openid: "OpenID Connect", | ||
| profile: "User profile", | ||
| email: "User email", | ||
| offline_access: "Refresh tokens", | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files matching agent-card and api route =="
fd -a 'route\.ts|route\.json|package\.json|README\.md' . | sed 's#^\./##' | rg 'agent-card|api|app|marketing|api' || true
echo
echo "== target file =="
if [ -f apps/marketing/src/app/.well-known/agent-card.json/route.ts ]; then
wc -l apps/marketing/src/app/.well-known/agent-card.json/route.ts
cat -n apps/marketing/src/app/.well-known/agent-card.json/route.ts
fi
echo
echo "== related route snippets =="
for f in $(rg -l 'api/auth/oauth2|API_URL|securitySchemes|agent-card|AgentCard|security:' apps -g 'route.ts' | head -20); do
echo "--- $f"
sed -n '1,220p' "$f"
done
echo
echo "== searches for A2A/security docs in repo =="
rg -n 'securitySchemes|security \[|AgentCard|A2A|a2a|securitySchemes|security:' apps/marketing apps/api .github README.md 2>/dev/null || trueRepository: superset-sh/superset
Length of output: 50377
🌐 Web query:
A2A Agent Card specification security securitySchemes authentication requirement v0.3.0
💡 Result:
In the A2A Agent Card specification v0.3.0, the securitySchemes and security fields are used in tandem to manage authentication, following conventions derived from the OpenAPI Specification [1][2][3]. 1. securitySchemes: This object defines the available authentication mechanisms for the agent [1][2]. It acts as a registry where each key is a unique name for a scheme, and the value is the configuration for that scheme (e.g., type: apiKey, http, oauth2, openIdConnect, or mutualTLS) [2][3][4]. No actual credentials appear in the Agent Card; it only describes the mechanisms [5]. 2. security: This array specifies the default authentication requirements for the agent [1][2][3]. Each entry in the array is an object that maps a scheme name (defined in securitySchemes) to a list of required scopes [1][2]. If multiple entries exist in the security array, they function as alternatives (an OR condition) [2]. Multiple keys within a single entry indicate that all specified schemes and scopes are required (an AND condition) [2]. If these fields are omitted from the Agent Card, the agent is considered intentionally public [5]. When authentication is required, clients are expected to authenticate requests using one of the schemes declared in these fields [6][7]. For agents supporting extended functionality (e.g., extendedAgentCard: true), these same security requirements apply to the authenticated requests used to retrieve additional capabilities [6][7][3].
Citations:
- 1: https://stacka2a.dev/learn/agent-card-spec
- 2: https://stacka2a.dev/blog/a2a-agent-card-json-schema
- 3: https://stacka2a.dev/blog/a2a-agent-card-explained
- 4: https://github.com/inference-gateway/schemas/blob/main/a2a/a2a-schema.yaml
- 5: https://www.agentcard.net/agent-card-schema
- 6: https://github.com/a2aproject/A2A/blob/main/docs/specification.md
- 7: https://github.com/google/A2A/blob/main/docs/specification.md
🏁 Script executed:
#!/bin/bash
set -euo pipefail
TARGET='apps/marketing/src/app/.well-known/agent-card.json/route.ts'
echo "== target file length =="
wc -l "$TARGET"
echo
echo "== relevant target lines =="
sed -n '1,120p' "$TARGET" | cat -n
echo
echo "== api route matching lines =="
rg -n -C 6 'API_KEY|api keys|apiKey|Authorization|Bearer|securitySchemes|security \[|AgentCard' apps/api apps/marketing/src/app/.well-known/agent-card.json/route.tsRepository: superset-sh/superset
Length of output: 30054
Declare the MCP authentication requirement.
This card only defines securitySchemes, but omitted security signals an intentionally public Agent Card. The API route also advertises MCP authentication because requests without a valid bearer/API key return 401.
Proposed fix
securitySchemes: {
oauth2: {
// ...
},
},
+ security: [
+ { oauth2: ["openid", "profile", "email", "offline_access"] },
+ { supersetApiKey: [] },
+ ],🤖 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/src/app/.well-known/agent-card.json/route.ts` around lines 25
- 43, Update the Agent Card object containing securitySchemes to also declare
its MCP authentication requirement through the appropriate security field.
Reference the existing oauth2 scheme and preserve the current authorizationCode
flow and scope definitions.
| name: COMPANY.NAME, | ||
| url: COMPANY.MARKETING_URL, | ||
| logo: `${COMPANY.MARKETING_URL}/logo.png`, | ||
| description: "Run 10+ parallel coding agents on your machine", | ||
| sameAs: [COMPANY.GITHUB_URL, COMPANY.X_URL], | ||
| email: supportEmail, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Align structured-data claims with the rendered hero copy.
The Organization description says “10+” agents, while HERO_COPY.control.subheadline in apps/marketing/src/app/components/HeroSection/HeroSection.tsx Line [36] says “100+”. The new WebPage name at Line [216] repeats the “10+” claim. Use one approved source of truth so search engines do not receive contradictory product claims.
🤖 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/src/components/JsonLd/JsonLd.tsx` around lines 37 - 41, Align
the structured-data claims with HERO_COPY.control.subheadline by replacing the
hardcoded “10+” wording in the Organization description and new WebPage name
with the approved “100+” claim or a shared source-of-truth value. Update the
JsonLd component’s relevant fields while preserving the existing schema
structure and other metadata.
| export function HomeWebPageJsonLd() { | ||
| const schema = { | ||
| "@context": "https://schema.org", | ||
| "@type": "WebPage", | ||
| "@id": COMPANY.MARKETING_URL, | ||
| url: COMPANY.MARKETING_URL, | ||
| name: `${COMPANY.NAME} — Run 10+ parallel coding agents on your machine`, | ||
| isPartOf: { | ||
| "@type": "WebSite", | ||
| name: COMPANY.NAME, | ||
| url: COMPANY.MARKETING_URL, | ||
| }, | ||
| speakable: { | ||
| "@type": "SpeakableSpecification", | ||
| cssSelector: ["h1", "#hero-subheadline"], | ||
| }, | ||
| }; | ||
|
|
||
| return <JsonLdScript schema={schema} />; | ||
| } | ||
|
|
||
| export function ServiceJsonLd() { | ||
| const schema = { | ||
| "@context": "https://schema.org", | ||
| "@type": "Service", | ||
| name: `${COMPANY.NAME} agent orchestration`, | ||
| serviceType: "AI coding agent orchestration platform", | ||
| description: | ||
| "Run and orchestrate parallel AI coding agents (Claude Code, Codex, OpenCode, and any CLI agent) in isolated Git worktrees, with diff review, persistent terminals, scheduled automations, and an MCP server for programmatic control.", | ||
| provider: { | ||
| "@type": "Organization", | ||
| name: COMPANY.NAME, | ||
| url: COMPANY.MARKETING_URL, | ||
| }, | ||
| url: COMPANY.MARKETING_URL, | ||
| offers: { | ||
| "@type": "Offer", | ||
| price: "0", | ||
| priceCurrency: "USD", | ||
| }, | ||
| }; | ||
|
|
||
| return <JsonLdScript schema={schema} />; | ||
| } | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Keep each new component in its own component file.
HomeWebPageJsonLd and ServiceJsonLd are added to JsonLd.tsx, which now contains multiple components. Move them into HomeWebPageJsonLd/HomeWebPageJsonLd.tsx and ServiceJsonLd/ServiceJsonLd.tsx, with colocated index.ts files, while preserving the barrel exports.
As per coding guidelines, “Use one folder per component with ComponentName/ComponentName.tsx and index.ts; keep one component per file.”
🤖 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/src/components/JsonLd/JsonLd.tsx` around lines 210 - 254, Move
HomeWebPageJsonLd and ServiceJsonLd out of JsonLd.tsx into separate
HomeWebPageJsonLd/HomeWebPageJsonLd.tsx and ServiceJsonLd/ServiceJsonLd.tsx
component files, adding colocated index.ts files for each. Preserve their
existing schemas and behavior, and update the existing barrel exports so both
components remain publicly available.
Source: Coding guidelines
| .replace(/<[A-Z]\w*\b[^>]*\/>/g, "") | ||
| .replace(/<[A-Z]\w*\b[^>]*>[\s\S]*?<\/[A-Z]\w*>/g, "") |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Preserve text inside MDX wrapper components.
Line 16 removes the entire component body, so callouts, tabs, or other wrappers containing prose disappear from /llms-full.txt and Markdown twins. Strip the tags while retaining children.
Proposed fix
- .replace(/<[A-Z]\w*\b[^>]*>[\s\S]*?<\/[A-Z]\w*>/g, "")
+ .replace(/<([A-Z]\w*)\b[^>]*>([\s\S]*?)<\/\1>/g, "$2")📝 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.
| .replace(/<[A-Z]\w*\b[^>]*\/>/g, "") | |
| .replace(/<[A-Z]\w*\b[^>]*>[\s\S]*?<\/[A-Z]\w*>/g, "") | |
| .replace(/<[A-Z]\w*\b[^>]*\/>/g, "") | |
| .replace(/<([A-Z]\w*)\b[^>]*>([\s\S]*?)<\/\1>/g, "$2") |
🤖 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/src/lib/llms.ts` around lines 15 - 16, Update the
component-removal logic in the LLM text transformation chain to strip MDX
wrapper opening and closing tags while preserving their inner text, instead of
deleting the entire matched body. Keep the existing self-closing component
removal behavior, and ensure nested or multiline wrapper content remains
available in the generated outputs.
| function acceptsMarkdown(request: NextRequest): boolean { | ||
| const accept = request.headers.get("accept") ?? ""; | ||
| return accept.includes("text/markdown"); | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Honor q=0 Markdown refusals.
Line 7 treats Accept: text/markdown;q=0, text/html as Markdown-capable, even though the client explicitly rejects that representation.
Proposed fix
function acceptsMarkdown(request: NextRequest): boolean {
- const accept = request.headers.get("accept") ?? "";
- return accept.includes("text/markdown");
+ return (request.headers.get("accept") ?? "")
+ .split(",")
+ .some((entry) => {
+ const [mediaType, ...params] = entry.trim().toLowerCase().split(";");
+ const quality = params.find((param) => param.trim().startsWith("q="));
+ return (
+ mediaType === "text/markdown" &&
+ (quality === undefined || Number(quality.trim().slice(2)) > 0)
+ );
+ });
}📝 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.
| function acceptsMarkdown(request: NextRequest): boolean { | |
| const accept = request.headers.get("accept") ?? ""; | |
| return accept.includes("text/markdown"); | |
| } | |
| function acceptsMarkdown(request: NextRequest): boolean { | |
| return (request.headers.get("accept") ?? "") | |
| .split(",") | |
| .some((entry) => { | |
| const [mediaType, ...params] = entry.trim().toLowerCase().split(";"); | |
| const quality = params.find((param) => param.trim().startsWith("q=")); | |
| return ( | |
| mediaType === "text/markdown" && | |
| (quality === undefined || Number(quality.trim().slice(2)) > 0) | |
| ); | |
| }); | |
| } |
🤖 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/src/proxy.ts` around lines 5 - 8, Update acceptsMarkdown to
parse the Accept header’s media ranges and reject text/markdown entries with
q=0, including parameterized values such as text/markdown;q=0. Preserve Markdown
acceptance for entries with a positive or unspecified quality value, while
continuing to return false when Markdown is not accepted.
|
|
||
| | Change | Where | Growth | Debt | | ||
| |---|---|---|---| | ||
| | llms.txt: when-to-use + developer-resource index (MCP, OpenAPI, auth.md, CLI, SDK) | `marketing/src/lib/llms.ts` + routes | **High** — the primary agent entry point; names every resource for name-based search | Low — built from constants + content dirs | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the stale OpenAPI reference.
The shipped table says llms.txt indexes OpenAPI, but line 23 says /openapi.json was deliberately removed, and the current apps/marketing/src/lib/llms.ts resource list exposes API docs/MCP instead. Update this row so the completed plan does not document a nonexistent surface.
Suggested correction
-| llms.txt: when-to-use + developer-resource index (MCP, OpenAPI, auth.md, CLI, SDK) | ...
+| llms.txt: when-to-use + developer-resource index (MCP, API docs, auth.md, CLI, SDK) | ...📝 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.
| | llms.txt: when-to-use + developer-resource index (MCP, OpenAPI, auth.md, CLI, SDK) | `marketing/src/lib/llms.ts` + routes | **High** — the primary agent entry point; names every resource for name-based search | Low — built from constants + content dirs | | |
| | llms.txt: when-to-use + developer-resource index (MCP, API docs, auth.md, CLI, SDK) | `marketing/src/lib/llms.ts` + routes | **High** — the primary agent entry point; names every resource for name-based search | Low — built from constants + content dirs | |
🤖 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 `@plans/done/20260722-agent-readiness.md` at line 11, Update the llms.txt row
in the completed plan to remove the stale OpenAPI reference and describe only
the currently exposed API docs/MCP resources, matching the resource list in
llms.ts. Preserve the row’s existing scope and formatting.
Round 2 (after 70/100 rescan, targeting >85)
Still deliberately skipped: MCP Apps |
Links
plans/done/20260722-agent-readiness.mdSummary
.well-known, an agent auth walkthrough wired into the OAuth metadata, and structured JSON API errors.Why / Context
An orank agent-readiness scan graded superset.sh 59/100: agents landing on the site couldn't get markdown, couldn't discover the MCP server from well-known paths, couldn't learn the auth flow without reading human docs, and got HTML error pages from the API. This PR closes the codebase-fixable gaps; external items (Wikipedia entity, ChatGPT directory, skills.sh publishing) are listed in the plan doc.
How It Works
Marketing (superset.sh)
src/lib/llms.tsis the single builder behindllms.txt/llms.md— adds "When to use Superset" and a developer-resource index (MCP server, auth.md, CLI, SDK, scoped llms.txt files).proxy.ts(Next 16) rewrites.md-suffixed blog/compare URLs to a markdown route, servesAccept: text/markdownnegotiation on/and content pages, and/?mode=agent. Markdown twins derive from the same MDX sources (/md/[...path]strips frontmatter/JSX)./index.md,/agents.md,/auth.md(WorkOS auth.md convention: Discover → Register → Claim → Use → Errors → Revocation, all real endpoints).robots.txtroute (replacesrobots.ts): explicit allows for AI search/user agents, blocks CCBot/Bytespider,Content-Signalline..well-known/: A2A agent card (honest — states we speak MCP, not A2A), MCP discovery + server card, RFC 9727 api-catalog. RFC 8288Linkheaders on/.API (api.superset.sh)
/.well-known/mcp+/.well-known/mcp/server-card.json: card introspects the running mcp-v2 server via an in-memory MCP client (tools/list), so the 27-tool catalog can never drift from code. Marketing proxies this card with a static fallback.agent_authblock (skill → auth.md, register/revocation URIs read from better-auth's own metadata). PRM gainsresource_documentation./apiroot returns 401 JSON with spec-shapedWWW-Authenticate: Bearer resource_metadata=...; unmatched/api/*paths return JSON 404s with hints instead of the Next HTML 404.Docs (docs.superset.sh)
/llms.txtpage index (docs already had/llms-full.txtand per-page/llms.mdx/*).Manual QA Checklist
Validated locally against dev servers of all three apps, plus production builds (
next build && next start) of marketing and api:llms.txt,llms.md,index.md,agents.md,auth.md,robots.txtserve 200 with correct content-types (text/markdownwhere applicable)Accept: text/markdownon/and blog/compare pages returns markdown withVary: Accept; plain requests still get HTML;/blog/llms.txtnot hijacked by negotiation/blog/<slug>.mdand/compare/<slug>.mdtwins return frontmatter-stripped markdown; bad slugs 404/?mode=agentreturns the agent view.well-knownroutes: agent-card, mcp, server-card (27 tools introspected), api-catalog withapplication/linkset+json;profile=...content-typeagent_auth; PRM carriesresource_documentation; existing fields unchanged/api→ 401 JSON +WWW-Authenticate;/api/v1→ JSON 404; real routes not shadowed (MCP endpoint still 401s correctly, better-auth register still responds)/llms.txtlists all pagesTesting
bun run typecheck(marketing, api, docs)bun run lint(exits 0)bun run build(marketing + api production builds pass)Design Decisions
tools/liston the running server; zero drift, no duplicated descriptions./openapi.json(shipped mid-branch, then reverted): our API is JSON-RPC over one endpoint, so an OpenAPI spec reduces to a single generic operation no function-calling framework can use.service-desclinks point at the MCP server card instead. Forfeits ~7-9 scanner points deliberately./v1,/v2), Web Bot Auth key directory (keys nothing signs with). Details in the plan doc.ai-train=yes: being in training data helps LLMs recommend Superset; CCBot/Bytespider blocked as bulk scrapers.Known Limitations
Vary: Accept— Next.js owns the Vary header for HTML routes and drops middleware/config overrides (verified innext start). Markdown responses do carry it;/renders dynamically so cache-poisoning risk is low.agent_authintentionally omits the draft-specidentity_types_supportedceremony we don't implement.Risks / Rollout
proxy.tsruns on/,/blog/:slug,/compare/:slug. Matcher is narrow and pass-through by default; segments with extensions are excluded from negotiation./api/*JSON 404 catch-all answers previously-HTML 404s; defined routes always win, verified live routes unaffected.Summary by cubic
Makes superset.sh discoverable and usable by agents. Adds markdown twins and content negotiation,
.well-knownMCP discovery with a live server card, anauth.mdwalkthrough wired into OAuth metadata, and JSON API errors./index.md,/agents.md,/auth.md),.mdtwins andAccept: text/markdownnegotiation (/?mode=agent); discovery at/.well-known(MCP registry + live server card with static fallback,agent-card.json, RFC 9727api-catalog, Link headers on/); rebuiltllms.txtand newllms.md; updatedrobots.txtto welcome AI crawlers; richer Organization/WebPage/Service JSON‑LD and contact info./.well-known/mcpand a server card that introspects the running@superset/mcp-v2server; OAuth metadata addsagent_authand PRM addsresource_documentation;/apinow returns spec-shaped401withWWW-Authenticateand JSON404with hints./llms.txtindex of pages.Written for commit d9a66fa. Summary will update on new commits.
Summary by CodeRabbit