Skip to content

feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata - #5910

Merged
saddlepaddle merged 3 commits into
mainfrom
improve-agent-readiness
Jul 24, 2026
Merged

saddlepaddle merged 3 commits into
mainfrom
improve-agent-readiness

Conversation

@saddlepaddle

@saddlepaddle saddlepaddle commented Jul 24, 2026 •

Copy link
Copy Markdown
Collaborator

Links

Summary

  • Make superset.sh discoverable and usable by AI agents: markdown surfaces for every content page, MCP server discovery via .well-known, an agent auth walkthrough wired into the OAuth metadata, and structured JSON API errors.
  • Everything machine-readable is either generated from existing constants/content or introspected from the live MCP server — no hand-maintained catalogs.

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.ts is the single builder behind llms.txt/llms.md — adds "When to use Superset" and a developer-resource index (MCP server, auth.md, CLI, SDK, scoped llms.txt files).
  • New proxy.ts (Next 16) rewrites .md-suffixed blog/compare URLs to a markdown route, serves Accept: text/markdown negotiation on / and content pages, and /?mode=agent. Markdown twins derive from the same MDX sources (/md/[...path] strips frontmatter/JSX).
  • Static agent surfaces: /index.md, /agents.md, /auth.md (WorkOS auth.md convention: Discover → Register → Claim → Use → Errors → Revocation, all real endpoints).
  • robots.txt route (replaces robots.ts): explicit allows for AI search/user agents, blocks CCBot/Bytespider, Content-Signal line.
  • .well-known/: A2A agent card (honest — states we speak MCP, not A2A), MCP discovery + server card, RFC 9727 api-catalog. RFC 8288 Link headers on /.
  • JSON-LD: Organization gains contactPoint/address/sameAs; homepage gains WebPage speakable + Service. Contact page gains direct-channel prose.

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.
  • AS metadata (RFC 8414) gains an agent_auth block (skill → auth.md, register/revocation URIs read from better-auth's own metadata). PRM gains resource_documentation.
  • /api root returns 401 JSON with spec-shaped WWW-Authenticate: Bearer resource_metadata=...; unmatched /api/* paths return JSON 404s with hints instead of the Next HTML 404.

Docs (docs.superset.sh)

  • /llms.txt page index (docs already had /llms-full.txt and 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.txt serve 200 with correct content-types (text/markdown where applicable)
  • Accept: text/markdown on / and blog/compare pages returns markdown with Vary: Accept; plain requests still get HTML; /blog/llms.txt not hijacked by negotiation
  • /blog/<slug>.md and /compare/<slug>.md twins return frontmatter-stripped markdown; bad slugs 404
  • /?mode=agent returns the agent view
  • .well-known routes: agent-card, mcp, server-card (27 tools introspected), api-catalog with application/linkset+json;profile=... content-type
  • AS metadata carries agent_auth; PRM carries resource_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)
  • Homepage renders all JSON-LD types (Organization/ContactPoint/PostalAddress/Service/WebPage/Speakable/FAQPage)
  • docs /llms.txt lists all pages

Testing

  • bun run typecheck (marketing, api, docs)
  • bun run lint (exits 0)
  • bun run build (marketing + api production builds pass)

Design Decisions

  • Live introspection over a static tool catalog: the server card builds from tools/list on the running server; zero drift, no duplicated descriptions.
  • Dropped a hand-authored /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-desc links point at the MCP server card instead. Forfeits ~7-9 scanner points deliberately.
  • Also dropped: NLWeb schemamap (unverifiable format), 401 stubs at nonexistent paths (/v1, /v2), Web Bot Auth key directory (keys nothing signs with). Details in the plan doc.
  • robots ai-train=yes: being in training data helps LLMs recommend Superset; CCBot/Bytespider blocked as bulk scrapers.

Known Limitations

  • Homepage HTML variant can't carry Vary: Accept — Next.js owns the Vary header for HTML routes and drops middleware/config overrides (verified in next start). Markdown responses do carry it; / renders dynamically so cache-poisoning risk is low.
  • Marketing's server-card proxies the api card at request time (1h revalidate) with a static fallback until the api deploy is live.
  • agent_auth intentionally omits the draft-spec identity_types_supported ceremony we don't implement.

Risks / Rollout

  • Risk: new marketing proxy.ts runs on /, /blog/:slug, /compare/:slug. Matcher is narrow and pass-through by default; segments with extensions are excluded from negotiation.
  • Risk: /api/* JSON 404 catch-all answers previously-HTML 404s; defined routes always win, verified live routes unaffected.
  • Rollback: revert the PR — all changes are additive routes/headers; no data or schema changes.

Summary by cubic

Makes superset.sh discoverable and usable by agents. Adds markdown twins and content negotiation, .well-known MCP discovery with a live server card, an auth.md walkthrough wired into OAuth metadata, and JSON API errors.

  • New Features
    • Marketing: machine-readable markdown pages (/index.md, /agents.md, /auth.md), .md twins and Accept: text/markdown negotiation (/?mode=agent); discovery at /.well-known (MCP registry + live server card with static fallback, agent-card.json, RFC 9727 api-catalog, Link headers on /); rebuilt llms.txt and new llms.md; updated robots.txt to welcome AI crawlers; richer Organization/WebPage/Service JSON‑LD and contact info.
    • API: /.well-known/mcp and a server card that introspects the running @superset/mcp-v2 server; OAuth metadata adds agent_auth and PRM adds resource_documentation; /api now returns spec-shaped 401 with WWW-Authenticate and JSON 404 with hints.
    • Docs: new /llms.txt index of pages.

Written for commit d9a66fa. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • New Features
    • Added machine-readable MCP and agent discovery endpoints, including server cards, API catalogs, and authentication metadata.
    • Added Markdown and plain-text resources for AI-readable documentation, blog posts, comparisons, and site content.
    • Added OAuth guidance, agent capabilities documentation, and clearer authentication responses.
    • Added crawler directives, structured data, and improved contact information on the marketing site.
  • Improvements
    • Added content negotiation for Markdown responses and resilient MCP server-card delivery.
    • Added consistent public caching and cross-origin access for discovery resources.

…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
@coderabbitai

coderabbitai Bot commented Jul 24, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds 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.

Changes

API discovery and authentication

Layer / File(s) Summary
MCP and OAuth metadata
apps/api/src/app/.well-known/..., apps/api/src/lib/agent-auth-metadata.ts
MCP discovery and tool-card routes are added, OAuth metadata gains agent_auth and documentation fields, and API authorization responses expose OAuth resource hints.
API fallback responses
apps/api/src/app/api/...
Unmatched API methods return structured 404 responses, while the base API route returns structured 401 responses with WWW-Authenticate metadata.

Marketing discovery and content surfaces

Layer / File(s) Summary
Discovery documents
apps/marketing/src/app/.well-known/..., apps/marketing/next.config.ts
Agent-card, MCP, API-catalog, fallback server-card, and homepage Link metadata are added.
Markdown generation and routes
apps/marketing/src/lib/llms.ts, apps/marketing/src/app/..., apps/docs/src/app/llms.txt/route.ts
Shared Markdown builders, documentation indexes, authentication and agent guides, content indexes, and dynamic blog/comparison Markdown routes are added.
Content negotiation
apps/marketing/src/proxy.ts
Requests negotiate Markdown through Accept, agent mode rewrites the homepage, and .md twin URLs resolve to Markdown content.

Site metadata and documentation

Layer / File(s) Summary
Crawler and structured metadata
apps/marketing/src/app/robots.txt/route.ts, apps/marketing/src/components/JsonLd/*, apps/marketing/src/app/page.tsx
Robots directives, organization contact data, homepage and service JSON-LD, and a homepage subheadline selector are added.
Marketing contact content
apps/marketing/src/app/contact/page.tsx
The contact page gains support, issue-reporting, community, status, and trust links.
Readiness record
plans/done/20260722-agent-readiness.md
The shipped changes, dropped items, external actions, and Markdown negotiation caveat are documented.

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
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 2.78% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title is specific, conventional, and matches the main agent-readiness changes across marketing, API, and docs.
Description check ✅ Passed The description covers what changed, why, how it was tested, and includes detailed QA/testing notes, with only minor template-format differences.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch improve-agent-readiness

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Jul 24, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 win

Keep advertised OAuth scopes synchronized.

apps/api/src/app/.well-known/oauth-protected-resource/route.ts derives scopes_supported from 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

📥 Commits

Reviewing files that changed from the base of the PR and between f1bce64 and d9a66fa.

📒 Files selected for processing (34)
  • apps/api/src/app/.well-known/mcp/route.ts
  • apps/api/src/app/.well-known/mcp/server-card.json/route.ts
  • apps/api/src/app/.well-known/oauth-authorization-server/[...path]/route.ts
  • apps/api/src/app/.well-known/oauth-authorization-server/route.ts
  • apps/api/src/app/.well-known/oauth-protected-resource/[...path]/route.ts
  • apps/api/src/app/.well-known/oauth-protected-resource/route.ts
  • apps/api/src/app/api/[...unmatched]/route.ts
  • apps/api/src/app/api/route.ts
  • apps/api/src/lib/agent-auth-metadata.ts
  • apps/docs/src/app/llms.txt/route.ts
  • apps/marketing/next.config.ts
  • apps/marketing/src/app/.well-known/agent-card.json/route.ts
  • apps/marketing/src/app/.well-known/api-catalog/route.ts
  • apps/marketing/src/app/.well-known/mcp/route.ts
  • apps/marketing/src/app/.well-known/mcp/server-card.json/route.ts
  • apps/marketing/src/app/agents.md/route.ts
  • apps/marketing/src/app/auth.md/route.ts
  • apps/marketing/src/app/blog/llms.txt/route.ts
  • apps/marketing/src/app/compare/llms.txt/route.ts
  • apps/marketing/src/app/components/HeroSection/HeroSection.tsx
  • apps/marketing/src/app/contact/page.tsx
  • apps/marketing/src/app/index.md/route.ts
  • apps/marketing/src/app/llms-full.txt/route.ts
  • apps/marketing/src/app/llms.md/route.ts
  • apps/marketing/src/app/llms.txt/route.ts
  • apps/marketing/src/app/md/[...path]/route.ts
  • apps/marketing/src/app/page.tsx
  • apps/marketing/src/app/robots.ts
  • apps/marketing/src/app/robots.txt/route.ts
  • apps/marketing/src/components/JsonLd/JsonLd.tsx
  • apps/marketing/src/components/JsonLd/index.ts
  • apps/marketing/src/lib/llms.ts
  • apps/marketing/src/proxy.ts
  • plans/done/20260722-agent-readiness.md
💤 Files with no reviewable changes (1)
  • apps/marketing/src/app/robots.ts

Comment on lines +7 to +10
const server = createMcpServer();
const [serverTransport, clientTransport] =
InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 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.

Comment on lines +14 to +15
const { tools } = await client.listTools();
return tools.map((tool) => ({

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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);
JS

Repository: 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);
JS

Repository: 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:


🌐 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:


🌐 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:


🌐 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:


🏁 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"
done

Repository: 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.

Comment on lines +11 to +20
"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}`;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.

Suggested change
"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.

Comment on lines +7 to +23
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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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 -200

Repository: 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:


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.

Comment on lines +25 to +43
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",
},
},
},
},
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 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 || true

Repository: 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:


🏁 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.ts

Repository: 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.

Comment on lines 37 to +41
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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ 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.

Comment on lines +210 to +254
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} />;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 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

Comment on lines +15 to +16
.replace(/<[A-Z]\w*\b[^>]*\/>/g, "")
.replace(/<[A-Z]\w*\b[^>]*>[\s\S]*?<\/[A-Z]\w*>/g, "")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.

Suggested change
.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.

Comment on lines +5 to +8
function acceptsMarkdown(request: NextRequest): boolean {
const accept = request.headers.get("accept") ?? "";
return accept.includes("text/markdown");
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.

Suggested change
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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 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.

Suggested change
| 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.

@saddlepaddle
saddlepaddle merged commit 6b2e907 into main Jul 24, 2026
18 checks passed
@saddlepaddle

Copy link
Copy Markdown
Collaborator Author

Round 2 (after 70/100 rescan, targeting >85)

  • Docs MCP server: docs.superset.sh/mcp now speaks MCP — docs_search + docs_read over the live fumadocs source, stateless Streamable HTTP, no auth (public read-only content). The docs page moved to /mcp-server; browser GETs 308-redirect, so old links keep working. Verified initialize/tools-list/tools-call locally + prod build.
  • Reinstated /openapi.json (revert of the drop): the rescan revealed ~16 pts hang off it (spec 7, new scoped-permissions 5, schema complexity 2, function calling 2 — they read securitySchemes/operations from the spec). Same protocol-stable scope as before; tools still self-described via tools/list.
  • agent_auth completed with identity_types_supported: ["anonymous"] + per-type block — "anonymous DCR, user claims via browser consent" accurately describes our flow.
  • /mcp alias on api.superset.sh (re-export of the v2 handler) + superset.sh/mcp 307 redirect.
  • Smaller: /api/llms.txt (+robots carve-out), .md twins + Accept negotiation extended to changelog, applicationSubCategory: "Developer Tools" in JSON-LD.

Still deliberately skipped: MCP Apps ui:// / A2UI (real product feature, ~6 pts), Web Bot Auth, NLWeb, sandbox, AggregateRating. Remaining points above ~90 are external actions (Wikipedia/Wikidata, skills.sh npx skills add, ChatGPT directory, PyPI SDK).

This branch was previously deployed

1 inactive deployment
preview — d9a66fa5 Deployed Jul 24, 2026 by saddlepaddle via Deploy Admin #6811
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant