docs(integrations): add 'Popular use cases' to the MCP Servers browse page - #1109
Merged
Conversation
…se page The integrations index page previously rendered only a client-side <Toolkits /> component with no server text, so Algolia had nothing to index for terms like "toolkits", "finance", "stock", "market data", "vector search", or the category names. This week's report showed 10 zero-hit queries, several of which point directly at this gap. Add a short intro plus a Categories list naming each category, key toolkits, and useful cross-references (Google Finance for stock quotes and market data, Weaviate for vector/semantic search, the GitHub API toolkit for code and secret scanning alerts). Content is Nextra MDX so it renders into the same page above <Toolkits />.
A user searching Algolia for "custom user verifier verification route
user_mismatch" returned zero hits this week even though the concept page
exists. The docs describe the failure case ("the user's ID does not
match") but never use the phrase the user typed. Adding "user mismatch"
inline gives Algolia a token to match on without inventing an API error
code that isn't documented elsewhere.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
teallarson
marked this pull request as draft
August 3, 2026 14:45
EricGustin
approved these changes
Aug 3, 2026
…ction Review feedback: my first pass on this page was a wall of bullet-linked prose that duplicated <Toolkits /> below and was really just there to plant search keywords. Drop it. Replace with a short honest intro plus a 'Popular use cases' section: five jobs-to-be-done (coding agent, sales copilot, research/RAG, financial workflows, customer support automation), each with 3-4 real linked toolkits. This is the entry point a first-time visitor actually needs, and it still surfaces the high-signal terms from this week's zero-hit queries (semantic search, stock quotes / market data, secret scanning) in prose that a human wants to read. Algolia will still miss those terms on the individual toolkit detail pages until we improve their descriptions at the source (design-system upstream, or wire in a committed custom-sections overrides file). That work lands in a follow-up; see the PR body.
On reflection, the earlier edit was a keyword patch for one zero-hit query, not a real docs improvement — "user_mismatch" is an API error code that isn't documented anywhere else, and inventing a phrase to match a search term is the wrong reason to change docs. Restoring the original wording. If the API does return a specific machine-readable error code for this case, the durable fix is to document that code in the REST tab of the 'Invalid Response' example, not to plant it in prose. Filing as a follow-up rather than doing it half-right here.
teallarson
changed the title
My previous intro said "Arcade ships every integration as both a toolkit for the Arcade Engine and an MCP server" and "100+ services". Both wrong: - The site's own about-arcade page says "7,500+ agent-optimized tools across 81 MCP servers", and the glossary frames MCP as *how* Arcade tools are surfaced, not as a parallel form. There is no "toolkit-and-also-MCP-server" duality being asserted anywhere else in the docs. - The 118 JSON files in toolkit-docs-generator include arcade_starter and community entries not counted in the official 81. Using "100+" contradicts the site's own number, and hardcoding "81" would go stale, so drop the count entirely. Rewritten intro uses "MCP server" consistently (matches STYLEGUIDE.md and the page title), doesn't editorialize on the toolkit/MCP relationship, and doesn't invent stats. Popular use cases section is unchanged.
…rror case Restoring the earlier edit. Naming the failure condition helps a reader who hits it or is searching for it — which is a legitimate docs improvement, independent of the search-relevance angle I originally talked myself out of it on.
teallarson
marked this pull request as ready for review
August 3, 2026 20:00
vfanelle
approved these changes
Aug 3, 2026
Contributor
There was a problem hiding this comment.
I don't think category tags should be the first filter for finding toolkits. Most people arrive already knowing the job or toolkit they want. The new popular-use-cases section fits that behavior better than our current categories, so let's try it. Longer term, we should improve or drop the category filter, whatever gets users to the right toolkit fastest.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Algolia weekly report for Jul 27 - Aug 02 had a 17.27% no-result rate. Most of the 10 zero-hit queries landed on
/en/resources/integrations, which was 8 lines — frontmatter plus a client-side<Toolkits />catalog — with no entry-point content for someone landing cold.This PR:
app/en/resources/integrations/page.mdx. The<Toolkits />catalog still renders below.app/en/guides/user-facing-agents/secure-auth-production/page.mdx. Useful for a reader who hits or searches for that condition, independent of any search-relevance angle.What this fixes and what it doesn't
Fixes:
available toolkits list ...variants — the browse page now has real server-rendered content.market data stock quotes finance toolkit— Financial workflows bullet points at Google Finance with those words.semantic search— Research and RAG bullet describes Weaviate as "vector and semantic search over embeddings".github toolkit tool list secret scanning code scanning alerts— Coding agent bullet calls out the GitHub API MCP server's code-scanning and secret-scanning coverage.custom user verifier verification route user_mismatch— concept page now names "user mismatch" as the failure condition.Not fixed here (follow-ups):
alpaca stock trading market data toolkit— no Alpaca MCP server exists. Product/roadmap call, not a docs fix.gdpr ukandprivacy concern— no UK GDPR or privacy overview pages exist. Editorial call; recommend filing separate issues rather than papering over with keywords.user source oidc identity provider setup redirect uri— strong content already exists atapp/en/guides/user-sources/. Likely a tokenization edge case; recommend re-checking in the next report before adding keyword bloat.Bigger follow-up (not in this PR):
Most of the search relevance work should really happen at the individual MCP server's description layer, not on the browse page. Detail pages render the JSON's top-level
descriptionas<p>(seeapp/_components/toolkit-docs/components/toolkit-header.tsx:161), and Algolia's crawler already indexesarticle p. A better Weaviate description ("vector database for semantic search over embeddings") onweaviateapi.jsonwould surface Weaviate directly for that query on its own page — which is where the searcher wants to land.The blocker is durability:
toolkit-docs-generator/data/toolkits/*.jsonis auto-regenerated from@arcadeai/design-system/metadata/toolkits+ the LLM enrichment pipeline. Direct JSON edits get overwritten. The generator has aCustomSectionsFileSourcemechanism (seetoolkit-docs-generator/src/sources/custom-sections-file.ts) that could layer overrides in, but nothing in this repo currently commits or points at such a file, and theCustomSectionsschema doesn't include the top-level description — only per-tool chunks and documentation chunks around it. So the durable path is either (a) fix the descriptions upstream in@arcadeai/design-system, or (b) extend the merger to accept a top-level description override and wire in a committed overrides file.Changes
app/en/resources/integrations/page.mdx— rewritten from an 8-line shell to intro + Popular use cases +<Toolkits />.app/en/guides/user-facing-agents/secure-auth-production/page.mdx— line 220 names "user mismatch" as the failure condition.Test plan
pnpm buildlocally, confirm the browse page renders and<Toolkits />still filters.pnpm vale:checkon both changed files.algolia-reindex.ymlon the production deploy (or trigger it manually) and confirm the four highest-signal queries (toolkits list,stock market data,semantic search,user mismatch) return results.Note
Low Risk
Documentation-only copy and metadata changes with no application or auth logic changes.
Overview
Adds server-rendered entry content on the MCP Servers browse page so cold landings and search have something to index beyond the client-side
<Toolkits />catalog.The page gets an updated meta description, a short intro, a Popular use cases section with five job-to-be-done bullets (linked MCP servers for coding, sales, RAG, finance, support), and a Browse all MCP servers heading before the existing catalog component.
Separately, the secure custom-verifier docs now label a failed ID match as a user mismatch in the invalid-response section, so that term appears in prose for readers and search.
Reviewed by Cursor Bugbot for commit 02733c8. Bugbot is set up for automated code reviews on this repo. Configure here.