From 4a0b62804fb1b356e3d09df7b508ab46bde1c89d Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 6 Aug 2026 06:57:03 +0000 Subject: [PATCH] docs: translate Mintlify Index updates --- es.json | 18 + es/ai-native.mdx | 2 + es/ai/mintlify-mcp.mdx | 20 +- es/ai/model-context-protocol.mdx | 2 +- es/api/introduction.mdx | 26 +- es/api/search-index/contents.mdx | 7 + es/api/search-index/context.mdx | 7 + es/api/search-index/introduction.mdx | 101 ++++ es/api/search-index/search.mdx | 7 + es/changelog.mdx | 13 + es/index-openapi.json | 715 +++++++++++++++++++++++++++ es/search-index/connect.mdx | 141 ++++++ es/search-index/index.mdx | 53 ++ es/search-index/mcp.mdx | 85 ++++ fr.json | 18 + fr/ai-native.mdx | 2 + fr/ai/mintlify-mcp.mdx | 20 +- fr/ai/model-context-protocol.mdx | 2 +- fr/api/introduction.mdx | 26 +- fr/api/search-index/contents.mdx | 7 + fr/api/search-index/context.mdx | 7 + fr/api/search-index/introduction.mdx | 101 ++++ fr/api/search-index/search.mdx | 7 + fr/changelog.mdx | 13 + fr/index-openapi.json | 715 +++++++++++++++++++++++++++ fr/search-index/connect.mdx | 141 ++++++ fr/search-index/index.mdx | 53 ++ fr/search-index/mcp.mdx | 85 ++++ snippets/es/previewbutton.jsx | 7 + snippets/fr/previewbutton.jsx | 7 + snippets/zh/previewbutton.jsx | 7 + zh.json | 18 + zh/ai-native.mdx | 2 + zh/ai/mintlify-mcp.mdx | 20 +- zh/ai/model-context-protocol.mdx | 2 +- zh/api/introduction.mdx | 26 +- zh/api/search-index/contents.mdx | 7 + zh/api/search-index/context.mdx | 7 + zh/api/search-index/introduction.mdx | 101 ++++ zh/api/search-index/search.mdx | 7 + zh/changelog.mdx | 13 + zh/index-openapi.json | 715 +++++++++++++++++++++++++++ zh/search-index/connect.mdx | 141 ++++++ zh/search-index/index.mdx | 53 ++ zh/search-index/mcp.mdx | 85 ++++ 45 files changed, 3570 insertions(+), 42 deletions(-) create mode 100644 es/api/search-index/contents.mdx create mode 100644 es/api/search-index/context.mdx create mode 100644 es/api/search-index/introduction.mdx create mode 100644 es/api/search-index/search.mdx create mode 100644 es/index-openapi.json create mode 100644 es/search-index/connect.mdx create mode 100644 es/search-index/index.mdx create mode 100644 es/search-index/mcp.mdx create mode 100644 fr/api/search-index/contents.mdx create mode 100644 fr/api/search-index/context.mdx create mode 100644 fr/api/search-index/introduction.mdx create mode 100644 fr/api/search-index/search.mdx create mode 100644 fr/index-openapi.json create mode 100644 fr/search-index/connect.mdx create mode 100644 fr/search-index/index.mdx create mode 100644 fr/search-index/mcp.mdx create mode 100644 snippets/es/previewbutton.jsx create mode 100644 snippets/fr/previewbutton.jsx create mode 100644 snippets/zh/previewbutton.jsx create mode 100644 zh/api/search-index/contents.mdx create mode 100644 zh/api/search-index/context.mdx create mode 100644 zh/api/search-index/introduction.mdx create mode 100644 zh/api/search-index/search.mdx create mode 100644 zh/index-openapi.json create mode 100644 zh/search-index/connect.mdx create mode 100644 zh/search-index/index.mdx create mode 100644 zh/search-index/mcp.mdx diff --git a/es.json b/es.json index 4b3fbb211a..e5ee4a0327 100644 --- a/es.json +++ b/es.json @@ -228,6 +228,14 @@ "es/ai/model-context-protocol", "es/ai/mintlify-mcp", "es/optimize/search", + { + "group": "Mintlify Index", + "pages": [ + "es/search-index/index", + "es/search-index/connect", + "es/search-index/mcp" + ] + }, "es/optimize/seo", "es/ai/markdown-export", "es/optimize/pdf-exports", @@ -329,6 +337,16 @@ "es/api/assistant/get-page-content" ] }, + { + "group": "Mintlify Index", + "icon": "library", + "pages": [ + "es/api/search-index/introduction", + "es/api/search-index/context", + "es/api/search-index/search", + "es/api/search-index/contents" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/es/ai-native.mdx b/es/ai-native.mdx index 2cf89c4e2a..515d6b5aed 100644 --- a/es/ai-native.mdx +++ b/es/ai-native.mdx @@ -47,6 +47,8 @@ Mintlify hospeda los archivos `llms.txt` y `skill.md` para tu documentación. Es Tu sitio de documentación también ejecuta un servidor MCP (Model Context Protocol) que permite a los usuarios conectar tu documentación directamente con sus herramientas de IA para obtener información actualizada sobre tu producto, justo donde la necesitan. +Para preguntas de implementación que abarcan varios productos o requieren búsquedas web, [Mintlify Index](/es/search-index) ofrece a los agentes de programación un único servidor MCP y una API REST para recuperar contexto de documentación mantenida por sus editores y de la web. + La búsqueda de texto completo y la comprensión semántica ayudan a los usuarios y a las herramientas de IA a encontrar información relevante rápidamente. La búsqueda comprende la intención del usuario en lugar de limitarse a coincidir palabras clave. Y si un usuario se encuentra con un error 404, tu sitio sugiere páginas relacionadas para ayudarle a encontrar lo que busca. No se requiere configuración.
diff --git a/es/ai/mintlify-mcp.mdx b/es/ai/mintlify-mcp.mdx index c1ed44a247..e7497a7823 100644 --- a/es/ai/mintlify-mcp.mdx +++ b/es/ai/mintlify-mcp.mdx @@ -17,18 +17,20 @@ Conecta cualquier cliente MCP como Claude, Claude Code, ChatGPT o Cursor al serv El servidor Admin MCP permite que las herramientas de IA accedan a tu panel de Mintlify. Trátalo como a un compañero de trabajo con acceso de escritura. Conéctalo solo desde herramientas de IA de confianza y revisa cada pull request antes de fusionarla. -El Admin MCP es un servicio alojado por Mintlify en `https://mcp.mintlify.com`. No hay una versión autoalojada: todos los clientes se conectan al mismo endpoint y se autentican con tu cuenta de Mintlify. +El Admin MCP es un servicio alojado por Mintlify en `https://mcp.mintlify.com`. Todos los clientes se conectan al mismo endpoint y se autentican con tu cuenta de Mintlify. -
- ### Cómo se diferencia el Admin MCP del Search MCP +
+ ### Cómo se diferencia el Admin MCP de otros servidores MCP de Mintlify
-| | Admin MCP | Search MCP | -| :-- | :-- | :-- | -| **Audiencia** | Tu equipo | Tus usuarios finales | -| **Acceso** | Leer, editar, reestructurar, guardar, crear workflows, gestionar la configuración | Leer y buscar en las páginas publicadas | -| **Endpoints** | Alojado por Mintlify, limitado a tu proyecto | `/mcp` en el dominio de tu sitio | -| **Salida** | Ediciones de contenido, cambios de navegación, pull requests, ejecuciones de workflows | Resultados de búsqueda y contenido de páginas | +| | Admin MCP | Search MCP | Index MCP | +| :-- | :-- | :-- | :-- | +| **Audiencia** | Tu equipo | Tus usuarios finales | Todos los desarrolladores y agentes | +| **Acceso** | Leer, editar, reestructurar, guardar, crear workflows, gestionar la configuración | Leer y buscar en las páginas publicadas de un sitio | Leer y buscar en todos los sitios de Mintlify | +| **Endpoint** | `https://mcp.mintlify.com` | `/mcp` en el dominio de tu sitio | `https://index.mintlify.com` | +| **Salida** | Ediciones de contenido, cambios de navegación, pull requests, ejecuciones de workflows | Resultados de búsqueda y contenido de páginas de tu sitio | Resultados de búsqueda y contenido de páginas de todos los sitios de Mintlify | + +Consulta la [referencia del MCP de Mintlify Index](/es/search-index/mcp) para ver sus entradas de herramientas y límites de uso.
## Requisitos previos diff --git a/es/ai/model-context-protocol.mdx b/es/ai/model-context-protocol.mdx index f6a05f1550..9a0df8681b 100644 --- a/es/ai/model-context-protocol.mdx +++ b/es/ai/model-context-protocol.mdx @@ -16,7 +16,7 @@ El Model Context Protocol (MCP) es un protocolo abierto que crea conexiones esta Tu servidor Search MCP expone herramientas para que las aplicaciones de IA busquen y recuperen tu contenido. Tus usuarios deben conectar tu servidor Search MCP a sus herramientas. - ¿Quieres permitir que los agentes editen tu contenido en lugar de solo leerlo? Usa el [servidor Admin MCP](/es/ai/mintlify-mcp) para acceder a un servidor MCP autenticado que expone herramientas de branching, edición de páginas, navegación y `docs.json` a agentes de confianza. + Para permitir que agentes de confianza editen tu contenido, usa el [servidor Admin MCP](/es/ai/mintlify-mcp). Para ofrecer a los agentes de programación una única fuente de recuperación en todos los sitios de Mintlify, usa [Mintlify Index](/es/search-index).
diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index c49c39a0de..1db95a1d18 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -6,7 +6,9 @@ boost: 3 --- - La API REST requiere un [plan Pro o Enterprise](https://mintlify.com/pricing?ref=api). + La API REST de la plataforma requiere un [plan Pro o Enterprise](https://mintlify.com/pricing?ref=api). + + La [API REST de Mintlify Index](/es/api/search-index/introduction) usa una clave de API y una URL base independientes. La REST (Representational State Transfer) API de Mintlify te permite interactuar de forma programática con tu documentación, lanzar actualizaciones, integrar experiencias de chat impulsadas por IA y exportar datos de Analytics. @@ -58,12 +60,20 @@ https://api.mintlify.com ## Autenticación
-Puedes generar API keys en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. Cada API key pertenece a una organización; puedes usar API keys en múltiples implementaciones dentro de la misma organización. +Puedes generar API keys en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. Las claves de API de administrador e Index pertenecen a una organización. Puedes usar las mismas claves en múltiples implementaciones dentro de la misma organización. Las claves de API del Assistant pertenecen al despliegue donde las creas. Puedes crear hasta 10 API keys por hora y por organización. Al crear una API key, puedes configurarla para que caduque en 7, 30, 60 o 90 días, o seleccionar **Sin caducidad**. Las nuevas API keys caducan en 90 días de forma predeterminada. La página de API keys muestra una insignia **Caduca en …** para las API keys que caducan en los próximos 7 días y una insignia **Caducada** para las que ya han caducado. Las API keys caducadas dejan de funcionar, por lo que debes rotarlas o reemplazarlas antes de la fecha de caducidad. +Mintlify utiliza tres tipos de API keys, cada una con un conjunto diferente de endpoints: + +| Tipo de key | Prefijo | Se usa para | +| ----------------- | ----------- | ----------------------------------------------------------------------------- | +| Admin API key | `mint_` | Actualizaciones, tareas de agente y exportaciones de Analytics. Solo servidor. | +| Assistant API key | `mint_dsc_` | Mensajes del asistente, búsqueda de documentación y contenido de páginas. Usa un proxy en producción. | +| Index API key | `mint_us_` | Búsqueda de Index, ensamblaje de contexto y recuperación de contenido. Solo servidor. | +
### Clave de la API de administrador
@@ -86,11 +96,19 @@ Las keys del Assistant API comienzan con el prefijo `mint_dsc_`. Las solicitudes de Search documentation y Get page content no consumen créditos. Las solicitudes de Create assistant message usan créditos y pueden generar excedentes. +
+ ### Clave de la API de Index +
+ +Usa una clave de la API de Index para autenticar solicitudes a la [API REST de Mintlify Index](/es/search-index). Las claves de la API de Index comienzan con el prefijo `mint_us_`. + +La clave de la API de Index es un secreto del lado del servidor. No la expongas en código del lado del cliente. +
### Restringir claves por dirección IP
-Puedes restringir opcionalmente una API key a una lista de direcciones IP o rangos CIDR permitidos. Cuando una key tiene una lista de permitidos, las solicitudes desde cualquier otra dirección IP se rechazan con una respuesta `403`. Tanto las claves de la API de administrador como las del Assistant API admiten listas de permitidos. +Puedes restringir opcionalmente una API key a una lista de direcciones IP o rangos CIDR permitidos. Cuando una key tiene una lista de permitidos, las solicitudes desde cualquier otra dirección IP se rechazan con una respuesta `403`. Las claves de las API de administrador, Assistant e Index admiten listas de permitidos. Configura la lista de permitidos al crear la key en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. La lista de permitidos es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una lista de permitidos, la key acepta solicitudes desde cualquier dirección IP. @@ -126,7 +144,7 @@ Solo se aceptan `read` y `write`. Cualquier otro valor devuelve una respuesta `4 ### Establecer una fecha de expiración
-Puedes establecer opcionalmente una fecha de expiración en cualquier API key al crearla. Cuando pasa la marca de tiempo de expiración, las solicitudes que usan la key se rechazan. Tanto las claves de la API de administrador como las del Assistant API admiten expiración. +Puedes establecer opcionalmente una fecha de expiración en cualquier API key al crearla. Cuando pasa la marca de tiempo de expiración, las solicitudes que usan la key se rechazan con una respuesta `401`. Todas las API keys admiten expiración. Configura la expiración en la [página de API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard. La expiración es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una expiración, la key nunca expira. diff --git a/es/api/search-index/contents.mdx b/es/api/search-index/contents.mdx new file mode 100644 index 0000000000..676c367b42 --- /dev/null +++ b/es/api/search-index/contents.mdx @@ -0,0 +1,7 @@ +--- +title: "Obtener contenido de resultados" +sidebarTitle: "Contenido" +description: "Recupera contenido de Mintlify Index mediante el ID o la URL de un resultado después de buscar." +keywords: ["Mintlify Index", "contents API", "result IDs", "URLs"] +openapi: "/es/index-openapi.json POST /v1/contents" +--- diff --git a/es/api/search-index/context.mdx b/es/api/search-index/context.mdx new file mode 100644 index 0000000000..7c03eb7910 --- /dev/null +++ b/es/api/search-index/context.mdx @@ -0,0 +1,7 @@ +--- +title: "Crear contexto de implementación" +sidebarTitle: "Contexto" +description: "Reúne contexto técnico con fuentes citadas dentro de un presupuesto de tokens para una aplicación o agente." +keywords: ["Mintlify Index", "context", "citations", "token budget"] +openapi: "/es/index-openapi.json POST /v1/context" +--- diff --git a/es/api/search-index/introduction.mdx b/es/api/search-index/introduction.mdx new file mode 100644 index 0000000000..6e5fd786c5 --- /dev/null +++ b/es/api/search-index/introduction.mdx @@ -0,0 +1,101 @@ +--- +title: "API REST de Mintlify Index" +sidebarTitle: "Descripción general" +description: "Usa la API REST de Mintlify Index para buscar en la documentación y la web, reunir contexto con fuentes citadas y recuperar el contenido de páginas para aplicaciones y agentes." +keywords: ["Mintlify Index API", "REST API", "authentication", "API key"] +--- + +Usa la API REST de Mintlify Index para recuperar conocimientos técnicos para aplicaciones y agentes. La API admite tres patrones de recuperación: + +- [`context`](/es/api/search-index/context) reúne contenido con fuentes citadas dentro de un presupuesto de tokens. +- [`search`](/es/api/search-index/search) devuelve resultados clasificados de documentación y la web. +- [`contents`](/es/api/search-index/contents) recupera contenido para los ID de resultados de Mintlify o las URL de resultados seleccionados. + + + La API REST requiere una clave de API para tu organización. El [servidor MCP de Index](/es/search-index/mcp) público no requiere una clave de API. + + +
+ ## URL base +
+ +Envía las solicitudes a la API REST a: + +```text +https://leaves.mintlify.com/api/universal-search/v1 +``` + +Añade una ruta de endpoint a esta URL base, por ejemplo `/context`, `/search` o `/contents`. + +
+ ## Autenticación +
+ +Autentica cada solicitud con una clave de API de Index en el encabezado `Authorization`: + +```http +Authorization: Bearer mint_us_... +``` + +Las claves de API de Index comienzan por `mint_us_`. + + + + Abre la [página de claves de API](https://app.mintlify.com/settings/organization/api-keys) en tu dashboard y crea una clave de API de Index. + + Si este tipo de clave no está disponible, tu organización no tiene acceso a la API REST de Index. + + + Guarda la clave en una variable de entorno del lado del servidor. Mintlify solo muestra la clave completa cuando la creas por primera vez. Guárdala de forma segura. + + ```bash + export MINTLIFY_INDEX_API_KEY="mint_us_..." + ``` + + + No expongas una clave de API de Index en código del lado del cliente ni la confirmes en el control de versiones. + + + + Envía tu primera solicitud al endpoint `context`: + + ```bash + curl -X POST "https://leaves.mintlify.com/api/universal-search/v1/context" \ + -H "Authorization: Bearer $MINTLIFY_INDEX_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "How should I configure caching in Next.js 16?", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + }' + ``` + + Una respuesta correcta incluye el contexto reunido con las URL de las fuentes, el número de resultados utilizados y el recuento de tokens de salida. + + + +
+ ## Límites de uso +
+ +Los límites de la API REST se aplican por organización de Mintlify. Todas las claves de API de una organización comparten el mismo límite: + +| Ventana | Límite | +| --- | ---: | +| Por segundo | 10 solicitudes | +| Por día | 1.000 solicitudes | + +Las solicitudes que superan cualquiera de los límites devuelven `429 Too Many Requests`. Usa un backoff exponencial antes de volver a intentarlo. + +
+ ## Errores +
+ +| Estado | Significado | +| --- | --- | +| `400` | El cuerpo de la solicitud no es válido. | +| `401` | Falta la clave de API, no es válida o la organización no tiene acceso a la API REST de Index. | +| `403` | La IP de la solicitud no está permitida por la clave de API. | +| `429` | La organización superó un límite de uso. | +| `500` | Index no pudo completar la solicitud. | diff --git a/es/api/search-index/search.mdx b/es/api/search-index/search.mdx new file mode 100644 index 0000000000..4cbe182241 --- /dev/null +++ b/es/api/search-index/search.mdx @@ -0,0 +1,7 @@ +--- +title: "Buscar conocimientos técnicos" +sidebarTitle: "Búsqueda" +description: "Busca en Mintlify Index documentación técnica y resultados web clasificados." +keywords: ["Mintlify Index", "search API", "technical documentation", "ranked results"] +openapi: "/es/index-openapi.json POST /v1/search" +--- diff --git a/es/changelog.mdx b/es/changelog.mdx index 517213bf89..9ab2e278ed 100644 --- a/es/changelog.mdx +++ b/es/changelog.mdx @@ -5,6 +5,19 @@ rss: true noindex: true --- + + +
+ ## Mintlify Index +
+ + [Mintlify Index](/es/search-index) proporciona a los agentes de programación una única capa de recuperación para documentación técnica mantenida por los editores y la web. + + - **Servidor MCP público:** [Conecta](/es/search-index/connect) agentes de programación sin una API key. La herramienta `context` devuelve material con citas de fuentes para tareas de implementación. + - **API REST con control de acceso:** Busca fuentes clasificadas, ensambla contexto dentro de un presupuesto de tokens y recupera contenidos seleccionados mediante endpoints de API independientes. Requiere una API key de Index. + + +
diff --git a/es/index-openapi.json b/es/index-openapi.json new file mode 100644 index 0000000000..230eaa32dd --- /dev/null +++ b/es/index-openapi.json @@ -0,0 +1,715 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "API de Mintlify Index", + "description": "Busca y recupera documentación técnica y contexto web para aplicaciones y agentes.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://leaves.mintlify.com/api/universal-search" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/v1/context": { + "post": { + "operationId": "buildIndexContext", + "summary": "Crear contexto de implementación", + "description": "Busca en Mintlify Index y devuelve contenido con fuentes citadas reunido dentro de un presupuesto de tokens. Usa este endpoint cuando una aplicación o agente necesite contexto listo para usar en una sola solicitud.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextRequest" + }, + "example": { + "query": "¿Cómo debo configurar el almacenamiento en caché en Next.js 16?", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + } + } + } + }, + "responses": { + "200": { + "description": "El contexto se creó correctamente.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextResponse" + }, + "example": { + "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c", + "query": "¿Cómo debo configurar el almacenamiento en caché en Next.js 16?", + "response": "### Almacenamiento en caché y revalidación\n\nFuente: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUsa las API de almacenamiento en caché actuales descritas en esta guía.\n\n--------------------------------", + "resultsCount": 3, + "outputTokens": 1842 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search": { + "post": { + "operationId": "searchIndex", + "summary": "Buscar conocimientos técnicos", + "description": "Devuelve resultados clasificados de documentación mantenida por sus editores o de la web. Usa los ID de resultados de Mintlify o cualquier URL de resultado con el endpoint de contenido cuando necesites más contenido.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchRequest" + }, + "example": { + "query": "Almacenamiento en caché y revalidación en Next.js 16", + "numResults": 5, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "nextjs.org" + ] + } + } + } + }, + "responses": { + "200": { + "description": "La búsqueda se completó correctamente.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "example": { + "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "Almacenamiento en caché y revalidación", + "text": "El almacenamiento en caché es una técnica para guardar el resultado de la obtención de datos y otros cálculos.", + "truncated": false, + "totalCharacters": 92, + "score": 0.91, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "Enrutador de aplicaciones", + "Primeros pasos" + ], + "publishedDate": null + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/contents": { + "post": { + "operationId": "getIndexContents", + "summary": "Obtener contenido de resultados", + "description": "Recupera contenido para los ID de resultados de Mintlify o las URL de resultados devueltos por el endpoint de búsqueda. Una solicitud puede incluir hasta 20 elementos entre ambos campos.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsRequest" + }, + "example": { + "ids": [ + "nextjs:/docs/app/getting-started/caching-and-revalidating" + ], + "query": "revalidar datos almacenados en caché", + "maxCharacters": 12000 + } + } + } + }, + "responses": { + "400": { + "description": "El cuerpo de la solicitud no es válido.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Una solicitud puede hacer referencia como máximo a 20 elementos entre urls e ids" + } + } + } + }, + "200": { + "description": "La recuperación de contenido se completó. Comprueba cada estado para determinar si el elemento se procesó correctamente.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsResponse" + }, + "example": { + "requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "Almacenamiento en caché y revalidación", + "text": "# Almacenamiento en caché y revalidación\n\nUsa las API de revalidación para actualizar los datos almacenados en caché.", + "truncated": false, + "totalCharacters": 78, + "score": 0, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "Enrutador de aplicaciones", + "Primeros pasos" + ], + "publishedDate": null + } + ], + "statuses": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "status": "success" + } + ] + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Clave de API de Mintlify Index", + "description": "Clave de API de Mintlify Index con el prefijo `mint_us_`." + } + }, + "responses": { + "BadRequest": { + "description": "El cuerpo de la solicitud no es válido.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Cuerpo de solicitud no válido" + } + } + } + }, + "Unauthorized": { + "description": "Falta la clave de API, no es válida o la organización no tiene acceso a la API REST de Index.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "No autorizado" + } + } + } + }, + "Forbidden": { + "description": "La IP de la solicitud no está permitida por la clave de API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "La dirección IP no está permitida para esta clave de API" + } + } + } + }, + "RateLimited": { + "description": "La organización superó un límite de uso.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Límite de uso superado. Vuelve a intentarlo más tarde" + } + } + } + }, + "InternalError": { + "description": "Index no pudo completar la solicitud.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "schemas": { + "ContextRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "Pregunta de implementación que se investigará." + }, + "product": { + "type": "string", + "minLength": 1, + "description": "Nombre del producto o empresa que se usará como indicio adicional de recuperación." + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "Formato de la cadena `response`. `txt` devuelve secciones Markdown. `json` devuelve un objeto JSON serializado que contiene elementos de resultados." + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Dominios que se incluirán en la recuperación." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Dominios que se excluirán de la recuperación." + }, + "tokenBudget": { + "type": "integer", + "minimum": 1, + "maximum": 6000, + "default": 3000, + "description": "Número máximo de tokens de salida." + } + } + }, + "ContextResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identificador único de la solicitud." + }, + "query": { + "type": "string", + "description": "Consulta original de la solicitud." + }, + "response": { + "type": "string", + "description": "Contenido de fuentes reunido. El valor es Markdown para solicitudes `txt` y JSON serializado para solicitudes `json`. La cadena puede estar vacía cuando ningún contenido cabe en el presupuesto de tokens." + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "Número de fragmentos de fuentes incluidos en la respuesta." + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "Número de tokens de la respuesta reunida." + } + } + }, + "SearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "Consulta de búsqueda." + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "Número máximo de resultados que se devolverán." + }, + "text": { + "default": false, + "description": "Controla el contenido de los resultados. Establécelo en `true` para incluir contenido coincidente, en `false` para omitirlo o proporciona `maxCharacters` para incluir contenido truncado. Si se omite, el valor predeterminado es `false`.", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Número máximo de caracteres de contenido que se incluirán por resultado." + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Dominios que se incluirán en los resultados de búsqueda." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Dominios que se excluirán de los resultados de búsqueda." + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identificador único de la solicitud." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "Resultados de búsqueda clasificados." + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "Identificador del resultado. Pasa los ID de resultados de Mintlify en el campo `ids` de la solicitud de contenido. Para resultados web, pasa la URL del resultado en `urls`." + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL canónica de la fuente." + }, + "title": { + "type": "string", + "description": "Título de la fuente." + }, + "text": { + "type": "string", + "description": "Contenido coincidente cuando se solicita. De lo contrario, una cadena vacía." + }, + "truncated": { + "type": "boolean", + "description": "Indica si el contenido devuelto es más corto que el contenido disponible." + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "Número de caracteres disponibles antes del truncamiento. Está presente cuando está disponible." + }, + "score": { + "type": "number", + "description": "Puntuación de relevancia relativa. Las respuestas de contenido usan `0` porque recuperan elementos seleccionados en lugar de clasificar resultados." + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "Fuente de recuperación." + }, + "siteName": { + "type": "string", + "description": "Sitio de documentación o hostname web." + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Jerarquía de documentación del resultado." + }, + "publishedDate": { + "type": "string", + "nullable": true, + "description": "Fecha de publicación cuando la fuente proporciona una; de lo contrario, `null`. Los resultados de `search` la normalizan a una marca de tiempo ISO 8601 completa. Los resultados de `contents` recuperados mediante `urls` transmiten la cadena de fecha original de la fuente sin normalizarla, que puede ser una marca de tiempo completa o una cadena que solo contenga la fecha." + } + } + }, + "ContentsRequest": { + "type": "object", + "additionalProperties": false, + "description": "Proporciona al menos un ID de resultado de Mintlify o una URL de resultado. Puedes combinar ambos campos, con un máximo total de 20 elementos.", + "anyOf": [ + { + "required": [ + "urls" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "URL de resultados que se recuperarán. Usa este campo para resultados web." + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "ID de resultados de Mintlify que se recuperarán." + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Número máximo de caracteres de contenido que se devolverán por resultado." + }, + "query": { + "type": "string", + "minLength": 1, + "description": "Consulta que se usará para seleccionar las secciones más relevantes cuando el contenido supere `maxCharacters`." + } + } + }, + "ContentsResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identificador único de la solicitud." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "Resultados recuperados correctamente." + }, + "statuses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentStatus" + }, + "description": "Estado de recuperación de cada elemento solicitado." + } + } + }, + "ContentStatus": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "ID o URL solicitados." + }, + "status": { + "type": "string", + "enum": [ + "success" + ], + "description": "Estado de recuperación." + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "ID o URL solicitados." + }, + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Estado de recuperación." + }, + "error": { + "type": "object", + "additionalProperties": false, + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "description": "Categoría de error legible por máquinas." + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "Código de estado HTTP del upstream cuando está disponible." + } + } + } + } + } + ] + }, + "Error": { + "type": "object", + "additionalProperties": false, + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Mensaje de error." + } + } + } + } + } +} diff --git a/es/search-index/connect.mdx b/es/search-index/connect.mdx new file mode 100644 index 0000000000..afd7a45824 --- /dev/null +++ b/es/search-index/connect.mdx @@ -0,0 +1,141 @@ +--- +title: "Conecta Mintlify Index a tu agente de programación" +sidebarTitle: "Conectar" +description: "Configura el servidor MCP de Mintlify Index en Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf o Zed mediante la CLI o una configuración manual." +keywords: ["Mintlify Index", "CLI", "Claude Code", "Cursor", "MCP", "technical documentation"] +--- + +import { PreviewButton } from "/snippets/es/previewbutton.jsx" + +Conecta tu agente de programación a Mintlify Index para que pueda recuperar documentación técnica actual y contexto web mientras planifica y escribe código. Index es compatible con Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf y Zed. + + + No necesitas una cuenta de Mintlify ni una clave de API para conectarte al servidor MCP público de Index. + + +
+ ## Configurar con la CLI +
+ +Ejecuta el comando de configuración de Index para configurar uno o más agentes de programación en un solo paso: + +```bash +npx mint index +``` + +El comando detecta qué agentes de programación compatibles tienes instalados y te pide que elijas cuáles configurar. Para cada agente que selecciones, añade el servidor MCP de Index a su configuración e instala una regla que indica al agente cuándo usar la herramienta `context`. + +Para omitir el selector, pasa uno o más indicadores de agente: + +```bash +npx mint index --claude --cursor +``` + +| Indicador | Agente de programación | +| --- | --- | +| `--claude` | Claude Code | +| `--cursor` | Cursor | +| `--vscode` | VS Code | +| `--codex` | Codex | +| `--opencode` | OpenCode | +| `--windsurf` | Windsurf | +| `--zed` | Zed | + + + Añade `--yes` para configurar todos los agentes detectados sin preguntar, o `--project` para escribir la configuración en el proyecto actual en lugar de en la configuración global del agente. No todos los agentes admiten configuración a nivel de proyecto. Esos agentes siempre reciben la configuración global. + + +Vuelve a ejecutar el comando para actualizar una configuración existente o añadir otro agente. + +
+ ## Configurar manualmente +
+ +Para configurar Claude Code o Cursor manualmente, o para verificar lo que cambió la CLI, sigue los pasos correspondientes a tu agente. + + + + + + Ejecuta el siguiente comando: + + ```bash + claude mcp add --transport http mintlify-index https://index.mintlify.com + ``` + + + Muestra tus servidores MCP configurados: + + ```bash + claude mcp list + ``` + + La salida debe incluir `mintlify-index` con un estado conectado. + + + + + Selecciona **Instalar en Cursor**, revisa la configuración de MCP y aprueba la instalación. + + Instalar en Cursor + + Para configurar Cursor manualmente: + + + + 1. Abre la paleta de comandos con Command + Shift + P (Ctrl + Shift + P en Windows). + 2. Busca **Open MCP settings**. + 3. Selecciona **Add custom MCP** para abrir `mcp.json`. + + + Añade el siguiente servidor: + + ```json + { + "mcpServers": { + "mintlify-index": { + "url": "https://index.mintlify.com" + } + } + } + ``` + + + Recarga Cursor y abre **Settings → Tools & MCP**. El servidor `mintlify-index` debe aparecer como conectado y con la herramienta `context` disponible. + + + + + +
+ ## Usar Index en una sesión +
+ +Haz una pregunta de implementación y dile a tu agente que use Index cuando quieras asegurarte de que recupere fuentes actuales. Por ejemplo: + +```text +Use Mintlify Index to find the current recommended way to configure caching in Next.js 16. Cite the sources you use. +``` + +El agente llama a la herramienta `context` de Index cuando necesita contexto técnico e incluye los enlaces a las fuentes devueltas en su trabajo. + +
+ ## Eliminar la conexión +
+ + + + Ejecuta el siguiente comando: + + ```bash + claude mcp remove mintlify-index + ``` + + + Abre **Settings → Tools & MCP** y elimina la entrada `mintlify-index` de `mcp.json`. + + + +Para VS Code, Codex, OpenCode, Windsurf o Zed, elimina la entrada `mintlify-index` de la configuración de servidores MCP de ese agente. + +Consulta la [referencia de MCP de Index](/es/search-index/mcp) para ver las entradas de las herramientas y los límites de uso. diff --git a/es/search-index/index.mdx b/es/search-index/index.mdx new file mode 100644 index 0000000000..2c5e00b6de --- /dev/null +++ b/es/search-index/index.mdx @@ -0,0 +1,53 @@ +--- +title: "Mintlify Index" +sidebarTitle: "Descripción general" +description: "Proporciona a los agentes de programación contexto técnico actualizado de documentación mantenida por sus editores y de la web mediante un único servidor MCP o API REST." +keywords: ["Mintlify Index", "technical search", "coding agents", "MCP", "REST API"] +--- + +Mintlify Index proporciona a los agentes de programación una única capa de búsqueda para conocimientos técnicos. Dirige las preguntas sobre productos indexados a documentación mantenida por sus editores y alojada en Mintlify, y usa la búsqueda web para las preguntas que quedan fuera de ese corpus. + +Usa Index mediante el servidor MCP público o la API REST con control de acceso. + +- **Servidor MCP**: Conecta una herramienta de IA y permite que recupere contexto con fuentes citadas mientras trabajas. Está disponible públicamente. No requiere una clave de API. +- **API REST**: Busca fuentes clasificadas, reúne contexto dentro de un presupuesto de tokens o recupera el contenido de resultados seleccionados. Tiene control de acceso. Requiere una clave de API de Index. + +
+ ## Primeros pasos +
+ + + + Añade Index a Claude Code, Codex, Cursor y otros agentes de programación. + + + Consulta la herramienta `context`, sus campos de entrada, salida y límites de uso. + + + Usa `search`, `context` y `contents` en una aplicación o agente. + + + +
+ ## Cómo recupera Index el contexto +
+ + + + Index identifica si la pregunta se refiere a un producto incluido en su corpus de documentación o si requiere resultados web más amplios. + + + Las preguntas específicas de un producto buscan en la documentación actual del editor. Las demás preguntas buscan en la web. + + + Index clasifica los resultados y devuelve las URL de las fuentes junto con el contenido relevante. La herramienta MCP `context` y el endpoint REST `context` reúnen ese contenido dentro de un presupuesto de tokens. + + + +
+ ## Elegir una operación de recuperación +
+ +- **[`context`](/es/api/search-index/context)**: Úsalo para la mayoría de las tareas de agentes. Devuelve un conjunto compacto de material de fuentes citadas en una sola solicitud. +- **[`search`](/es/api/search-index/search)**: Úsalo cuando tu aplicación necesite resultados clasificados y controle qué fuentes leer. Está disponible mediante la API REST. +- **[`contents`](/es/api/search-index/contents)**: Úsalo después de `search` para recuperar contenido de los ID de resultados de Mintlify o de sus URL. Está disponible mediante la API REST. diff --git a/es/search-index/mcp.mdx b/es/search-index/mcp.mdx new file mode 100644 index 0000000000..4945b37a66 --- /dev/null +++ b/es/search-index/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "Servidor MCP de Mintlify Index" +sidebarTitle: "Referencia de MCP" +description: "Referencia del servidor MCP público de Mintlify Index, incluida su herramienta context, parámetros, salida y límites de uso." +keywords: ["Mintlify Index", "MCP server", "context tool", "rate limits"] +--- + +El servidor MCP de Mintlify Index proporciona a las herramientas de IA acceso de solo lectura a documentación técnica y contexto web. Conéctate a: + +```text +https://index.mintlify.com +``` + +No necesitas autenticarte en el servidor público. Consulta [Conectar](/es/search-index/connect) para ver las instrucciones de configuración de Claude Code y Cursor. + + + Index MCP busca en la documentación de productos incluidos y en la web técnica. Para buscar únicamente el contenido de un sitio específico alojado en Mintlify, usa el [servidor MCP de búsqueda](/es/ai/model-context-protocol) de ese sitio. + + +
+ ## Herramienta `context` +
+ +Usa `context` para investigar una tarea de implementación y devolver contexto compacto con fuentes citadas en una sola llamada. La herramienta es de solo lectura y puede acceder a la web abierta. + + + Pregunta de implementación que se investigará. + + + + Nombre del producto o empresa que se usará como indicio adicional de recuperación. + + + + Dominios que se incluirán en la recuperación. Cuando se establece, la recuperación limita los resultados a estos dominios. + + + + Dominios que se excluirán de la recuperación. + + + + Número máximo de tokens que se devolverán. El valor máximo es `6000`. Usa el valor predeterminado para preguntas concretas y un presupuesto mayor para tareas complejas con varias partes. + + +
+ ### Salida +
+ +La herramienta devuelve contexto con formato Markdown reunido a partir de fuentes clasificadas. Cada sección incluye un título, la URL de la fuente y el contenido de fuente relevante. + +```text +### Configure caching + +Source: https://nextjs.org/docs/app/getting-started/caching-and-revalidating + +Relevant source content appears here. + +-------------------------------- +``` + +El servidor MCP devuelve material de fuentes para que lo use el agente conectado. El agente decide cómo aplicar ese contexto a tu tarea. + +
+ ## Límites de uso +
+ +Index aplica los siguientes límites por IP al servidor MCP público: + +| Ventana | Límite | +| --- | ---: | +| Por segundo | 10 solicitudes | +| Por día | 1.000 solicitudes | + +Las solicitudes que superan cualquiera de los límites devuelven `429 Too Many Requests`. Espera antes de volver a intentarlo y usa un backoff exponencial para clientes automatizados. + +
+ ## Comportamiento del protocolo +
+ +Index MCP usa Streamable HTTP sin estado: + +- Envía cada solicitud JSON-RPC como un `POST` HTTP. +- Envía una solicitud JSON-RPC por solicitud HTTP. No se admiten lotes. +- No conserves ni envíes un ID de sesión MCP entre solicitudes. diff --git a/fr.json b/fr.json index 64ba1b61d3..47ae932bed 100644 --- a/fr.json +++ b/fr.json @@ -228,6 +228,14 @@ "fr/ai/model-context-protocol", "fr/ai/mintlify-mcp", "fr/optimize/search", + { + "group": "Mintlify Index", + "pages": [ + "fr/search-index/index", + "fr/search-index/connect", + "fr/search-index/mcp" + ] + }, "fr/optimize/seo", "fr/ai/markdown-export", "fr/optimize/pdf-exports", @@ -329,6 +337,16 @@ "fr/api/assistant/get-page-content" ] }, + { + "group": "Mintlify Index", + "icon": "library", + "pages": [ + "fr/api/search-index/introduction", + "fr/api/search-index/context", + "fr/api/search-index/search", + "fr/api/search-index/contents" + ] + }, { "group": "Analytics", "icon": "chart-line", diff --git a/fr/ai-native.mdx b/fr/ai-native.mdx index ac56b2dc85..62fe83eee8 100644 --- a/fr/ai-native.mdx +++ b/fr/ai-native.mdx @@ -47,6 +47,8 @@ Mintlify héberge les fichiers `llms.txt` et `skill.md` pour votre documentation Votre site de documentation héberge également un serveur MCP qui permet aux utilisateurs de connecter votre documentation directement à leurs outils d’IA pour obtenir des informations à jour sur votre produit, là où ils en ont besoin. +Pour les questions d’implémentation qui couvrent plusieurs produits ou nécessitent une recherche web, [Mintlify Index](/fr/search-index) fournit aux agents de programmation un serveur MCP et une API REST uniques pour récupérer du contexte depuis la documentation gérée par les éditeurs et le web. + La recherche en texte intégral et la compréhension sémantique aident les utilisateurs et les outils d’IA à trouver rapidement des informations pertinentes. La recherche comprend l’intention de l’utilisateur plutôt que de simplement faire correspondre des mots-clés. Et si un utilisateur rencontre une erreur 404, votre site suggère des pages pertinentes pour l’aider à trouver ce qu’il recherche. Aucune configuration n’est requise.
diff --git a/fr/ai/mintlify-mcp.mdx b/fr/ai/mintlify-mcp.mdx index 2f74822e2a..118164d962 100644 --- a/fr/ai/mintlify-mcp.mdx +++ b/fr/ai/mintlify-mcp.mdx @@ -17,18 +17,20 @@ Connectez n'importe quel client MCP comme Claude, Claude Code, ChatGPT ou Cursor Le serveur Admin MCP permet aux outils d'IA d'accéder à votre tableau de bord Mintlify. Considérez-le comme un collègue avec un accès en écriture. Connectez-le uniquement depuis des outils d'IA de confiance et examinez chaque pull request avant de la fusionner. -L'Admin MCP est un service Mintlify hébergé à l'adresse `https://mcp.mintlify.com`. Il n'existe pas de version auto-hébergée — chaque client se connecte au même endpoint et s'authentifie avec votre compte Mintlify. +L'Admin MCP est un service Mintlify hébergé à l'adresse `https://mcp.mintlify.com`. Chaque client se connecte au même endpoint et s'authentifie avec votre compte Mintlify. -
- ### En quoi l'Admin MCP diffère du Search MCP +
+ ### En quoi l'Admin MCP diffère des autres serveurs MCP Mintlify
-| | Admin MCP | Search MCP | -| :-- | :-- | :-- | -| **Audience** | Votre équipe | Vos utilisateurs finaux | -| **Accès** | Lire, modifier, restructurer, enregistrer, créer des workflows, gérer les paramètres | Lire et rechercher dans les pages publiées | -| **Endpoints** | Hébergé par Mintlify, à la portée de votre projet | `/mcp` sur le domaine de votre site | -| **Résultat** | Modifications de contenu, changements de navigation, pull requests, exécutions de workflows | Résultats de recherche et contenu des pages | +| | Admin MCP | Search MCP | Index MCP | +| :-- | :-- | :-- | :-- | +| **Audience** | Votre équipe | Vos utilisateurs finaux | Tous les développeurs et agents | +| **Accès** | Lire, modifier, restructurer, enregistrer, créer des workflows, gérer les paramètres | Lire et rechercher dans les pages publiées d'un site | Lire et rechercher dans tous les sites Mintlify | +| **Point de terminaison** | `https://mcp.mintlify.com` | `/mcp` sur le domaine de votre site | `https://index.mintlify.com` | +| **Résultat** | Modifications de contenu, changements de navigation, pull requests, exécutions de workflows | Résultats de recherche et contenu des pages de votre site | Résultats de recherche et contenu des pages de tous les sites Mintlify | + +Consultez la [référence MCP de Mintlify Index](/fr/search-index/mcp) pour connaître les paramètres de ses outils et ses limites de débit.
## Prérequis diff --git a/fr/ai/model-context-protocol.mdx b/fr/ai/model-context-protocol.mdx index 68a34b2aa6..22a7875b64 100644 --- a/fr/ai/model-context-protocol.mdx +++ b/fr/ai/model-context-protocol.mdx @@ -16,7 +16,7 @@ Le Model Context Protocol (MCP) est un protocole ouvert qui crée des connexions Votre serveur Search MCP expose des outils permettant aux applications d'IA de rechercher et de récupérer votre contenu. Vos utilisateurs doivent connecter votre serveur Search MCP à leurs outils. - Vous souhaitez plutôt permettre aux agents de modifier votre contenu au lieu de simplement le lire ? Utilisez le [serveur Admin MCP](/fr/ai/mintlify-mcp) pour un serveur MCP authentifié qui expose des outils de branching, d'édition de pages, de navigation et de `docs.json` aux agents de confiance. + Pour permettre à des agents de confiance de modifier votre contenu, utilisez le [serveur Admin MCP](/fr/ai/mintlify-mcp). Pour fournir aux agents de programmation une source de récupération unique sur tous les sites Mintlify, utilisez [Mintlify Index](/fr/search-index).
diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index 0b4eed9e2a..419a8f2c2c 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -6,7 +6,9 @@ boost: 3 --- - L'API REST nécessite une [offre Pro ou Enterprise](https://mintlify.com/pricing?ref=api). + L'API REST de la plateforme nécessite une [offre Pro ou Enterprise](https://mintlify.com/pricing?ref=api). + + L'[API REST Mintlify Index](/fr/api/search-index/introduction) utilise une clé d'API et une URL de base distinctes. L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir programmatiquement avec votre documentation, de déclencher des mises à jour, d'intégrer des expériences de chat propulsées par l'IA et d'exporter les données d'analyse. @@ -58,12 +60,20 @@ https://api.mintlify.com ## Authentification
-Générez des clés d'API depuis la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. Les clés d'API sont associées à toute l'organisation et peuvent être utilisées sur plusieurs déploiements au sein de la même organisation. +Générez des clés d'API depuis la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. Les clés d'API administrateur et Index appartiennent à une organisation. Vous pouvez utiliser les mêmes clés sur plusieurs déploiements au sein de cette organisation. Les clés d'API de l'Assistant appartiennent au déploiement dans lequel vous les créez. Vous pouvez créer jusqu'à 10 clés d'API par heure et par organisation. Lorsque vous créez une clé, vous pouvez la faire expirer dans 7, 30, 60 ou 90 jours, ou sélectionner **Aucune expiration**. Les nouvelles clés expirent par défaut dans 90 jours. La page API keys affiche un badge **Expire dans …** pour les clés qui expirent dans les 7 jours et un badge **Expirée** pour celles qui ont déjà expiré. Les clés expirées cessent de fonctionner. Faites-les tourner ou remplacez-les avant leur date d'expiration. +Mintlify utilise trois types de clés d'API, chacune associée à un ensemble différent de points de terminaison : + +| Type de clé | Préfixe | Utilisation | +| ---------------- | ----------- | ------------------------------------------------------------------------------ | +| Clé d'API admin | `mint_` | Mises à jour, jobs d'agent et exports Analytics. Serveur uniquement. | +| Clé d'API Assistant | `mint_dsc_` | Messages de l'Assistant, recherche documentaire et contenu des pages. Utilisez un proxy en production. | +| Clé d'API Index | `mint_us_` | Recherche Index, assemblage de contexte et récupération de contenu. Serveur uniquement. | +
### Clé d'API administrateur
@@ -86,11 +96,19 @@ Les clés d'API de l'Assistant commencent par le préfixe `mint_dsc_`. Les requêtes Search documentation et Get page content ne consomment pas de crédits. Les requêtes Create assistant message utilisent des crédits et peuvent entraîner des dépassements. +
+ ### Clé d'API Index +
+ +Utilisez une clé d'API Index pour authentifier les requêtes vers l'[API REST Mintlify Index](/fr/search-index). Les clés d'API Index commencent par le préfixe `mint_us_`. + +La clé d'API Index est un secret côté serveur. Ne l'exposez pas dans du code côté client. +
### Restreindre les clés par adresse IP
-Vous pouvez éventuellement restreindre une clé d'API à une liste d'adresses IP ou de plages CIDR autorisées. Lorsqu'une clé possède une liste d'autorisation, les requêtes provenant de toute autre adresse IP sont rejetées avec une réponse `403`. Les clés d'API administrateur et les clés d'API de l'Assistant prennent en charge les listes d'autorisation. +Vous pouvez éventuellement restreindre une clé d'API à une liste d'adresses IP ou de plages CIDR autorisées. Lorsqu'une clé possède une liste d'autorisation, les requêtes provenant de toute autre adresse IP sont rejetées avec une réponse `403`. Les clés d'API administrateur, Assistant et Index prennent en charge les listes d'autorisation. Configurez la liste d'autorisation lors de la création de la clé sur la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. La liste d'autorisation est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas de liste d'autorisation, la clé accepte les requêtes depuis n'importe quelle adresse IP. @@ -126,7 +144,7 @@ Seuls `read` et `write` sont acceptés. Toute autre valeur renvoie une réponse ### Définir une date d'expiration
-Vous pouvez éventuellement définir une date d'expiration sur toute clé d'API lors de sa création. Une fois l'horodatage d'expiration dépassé, les requêtes utilisant la clé sont rejetées. Les clés d'API administrateur et les clés d'API de l'Assistant prennent en charge l'expiration. +Vous pouvez éventuellement définir une date d'expiration sur toute clé d'API lors de sa création. Une fois l'horodatage d'expiration dépassé, les requêtes utilisant la clé sont rejetées avec une réponse `401`. Toutes les clés d'API prennent en charge l'expiration. Définissez l'expiration sur la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard. L'expiration est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas d'expiration, la clé n'expire jamais. diff --git a/fr/api/search-index/contents.mdx b/fr/api/search-index/contents.mdx new file mode 100644 index 0000000000..dedd864e2c --- /dev/null +++ b/fr/api/search-index/contents.mdx @@ -0,0 +1,7 @@ +--- +title: "Obtenir le contenu des résultats" +sidebarTitle: "Contenu" +description: "Récupérez le contenu de Mintlify Index à partir d’un identifiant ou d’une URL de résultat après une recherche." +keywords: ["Mintlify Index", "contents API", "result IDs", "URLs"] +openapi: "/fr/index-openapi.json POST /v1/contents" +--- diff --git a/fr/api/search-index/context.mdx b/fr/api/search-index/context.mdx new file mode 100644 index 0000000000..41157899c2 --- /dev/null +++ b/fr/api/search-index/context.mdx @@ -0,0 +1,7 @@ +--- +title: "Construire le contexte d’implémentation" +sidebarTitle: "Contexte" +description: "Assemblez un contexte technique accompagné de ses sources dans une limite de jetons pour une application ou un agent." +keywords: ["Mintlify Index", "context", "citations", "token budget"] +openapi: "/fr/index-openapi.json POST /v1/context" +--- diff --git a/fr/api/search-index/introduction.mdx b/fr/api/search-index/introduction.mdx new file mode 100644 index 0000000000..5fa8a7ba8f --- /dev/null +++ b/fr/api/search-index/introduction.mdx @@ -0,0 +1,101 @@ +--- +title: "API REST Mintlify Index" +sidebarTitle: "Vue d’ensemble" +description: "Utilisez l’API REST Mintlify Index pour rechercher dans la documentation et sur le web, assembler un contexte accompagné de sources et récupérer le contenu de pages pour vos applications et agents." +keywords: ["Mintlify Index API", "REST API", "authentication", "API key"] +--- + +Utilisez l’API REST Mintlify Index pour récupérer des connaissances techniques pour vos applications et agents. L’API prend en charge trois modes de récupération : + +- [`context`](/fr/api/search-index/context) assemble du contenu accompagné de ses sources dans une limite de jetons. +- [`search`](/fr/api/search-index/search) renvoie des résultats classés issus de la documentation et du web. +- [`contents`](/fr/api/search-index/contents) récupère le contenu correspondant aux identifiants de résultats Mintlify ou aux URL de résultats sélectionnés. + + + L’API REST nécessite une clé d’API pour votre organisation. Le [serveur MCP Index public](/fr/search-index/mcp) ne nécessite pas de clé d’API. + + +
+ ## URL de base +
+ +Envoyez les requêtes de l’API REST à l’adresse suivante : + +```text +https://leaves.mintlify.com/api/universal-search/v1 +``` + +Ajoutez un chemin de point de terminaison à cette URL de base, par exemple `/context`, `/search` ou `/contents`. + +
+ ## Authentification +
+ +Authentifiez chaque requête avec une clé d’API Index dans l’en-tête `Authorization` : + +```http +Authorization: Bearer mint_us_... +``` + +Les clés d’API Index commencent par `mint_us_`. + + + + Ouvrez la [page des clés d’API](https://app.mintlify.com/settings/organization/api-keys) dans votre tableau de bord et créez une clé d’API Index. + + Si ce type de clé n’est pas disponible, votre organisation n’a pas accès à l’API REST Index. + + + Enregistrez la clé dans une variable d’environnement côté serveur. Mintlify n’affiche la clé complète qu’au moment de sa création. Stockez-la en lieu sûr. + + ```bash + export MINTLIFY_INDEX_API_KEY="mint_us_..." + ``` + + + N’exposez pas une clé d’API Index dans du code côté client et ne la validez pas dans le contrôle de version. + + + + Envoyez votre première requête au point de terminaison `context` : + + ```bash + curl -X POST "https://leaves.mintlify.com/api/universal-search/v1/context" \ + -H "Authorization: Bearer $MINTLIFY_INDEX_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "How should I configure caching in Next.js 16?", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + }' + ``` + + Une réponse réussie inclut le contexte assemblé avec les URL sources, le nombre de résultats utilisés et le nombre de jetons générés. + + + +
+ ## Limites de débit +
+ +Les limites de l’API REST s’appliquent à chaque organisation Mintlify. Toutes les clés d’API d’une organisation partagent la même limite : + +| Fenêtre | Limite | +| --- | ---: | +| Par seconde | 10 requêtes | +| Par jour | 1 000 requêtes | + +Les requêtes dépassant l’une ou l’autre limite renvoient `429 Too Many Requests`. Utilisez un back-off exponentiel avant de réessayer. + +
+ ## Erreurs +
+ +| Statut | Signification | +| --- | --- | +| `400` | Le corps de la requête n’est pas valide. | +| `401` | La clé d’API est absente ou invalide, ou l’organisation n’a pas accès à l’API REST Index. | +| `403` | L’adresse IP de la requête n’est pas autorisée par la clé d’API. | +| `429` | L’organisation a dépassé une limite de débit. | +| `500` | Index n’a pas pu terminer la requête. | diff --git a/fr/api/search-index/search.mdx b/fr/api/search-index/search.mdx new file mode 100644 index 0000000000..4aac5681d8 --- /dev/null +++ b/fr/api/search-index/search.mdx @@ -0,0 +1,7 @@ +--- +title: "Rechercher des connaissances techniques" +sidebarTitle: "Recherche" +description: "Recherchez dans Mintlify Index des résultats classés issus de la documentation technique et du web." +keywords: ["Mintlify Index", "search API", "technical documentation", "ranked results"] +openapi: "/fr/index-openapi.json POST /v1/search" +--- diff --git a/fr/changelog.mdx b/fr/changelog.mdx index a605c9e52b..a7a661f71a 100644 --- a/fr/changelog.mdx +++ b/fr/changelog.mdx @@ -5,6 +5,19 @@ rss: true noindex: true --- + + +
+ ## Mintlify Index +
+ + [Mintlify Index](/fr/search-index) fournit aux agents de programmation une couche de récupération unique pour la documentation technique maintenue par les éditeurs et pour le web. + + - **Serveur MCP public :** [Connectez](/fr/search-index/connect) les agents de programmation sans clé d'API. L'outil `context` renvoie des informations citées par source pour les tâches d'implémentation. + - **API REST avec contrôle d'accès :** Recherchez des sources classées, assemblez un contexte dans une limite de jetons et récupérez les contenus sélectionnés via des points de terminaison d'API distincts. Une clé d'API Index est requise. + + +
diff --git a/fr/index-openapi.json b/fr/index-openapi.json new file mode 100644 index 0000000000..95917be4ab --- /dev/null +++ b/fr/index-openapi.json @@ -0,0 +1,715 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "API Mintlify Index", + "description": "Recherchez et récupérez de la documentation technique et du contexte web pour vos applications et agents.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://leaves.mintlify.com/api/universal-search" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/v1/context": { + "post": { + "operationId": "buildIndexContext", + "summary": "Construire le contexte d’implémentation", + "description": "Recherche dans Mintlify Index et renvoie du contenu accompagné de ses sources, assemblé dans une limite de jetons. Utilisez ce point de terminaison lorsqu’une application ou un agent a besoin d’un contexte prêt à l’emploi en une seule requête.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextRequest" + }, + "example": { + "query": "Comment dois-je configurer la mise en cache dans Next.js 16 ?", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + } + } + } + }, + "responses": { + "200": { + "description": "Contexte assemblé avec succès.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextResponse" + }, + "example": { + "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c", + "query": "Comment dois-je configurer la mise en cache dans Next.js 16 ?", + "response": "### Mise en cache et revalidation\n\nSource: https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\nUtilisez les API de mise en cache actuelles décrites dans ce guide.\n\n--------------------------------", + "resultsCount": 3, + "outputTokens": 1842 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search": { + "post": { + "operationId": "searchIndex", + "summary": "Rechercher des connaissances techniques", + "description": "Renvoie des résultats classés issus de la documentation gérée par les éditeurs ou du web. Utilisez les identifiants de résultats Mintlify ou l’URL de n’importe quel résultat avec le point de terminaison contents lorsque vous avez besoin de davantage de contenu.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchRequest" + }, + "example": { + "query": "Mise en cache et revalidation dans Next.js 16", + "numResults": 5, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "nextjs.org" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Recherche terminée avec succès.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "example": { + "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "Mise en cache et revalidation", + "text": "La mise en cache est une technique qui consiste à stocker le résultat de la récupération de données et d’autres calculs.", + "truncated": false, + "totalCharacters": 92, + "score": 0.91, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "Routeur App", + "Premiers pas" + ], + "publishedDate": null + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/contents": { + "post": { + "operationId": "getIndexContents", + "summary": "Obtenir le contenu des résultats", + "description": "Récupère le contenu correspondant aux identifiants de résultats Mintlify ou aux URL de résultats renvoyés par le point de terminaison search. Une requête peut inclure jusqu’à 20 éléments répartis entre les deux champs.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsRequest" + }, + "example": { + "ids": [ + "nextjs:/docs/app/getting-started/caching-and-revalidating" + ], + "query": "revalider les données mises en cache", + "maxCharacters": 12000 + } + } + } + }, + "responses": { + "400": { + "description": "Le corps de la requête n’est pas valide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Une requête peut référencer au maximum 20 éléments entre urls et ids" + } + } + } + }, + "200": { + "description": "Récupération du contenu terminée. Vérifiez chaque statut pour déterminer si l’élément correspondant a réussi.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsResponse" + }, + "example": { + "requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "Mise en cache et revalidation", + "text": "# Mise en cache et revalidation\n\nUtilisez les API de revalidation pour actualiser les données mises en cache.", + "truncated": false, + "totalCharacters": 78, + "score": 0, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "Routeur App", + "Premiers pas" + ], + "publishedDate": null + } + ], + "statuses": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "status": "success" + } + ] + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Clé d’API Mintlify Index", + "description": "Clé d’API Mintlify Index avec le préfixe `mint_us_`." + } + }, + "responses": { + "BadRequest": { + "description": "Le corps de la requête n’est pas valide.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Corps de requête invalide" + } + } + } + }, + "Unauthorized": { + "description": "La clé d’API est absente ou invalide, ou l’organisation n’a pas accès à l’API REST Index.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Non autorisé" + } + } + } + }, + "Forbidden": { + "description": "L’adresse IP de la requête n’est pas autorisée par la clé d’API.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "L’adresse IP n’est pas autorisée pour cette clé d’API" + } + } + } + }, + "RateLimited": { + "description": "L’organisation a dépassé une limite de débit.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "Limite de débit dépassée. Veuillez réessayer plus tard" + } + } + } + }, + "InternalError": { + "description": "Index n’a pas pu terminer la requête.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "schemas": { + "ContextRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "Question d’implémentation à étudier." + }, + "product": { + "type": "string", + "minLength": 1, + "description": "Nom du produit ou de l’entreprise à utiliser comme indication de récupération supplémentaire." + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "Format de la chaîne `response`. `txt` renvoie des sections Markdown. `json` renvoie un objet JSON sérialisé contenant les éléments de résultat." + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Domaines à inclure dans la récupération." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Domaines à exclure de la récupération." + }, + "tokenBudget": { + "type": "integer", + "minimum": 1, + "maximum": 6000, + "default": 3000, + "description": "Nombre maximal de jetons en sortie." + } + } + }, + "ContextResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identifiant unique de la requête." + }, + "query": { + "type": "string", + "description": "Requête d’origine." + }, + "response": { + "type": "string", + "description": "Contenu source assemblé. La valeur est au format Markdown pour les requêtes `txt` et au format JSON sérialisé pour les requêtes `json`. La chaîne peut être vide lorsqu’aucun contenu ne tient dans la limite de jetons." + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "Nombre d’extraits de sources inclus dans la réponse." + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "Nombre de jetons dans la réponse assemblée." + } + } + }, + "SearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "Requête de recherche." + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "Nombre maximal de résultats à renvoyer." + }, + "text": { + "default": false, + "description": "Contrôle le contenu des résultats. Définissez `true` pour inclure le contenu correspondant, `false` pour l’omettre, ou fournissez `maxCharacters` pour inclure du contenu tronqué. En l’absence de valeur, le paramètre vaut `false`.", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Nombre maximal de caractères de contenu à inclure par résultat." + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Domaines à inclure dans les résultats de recherche." + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Domaines à exclure des résultats de recherche." + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identifiant unique de la requête." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "Résultats de recherche classés." + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "Identifiant du résultat. Transmettez les identifiants des résultats Mintlify dans le champ `ids` de la requête contents. Pour les résultats web, transmettez l’URL du résultat dans `urls`." + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL canonique de la source." + }, + "title": { + "type": "string", + "description": "Titre de la source." + }, + "text": { + "type": "string", + "description": "Contenu correspondant lorsqu’il est demandé. Sinon, une chaîne vide." + }, + "truncated": { + "type": "boolean", + "description": "Indique si le contenu renvoyé est plus court que le contenu disponible." + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "Nombre de caractères disponibles avant troncature. Présent lorsqu’il est disponible." + }, + "score": { + "type": "number", + "description": "Score de pertinence relatif. Les réponses contents utilisent `0`, car elles récupèrent des éléments sélectionnés au lieu de classer les résultats." + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "Source de récupération." + }, + "siteName": { + "type": "string", + "description": "Site de documentation ou nom d’hôte web." + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Hiérarchie documentaire du résultat." + }, + "publishedDate": { + "type": "string", + "nullable": true, + "description": "Date de publication lorsque la source en fournit une, sinon `null`. Les résultats `search` la normalisent en horodatage ISO 8601 complet. Les résultats `contents` récupérés via `urls` transmettent la chaîne de date originale de la source sans normalisation ; il peut s’agir d’un horodatage complet ou d’une date seule." + } + } + }, + "ContentsRequest": { + "type": "object", + "additionalProperties": false, + "description": "Fournissez au moins un identifiant de résultat Mintlify ou une URL de résultat. Vous pouvez combiner les deux champs, dans la limite de 20 éléments au total.", + "anyOf": [ + { + "required": [ + "urls" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "URL de résultats à récupérer. Utilisez ce champ pour les résultats web." + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Identifiants de résultats Mintlify à récupérer." + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "Nombre maximal de caractères de contenu à renvoyer par résultat." + }, + "query": { + "type": "string", + "minLength": 1, + "description": "Requête utilisée pour sélectionner les sections les plus pertinentes lorsque le contenu dépasse `maxCharacters`." + } + } + }, + "ContentsResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "Identifiant unique de la requête." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "Résultats récupérés avec succès." + }, + "statuses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentStatus" + }, + "description": "Statut de récupération de chaque élément demandé." + } + } + }, + "ContentStatus": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Identifiant ou URL demandé." + }, + "status": { + "type": "string", + "enum": [ + "success" + ], + "description": "Statut de récupération." + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "Identifiant ou URL demandé." + }, + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Statut de récupération." + }, + "error": { + "type": "object", + "additionalProperties": false, + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "description": "Catégorie d’erreur lisible par machine." + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "Code de statut HTTP amont lorsqu’il est disponible." + } + } + } + } + } + ] + }, + "Error": { + "type": "object", + "additionalProperties": false, + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "Message d’erreur." + } + } + } + } + } +} diff --git a/fr/search-index/connect.mdx b/fr/search-index/connect.mdx new file mode 100644 index 0000000000..75686c1462 --- /dev/null +++ b/fr/search-index/connect.mdx @@ -0,0 +1,141 @@ +--- +title: "Connecter Mintlify Index à votre agent de programmation" +sidebarTitle: "Connexion" +description: "Configurez le serveur MCP Mintlify Index dans Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf ou Zed avec la CLI ou une configuration manuelle." +keywords: ["Mintlify Index", "CLI", "Claude Code", "Cursor", "MCP", "technical documentation"] +--- + +import { PreviewButton } from "/snippets/fr/previewbutton.jsx" + +Connectez votre agent de programmation à Mintlify Index afin qu’il puisse récupérer de la documentation technique actuelle et du contexte web pendant qu’il planifie et écrit du code. Index prend en charge Claude Code, Cursor, VS Code, Codex, OpenCode, Windsurf et Zed. + + + Vous n’avez besoin ni d’un compte Mintlify ni d’une clé d’API pour vous connecter au serveur MCP Index public. + + +
+ ## Configurer avec la CLI +
+ +Exécutez la commande de configuration Index pour configurer un ou plusieurs agents de programmation en une seule étape : + +```bash +npx mint index +``` + +La commande détecte les agents de programmation pris en charge que vous avez installés et vous invite à choisir ceux à configurer. Pour chaque agent sélectionné, elle ajoute le serveur MCP Index à sa configuration et installe une règle indiquant à l’agent quand utiliser l’outil `context`. + +Pour ignorer le sélecteur, transmettez directement un ou plusieurs indicateurs d’agent : + +```bash +npx mint index --claude --cursor +``` + +| Indicateur | Agent de programmation | +| --- | --- | +| `--claude` | Claude Code | +| `--cursor` | Cursor | +| `--vscode` | VS Code | +| `--codex` | Codex | +| `--opencode` | OpenCode | +| `--windsurf` | Windsurf | +| `--zed` | Zed | + + + Ajoutez `--yes` pour configurer tous les agents détectés sans invite, ou `--project` pour écrire la configuration dans le projet actuel plutôt que dans vos paramètres d’agent globaux. Tous les agents ne prennent pas en charge la configuration au niveau du projet. Ces agents reçoivent toujours la configuration globale. + + +Exécutez à nouveau la commande pour mettre à jour une configuration existante ou ajouter un autre agent. + +
+ ## Configurer manuellement +
+ +Pour configurer manuellement Claude Code ou Cursor, ou vérifier les modifications effectuées par la CLI, suivez les étapes correspondant à votre agent. + + + + + + Exécutez la commande suivante : + + ```bash + claude mcp add --transport http mintlify-index https://index.mintlify.com + ``` + + + Listez vos serveurs MCP configurés : + + ```bash + claude mcp list + ``` + + La sortie doit inclure `mintlify-index` avec un statut connecté. + + + + + Sélectionnez **Installer dans Cursor**, vérifiez la configuration MCP et approuvez l’installation. + + Installer dans Cursor + + Pour configurer Cursor manuellement : + + + + 1. Ouvrez la palette de commandes avec Command + Shift + P (Ctrl + Shift + P sous Windows). + 2. Recherchez **Ouvrir les paramètres MCP**. + 3. Sélectionnez **Ajouter un MCP personnalisé** pour ouvrir `mcp.json`. + + + Ajoutez le serveur suivant : + + ```json + { + "mcpServers": { + "mintlify-index": { + "url": "https://index.mintlify.com" + } + } + } + ``` + + + Rechargez Cursor, puis ouvrez **Paramètres → Outils et MCP**. Le serveur `mintlify-index` doit apparaître comme connecté, avec l’outil `context` disponible. + + + + + +
+ ## Utiliser Index dans une session +
+ +Posez une question d’implémentation et demandez à votre agent d’utiliser Index lorsque vous voulez vous assurer qu’il récupère des sources actuelles. Par exemple : + +```text +Use Mintlify Index to find the current recommended way to configure caching in Next.js 16. Cite the sources you use. +``` + +L’agent appelle l’outil Index `context` lorsqu’il a besoin de contexte technique et inclut les liens vers les sources renvoyées dans son travail. + +
+ ## Supprimer la connexion +
+ + + + Exécutez la commande suivante : + + ```bash + claude mcp remove mintlify-index + ``` + + + Ouvrez **Paramètres → Outils et MCP**, puis supprimez l’entrée `mintlify-index` de `mcp.json`. + + + +Pour VS Code, Codex, OpenCode, Windsurf ou Zed, supprimez l’entrée `mintlify-index` de la configuration des serveurs MCP de l’agent concerné. + +Consultez la [référence MCP Index](/fr/search-index/mcp) pour connaître les paramètres des outils et les limites de débit. diff --git a/fr/search-index/index.mdx b/fr/search-index/index.mdx new file mode 100644 index 0000000000..59f1ea86d4 --- /dev/null +++ b/fr/search-index/index.mdx @@ -0,0 +1,53 @@ +--- +title: "Mintlify Index" +sidebarTitle: "Vue d’ensemble" +description: "Donnez aux agents de programmation un contexte technique actuel provenant de documentation gérée par les éditeurs et du web via un serveur MCP ou une API REST uniques." +keywords: ["Mintlify Index", "technical search", "coding agents", "MCP", "REST API"] +--- + +Mintlify Index fournit aux agents de programmation une couche de recherche unique pour les connaissances techniques. Il oriente les questions sur les produits indexés vers la documentation gérée par les éditeurs et hébergée sur Mintlify, et utilise la recherche web pour les questions qui sortent de ce corpus. + +Utilisez Index via le serveur MCP public ou l’API REST soumise à un contrôle d’accès. + +- **Serveur MCP** : Connectez un outil d’IA et laissez-le récupérer du contexte accompagné de ses sources pendant votre travail. Disponible publiquement. Ne nécessite pas de clé d’API. +- **API REST** : Recherchez des sources classées, assemblez un contexte dans une limite de jetons ou récupérez le contenu de résultats sélectionnés. Soumise à un contrôle d’accès. Nécessite une clé d’API Index. + +
+ ## Commencer +
+ + + + Ajoutez Index à Claude Code, Codex, Cursor et à d’autres agents de programmation. + + + Consultez l’outil `context`, ses champs d’entrée, sa sortie et ses limites de débit. + + + Utilisez `search`, `context` et `contents` dans une application ou un agent. + + + +
+ ## Comment Index récupère le contexte +
+ + + + Index détermine si la question concerne un produit présent dans son corpus documentaire ou si elle nécessite des résultats web plus larges. + + + Les questions propres à un produit interrogent la documentation actuelle de l’éditeur. Les autres questions interrogent le web. + + + Index classe les résultats et renvoie les URL des sources avec le contenu pertinent. L’outil MCP `context` et le point de terminaison REST `context` assemblent ce contenu dans une limite de jetons. + + + +
+ ## Choisir une opération de récupération +
+ +- **[`context`](/fr/api/search-index/context)** : Utilisez cette opération pour la plupart des tâches d’agent. Elle renvoie en une requête un ensemble compact de sources citées. +- **[`search`](/fr/api/search-index/search)** : Utilisez-la lorsque votre application a besoin de résultats classés et contrôle les sources à lire. Disponible via l’API REST. +- **[`contents`](/fr/api/search-index/contents)** : Utilisez-la après `search` pour récupérer le contenu correspondant aux identifiants de résultats Mintlify ou aux URL de résultats sélectionnés. Disponible via l’API REST. diff --git a/fr/search-index/mcp.mdx b/fr/search-index/mcp.mdx new file mode 100644 index 0000000000..4757fe2890 --- /dev/null +++ b/fr/search-index/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "Serveur MCP Mintlify Index" +sidebarTitle: "Référence MCP" +description: "Référence du serveur MCP public Mintlify Index, notamment son outil context, ses paramètres, sa sortie et ses limites de débit." +keywords: ["Mintlify Index", "MCP server", "context tool", "rate limits"] +--- + +Le serveur MCP Mintlify Index donne aux outils d’IA un accès en lecture seule à la documentation technique et au contexte web. Connectez-vous à l’adresse suivante : + +```text +https://index.mintlify.com +``` + +Vous n’avez pas besoin de vous authentifier auprès du serveur public. Consultez [Connexion](/fr/search-index/connect) pour configurer Claude Code et Cursor. + + + Le MCP Index recherche dans la documentation des produits couverts et sur le web technique. Pour rechercher uniquement dans le contenu d’un site hébergé sur Mintlify, utilisez le [serveur MCP de recherche](/fr/ai/model-context-protocol) de ce site. + + +
+ ## Outil `context` +
+ +Utilisez `context` pour étudier une tâche d’implémentation et renvoyer en un appel un contexte compact accompagné de ses sources. L’outil est en lecture seule et peut accéder au web ouvert. + + + Question d’implémentation à étudier. + + + + Nom du produit ou de l’entreprise à utiliser comme indication de récupération supplémentaire. + + + + Domaines à inclure dans la récupération. Lorsque ce champ est défini, la récupération limite les résultats à ces domaines. + + + + Domaines à exclure de la récupération. + + + + Nombre maximal de jetons à renvoyer. La valeur maximale est `6000`. Utilisez la valeur par défaut pour les questions ciblées et une limite plus élevée pour les tâches complexes comportant plusieurs parties. + + +
+ ### Sortie +
+ +L’outil renvoie un contexte au format Markdown assemblé à partir de sources classées. Chaque section comprend un titre, une URL source et le contenu pertinent de la source. + +```text +### Configure caching + +Source: https://nextjs.org/docs/app/getting-started/caching-and-revalidating + +Relevant source content appears here. + +-------------------------------- +``` + +Le serveur MCP renvoie des sources que l’agent connecté peut utiliser. L’agent décide comment appliquer ce contexte à votre tâche. + +
+ ## Limites de débit +
+ +Index applique les limites par adresse IP suivantes au serveur MCP public : + +| Fenêtre | Limite | +| --- | ---: | +| Par seconde | 10 requêtes | +| Par jour | 1 000 requêtes | + +Les requêtes dépassant l’une ou l’autre limite renvoient `429 Too Many Requests`. Attendez avant de réessayer et utilisez un back-off exponentiel pour les clients automatisés. + +
+ ## Comportement du protocole +
+ +Le MCP Index utilise Streamable HTTP sans état : + +- Envoyez chaque requête JSON-RPC avec un `POST` HTTP. +- Envoyez une seule requête JSON-RPC par requête HTTP. Les lots ne sont pas pris en charge. +- Ne conservez pas et n’envoyez pas d’identifiant de session MCP entre les requêtes. diff --git a/snippets/es/previewbutton.jsx b/snippets/es/previewbutton.jsx new file mode 100644 index 0000000000..2c10604b0c --- /dev/null +++ b/snippets/es/previewbutton.jsx @@ -0,0 +1,7 @@ +export const PreviewButton = ({ children, href }) => { + return ( + + {children} + + ) + } \ No newline at end of file diff --git a/snippets/fr/previewbutton.jsx b/snippets/fr/previewbutton.jsx new file mode 100644 index 0000000000..2c10604b0c --- /dev/null +++ b/snippets/fr/previewbutton.jsx @@ -0,0 +1,7 @@ +export const PreviewButton = ({ children, href }) => { + return ( + + {children} + + ) + } \ No newline at end of file diff --git a/snippets/zh/previewbutton.jsx b/snippets/zh/previewbutton.jsx new file mode 100644 index 0000000000..2c10604b0c --- /dev/null +++ b/snippets/zh/previewbutton.jsx @@ -0,0 +1,7 @@ +export const PreviewButton = ({ children, href }) => { + return ( + + {children} + + ) + } \ No newline at end of file diff --git a/zh.json b/zh.json index f7864cdb5e..5b4e6cb318 100644 --- a/zh.json +++ b/zh.json @@ -223,6 +223,14 @@ "zh/ai/skillmd", "zh/ai/model-context-protocol", "zh/optimize/search-boost", + { + "group": "Mintlify Index", + "pages": [ + "zh/search-index/index", + "zh/search-index/connect", + "zh/search-index/mcp" + ] + }, "zh/optimize/seo", "zh/ai/markdown-export", "zh/optimize/pdf-exports", @@ -324,6 +332,16 @@ "zh/api/assistant/get-page-content" ] }, + { + "group": "Mintlify Index", + "icon": "library", + "pages": [ + "zh/api/search-index/introduction", + "zh/api/search-index/context", + "zh/api/search-index/search", + "zh/api/search-index/contents" + ] + }, { "group": "数据分析", "icon": "chart-line", diff --git a/zh/ai-native.mdx b/zh/ai-native.mdx index 5dbe10ef0a..a868542cce 100644 --- a/zh/ai-native.mdx +++ b/zh/ai-native.mdx @@ -47,6 +47,8 @@ Mintlify 会为你的文档托管 `llms.txt` 和 `skill.md` 文件。这些行 你的文档站点还会托管一个 MCP 服务器，使用户能够将你的文档直接连接到他们的 AI 工具，在他们需要的地方获取关于你产品的最新信息。 +对于涉及多个产品或需要 Web 搜索的实现问题，[Mintlify Index](/zh/search-index) 为编码代理提供一个 MCP 服务器和 REST API，用于从发布者维护的文档和 Web 中检索上下文。 + 全文搜索和语义理解帮助用户和 AI 工具快速找到相关信息。搜索能够理解用户意图，而不仅仅是匹配关键词。如果用户遇到 404 错误，你的网站会推荐相关页面，帮助他们找到所需内容。无需任何配置。
diff --git a/zh/ai/mintlify-mcp.mdx b/zh/ai/mintlify-mcp.mdx index d3b860ab12..1b943dff35 100644 --- a/zh/ai/mintlify-mcp.mdx +++ b/zh/ai/mintlify-mcp.mdx @@ -17,18 +17,20 @@ keywords: ["MCP", "写入权限", "AI", "编辑", "Claude", "ChatGPT", "Cursor", 管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的同事。仅从受信任的 AI 工具连接它，并在合并前审查每一个拉取请求。 -管理员 MCP 是由 Mintlify 托管的服务，地址为 `https://mcp.mintlify.com`。没有自托管版本——每个客户端都连接到同一个端点，并使用你的 Mintlify 账户进行身份认证。 +管理员 MCP 是由 Mintlify 托管的服务，地址为 `https://mcp.mintlify.com`。每个客户端都连接到同一个端点，并使用你的 Mintlify 账户进行身份认证。 -
- ### 管理员 MCP 与搜索 MCP 的区别 +
+ ### 管理员 MCP 与其他 Mintlify MCP 服务器的区别
-| | 管理员 MCP | 搜索 MCP | -| :-- | :-- | :-- | -| **受众** | 你的团队 | 你的终端用户 | -| **权限** | 读取、编辑、调整结构、保存、创建工作流、管理设置 | 读取并搜索已发布的页面 | -| **端点** | 由 Mintlify 托管，仅限于你的项目 | 位于你的站点域名上的 `/mcp` | -| **输出** | 内容编辑、导航更改、拉取请求、工作流运行 | 搜索结果和页面内容 | +| | 管理员 MCP | 搜索 MCP | Index MCP | +| :-- | :-- | :-- | :-- | +| **受众** | 你的团队 | 你的终端用户 | 所有开发者和代理 | +| **权限** | 读取、编辑、调整结构、保存、创建工作流、管理设置 | 读取并搜索某个站点的已发布页面 | 读取并搜索所有 Mintlify 站点 | +| **端点** | `https://mcp.mintlify.com` | 位于你的站点域名上的 `/mcp` | `https://index.mintlify.com` | +| **输出** | 内容编辑、导航更改、拉取请求、工作流运行 | 你站点的搜索结果和页面内容 | 所有 Mintlify 站点的搜索结果和页面内容 | + +请参阅 [Mintlify Index MCP 参考](/zh/search-index/mcp)，了解其工具输入和速率限制。
## 前置条件 diff --git a/zh/ai/model-context-protocol.mdx b/zh/ai/model-context-protocol.mdx index acb485d655..5788226216 100644 --- a/zh/ai/model-context-protocol.mdx +++ b/zh/ai/model-context-protocol.mdx @@ -15,7 +15,7 @@ Model Context Protocol (MCP，模型上下文协议) 是一个开放协议，用 你的 MCP 服务器会向 AI 应用提供搜索文档和获取完整页面内容的工具。你的用户必须将你的 MCP 服务器连接到他们的工具中。 - 想要让代理编辑你的内容，而不只是读取？请参阅 [Mintlify MCP 服务器](/ai/mintlify-mcp)，这是一个已认证的 MCP 服务器，会向受信任的代理公开 branching、页面编辑、导航和 `docs.json` 工具。 + 如需让受信任的代理编辑你的内容，请使用 [管理员 MCP 服务器](/zh/ai/mintlify-mcp)。如需为编码代理提供覆盖所有 Mintlify 站点的单一检索来源，请使用 [Mintlify Index](/zh/search-index)。
diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index 9d21848e8a..4d385a9a99 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -6,7 +6,9 @@ boost: 3 --- - REST API 需要 [Pro 或 Enterprise 方案](https://mintlify.com/pricing?ref=api)。 + 平台 REST API 需要 [Pro 或 Enterprise 方案](https://mintlify.com/pricing?ref=api)。 + + [Mintlify Index REST API](/zh/api/search-index/introduction) 使用单独的 API key 和基础 URL。 Mintlify 的 REST（Representational State Transfer）API 让你可以以编程方式与文档交互、触发更新、嵌入 AI 驱动的聊天体验，并导出 Analytics 数据。 @@ -58,12 +60,20 @@ https://api.mintlify.com ## 认证
-在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys)生成 API key。每个 API key 都属于一个组织，你可以在同一组织内的多个部署中使用这些 API key。 +在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys)生成 API key。管理员和 Index API key 属于组织。你可以在同一组织内的多个部署中使用相同的 key。Assistant API key 属于创建它的部署。 每个组织每小时最多可创建 10 个 API key。 创建 API key 时，你可以将其设置为在 7、30、60 或 90 天后过期，或选择**永不过期**。新的 API key 默认在 90 天后过期。API keys 页面会为将在 7 天内过期的 API key 显示**将在 … 后过期**徽章，为已过期的 API key 显示**已过期**徽章。已过期的 API key 将停止工作，请在过期日期之前轮换或更换它们。 +Mintlify 使用三种 API key，每种 key 对应不同的端点集合： + +| key 类型 | 前缀 | 用途 | +| ----------------- | ----------- | -------------------------------------------------------- | +| 管理员 API key | `mint_` | 更新、代理任务和 Analytics 导出。仅限服务器端。 | +| Assistant API key | `mint_dsc_` | 助手消息、文档搜索和页面内容。生产环境使用代理。 | +| Index API key | `mint_us_` | Index 搜索、上下文组装和内容检索。仅限服务器端。 | +
### 管理员 API key
@@ -86,11 +96,19 @@ assistant API key 以 `mint_dsc_` 前缀开头。 Search documentation 和 Get page content 请求不消耗额度。Create assistant message 请求会消耗额度，并可能产生超额费用。 +
+ ### Index API key +
+ +使用 Index API key 对 [Mintlify Index REST API](/zh/search-index) 的请求进行认证。Index API key 以 `mint_us_` 前缀开头。 + +Index API key 是一个服务器端密钥。不要在客户端代码中暴露它。 +
### 按 IP 地址限制 key
-你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员 API key 和 assistant API key 都支持允许列表。 +你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员、Assistant 和 Index API key 都支持允许列表。 在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 创建 key 时设置允许列表。允许列表在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置允许列表，key 会接受来自任何 IP 地址的请求。 @@ -126,7 +144,7 @@ Mintlify 根据请求的 HTTP 方法推导所需的 scope： ### 设置过期日期
-你可以在创建任何 API key 时选择性地设置过期日期。过期时间戳过后，使用该 key 的请求将被拒绝。管理员 API key 和 assistant API key 都支持过期设置。 +你可以在创建任何 API key 时选择性地设置过期日期。过期时间戳过后，使用该 key 的请求会以 `401` 响应被拒绝。所有 API key 都支持过期设置。 在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 设置过期时间。过期时间在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置过期时间，该 key 永不过期。 diff --git a/zh/api/search-index/contents.mdx b/zh/api/search-index/contents.mdx new file mode 100644 index 0000000000..0a24537b00 --- /dev/null +++ b/zh/api/search-index/contents.mdx @@ -0,0 +1,7 @@ +--- +title: "获取结果内容" +sidebarTitle: "内容" +description: "搜索后，通过结果 ID 或结果 URL 从 Mintlify Index 获取内容。" +keywords: ["Mintlify Index", "contents API", "结果 ID", "URL"] +openapi: "/zh/index-openapi.json POST /v1/contents" +--- diff --git a/zh/api/search-index/context.mdx b/zh/api/search-index/context.mdx new file mode 100644 index 0000000000..8dd622e998 --- /dev/null +++ b/zh/api/search-index/context.mdx @@ -0,0 +1,7 @@ +--- +title: "构建实现上下文" +sidebarTitle: "上下文" +description: "在 token 预算内为应用或代理组装带有来源引用的技术上下文。" +keywords: ["Mintlify Index", "上下文", "引用", "token 预算"] +openapi: "/zh/index-openapi.json POST /v1/context" +--- diff --git a/zh/api/search-index/introduction.mdx b/zh/api/search-index/introduction.mdx new file mode 100644 index 0000000000..a10d7b1069 --- /dev/null +++ b/zh/api/search-index/introduction.mdx @@ -0,0 +1,101 @@ +--- +title: "Mintlify Index REST API" +sidebarTitle: "概览" +description: "使用 Mintlify Index REST API 搜索文档和 Web，组装带有来源引用的上下文，并为应用和代理获取页面内容。" +keywords: ["Mintlify Index API", "REST API", "认证", "API key"] +--- + +使用 Mintlify Index REST API 为应用和代理检索技术知识。该 API 支持三种检索模式： + +- [`context`](/zh/api/search-index/context) 在 token 预算内组装带有来源引用的内容。 +- [`search`](/zh/api/search-index/search) 返回排名后的文档和 Web 结果。 +- [`contents`](/zh/api/search-index/contents) 获取所选 Mintlify 结果 ID 或结果 URL 对应的内容。 + + + REST API 需要组织的 API key。公开的 [Index MCP 服务器](/zh/search-index/mcp) 不需要 API key。 + + +
+ ## 基础 URL +
+ +向以下地址发送 REST API 请求： + +```text +https://leaves.mintlify.com/api/universal-search/v1 +``` + +在此基础 URL 后追加端点路径，例如 `/context`、`/search` 或 `/contents`。 + +
+ ## 认证 +
+ +在 `Authorization` 请求头中使用 Index API key 对每个请求进行认证： + +```http +Authorization: Bearer mint_us_... +``` + +Index API key 以 `mint_us_` 开头。 + + + + 打开控制台的 [API keys 页面](https://app.mintlify.com/settings/organization/api-keys)，创建一个 Index API key。 + + 如果没有此 key 类型，则表示你的组织无权访问 Index REST API。 + + + 将 key 保存到服务端环境变量中。Mintlify 只会在你首次创建 key 时显示完整 key，请妥善保存。 + + ```bash + export MINTLIFY_INDEX_API_KEY="mint_us_..." + ``` + + + 不要在客户端代码中暴露 Index API key，也不要将其提交到版本控制系统。 + + + + 向 `context` 端点发送第一个请求： + + ```bash + curl -X POST "https://leaves.mintlify.com/api/universal-search/v1/context" \ + -H "Authorization: Bearer $MINTLIFY_INDEX_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "How should I configure caching in Next.js 16?", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + }' + ``` + + 成功响应包含组装后的上下文、所用结果数量以及输出 token 数量。 + + + +
+ ## 速率限制 +
+ +REST API 限制按 Mintlify 组织计算。一个组织中的所有 API key 共享同一限制： + +| 时间窗口 | 限制 | +| --- | ---: | +| 每秒 | 10 个请求 | +| 每天 | 1,000 个请求 | + +超过任一限制的请求会返回 `429 Too Many Requests`。重试前请使用指数退避。 + +
+ ## 错误 +
+ +| 状态 | 含义 | +| --- | --- | +| `400` | 请求正文无效。 | +| `401` | API key 缺失或无效，或组织无权访问 Index REST API。 | +| `403` | API key 不允许该请求 IP。 | +| `429` | 组织超出速率限制。 | +| `500` | Index 无法完成请求。 | diff --git a/zh/api/search-index/search.mdx b/zh/api/search-index/search.mdx new file mode 100644 index 0000000000..9d8e62d616 --- /dev/null +++ b/zh/api/search-index/search.mdx @@ -0,0 +1,7 @@ +--- +title: "搜索技术知识" +sidebarTitle: "搜索" +description: "在 Mintlify Index 中搜索排名后的技术文档和 Web 结果。" +keywords: ["Mintlify Index", "搜索 API", "技术文档", "排名结果"] +openapi: "/zh/index-openapi.json POST /v1/search" +--- diff --git a/zh/changelog.mdx b/zh/changelog.mdx index 7c26b7c7e3..4293ec8969 100644 --- a/zh/changelog.mdx +++ b/zh/changelog.mdx @@ -5,6 +5,19 @@ rss: true noindex: true --- + + +
+ ## Mintlify Index +
+ + [Mintlify Index](/zh/search-index) 为编程代理提供统一的检索层，用于访问由发布者维护的技术文档和互联网内容。 + + - **公共 MCP 服务器：** 无需 API key 即可[连接](/zh/search-index/connect)编程代理。`context` 工具会为实现任务返回带有来源引用的资料。 + - **访问受控的 REST API：** 搜索排名靠前的来源，在 token 预算内组装上下文，并通过单独的 API 端点检索选定内容。需要 Index API key。 + + +
diff --git a/zh/index-openapi.json b/zh/index-openapi.json new file mode 100644 index 0000000000..c024d2fb40 --- /dev/null +++ b/zh/index-openapi.json @@ -0,0 +1,715 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "Mintlify Index API", + "description": "为应用和代理搜索并获取技术文档与 Web 上下文。", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://leaves.mintlify.com/api/universal-search" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/v1/context": { + "post": { + "operationId": "buildIndexContext", + "summary": "构建实现上下文", + "description": "搜索 Mintlify Index，并在 token 预算内组装带有来源引用的内容。当应用或代理需要通过一次请求获取可直接使用的上下文时，请使用此端点。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextRequest" + }, + "example": { + "query": "我应该如何在 Next.js 16 中配置缓存？", + "product": "Next.js", + "format": "txt", + "tokenBudget": 3000 + } + } + } + }, + "responses": { + "200": { + "description": "上下文组装成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContextResponse" + }, + "example": { + "requestId": "7f2ab8d1-3bea-4a29-bc51-c05a8d3a3e3c", + "query": "我应该如何在 Next.js 16 中配置缓存？", + "response": "### 缓存与重新验证\n\n来源：https://nextjs.org/docs/app/getting-started/caching-and-revalidating\n\n使用本指南中介绍的当前缓存 API。\n\n--------------------------------", + "resultsCount": 3, + "outputTokens": 1842 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/search": { + "post": { + "operationId": "searchIndex", + "summary": "搜索技术知识", + "description": "返回发布者维护的文档或 Web 中的排名结果。需要更多内容时，请将 Mintlify 结果 ID 或任意结果 URL 与 contents 端点搭配使用。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchRequest" + }, + "example": { + "query": "Next.js 16 缓存与重新验证", + "numResults": 5, + "text": { + "maxCharacters": 4000 + }, + "includeDomains": [ + "nextjs.org" + ] + } + } + } + }, + "responses": { + "200": { + "description": "搜索成功完成。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchResponse" + }, + "example": { + "requestId": "3d8ed0aa-c21c-4a18-b995-207aa6315ea8", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "缓存与重新验证", + "text": "缓存是一种存储数据获取和其他计算结果的技术。", + "truncated": false, + "totalCharacters": 92, + "score": 0.91, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "应用路由", + "开始使用" + ], + "publishedDate": null + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/v1/contents": { + "post": { + "operationId": "getIndexContents", + "summary": "获取结果内容", + "description": "获取搜索端点返回的 Mintlify 结果 ID 或结果 URL 对应的内容。一次请求最多可以在两个字段中包含 20 项。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsRequest" + }, + "example": { + "ids": [ + "nextjs:/docs/app/getting-started/caching-and-revalidating" + ], + "query": "重新验证缓存的数据", + "maxCharacters": 12000 + } + } + } + }, + "responses": { + "400": { + "description": "请求正文无效。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "一个请求最多可以在 urls 和 ids 中引用 20 项" + } + } + } + }, + "200": { + "description": "内容获取完成。请检查每个状态，以确定对应项目是否成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentsResponse" + }, + "example": { + "requestId": "6bf694e4-76cb-4d31-a222-c94b2d9b198a", + "results": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "url": "https://nextjs.org/docs/app/getting-started/caching-and-revalidating", + "title": "缓存与重新验证", + "text": "# 缓存与重新验证\n\n使用重新验证 API 刷新缓存的数据。", + "truncated": false, + "totalCharacters": 78, + "score": 0, + "source": "mintlify", + "siteName": "nextjs", + "breadcrumbs": [ + "应用路由", + "开始使用" + ], + "publishedDate": null + } + ], + "statuses": [ + { + "id": "nextjs:/docs/app/getting-started/caching-and-revalidating", + "status": "success" + } + ] + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "Mintlify Index API 密钥", + "description": "带有 `mint_us_` 前缀的 Mintlify Index API 密钥。" + } + }, + "responses": { + "BadRequest": { + "description": "请求正文无效。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "请求正文无效" + } + } + } + }, + "Unauthorized": { + "description": "API key 缺失或无效，或组织无权访问 Index REST API。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "未授权" + } + } + } + }, + "Forbidden": { + "description": "API key 不允许该请求 IP。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "该 API key 不允许此 IP 地址" + } + } + } + }, + "RateLimited": { + "description": "组织超出速率限制。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "error": "超出速率限制。请稍后重试" + } + } + } + }, + "InternalError": { + "description": "Index 无法完成请求。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "schemas": { + "ContextRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "format" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "要研究的实现问题。" + }, + "product": { + "type": "string", + "minLength": 1, + "description": "用作额外检索提示的产品或公司名称。" + }, + "format": { + "type": "string", + "enum": [ + "txt", + "json" + ], + "description": "`response` 字符串的格式。`txt` 返回 Markdown 部分，`json` 返回包含结果项目的序列化 JSON 对象。" + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "要纳入检索的域名。" + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "要从检索中排除的域名。" + }, + "tokenBudget": { + "type": "integer", + "minimum": 1, + "maximum": 6000, + "default": 3000, + "description": "输出 token 的最大数量。" + } + } + }, + "ContextResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "query", + "response", + "resultsCount", + "outputTokens" + ], + "properties": { + "requestId": { + "type": "string", + "description": "请求的唯一标识符。" + }, + "query": { + "type": "string", + "description": "请求中的原始查询。" + }, + "response": { + "type": "string", + "description": "组装后的来源内容。对于 `txt` 请求，该值为 Markdown；对于 `json` 请求，该值为序列化 JSON。当没有内容适合 token 预算时，该字符串可以为空。" + }, + "resultsCount": { + "type": "integer", + "minimum": 0, + "description": "响应中包含的来源片段数量。" + }, + "outputTokens": { + "type": "integer", + "minimum": 0, + "description": "组装后响应中的 token 数量。" + } + } + }, + "SearchRequest": { + "type": "object", + "additionalProperties": false, + "required": [ + "query", + "numResults" + ], + "properties": { + "query": { + "type": "string", + "minLength": 1, + "description": "搜索查询。" + }, + "numResults": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "要返回的最大结果数。" + }, + "text": { + "default": false, + "description": "控制结果内容。设置为 `true` 可包含匹配的内容，设置为 `false` 可省略内容，或提供 `maxCharacters` 以包含截断后的内容。省略时默认为 `false`。", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "maxCharacters" + ], + "properties": { + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "每个结果要包含的最大内容字符数。" + } + } + } + ] + }, + "includeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "要包含在搜索结果中的域名。" + }, + "excludeDomains": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "要从搜索结果中排除的域名。" + } + } + }, + "SearchResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results" + ], + "properties": { + "requestId": { + "type": "string", + "description": "请求的唯一标识符。" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "排名后的搜索结果。" + } + } + }, + "SearchResult": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "url", + "title", + "text", + "score", + "source", + "siteName", + "breadcrumbs", + "publishedDate" + ], + "properties": { + "id": { + "type": "string", + "description": "结果标识符。将 Mintlify 结果中的 ID 传入 contents 请求的 `ids` 字段。对于 Web 结果，请将结果 URL 传入 `urls`。" + }, + "url": { + "type": "string", + "format": "uri", + "description": "规范来源 URL。" + }, + "title": { + "type": "string", + "description": "来源标题。" + }, + "text": { + "type": "string", + "description": "请求时返回的匹配内容。否则为空字符串。" + }, + "truncated": { + "type": "boolean", + "description": "返回的内容是否短于可用内容。" + }, + "totalCharacters": { + "type": "integer", + "minimum": 0, + "description": "截断前的可用字符数（如果有）。" + }, + "score": { + "type": "number", + "description": "相对相关性分数。contents 响应使用 `0`，因为它获取的是所选项目，而不是对结果进行排名。" + }, + "source": { + "type": "string", + "enum": [ + "mintlify", + "web" + ], + "description": "检索来源。" + }, + "siteName": { + "type": "string", + "description": "文档站点或 Web 主机名。" + }, + "breadcrumbs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "结果的文档层级。" + }, + "publishedDate": { + "type": "string", + "nullable": true, + "description": "来源提供时的发布日期，否则为 `null`。`search` 结果会将其规范化为完整的 ISO 8601 时间戳。通过 `urls` 获取的 `contents` 结果会原样传递来源的日期字符串，不进行规范化；该字符串可以是完整时间戳，也可以只是日期。" + } + } + }, + "ContentsRequest": { + "type": "object", + "additionalProperties": false, + "description": "至少提供一个 Mintlify 结果 ID 或结果 URL。你可以同时使用两个字段，总计最多 20 项。", + "anyOf": [ + { + "required": [ + "urls" + ] + }, + { + "required": [ + "ids" + ] + } + ], + "properties": { + "urls": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "format": "uri" + }, + "description": "要获取的结果 URL。对于 Web 结果，请使用此字段。" + }, + "ids": { + "type": "array", + "minItems": 1, + "maxItems": 20, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "要获取的 Mintlify 结果 ID。" + }, + "maxCharacters": { + "type": "integer", + "minimum": 1, + "description": "每个结果要返回的最大内容字符数。" + }, + "query": { + "type": "string", + "minLength": 1, + "description": "当内容超过 `maxCharacters` 时，用于选择最相关部分的查询。" + } + } + }, + "ContentsResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "requestId", + "results", + "statuses" + ], + "properties": { + "requestId": { + "type": "string", + "description": "请求的唯一标识符。" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResult" + }, + "description": "成功获取的结果。" + }, + "statuses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentStatus" + }, + "description": "每个请求项目的获取状态。" + } + } + }, + "ContentStatus": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "请求的 ID 或 URL。" + }, + "status": { + "type": "string", + "enum": [ + "success" + ], + "description": "获取状态。" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status", + "error" + ], + "properties": { + "id": { + "type": "string", + "description": "请求的 ID 或 URL。" + }, + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "获取状态。" + }, + "error": { + "type": "object", + "additionalProperties": false, + "required": [ + "tag", + "httpStatusCode" + ], + "properties": { + "tag": { + "type": "string", + "description": "机器可读的错误类别。" + }, + "httpStatusCode": { + "type": "integer", + "nullable": true, + "description": "上游 HTTP 状态码（如果有）。" + } + } + } + } + } + ] + }, + "Error": { + "type": "object", + "additionalProperties": false, + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string", + "description": "错误消息。" + } + } + } + } + } +} diff --git a/zh/search-index/connect.mdx b/zh/search-index/connect.mdx new file mode 100644 index 0000000000..b49fb63fd7 --- /dev/null +++ b/zh/search-index/connect.mdx @@ -0,0 +1,141 @@ +--- +title: "将 Mintlify Index 连接到你的编码代理" +sidebarTitle: "连接" +description: "通过 CLI 或手动配置，在 Claude Code、Cursor、VS Code、Codex、OpenCode、Windsurf 或 Zed 中设置 Mintlify Index MCP 服务器。" +keywords: ["Mintlify Index", "CLI", "Claude Code", "Cursor", "MCP", "技术文档"] +--- + +import { PreviewButton } from "/snippets/zh/previewbutton.jsx" + +将你的编码代理连接到 Mintlify Index，使其可以在规划和编写代码时检索最新的技术文档和 Web 上下文。Index 支持 Claude Code、Cursor、VS Code、Codex、OpenCode、Windsurf 和 Zed。 + + + 连接公开的 Index MCP 服务器不需要 Mintlify 账户或 API key。 + + +
+ ## 使用 CLI 设置 +
+ +运行 Index 设置命令，即可在一个步骤中配置一个或多个编码代理： + +```bash +npx mint index +``` + +该命令会检测已安装的受支持编码代理，并提示你选择要配置的代理。对于每个选中的代理，它会将 Index MCP 服务器添加到该代理的配置中，并安装一条规则，告诉代理何时使用 `context` 工具。 + +要跳过选择器，请改为传入一个或多个代理标志： + +```bash +npx mint index --claude --cursor +``` + +| 标志 | 编码代理 | +| --- | --- | +| `--claude` | Claude Code | +| `--cursor` | Cursor | +| `--vscode` | VS Code | +| `--codex` | Codex | +| `--opencode` | OpenCode | +| `--windsurf` | Windsurf | +| `--zed` | Zed | + + + 添加 `--yes` 可在不提示的情况下配置检测到的所有代理，或添加 `--project` 将配置写入当前项目，而不是全局代理设置。并非所有代理都支持项目级配置；这些代理始终会接收全局配置。 + + +再次运行该命令即可更新现有设置或添加其他代理。 + +
+ ## 手动设置 +
+ +要手动配置 Claude Code 或 Cursor，或确认 CLI 所做的更改，请按照对应代理的步骤操作。 + + + + + + 运行以下命令： + + ```bash + claude mcp add --transport http mintlify-index https://index.mintlify.com + ``` + + + 列出已配置的 MCP 服务器： + + ```bash + claude mcp list + ``` + + 输出应包含状态为已连接的 `mintlify-index`。 + + + + + 选择**在 Cursor 中安装**，检查 MCP 配置，然后批准安装。 + + 在 Cursor 中安装 + + 也可以手动配置 Cursor： + + + + 1. 使用 Command + Shift + P（Windows 上为 Ctrl + Shift + P）打开命令面板。 + 2. 搜索**打开 MCP 设置**。 + 3. 选择**添加自定义 MCP**，打开 `mcp.json`。 + + + 添加以下服务器： + + ```json + { + "mcpServers": { + "mintlify-index": { + "url": "https://index.mintlify.com" + } + } + } + ``` + + + 重新加载 Cursor，然后打开 **Settings → Tools & MCP**（设置 → 工具和 MCP）。`mintlify-index` 服务器应显示为已连接，并且可以使用 `context` 工具。 + + + + + +
+ ## 在会话中使用 Index +
+ +提出实现问题，并告诉代理在你希望确保它检索最新来源时使用 Index。例如： + +```text +Use Mintlify Index to find the current recommended way to configure caching in Next.js 16. Cite the sources you use. +``` + +代理在需要技术上下文时会调用 Index 的 `context` 工具，并在工作中包含返回的来源链接。 + +
+ ## 移除连接 +
+ + + + 运行以下命令： + + ```bash + claude mcp remove mintlify-index + ``` + + + 打开 **Settings → Tools & MCP**（设置 → 工具和 MCP），然后从 `mcp.json` 中删除 `mintlify-index` 条目。 + + + +对于 VS Code、Codex、OpenCode、Windsurf 或 Zed，请从该代理的 MCP 服务器配置中删除 `mintlify-index` 条目。 + +有关工具输入和速率限制，请参阅 [Index MCP 参考](/zh/search-index/mcp)。 diff --git a/zh/search-index/index.mdx b/zh/search-index/index.mdx new file mode 100644 index 0000000000..9248a6a17c --- /dev/null +++ b/zh/search-index/index.mdx @@ -0,0 +1,53 @@ +--- +title: "Mintlify Index" +sidebarTitle: "概览" +description: "通过一个 MCP 服务器或 REST API，为编码代理提供来自发布者维护的文档和 Web 的最新技术上下文。" +keywords: ["Mintlify Index", "技术搜索", "编码代理", "MCP", "REST API"] +--- + +Mintlify Index 为编码代理提供一个统一的技术知识搜索层。它会将关于已索引产品的问题路由到托管在 Mintlify 上、由发布者维护的文档，并使用 Web 搜索处理不属于该语料库的问题。 + +你可以通过公开 MCP 服务器或受访问控制的 REST API 使用 Index。 + +- **MCP 服务器**：连接 AI 工具，让它在你工作时检索带有来源引用的上下文。公开提供，无需 API key。 +- **REST API**：搜索排名后的来源，在 token 预算内组装上下文，或获取所选结果的内容。受访问控制，需要 Index API key。 + +
+ ## 开始使用 +
+ + + + 将 Index 添加到 Claude Code、Codex、Cursor 和其他编码代理。 + + + 查看 `context` 工具、输入字段、输出和速率限制。 + + + 在应用或代理中使用 `search`、`context` 和 `contents`。 + + + +
+ ## Index 如何检索上下文 +
+ + + + Index 会判断问题涉及其文档语料库中的产品，还是需要更广泛的 Web 结果。 + + + 针对特定产品的问题会搜索发布者的最新文档，其他问题则会搜索 Web。 + + + Index 会为结果排序，并返回带有相关内容的来源 URL。MCP 的 `context` 工具和 REST 的 `context` 端点会在 token 预算内组装这些内容。 + + + +
+ ## 选择检索操作 +
+ +- **[`context`](/zh/api/search-index/context)**：适用于大多数代理任务。在一次请求中返回一组紧凑的带引用来源材料。 +- **[`search`](/zh/api/search-index/search)**：当应用需要排名后的结果并自行决定读取哪些来源时使用。可通过 REST API 使用。 +- **[`contents`](/zh/api/search-index/contents)**：在 `search` 之后使用，获取所选 Mintlify 结果 ID 或结果 URL 对应的内容。可通过 REST API 使用。 diff --git a/zh/search-index/mcp.mdx b/zh/search-index/mcp.mdx new file mode 100644 index 0000000000..f8b24f6cfb --- /dev/null +++ b/zh/search-index/mcp.mdx @@ -0,0 +1,85 @@ +--- +title: "Mintlify Index MCP 服务器" +sidebarTitle: "MCP 参考" +description: "公开 Mintlify Index MCP 服务器参考，包括其 context 工具、参数、输出和速率限制。" +keywords: ["Mintlify Index", "MCP 服务器", "context 工具", "速率限制"] +--- + +Mintlify Index MCP 服务器为 AI 工具提供对技术文档和 Web 上下文的只读访问。连接地址为： + +```text +https://index.mintlify.com +``` + +公开服务器无需认证。有关 Claude Code 和 Cursor 的设置说明，请参阅[连接](/zh/search-index/connect)。 + + + Index MCP 会搜索所覆盖产品的文档和技术 Web。若只想搜索特定 Mintlify 托管站点中的内容，请使用该站点的[搜索 MCP 服务器](/zh/ai/model-context-protocol)。 + + +
+ ## `context` 工具 +
+ +使用 `context` 研究实现任务，并在一次调用中返回紧凑且带有来源引用的上下文。该工具为只读工具，可以访问开放 Web。 + + + 要研究的实现问题。 + + + + 用作额外检索提示的产品或公司名称。 + + + + 要纳入检索的域名。设置后，检索结果会限制在这些域名内。 + + + + 要从检索中排除的域名。 + + + + 要返回的最大 token 数。最大值为 `6000`。对于聚焦的问题使用默认值，对于复杂的多部分任务使用更大的预算。 + + +
+ ### 输出 +
+ +该工具返回由排名后的来源组装而成的 Markdown 格式上下文。每个部分都包含标题、来源 URL 和相关来源内容。 + +```text +### Configure caching + +Source: https://nextjs.org/docs/app/getting-started/caching-and-revalidating + +Relevant source content appears here. + +-------------------------------- +``` + +MCP 服务器会返回供已连接代理使用的来源材料。代理决定如何将这些上下文应用到任务中。 + +
+ ## 速率限制 +
+ +Index 对公开 MCP 服务器实施以下按 IP 计算的限制： + +| 时间窗口 | 限制 | +| --- | ---: | +| 每秒 | 10 个请求 | +| 每天 | 1,000 个请求 | + +超过任一限制的请求会返回 `429 Too Many Requests`。请等待后重试，自动化客户端应使用指数退避。 + +
+ ## 协议行为 +
+ +Index MCP 使用无状态的 Streamable HTTP： + +- 将每个 JSON-RPC 请求作为 HTTP `POST` 发送。 +- 每个 HTTP 请求发送一个 JSON-RPC 请求。不支持批处理。 +- 不要在请求之间持久化或发送 MCP 会话 ID。