Ref MCP Server

Ref MCP

Un serveur ModelContextProtocol qui donne à votre outil de codage IA ou agent l'accès à la documentation des API, services, bibliothèques, etc. C'est votre guichet unique pour maintenir votre agent à jour sur la documentation de manière rapide et économe en tokens.

Pour plus d'informations, consultez ref.tools

Recherche agentique pour le contexte exact

Les outils de Ref sont conçus pour correspondre à la façon dont les modèles recherchent tout en utilisant le moins de contexte possible afin de réduire la dégradation du contexte. L'objectif est de trouver exactement le contexte dont votre agent de codage a besoin pour réussir tout en utilisant un minimum de tokens.

Selon la complexité de l'invite, les agents de codage LLM comme Claude Code effectueront généralement une ou plusieurs recherches, puis choisiront quelques ressources à lire plus en profondeur.

Pour une requête simple sur l'API REST Comment de Figma, il effectuera quelques appels pour obtenir exactement ce dont il a besoin :

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

Pour des situations plus complexes, le LLM essaiera d'affiner son invite au fur et à mesure qu'il lit les résultats. Par exemple :

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref tire parti des sessions MCP pour suivre la trajectoire de recherche et minimiser l'utilisation du contexte. Il y a beaucoup d'autres idées en préparation, mais voici ce que nous avons implémenté jusqu'à présent.

1. Filtrage des résultats de recherche

Pour des recherches similaires répétées dans une session, Ref ne renverra jamais de résultats répétés. Traditionnellement, on approfondit les résultats de recherche en passant à la page suivante, mais cette approche permet à l'agent de paginer ET d'ajuster l'invite en même temps.

2. Récupération de la partie pertinente de la page

Lors de la lecture d'une page de documentation, Ref utilise l'historique de recherche de session de l'agent pour supprimer les sections moins pertinentes et renvoyer les 5k tokens les plus pertinents. Cela aide Ref à éviter un gros problème avec le scraping web standard fetch() : lorsqu'il atteint une grande page de documentation, vous pouvez facilement vous retrouver avec plus de 20k tokens dans le contexte, dont la plupart ne sont pas pertinents.

Pourquoi minimiser les tokens du contexte de documentation est important ?

1. Plus de contexte rend les modèles moins intelligents

Il est bien documenté qu'en juillet 2025, les modèles deviennent moins intelligents à mesure que vous ajoutez plus de tokens. Vous avez peut-être entendu dire que les modèles sont désormais excellents avec un contexte long, et c'est en partie vrai, mais ce n'est pas toute l'histoire. Pour une introduction rapide à certaines recherches, regardez cette vidéo de l'équipe Chroma.

2. Les tokens coûtent cher

Imaginez que vous utilisez Claude Opus comme agent d'arrière-plan et que vous commencez par lui faire extraire du contexte de documentation. Supposons qu'il extraie 10000 tokens de contexte, dont 4000 pertinents et 6000 de bruit supplémentaire. Au prix de l'API, ces 6k tokens coûtent environ 0,09 $ PAR ÉTAPE. Si une invite finit par prendre 11 étapes avec Opus, vous avez dépensé 1 $ pour rien.

Configuration

Il existe deux options pour configurer Ref en tant que serveur MCP : soit via le serveur HTTP streamable (recommandé), soit via le serveur stdio local (hérité).

Ce dépôt contient le serveur stdio hérité.

HTTP streamable (recommandé)

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

Outils

Le serveur Ref MCP fournit tous les outils liés à la documentation pour les besoins de votre agent.

ref_search_documentation

Un outil de recherche puissant pour consulter la documentation technique. Idéal pour trouver des faits ou des extraits de code. Peut être utilisé pour rechercher de la documentation publique sur le web ou GitHub, ainsi que des ressources privées comme des dépôts et des PDF.

Paramètres :

• query (obligatoire) : Requête pour rechercher la documentation pertinente. Cela doit être une phrase complète ou une question.

ref_read_url

Un outil qui récupère le contenu d'une URL et le convertit en markdown pour une lecture facile avec Ref. Cet outil est puissant lorsqu'il est utilisé conjointement avec l'outil ref_search_documentation qui renvoie les URL du contenu pertinent.

Paramètres :

• url (obligatoire) : L'URL de la page web à lire.

Support de la recherche approfondie OpenAI

Ref peut être utilisé comme source pour la recherche approfondie. OpenAI nécessite des définitions d'outils spécifiques, donc lorsqu'il est utilisé avec un client OpenAI, Ref fournira les mêmes outils avec des noms légèrement différents.

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

Développement

npm install
npm run dev

Exécution avec Inspector

À des fins de développement et de débogage, vous pouvez utiliser l'outil MCP Inspector. L'Inspector fournit une interface visuelle pour tester et surveiller les interactions du serveur MCP.

Consultez la documentation d'Inspector pour des instructions de configuration détaillées.

Pour tester localement avec Inspector :

npm run inspect

Ou exécutez à la fois le surveillant et l'inspecteur :

npm run dev

Développement local

1. Cloner le dépôt
2. Installer les dépendances :

npm install

3. Construire le projet :

npm run build

4. Pour le développement avec reconstruction automatique :

npm run watch

Licence

MIT