diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000000..c879703312 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "algolia-docsearch": { + "type": "http", + "url": "https://mcp.algolia.com/1/docsearch/mcp" + } + } +} diff --git a/.cursor/rules/use-algolia-docsearch.mdc b/.cursor/rules/use-algolia-docsearch.mdc new file mode 120000 index 0000000000..d64ae41b2f --- /dev/null +++ b/.cursor/rules/use-algolia-docsearch.mdc @@ -0,0 +1 @@ +../../mcp/plugins/docsearch/cursor/algolia-docsearch/rules/use-algolia-docsearch.mdc \ No newline at end of file diff --git a/.cursor/settings.json b/.cursor/settings.json new file mode 100644 index 0000000000..0967ef424b --- /dev/null +++ b/.cursor/settings.json @@ -0,0 +1 @@ +{} diff --git a/.tool-versions b/.tool-versions index e55980b02d..c8a7bba396 100644 --- a/.tool-versions +++ b/.tool-versions @@ -1,2 +1,2 @@ -bun 1.3.10 -node 22.15.0 +bun 1.3.10 +nodejs latest diff --git a/README.md b/README.md index 8f1ca5519d..453c317bca 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,10 @@ export default App; [Read documentation →](https://docsearch.algolia.com/docs/styling) +## MCP plugins + +Client plugins for the public DocSearch MCP endpoint are in [`mcp/plugins/docsearch`](mcp/plugins/docsearch). They connect Cursor and Claude Code to `https://mcp.algolia.com/1/docsearch/mcp` for current public developer documentation. + ## Related projects DocSearch is made of the following repositories: diff --git a/mcp/README.md b/mcp/README.md new file mode 100644 index 0000000000..b2614568cf --- /dev/null +++ b/mcp/README.md @@ -0,0 +1,9 @@ +# DocSearch MCP + +Client plugin packages for the public Algolia DocSearch MCP endpoint live in [`plugins/docsearch`](plugins/docsearch). + +```text +https://mcp.algolia.com/1/docsearch/mcp +``` + +The plugins connect AI coding clients to the public DocSearch documentation corpus. They do not expose crawler operations, DocSearch administration, private documentation, or Algolia index credentials. diff --git a/mcp/plugins/docsearch/README.md b/mcp/plugins/docsearch/README.md new file mode 100644 index 0000000000..bd9a77f06f --- /dev/null +++ b/mcp/plugins/docsearch/README.md @@ -0,0 +1,71 @@ +# Algolia DocSearch MCP Plugins + +This directory contains client plugin packages for the public Algolia DocSearch MCP endpoint: + +```text +https://mcp.algolia.com/1/docsearch/mcp +``` + +The plugins connect AI coding clients to the public DocSearch documentation corpus. They do not expose crawler operations, DocSearch administration, private documentation, or Algolia index credentials. + +## Packages + +- `mcp/plugins/docsearch/cursor/algolia-docsearch` - Cursor plugin package with MCP config, rule, skill, and README. +- `mcp/plugins/docsearch/claude/algolia-docsearch` - Claude Code plugin package with MCP config, skill, command, and README. + +## Public MCP Tools + +You can query in natural language — full sentences and questions work well. + +### algolia_docsearch_search_docs + +One-shot lookup, and the right default for most questions. Pass a `library` and a `query`; it resolves the best matching documentation set and returns ranked content in a single call: + +```json +{ + "library": "Next.js", + "query": "how do middleware matchers work" +} +``` + +If the library is ambiguous, it returns candidate documentation sets instead — pick a `docset_id` and pass it to `algolia_docsearch_query_docs`. + +### algolia_docsearch_resolve_docset + +Step 1 of the manual flow. Finds matching documentation sets and returns candidates with: + +- `docset_id` +- title and description +- optional quality signals such as `trustScore`, `benchmarkScore`, and `popularityScore` + +```json +{ + "query": "Next.js app router" +} +``` + +### algolia_docsearch_query_docs + +Step 2 of the manual flow. Queries documentation content for the selected `docset_id` values. Pass several when a question spans multiple products: + +```json +{ + "query": "middleware matcher config", + "docsetIds": ["nextjs"] +} +``` + +## Claude Desktop And claude.ai + +Claude Desktop and claude.ai can connect directly to the same remote MCP endpoint when remote connectors are available in the client: + +```json +{ + "algolia-docsearch": { + "type": "http", + "url": "https://mcp.algolia.com/1/docsearch/mcp" + } +} +``` + +No user authentication is required for the public DocSearch MCP endpoint. diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/marketplace.json b/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/marketplace.json new file mode 100644 index 0000000000..1cecc6d49a --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/marketplace.json @@ -0,0 +1,15 @@ +{ + "name": "algolia-docsearch-marketplace", + "description": "Algolia DocSearch plugins for Claude Code — search up-to-date public developer documentation from the DocSearch corpus.", + "owner": { + "name": "Algolia" + }, + "plugins": [ + { + "name": "algolia-docsearch", + "source": ".", + "description": "up-to-date public developer documentation from the DocSearch corpus.", + "version": "1.0.0" + } + ] +} \ No newline at end of file diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/plugin.json b/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/plugin.json new file mode 100644 index 0000000000..81679d9b4b --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "algolia-docsearch", + "description": "Algolia DocSearch MCP plugin for searching up-to-date public developer documentation from the DocSearch corpus.", + "version": "1.0.0", + "author": { + "name": "Algolia" + } +} diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/.mcp.json b/mcp/plugins/docsearch/claude/algolia-docsearch/.mcp.json new file mode 100644 index 0000000000..6a7d1b7682 --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/.mcp.json @@ -0,0 +1,6 @@ +{ + "algolia-docsearch": { + "type": "http", + "url": "https://mcp.algolia.com/1/docsearch/mcp" + } +} diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/README.md b/mcp/plugins/docsearch/claude/algolia-docsearch/README.md new file mode 100644 index 0000000000..af5f38ebc7 --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/README.md @@ -0,0 +1,63 @@ +# Algolia DocSearch Plugin for Claude Code + +Algolia DocSearch connects Claude Code to the public DocSearch MCP endpoint for current public developer documentation. + +## What's Included + +- **MCP Server** - Connects Claude Code to `https://mcp.algolia.com/1/docsearch/mcp`. +- **Skill** - Auto-triggers documentation lookups for public developer docs questions. +- **Command** - `/algolia-docsearch:docs` for manual documentation queries. + +The plugin teaches the one-shot `search_docs` lookup and the `resolve_docset` + `query_docs` flow. + +## Installation + +For local beta testing, install this plugin package from: + +```text +mcp/plugins/docsearch/claude/algolia-docsearch +``` + +The MCP server config is also available at: + +```text +mcp/plugins/docsearch/claude/algolia-docsearch/.mcp.json +``` + +For Claude Code marketplace install from this repository: + +```text +/plugin marketplace add algolia/docsearch +/plugin install algolia-docsearch@algolia-docsearch-marketplace +``` + +## Available Tools + +### algolia_docsearch_search_docs + +One-shot lookup, and the right default for most questions. Pass a `library` (product or platform) and a `query` (the question); it resolves the best documentation set and returns ranked content in a single call. + +### algolia_docsearch_resolve_docset + +Step 1 of the manual flow. Finds matching documentation sets and returns candidates with a `docset_id`, title, description, and ranking signals. + +### algolia_docsearch_query_docs + +Step 2 of the manual flow. Queries documentation content for the `docset_id` values returned by `algolia_docsearch_resolve_docset`. Pass several `docsetIds` when a question spans multiple products. + +## Usage Examples + +Ask Claude questions like: + +- "How do I configure middleware in Next.js?" +- "Show me Stripe webhook signature verification from the docs." +- "What is the current Algolia InstantSearch React setup?" + +Or use the manual command: + +```text +/algolia-docsearch:docs Next.js middleware matcher +/algolia-docsearch:docs Stripe webhook signature verification +``` + +The plugin is for public developer documentation only. It does not expose crawler operations, DocSearch administration, private docs, or Algolia index credentials. diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/commands/docs.md b/mcp/plugins/docsearch/claude/algolia-docsearch/commands/docs.md new file mode 100644 index 0000000000..ac45f7235d --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/commands/docs.md @@ -0,0 +1,31 @@ +--- +description: Look up public developer documentation with Algolia DocSearch +argument-hint: [query] +--- + +# /algolia-docsearch:docs + +Fetch current public developer documentation from the Algolia DocSearch MCP corpus. + +## Usage + +```text +/algolia-docsearch:docs [topic] +``` + +For most lookups, call `algolia_docsearch_search_docs` in a single step: + +1. Set `library` to the product, library, or platform (use the official name). +2. Set `query` to the topic or question, in natural language. +3. Answer using the returned docs and include source URLs when available. + +If the library is ambiguous, `algolia_docsearch_search_docs` returns candidate documentation sets — pick the right `docset_id` and pass it to `algolia_docsearch_query_docs`. Use the `algolia_docsearch_resolve_docset` + `algolia_docsearch_query_docs` flow when a question spans several products. + +## Examples + +```text +/algolia-docsearch:docs Next.js middleware matcher +/algolia-docsearch:docs Stripe webhook signature verification +/algolia-docsearch:docs Algolia InstantSearch React configure search client +/algolia-docsearch:docs React Server Components data fetching +``` diff --git a/mcp/plugins/docsearch/claude/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md b/mcp/plugins/docsearch/claude/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md new file mode 100644 index 0000000000..0261def921 --- /dev/null +++ b/mcp/plugins/docsearch/claude/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md @@ -0,0 +1,72 @@ +--- +name: algolia-docsearch-mcp +description: Use this skill when the user asks about public developer documentation, SDKs, APIs, libraries, frameworks, setup, configuration, or code examples. Fetch current docs from Algolia DocSearch MCP and cite source URLs. +--- + +When the user asks about public developer documentation, use Algolia DocSearch MCP instead of relying only on training data. + +## When To Use + +Use this skill when the user: + +- Asks setup or configuration questions for a public library, framework, SDK, API, or developer tool. +- Requests code examples that should match current docs. +- Needs API reference details, migration guidance, or command syntax. +- Mentions a library or framework whose docs may have changed recently. +- Asks for sources or citations from public documentation. + +Do not use this skill for private company docs, internal repositories, unpublished APIs, or questions where the user already supplied the relevant docs. + +## Tools + +DocSearch MCP exposes three tools. You can query in natural language — full sentences and questions work well. + +- `algolia_docsearch_search_docs` — one-shot lookup. Use this by default. +- `algolia_docsearch_resolve_docset` — step 1 of the manual flow: find documentation sets. +- `algolia_docsearch_query_docs` — step 2 of the manual flow: fetch content for chosen docsets. + +## Default Flow: One-Shot Search + +Call `algolia_docsearch_search_docs` for most lookups. + +Input: + +- `library`: the product, library, SDK, or platform. Use the official name (for example: `Next.js`, `Stripe`, `Algolia InstantSearch`). +- `query`: the question, in natural language (for example: `how do middleware matchers work`). + +It resolves the best matching documentation set and returns ranked content in a single call. If `library` is ambiguous, it returns candidate documentation sets instead — pick the right one and pass its `docset_id` to `algolia_docsearch_query_docs`, or retry with the official product name. + +## Manual Flow: Resolve, Then Query + +Use the two-step flow when a question spans several products, or when you want to inspect and hand-pick documentation sets. + +### Step 1: Resolve The Docset + +Call `algolia_docsearch_resolve_docset`. + +Input: + +- `query`: describe the product, library, SDK, or platform. Including the vendor name improves matching. +- `topN`: optional. Use the default unless the initial result is ambiguous. + +Each candidate returns a `title`, `docset_id`, `description`, and ranking signals (`trustScore`, `benchmarkScore`, `popularityScore`). Prefer the official vendor's docset over third-party mentions, breaking ties by the higher scores. + +### Step 2: Query The Docs + +Call `algolia_docsearch_query_docs`. + +Input: + +- `query`: what to find in the docs, in natural language. +- `docsetIds`: an array of the `docset_id` values you selected. Pass several when a question spans multiple products. + +## Answer With Sources + +Use the returned documentation content to answer the user directly. + +Guidelines: + +- Include source URLs from the tool result when available. +- Say when DocSearch does not return a relevant result. +- Do not invent source citations. +- Keep the answer focused on the user's question. diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/.cursor-plugin/plugin.json b/mcp/plugins/docsearch/cursor/algolia-docsearch/.cursor-plugin/plugin.json new file mode 100644 index 0000000000..67e3fdd735 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/.cursor-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "algolia-docsearch", + "version": "1.0.0", + "description": "Algolia DocSearch MCP plugin for searching up-to-date public developer documentation from the DocSearch corpus.", + "author": { + "name": "Algolia" + }, + "homepage": "https://docsearch.algolia.com/docs/mcp/overview", + "keywords": ["documentation", "mcp", "algolia", "docsearch", "developer-docs"], + "logo": "assets/docsearch-monogram.svg" +} diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/README.md b/mcp/plugins/docsearch/cursor/algolia-docsearch/README.md new file mode 100644 index 0000000000..a918fb1454 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/README.md @@ -0,0 +1,47 @@ +# Algolia DocSearch Plugin for Cursor + +Algolia DocSearch connects Cursor to the public DocSearch MCP endpoint for current public developer documentation. + +## What's Included + +- **MCP Server** - Connects Cursor to `https://mcp.algolia.com/1/docsearch/mcp`. +- **Rule** - Nudges the agent to use DocSearch for public developer docs instead of guessing from training data. +- **Skill** - Documents the one-shot `search_docs` lookup and the `resolve_docset` + `query_docs` flow. + +## Installation + +For local beta testing, install this plugin package from: + +```text +mcp/plugins/docsearch/cursor/algolia-docsearch +``` + +The MCP server config is also available at: + +```text +mcp/plugins/docsearch/cursor/algolia-docsearch/mcp.json +``` + +## Available Tools + +### algolia_docsearch_search_docs + +One-shot lookup, and the right default for most questions. Pass a `library` (product or platform) and a `query` (the question); it resolves the best documentation set and returns ranked content in a single call. + +### algolia_docsearch_resolve_docset + +Step 1 of the manual flow. Finds matching documentation sets and returns candidates with a `docset_id`, title, description, and ranking signals. + +### algolia_docsearch_query_docs + +Step 2 of the manual flow. Queries documentation content for the `docset_id` values returned by `algolia_docsearch_resolve_docset`. Pass several `docsetIds` when a question spans multiple products. + +## Usage Examples + +Ask Cursor questions like: + +- "How do I configure middleware in Next.js?" +- "Show me Stripe webhook signature verification from the docs." +- "What is the current Algolia InstantSearch React setup?" + +The plugin is for public developer documentation only. It does not expose crawler operations, DocSearch administration, private docs, or Algolia index credentials. diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/assets/docsearch-monogram.svg b/mcp/plugins/docsearch/cursor/algolia-docsearch/assets/docsearch-monogram.svg new file mode 100644 index 0000000000..3ce446d230 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/assets/docsearch-monogram.svg @@ -0,0 +1 @@ + diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/mcp.json b/mcp/plugins/docsearch/cursor/algolia-docsearch/mcp.json new file mode 100644 index 0000000000..c879703312 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "algolia-docsearch": { + "type": "http", + "url": "https://mcp.algolia.com/1/docsearch/mcp" + } + } +} diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/rules/use-algolia-docsearch.mdc b/mcp/plugins/docsearch/cursor/algolia-docsearch/rules/use-algolia-docsearch.mdc new file mode 100644 index 0000000000..45d76f9d09 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/rules/use-algolia-docsearch.mdc @@ -0,0 +1,22 @@ +--- +description: Use Algolia DocSearch MCP for current public developer documentation instead of guessing from training data. +alwaysApply: true +--- + +When the user asks about public developer documentation, APIs, SDKs, libraries, frameworks, configuration, or code examples, use Algolia DocSearch MCP to fetch current documentation before answering. + +Use Algolia DocSearch when: +- The user asks about a public library, framework, SDK, API, or developer tool. +- The user needs syntax, configuration, migration, setup, or code examples from docs. +- The question may depend on recent documentation changes. +- You need source URLs to support an answer. + +Do not use Algolia DocSearch for: +- Private company docs, internal repos, or unpublished APIs. +- Questions already answered by code or docs the user provided. +- Crawler operations, DocSearch administration, or MCP server implementation details. +- General programming concepts that do not require external docs. + +For most lookups call `algolia_docsearch_search_docs` with the product as `library` and the question as `query`. Use the `algolia_docsearch_resolve_docset` + `algolia_docsearch_query_docs` flow when a question spans several products or you need to hand-pick documentation sets. Natural-language queries work well. + +See the `algolia-docsearch-mcp` skill for the full tool flow. diff --git a/mcp/plugins/docsearch/cursor/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md b/mcp/plugins/docsearch/cursor/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md new file mode 100644 index 0000000000..0261def921 --- /dev/null +++ b/mcp/plugins/docsearch/cursor/algolia-docsearch/skills/algolia-docsearch-mcp/SKILL.md @@ -0,0 +1,72 @@ +--- +name: algolia-docsearch-mcp +description: Use this skill when the user asks about public developer documentation, SDKs, APIs, libraries, frameworks, setup, configuration, or code examples. Fetch current docs from Algolia DocSearch MCP and cite source URLs. +--- + +When the user asks about public developer documentation, use Algolia DocSearch MCP instead of relying only on training data. + +## When To Use + +Use this skill when the user: + +- Asks setup or configuration questions for a public library, framework, SDK, API, or developer tool. +- Requests code examples that should match current docs. +- Needs API reference details, migration guidance, or command syntax. +- Mentions a library or framework whose docs may have changed recently. +- Asks for sources or citations from public documentation. + +Do not use this skill for private company docs, internal repositories, unpublished APIs, or questions where the user already supplied the relevant docs. + +## Tools + +DocSearch MCP exposes three tools. You can query in natural language — full sentences and questions work well. + +- `algolia_docsearch_search_docs` — one-shot lookup. Use this by default. +- `algolia_docsearch_resolve_docset` — step 1 of the manual flow: find documentation sets. +- `algolia_docsearch_query_docs` — step 2 of the manual flow: fetch content for chosen docsets. + +## Default Flow: One-Shot Search + +Call `algolia_docsearch_search_docs` for most lookups. + +Input: + +- `library`: the product, library, SDK, or platform. Use the official name (for example: `Next.js`, `Stripe`, `Algolia InstantSearch`). +- `query`: the question, in natural language (for example: `how do middleware matchers work`). + +It resolves the best matching documentation set and returns ranked content in a single call. If `library` is ambiguous, it returns candidate documentation sets instead — pick the right one and pass its `docset_id` to `algolia_docsearch_query_docs`, or retry with the official product name. + +## Manual Flow: Resolve, Then Query + +Use the two-step flow when a question spans several products, or when you want to inspect and hand-pick documentation sets. + +### Step 1: Resolve The Docset + +Call `algolia_docsearch_resolve_docset`. + +Input: + +- `query`: describe the product, library, SDK, or platform. Including the vendor name improves matching. +- `topN`: optional. Use the default unless the initial result is ambiguous. + +Each candidate returns a `title`, `docset_id`, `description`, and ranking signals (`trustScore`, `benchmarkScore`, `popularityScore`). Prefer the official vendor's docset over third-party mentions, breaking ties by the higher scores. + +### Step 2: Query The Docs + +Call `algolia_docsearch_query_docs`. + +Input: + +- `query`: what to find in the docs, in natural language. +- `docsetIds`: an array of the `docset_id` values you selected. Pass several when a question spans multiple products. + +## Answer With Sources + +Use the returned documentation content to answer the user directly. + +Guidelines: + +- Include source URLs from the tool result when available. +- Say when DocSearch does not return a relevant result. +- Do not invent source citations. +- Keep the answer focused on the user's question. diff --git a/packages/website/docs/mcp/installation.mdx b/packages/website/docs/mcp/installation.mdx new file mode 100644 index 0000000000..6f1409e98c --- /dev/null +++ b/packages/website/docs/mcp/installation.mdx @@ -0,0 +1,26 @@ +--- +title: Install DocSearch MCP +sidebar_label: Installation +--- + +import MCPInstall from '@site/src/components/mcp/MCPInstall'; + +DocSearch MCP is a remote MCP server. Point any MCP-compatible client at this endpoint — no authentication required: + +```text +https://mcp.algolia.com/1/docsearch/mcp +``` + +You can install it as a **plugin** (ships the MCP server plus client guidance like rules, skills, and commands) or **manually** (just the MCP server config). Pick your client below. + + + +## Verify the install + +Ask your MCP client a public documentation question, for example: + +```text +Use DocSearch MCP to find the current Next.js middleware matcher docs. +``` + +The client should call the DocSearch tools and answer with content from the matching documentation, ideally with source links. diff --git a/packages/website/docs/mcp/overview.mdx b/packages/website/docs/mcp/overview.mdx new file mode 100644 index 0000000000..0021b79c7f --- /dev/null +++ b/packages/website/docs/mcp/overview.mdx @@ -0,0 +1,43 @@ +--- +title: DocSearch MCP +sidebar_label: Overview +--- + +DocSearch MCP lets AI clients search current public developer documentation from the DocSearch corpus. + +Use it when you want an assistant to answer questions from public docs instead of relying only on model training data. The public endpoint does not require authentication: + +```text +https://mcp.algolia.com/1/docsearch/mcp +``` + +## What it does + +DocSearch MCP exposes documentation search through the [Model Context Protocol](https://modelcontextprotocol.io/). MCP-compatible clients connect to the endpoint and call DocSearch tools while answering your questions. + +The endpoint is focused on public developer documentation. You do not need an Algolia application ID, search API key, or DocSearch application to use it. + +## How it works + +Most lookups are a single call: name the product and ask your question, and DocSearch finds the right documentation set and returns the matching content together. + +When a question spans several products, or you want to inspect and hand-pick documentation sets first, there is a two-step flow: resolve the documentation sets, then query the ones you choose. + +## Available tools + +### `algolia_docsearch_search_docs` + +The one-shot tool, and the right default for most lookups. Give it a `library` (the product, SDK, or platform) and a `query` (your question); it resolves the best matching documentation set and returns ranked content in a single call. If the library is ambiguous, it returns candidate documentation sets to choose from instead. + +### `algolia_docsearch_resolve_docset` + +Step 1 of the manual flow. Finds the documentation sets that best match a product, library, or platform and returns candidates — each with a `docset_id`, title, description, and ranking signals to help pick the best match. + +### `algolia_docsearch_query_docs` + +Step 2 of the manual flow. Retrieves documentation content for one or more `docset_id`s returned by `algolia_docsearch_resolve_docset`. Pass several at once when a question spans multiple products. + +## Next steps + +- [Install DocSearch MCP](/docs/mcp/installation) +- [Use DocSearch MCP](/docs/mcp/usage) diff --git a/packages/website/docs/mcp/usage.mdx b/packages/website/docs/mcp/usage.mdx new file mode 100644 index 0000000000..fb7b8a9bd4 --- /dev/null +++ b/packages/website/docs/mcp/usage.mdx @@ -0,0 +1,113 @@ +--- +title: Use DocSearch MCP +sidebar_label: Usage +--- + +DocSearch MCP works best when your client knows to search public documentation before answering library, framework, API, or SDK questions. + +## Ask documentation questions + +After installation, ask your client about public developer docs in natural language: + +```text +How do I configure middleware matchers in Next.js? +``` + +```text +Show me the current Stripe webhook signature verification docs. +``` + +```text +What is the current setup for Algolia InstantSearch React? +``` + +If your client does not automatically use MCP tools, mention DocSearch MCP explicitly: + +```text +Use DocSearch MCP to look up React Server Components data fetching. +``` + +## Use the Claude Code command + +The Claude Code plugin includes a manual command: + +```text +/algolia-docsearch:docs [topic] +``` + +Examples: + +```text +/algolia-docsearch:docs Next.js middleware matcher +/algolia-docsearch:docs Stripe webhook signature verification +/algolia-docsearch:docs Algolia InstantSearch React configure search client +``` + +## Tool flow + +DocSearch MCP exposes three tools. Most of the time the client only needs the one-shot tool; the two-step flow is for multi-product questions or when you want to hand-pick documentation sets. + +You can ask in natural language — full sentences and questions work well. For the one-shot tool, keep `library` to the product name and put the actual question in `query`. + +### One-shot: `algolia_docsearch_search_docs` + +The client names the product and asks the question in a single call: + +```json +{ + "library": "Next.js", + "query": "how do middleware matchers work" +} +``` + +It returns ranked documentation content for the best matching set. If the library is ambiguous, it returns candidate documentation sets instead so the client can pick one and fall back to `algolia_docsearch_query_docs`. + +### Two-step: resolve, then query + +For questions that span several products, or when the client wants to choose documentation sets explicitly: + +1. `algolia_docsearch_resolve_docset` finds documentation sets: + +```json +{ + "query": "Next.js app router" +} +``` + +It returns candidates, each with a `docset_id`. + +2. `algolia_docsearch_query_docs` retrieves content for the chosen `docset_id`(s): + +```json +{ + "query": "middleware matcher config", + "docsetIds": ["nextjs"] +} +``` + +Pass multiple `docsetIds` when a question spans more than one product. + +## Tips + +- Be specific about the product and topic you want. +- Include a version when it matters. +- Ask for source URLs if you want the client to show where the answer came from. +- If the first result is too broad, ask for a narrower topic. + +## Troubleshooting + +### The client does not call DocSearch MCP + +Make sure the MCP server is enabled in your client and named `algolia-docsearch`. If you installed the plugin, check that the plugin is enabled too. + +### The result is about the wrong product + +Ask again with the official product name. For the one-shot tool, set `library` to the vendor's product name (for example, `Algolia InstantSearch` rather than `search`). + +### The client cannot connect + +Confirm that your client supports remote HTTP MCP servers and that the configured URL is: + +```text +https://mcp.algolia.com/1/docsearch/mcp +``` diff --git a/packages/website/docusaurus.config.mjs b/packages/website/docusaurus.config.mjs index 8414777bb6..b32cb9ab34 100644 --- a/packages/website/docusaurus.config.mjs +++ b/packages/website/docusaurus.config.mjs @@ -111,6 +111,11 @@ export default { to: 'docs/what-is-docsearch', position: 'left', }, + { + label: 'MCP', + to: 'docs/mcp/overview', + position: 'left', + }, { label: 'Playground', to: 'https://community.algolia.com/docsearch-playground/', diff --git a/packages/website/sidebars.js b/packages/website/sidebars.js index a708f51620..8f4c565369 100644 --- a/packages/website/sidebars.js +++ b/packages/website/sidebars.js @@ -21,6 +21,11 @@ export default { label: 'DocSearch v4', items: ['docsearch', 'docusaurus-adapter', 'composable-api', 'styling', 'api', 'examples', 'migrating-from-v3'], }, + { + type: 'category', + label: 'MCP', + items: ['mcp/overview', 'mcp/installation', 'mcp/usage'], + }, { type: 'category', label: 'Algolia Ask AI', diff --git a/packages/website/src/components/mcp/MCPInstall.jsx b/packages/website/src/components/mcp/MCPInstall.jsx new file mode 100644 index 0000000000..919508423c --- /dev/null +++ b/packages/website/src/components/mcp/MCPInstall.jsx @@ -0,0 +1,639 @@ +import useBaseUrl from '@docusaurus/useBaseUrl'; +import { Code2 } from 'lucide-react'; +import { AnimatePresence, motion, useReducedMotion } from 'motion/react'; +import React, { useState } from 'react'; + +const ENDPOINT = 'https://mcp.algolia.com/1/docsearch/mcp'; + +// Base64 of {"url":"https://mcp.algolia.com/1/docsearch/mcp"} for the Cursor install link. +const CURSOR_DEEPLINK = + 'https://cursor.com/en-US/install-mcp?name=algolia-docsearch&config=eyJ1cmwiOiJodHRwczovL21jcC5hbGdvbGlhLmNvbS8xL2RvY3NlYXJjaC9tY3AifQ%3D%3D'; + +const SPRING = { type: 'spring', stiffness: 800, damping: 38, mass: 0.35 }; + +const CLIENTS = [ + { + id: 'cursor', + name: 'Cursor', + blurb: 'Plugin · 1-click · manual', + logo: 'cursor.svg', + logoDark: 'cursor_dark.svg', + plugin: [ + { kind: 'installButton', href: CURSOR_DEEPLINK, label: 'Install in Cursor' }, + { kind: 'text', content: 'Install the Cursor plugin package from the DocSearch repository:' }, + { kind: 'code', caption: 'Plugin package', code: 'mcp/plugins/docsearch/cursor/algolia-docsearch' }, + { + kind: 'text', + content: + 'It ships the MCP server, a rule, and a skill that teach Cursor when and how to call the DocSearch tools.', + }, + ], + manual: [ + { kind: 'installButton', href: CURSOR_DEEPLINK, label: 'Install in Cursor' }, + { kind: 'text', content: 'Or add it to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):' }, + { + kind: 'code', + caption: '~/.cursor/mcp.json', + code: `{ + "mcpServers": { + "algolia-docsearch": { + "url": "${ENDPOINT}" + } + } +}`, + }, + ], + }, + { + id: 'claude', + name: 'Claude', + blurb: 'Code & Desktop', + logo: 'claude.svg', + plugin: [ + { kind: 'subhead', content: 'Claude Code' }, + { kind: 'text', content: 'Add the marketplace and install the plugin from inside Claude Code:' }, + { + kind: 'code', + caption: 'In Claude Code', + code: `/plugin marketplace add algolia/docsearch +/plugin install algolia-docsearch@algolia-docsearch-marketplace`, + }, + { + kind: 'text', + content: + 'The plugin adds the MCP server, a skill, and the /algolia-docsearch:docs command. Plugins are a Claude Code feature — Claude Desktop connects via a custom connector (see Manual).', + }, + ], + manual: [ + { kind: 'subhead', content: 'Claude Code' }, + { kind: 'text', content: 'Add the remote server with the Claude Code CLI:' }, + { + kind: 'code', + caption: 'Terminal', + code: `claude mcp add --scope user --transport http algolia-docsearch ${ENDPOINT}`, + }, + { kind: 'subhead', content: 'Claude Desktop' }, + { + kind: 'steps', + items: ['Open Settings → Connectors.', 'Click Add custom connector.', 'Enter the name and URL, then save.'], + }, + { + kind: 'code', + caption: 'Connector', + code: `Name: Algolia DocSearch +URL: ${ENDPOINT}`, + }, + ], + }, + { + id: 'codex', + name: 'Codex', + blurb: 'CLI · config.toml', + logo: 'codex.svg', + logoDark: 'codex_dark.svg', + manual: [ + { kind: 'text', content: 'Add the remote MCP server with the Codex CLI:' }, + { + kind: 'code', + caption: 'Terminal', + code: `codex mcp add algolia-docsearch --url ${ENDPOINT}`, + }, + { + kind: 'text', + content: 'Or add the same URL under [mcp_servers.algolia-docsearch] in ~/.codex/config.toml.', + }, + ], + }, + { + id: 'chatgpt', + name: 'ChatGPT', + blurb: 'Custom connector', + logo: 'chatgpt.svg', + logoDark: 'chatgpt_dark.svg', + manual: [ + { + kind: 'steps', + items: [ + 'Open Settings -> Connectors.', + 'Enable Developer Mode if your workspace requires it.', + 'Create a custom connector named Algolia DocSearch.', + 'Paste the MCP endpoint shown above as the server URL and choose No Auth.', + ], + }, + { kind: 'note', content: 'Custom connector availability depends on your ChatGPT plan and workspace settings.' }, + ], + }, + { + id: 'opencode', + name: 'OpenCode', + blurb: 'Remote MCP', + logo: 'opencode.svg', + logoDark: 'opencode_dark.svg', + manual: [ + { kind: 'text', content: 'Add a remote MCP entry to your OpenCode config:' }, + { + kind: 'code', + caption: 'opencode.json', + code: `{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "algolia-docsearch": { + "type": "remote", + "url": "${ENDPOINT}", + "enabled": true + } + } +}`, + }, + ], + }, + { + id: 'pi', + name: 'Pi', + blurb: 'Extension required', + logo: 'pi.svg', + manual: [ + { + kind: 'text', + content: + 'Pi does not include MCP support by default. Install an MCP extension or adapter first, then add the DocSearch server:', + }, + { + kind: 'code', + caption: 'Terminal', + code: 'pi install npm:pi-mcp-adapter', + }, + { + kind: 'code', + caption: '.mcp.json', + code: `{ + "mcpServers": { + "algolia-docsearch": { + "url": "${ENDPOINT}" + } + } +}`, + }, + ], + }, + { + id: 'vscode', + name: 'VS Code', + blurb: 'Copilot agent', + logo: 'vscode.svg', + manual: [ + { + kind: 'text', + content: + 'Add a remote server in .vscode/mcp.json (workspace) or your user config. VS Code uses the servers key.', + }, + { + kind: 'code', + caption: '.vscode/mcp.json', + code: `{ + "servers": { + "algolia-docsearch": { + "type": "http", + "url": "${ENDPOINT}" + } + } +}`, + }, + { kind: 'note', content: 'DocSearch tools become available in Copilot Chat agent mode.' }, + ], + }, + { + id: 'windsurf', + name: 'Windsurf', + blurb: 'Cascade', + logo: 'windsurf.svg', + logoDark: 'windsurf_dark.svg', + manual: [ + { + kind: 'text', + content: 'Edit ~/.codeium/windsurf/mcp_config.json. Windsurf uses serverUrl for remote servers.', + }, + { + kind: 'code', + caption: 'mcp_config.json', + code: `{ + "mcpServers": { + "algolia-docsearch": { + "serverUrl": "${ENDPOINT}" + } + } +}`, + }, + { kind: 'note', content: 'Restart Windsurf after saving.' }, + ], + }, + { + id: 'zed', + name: 'Zed', + blurb: 'Context server', + logo: 'zed.svg', + logoDark: 'zed_dark.svg', + manual: [ + { kind: 'text', content: 'Add a context server in settings.json. Zed uses the context_servers key.' }, + { + kind: 'code', + caption: 'settings.json', + code: `{ + "context_servers": { + "algolia-docsearch": { + "url": "${ENDPOINT}" + } + } +}`, + }, + ], + }, + { + id: 'conductor', + name: 'Conductor', + blurb: 'Agent host config', + logo: 'conductor.svg', + logoDark: 'conductor_dark.svg', + manual: [ + { + kind: 'text', + content: + 'Conductor loads MCP servers from the selected agent host. Configure DocSearch in Claude Code, Codex, or Cursor, then start a Conductor session with that host.', + }, + { + kind: 'note', + content: + 'There is no separate Conductor MCP config for normal Claude Code, Codex, or Cursor Composer sessions.', + }, + ], + }, + { + id: 'antigravity', + name: 'Antigravity', + blurb: 'Google agent', + logo: 'antigravity.svg', + manual: [ + { kind: 'text', content: 'Open Manage MCP Servers -> View raw config, then add:' }, + { + kind: 'code', + caption: '~/.gemini/config/mcp_config.json', + code: `{ + "mcpServers": { + "algolia-docsearch": { + "serverUrl": "${ENDPOINT}" + } + } +}`, + }, + { kind: 'note', content: 'Save and refresh the Installed MCP Servers list.' }, + ], + }, + { + id: 'other', + name: 'Other clients', + blurb: 'Any MCP host', + icon: 'code', + manual: [ + { + kind: 'text', + content: 'Most clients that support remote HTTP MCP servers accept this shape. Keep the name and URL:', + }, + { + kind: 'code', + caption: 'MCP config', + code: `{ + "mcpServers": { + "algolia-docsearch": { + "type": "http", + "url": "${ENDPOINT}" + } + } +}`, + }, + { + kind: 'note', + content: + 'If your client uses a different key (servers, context_servers) or field (serverUrl), follow its MCP docs.', + }, + ], + }, +]; + +function CopyButton({ value, className = '' }) { + const [copied, setCopied] = useState(false); + + function onCopy() { + if (typeof navigator === 'undefined' || !navigator.clipboard) return; + navigator.clipboard.writeText(value).then(() => { + setCopied(true); + setTimeout(() => setCopied(false), 1500); + }); + } + + return ( + + + + {copied ? 'Copied' : 'Copy'} + + + + ); +} + +function CodeCard({ caption, code }) { + return ( +
+
+ {caption} + +
+ 
+        {code}
+
+
+ ); +} + +function CursorInstallButton({ href, label }) { + return ( + + {label} + {label} + + ); +} + +function Block({ block }) { + switch (block.kind) { + case 'subhead': + return ( +
+ + {block.content} + + +
+ ); + case 'text': + return

{block.content}

; + case 'note': + return ( +

+ {block.content} +

+ ); + case 'code': + return ; + case 'steps': + return ( +
    + {block.items.map((item, idx) => ( +
  1. + + {idx + 1} + + {item} +
    2. + ))} +
+ ); + case 'button': + return ( + + {block.label} + + ); + case 'installButton': + return ; + default: + return null; + } +} + +function ClientLogo({ client, size = 'h-7 w-7' }) { + if (client.icon === 'code') { + return ( + + + + ); + } + + const single = useBaseUrl(`/img/mcp-clients/${client.icon ?? client.logo}`); + const dark = useBaseUrl(`/img/mcp-clients/${client.logoDark ?? client.logo}`); + const hasDark = Boolean(client.logoDark); + + if (!hasDark) { + return {`${client.name}; + } + + return ( + <> + {`${client.name} + + + ); +} + +export default function MCPInstall() { + const [selectedId, setSelectedId] = useState(CLIENTS[0].id); + const [mode, setMode] = useState('plugin'); + const reduce = useReducedMotion(); + + const selected = CLIENTS.find((client) => client.id === selectedId) ?? CLIENTS[0]; + const hasPlugin = Array.isArray(selected.plugin); + const activeMode = hasPlugin ? mode : 'manual'; + const blocks = activeMode === 'plugin' ? selected.plugin : selected.manual; + + const rise = reduce ? 0 : 10; + const cardRise = reduce ? 0 : 8; + + function selectClient(id) { + setSelectedId(id); + setMode('plugin'); + } + + return ( + +
+ {/* Header */} +
+
+
+

+ Connect DocSearch MCP +

+

+ Pick your client to get the install steps +

+
+
+
+ + {/* Client picker */} + + {CLIENTS.map((client) => { + const isActive = client.id === selectedId; + return ( + selectClient(client.id)} + > + {isActive && ( + + )} + + + {client.name} + + + ); + })} + + + {/* Detail panel */} +
+
+ + + + + {selected.name} + + {selected.blurb} + + + + {hasPlugin && ( +
+ {['plugin', 'manual'].map((value) => { + const isActive = activeMode === value; + return ( + + ); + })} +
+ )} +
+ + + + {blocks.map((block, idx) => ( + + + + ))} + + +
+
+ + ); +} diff --git a/packages/website/static/img/docsearch-monogram.svg b/packages/website/static/img/docsearch-monogram.svg new file mode 100644 index 0000000000..3ce446d230 --- /dev/null +++ b/packages/website/static/img/docsearch-monogram.svg @@ -0,0 +1 @@ + diff --git a/packages/website/static/img/mcp-clients/algolia.svg b/packages/website/static/img/mcp-clients/algolia.svg new file mode 100644 index 0000000000..428be9f600 --- /dev/null +++ b/packages/website/static/img/mcp-clients/algolia.svg @@ -0,0 +1 @@ + diff --git a/packages/website/static/img/mcp-clients/antigravity.svg b/packages/website/static/img/mcp-clients/antigravity.svg new file mode 100644 index 0000000000..1b048dd58a --- /dev/null +++ b/packages/website/static/img/mcp-clients/antigravity.svg @@ -0,0 +1,97 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/website/static/img/mcp-clients/chatgpt.svg b/packages/website/static/img/mcp-clients/chatgpt.svg new file mode 100644 index 0000000000..2ebab679f6 --- /dev/null +++ b/packages/website/static/img/mcp-clients/chatgpt.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/chatgpt_dark.svg b/packages/website/static/img/mcp-clients/chatgpt_dark.svg new file mode 100644 index 0000000000..b6d542d099 --- /dev/null +++ b/packages/website/static/img/mcp-clients/chatgpt_dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/claude.svg b/packages/website/static/img/mcp-clients/claude.svg new file mode 100644 index 0000000000..d3007012b7 --- /dev/null +++ b/packages/website/static/img/mcp-clients/claude.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/codex.svg b/packages/website/static/img/mcp-clients/codex.svg new file mode 100644 index 0000000000..bae0b51e84 --- /dev/null +++ b/packages/website/static/img/mcp-clients/codex.svg @@ -0,0 +1 @@ +Codex \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/codex_dark.svg b/packages/website/static/img/mcp-clients/codex_dark.svg new file mode 100644 index 0000000000..920b984920 --- /dev/null +++ b/packages/website/static/img/mcp-clients/codex_dark.svg @@ -0,0 +1 @@ +Codex \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/conductor.svg b/packages/website/static/img/mcp-clients/conductor.svg new file mode 100644 index 0000000000..446c53f3dd --- /dev/null +++ b/packages/website/static/img/mcp-clients/conductor.svg @@ -0,0 +1 @@ + diff --git a/packages/website/static/img/mcp-clients/conductor_dark.svg b/packages/website/static/img/mcp-clients/conductor_dark.svg new file mode 100644 index 0000000000..0938e08088 --- /dev/null +++ b/packages/website/static/img/mcp-clients/conductor_dark.svg @@ -0,0 +1 @@ + diff --git a/packages/website/static/img/mcp-clients/cursor.svg b/packages/website/static/img/mcp-clients/cursor.svg new file mode 100644 index 0000000000..635d3ccdc6 --- /dev/null +++ b/packages/website/static/img/mcp-clients/cursor.svg @@ -0,0 +1,12 @@ + + + + + + + + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/cursor_dark.svg b/packages/website/static/img/mcp-clients/cursor_dark.svg new file mode 100644 index 0000000000..10d50ca847 --- /dev/null +++ b/packages/website/static/img/mcp-clients/cursor_dark.svg @@ -0,0 +1,12 @@ + + + + + + + + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/opencode.svg b/packages/website/static/img/mcp-clients/opencode.svg new file mode 100644 index 0000000000..542a9188c3 --- /dev/null +++ b/packages/website/static/img/mcp-clients/opencode.svg @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/opencode_dark.svg b/packages/website/static/img/mcp-clients/opencode_dark.svg new file mode 100644 index 0000000000..157edc4d75 --- /dev/null +++ b/packages/website/static/img/mcp-clients/opencode_dark.svg @@ -0,0 +1,7 @@ + + + + + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/pi.svg b/packages/website/static/img/mcp-clients/pi.svg new file mode 100644 index 0000000000..c28d624233 --- /dev/null +++ b/packages/website/static/img/mcp-clients/pi.svg @@ -0,0 +1,21 @@ + + + + + + diff --git a/packages/website/static/img/mcp-clients/vscode.svg b/packages/website/static/img/mcp-clients/vscode.svg new file mode 100644 index 0000000000..1c21199969 --- /dev/null +++ b/packages/website/static/img/mcp-clients/vscode.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/windsurf.svg b/packages/website/static/img/mcp-clients/windsurf.svg new file mode 100644 index 0000000000..bcaf639146 --- /dev/null +++ b/packages/website/static/img/mcp-clients/windsurf.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/windsurf_dark.svg b/packages/website/static/img/mcp-clients/windsurf_dark.svg new file mode 100644 index 0000000000..8f4b214454 --- /dev/null +++ b/packages/website/static/img/mcp-clients/windsurf_dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/zed.svg b/packages/website/static/img/mcp-clients/zed.svg new file mode 100644 index 0000000000..eca91c5382 --- /dev/null +++ b/packages/website/static/img/mcp-clients/zed.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/website/static/img/mcp-clients/zed_dark.svg b/packages/website/static/img/mcp-clients/zed_dark.svg new file mode 100644 index 0000000000..89df32321d --- /dev/null +++ b/packages/website/static/img/mcp-clients/zed_dark.svg @@ -0,0 +1 @@ + \ No newline at end of file