Skip to main content
Glama
deenesjakoruzh
ref-tools

Ref

by ref-tools
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Dokumentation für Ihren Agenten Website Lizenz npm version

Ref MCP

Ein ModelContextProtocol-Server, der Ihrem KI-Coding-Tool oder Agenten Zugriff auf Dokumentationen für APIs, Dienste, Bibliotheken usw. gewährt. Es ist Ihre zentrale Anlaufstelle, um Ihren Agenten schnell und token-effizient mit aktueller Dokumentation zu versorgen.

Weitere Informationen finden Sie unter ref.tools

Agentische Suche für genau den richtigen Kontext

Die Tools von Ref sind darauf ausgelegt, die Suchweise von Modellen nachzuahmen und dabei so wenig Kontext wie möglich zu verbrauchen, um Context Rot zu reduzieren. Das Ziel ist es, genau den Kontext zu finden, den Ihr Coding-Agent benötigt, um erfolgreich zu sein, während die Anzahl der verwendeten Token minimiert wird.

Je nach Komplexität des Prompts führen LLM-Coding-Agenten wie Claude Code normalerweise eine oder mehrere Suchen durch und wählen dann einige Ressourcen aus, um sie genauer zu lesen.

Für eine einfache Anfrage zur Figma Comment REST API werden ein paar Aufrufe getätigt, um genau das zu erhalten, was benötigt wird:

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

Für komplexere Situationen versucht das LLM, seinen Prompt während des Lesens der Ergebnisse zu verfeinern. 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 den Kontextverbrauch zu minimieren. Es sind noch viele weitere Ideen in Arbeit, aber hier ist das, was wir bisher implementiert haben.

1. Filtern von Suchergebnissen

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

2. Abrufen des relevanten Teils der Seite

Beim Lesen einer Dokumentationsseite verwendet Ref den Suchverlauf der Agentensitzung, um weniger relevante Abschnitte auszublenden und die relevantesten 5k Token zurückzugeben. Dies hilft Ref, ein großes Problem beim Standard-fetch()-Web-Scraping zu vermeiden: Wenn eine große Dokumentationsseite aufgerufen wird, können leicht 20k+ Token in den Kontext geladen werden, von denen die meisten irrelevant sind.

Related MCP server: graphpilot

Warum ist die Minimierung von Token aus dem Dokumentationskontext wichtig?

1. Mehr Kontext macht Modelle dümmer

Es ist seit Juli 2025 gut dokumentiert, dass Modelle dümmer werden, je mehr Token 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 sehen Sie sich dieses Video vom Team bei Chroma an.

2. Token kosten $$$

Stellen Sie sich vor, Sie verwenden Claude Opus als Hintergrund-Agenten und lassen den Agenten Dokumentationskontext abrufen. Angenommen, er zieht 10.000 Token Kontext, wobei 4.000 relevant sind und 6.000 zusätzliches Rauschen darstellen. Bei den API-Preisen kosten diese 6k Token etwa 0,09 $ PRO SCHRITT. Wenn ein Prompt am Ende 11 Schritte mit Opus erfordert, haben Sie 1 $ ohne Grund 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 Repo 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>
  }
}

Tools

Der Ref MCP-Server bietet alle dokumentationsbezogenen Tools, die Ihr Agent benötigt.

ref_search_documentation

Ein leistungsstarkes Suchwerkzeug zur Überprüfung technischer Dokumentationen. Großartig zum Finden von Fakten oder Code-Snippets. Kann verwendet werden, um öffentliche Dokumentationen im Web oder auf GitHub sowie private Ressourcen wie Repos und PDFs zu durchsuchen.

Parameter:

  • query (erforderlich): Suchanfrage für relevante Dokumentation. Dies sollte ein vollständiger Satz oder eine Frage sein.

ref_read_url

Ein Tool, das Inhalte von einer URL abruft und für das einfache Lesen mit Ref in Markdown konvertiert. Dies ist besonders leistungsstark in Verbindung mit dem Tool ref_search_documentation, das URLs relevanter Inhalte zurückgibt.

Parameter:

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

Unterstützung für OpenAI Deep Research

Ref kann als Quelle für Deep Research verwendet werden. OpenAI erfordert spezifische Tool-Definitionen. Wenn Ref also mit einem OpenAI-Client verwendet wird, stellt es dieselben Tools mit leicht abweichenden Namen bereit.

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

Entwicklung

npm install
npm run dev

Ausführung 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. Klonen Sie das Repository

  2. Installieren Sie die Abhängigkeiten:

npm install

  1. Bauen Sie das Projekt:

npm run build

  1. Für die Entwicklung mit automatischem Neuaufbau:

npm run watch

Lizenz

MIT

Available Tools

2 tools
ref_read_urlAInspect

Read the content of a url as markdown. The entire exact URL from a Ref 'ref_search_documentation' result should be passed to this tool to read it.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL of the webpage to read.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool reads content and converts it to markdown, but lacks details on error handling, rate limits, authentication needs, or output format. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured in two sentences. The first sentence states the core purpose, and the second provides usage context. There is no wasted language, making it front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (reading and converting web content) and lack of annotations or output schema, the description is adequate but incomplete. It covers purpose and basic usage but omits behavioral details like error cases or output specifics, leaving room for improvement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the parameter 'url' documented as 'The URL of the webpage to read.' The description adds minimal value beyond this by specifying that the URL should come from 'ref_search_documentation' results, but does not provide additional syntax or format details. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read the content of a url as markdown.' It specifies the verb ('Read') and resource ('content of a url'), making the action explicit. However, it does not explicitly distinguish this tool from its sibling 'ref_search_documentation', which likely searches rather than reads content, so it misses full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: 'The entire exact URL from a Ref 'ref_search_documentation' result should be passed to this tool to read it.' This implies usage after obtaining a URL from the sibling tool, offering a workflow guideline. However, it does not specify when not to use it or alternatives, keeping it from a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ref_search_documentationBInspect

Search for documentation on the web or github as well from private resources like repos and pdfs. Use Ref 'ref_read_url' to read the content of a url.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesQuery for documentation. Should include programming language and framework or library names. Searches public only docs by default, include ref_src=private to search a user's private docs.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only mentions searching capabilities and a related tool. It fails to disclose critical behavioral traits like whether this is a read-only operation, potential rate limits, authentication needs for private resources, or what the search results look like (e.g., format, pagination).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences that directly state the tool's function and a usage tip. It's front-loaded and avoids unnecessary words, though it could be slightly more structured for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a search tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., search results format), how private resources are accessed, or error handling, leaving significant gaps for an AI agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, fully describing the single 'query' parameter with details on including language/framework names and the 'ref_src=private' option. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as searching for documentation across web, GitHub, and private resources, which is specific and actionable. However, it doesn't explicitly differentiate from its sibling 'ref_read_url', which is for reading URL content rather than searching, so it misses full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning 'ref_read_url' for reading content, suggesting a workflow, but lacks explicit guidance on when to use this tool versus alternatives or any exclusions. It provides some context but no clear when/when-not rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: ref_search_documentation finds documentation resources, while ref_read_url reads the content of specific URLs. There is no overlap or ambiguity between searching and reading operations.

Naming Consistency5/5

Both tools follow a consistent 'ref_verb_noun' naming pattern with snake_case. The prefix 'ref_' provides clear namespace identification, and the verb-noun structure (search_documentation, read_url) is uniform and predictable.

Tool Count3/5

With only two tools, the server feels minimal but functional for its documentation search/read purpose. While it covers core workflows, the count is borderline thin—additional tools for filtering, saving, or managing searches might enhance completeness without overcomplication.

Completeness4/5

The tool set covers the essential documentation workflow: searching and reading. However, there are minor gaps, such as no tools for saving results, filtering searches, or managing cached content, which agents might need to work around for advanced use cases.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ref-tools/ref-tools-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server