Ref MCP Server

offiziell

Aktuelle Dokumentation für Ihren Codierungsagenten. Deckt Tausende öffentlicher Repos und Websites ab. Entwickelt von ref.tools

GitHub
1.1k

Dokumentation

Documentation for your agent smithery badge Website License npm version

Ref MCP

Ein ModelContextProtocol-Server, der Ihrem KI-Coding-Tool oder Agenten Zugriff auf Dokumentation für APIs, Dienste, Bibliotheken usw. gewährt. Er ist Ihre zentrale Anlaufstelle, um Ihren Agenten schnell und token-effizient über Dokumentation auf dem Laufenden zu halten.

Weitere Informationen finden Sie unter ref.tools

Agentische Suche nach genau dem richtigen Kontext

Die Werkzeuge von Ref sind darauf ausgelegt, der Art und Weise zu entsprechen, wie Modelle suchen, und dabei so wenig Kontext wie möglich zu verwenden, um Kontextverfall zu reduzieren. Das Ziel ist es, genau den Kontext zu finden, den Ihr Coding-Agent für den Erfolg benötigt, und dabei ein Minimum an Tokens zu verbrauchen.

Abhängig von der Komplexität der Eingabeaufforderung führen LLM-Coding-Agenten wie Claude Code typischerweise eine oder mehrere Suchen durch und wählen dann einige Ressourcen aus, um sie detaillierter zu lesen.

Für eine einfache Abfrage zur Figma Comment REST API wird es ein paar Aufrufe tätigen, um genau das zu bekommen, was es benötigt:

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

In komplexeren Situationen wird das LLM versuchen, seine Eingabeaufforderung zu verfeinern, während es Ergebnisse liest. Zum Beispiel:

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 nutzt MCP-Sitzungen, um den Suchverlauf zu verfolgen und die Kontextnutzung zu minimieren. Es gibt noch viele weitere Ideen in der Entwicklung, aber hier ist, was wir bisher implementiert haben.

1. Filtern von Suchergebnissen

Bei wiederholten ähnlichen Suchen in einer Sitzung liefert Ref niemals wiederholte Ergebnisse zurück. Traditionell gräbt man sich tiefer in die Suchergebnisse ein, indem man zur nächsten Seite blättert, aber dieser Ansatz erlaubt es dem Agenten, gleichzeitig zu blättern UND die Eingabeaufforderung anzupassen.

2. Abrufen des relevanten Teils der Seite

Beim Lesen einer Dokumentationsseite nutzt Ref den Sitzungssuchverlauf des Agenten, um weniger relevante Abschnitte auszublenden und die relevantesten 5k Tokens zurückzugeben. Dies hilft Ref, ein großes Problem beim standardmäßigen fetch() Web Scraping zu vermeiden, bei dem man bei großen Dokumentationsseiten leicht 20k+ Tokens in den Kontext ziehen kann, von denen die meisten irrelevant sind.

Warum ist die Minimierung von Tokens aus dem Dokumentationskontext wichtig?

1. Mehr Kontext macht Modelle dümmer

Es ist gut dokumentiert, dass Modelle (Stand Juli 2025) dümmer werden, je mehr Tokens man eingibt. Sie haben vielleicht gehört, dass Modelle jetzt großartig mit langem Kontext umgehen können, und das stimmt teilweise, ist aber nicht das ganze Bild. Für eine kurze Einführung in einige Forschungsergebnisse schauen Sie sich dieses Video vom Team bei Chroma an.

2. Tokens kosten $$$

Stellen Sie sich vor, Sie verwenden Claude Opus als Hintergrundagenten und lassen den Agenten zunächst Dokumentationskontext abrufen. Angenommen, er ruft 10000 Tokens Kontext ab, wovon 4000 relevant und 6000 zusätzliches Rauschen sind. Bei API-Preisen kosten diese 6k Tokens etwa 0,09 $ PRO SCHRITT. Wenn eine Eingabeaufforderung am Ende 11 Schritte mit Opus benötigt, haben Sie 1 $ für nichts ausgegeben.

Einrichtung

Es gibt zwei Optionen für die Einrichtung von Ref als MCP-Server, entweder über den Streamable-HTTP-Server (empfohlen) oder den lokalen stdio-Server (veraltet).

Dieses Repository enthält den veralteten stdio-Server.

Streamable HTTP (empfohlen)

Install Ref MCP in Cursor

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

stdio

Install Ref MCP in Cursor (stdio)

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

Werkzeuge

Der Ref MCP-Server stellt alle dokumentationsbezogenen Werkzeuge für die Bedürfnisse Ihres Agenten bereit.

ref_search_documentation

Ein leistungsstarkes Suchwerkzeug zur Überprüfung technischer Dokumentation. Hervorragend geeignet, um Fakten oder Code-Snippets zu finden. Kann verwendet werden, um öffentliche Dokumentation im Web oder auf GitHub sowie private Ressourcen wie Repos und PDFs zu durchsuchen.

Parameter:

  • query (erforderlich): Suchanfrage, um relevante Dokumentation zu finden. Dies sollte ein vollständiger Satz oder eine Frage sein.

ref_read_url

Ein Werkzeug, das Inhalte von einer URL abruft und zur einfachen Lesbarkeit mit Ref in Markdown konvertiert. Dies ist leistungsstark in Verbindung mit dem ref_search_documentation-Werkzeug, das URLs relevanter Inhalte zurückgibt.

Parameter:

  • url (erforderlich): Die URL der zu lesenden Webseite.

OpenAI Deep Research Unterstützung

Ref kann als Quelle für Deep Research verwendet werden. OpenAI erfordert spezifische Werkzeugdefinitionen, daher stellt Ref bei Verwendung mit einem OpenAI-Client dieselben Werkzeuge mit leicht unterschiedlicher Benennung bereit.

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

Entwicklung

npm install
npm run dev

Ausführen mit Inspector

Für Entwicklungs- und Debugging-Zwecke können Sie das MCP Inspector-Tool verwenden. Der Inspector bietet eine visuelle Schnittstelle zum Testen und Überwachen von MCP-Server-Interaktionen.

Besuchen Sie die Inspector-Dokumentation für detaillierte Einrichtungsanweisungen.

Zum lokalen Testen mit Inspector:

npm run inspect

Oder führen Sie sowohl den Watcher als auch den Inspector aus:

npm run dev

Lokale Entwicklung

  1. Repository klonen
  2. Abhängigkeiten installieren:
npm install
  1. Projekt bauen:
npm run build
  1. Für Entwicklung mit automatischem Neubau:
npm run watch

Lizenz

MIT