ref-tools/ref-tools-mcp

Helping coding agents never make mistakes working with public or private libraries without wasting the context window.

Ref MCP – a Model‑Context‑Protocol server for documentation lookup

What it is – Ref MCP is a small Node‑JS service that implements the Model Context Protocol (MCP). It lets an LLM‑powered coding assistant (e.g., Claude Code, Cursor) fetch only the parts of API or library documentation that are actually needed, keeping the token count low and the cost down.

Why it matters – When an agent searches the web for a function signature or usage example, the raw HTML can be tens of thousands of tokens. Feeding all of that to the model wastes context, makes the model’s reasoning noisier, and raises API costs. Ref MCP solves this by:

  1. Search‑first – the agent asks ref_search_documentation with a natural‑language query. Ref returns a short list of URLs that match.
  2. Selective read – the agent then calls ref_read_url. Ref uses the session’s search history to trim the page down to the most relevant ~5 k tokens, discarding unrelated sections.
  3. Session awareness – repeated searches in the same MCP session are de‑duplicated and the server remembers which parts of a page have already been read, further reducing token waste.

Core tools exposed via MCP

Tool Purpose Parameters
ref_search_documentation (alias search) Full‑text search over public docs, GitHub repos, PDFs, etc. query – a sentence or question describing what the agent needs
ref_read_url (alias fetch) Fetch a URL and return a markdown‑ified, relevance‑filtered excerpt url – the page to read

How to run it

  • Streamable‑HTTP server (recommended) – Deploy the server at https://api.ref.tools/mcp and point your agent to it via a simple JSON config.
  • Legacy stdio server – Run locally with npx ref-tools-mcp@latest. The repository contains the code for this mode.

Both modes require an API key (REF_API_KEY) that you obtain from ref.tools.

Typical workflow example

Agent: SEARCH "Figma API post comment endpoint documentation"
Ref MCP → returns the Figma docs URL (≈54 tokens)
Agent: READ https://www.figma.com/developers/api#post-comments-endpoint
Ref MCP → returns only the 385‑token snippet that actually describes the endpoint

For more involved queries the agent can interleave additional searches and reads, with Ref remembering the session state to avoid duplicate results.

Development & debugging

  • npm run dev – start the server with hot‑reloading.
  • npm run inspect – launch the MCP Inspector UI for visual testing of tool calls.
  • Standard Node scripts (build, watch, etc.) are provided.

License – MIT, so you can freely embed or modify the server in your own AI tooling stack.

Bottom line – Ref MCP is a practical, token‑efficient bridge between LLM agents and the ever‑growing sea of technical documentation, letting agents stay up‑to‑date without drowning in irrelevant text.

Related

  • Project
    laude-institute/headlong

    Headlong is a Bash‑based micro‑harness that runs a continuously thinking LLM‑backed agent. The core `shellm` engine lets the model write Bash commands, executes them, and feeds the output back as context. Agents persistently generate thoughts, can be accessed via Slack, Telegram, or a web dashboard, and store their entire history as a JSON‑L DAG with tiered summarisation. Installation is a one‑liner that sets up Docker sandboxing (or host mode) and a unified `llm` CLI for Anthropic, OpenAI, Gemini, OpenRouter, or any local OpenAI‑compatible server (Ollama, llama.cpp, vLLM, etc.). The framework emphasizes tiny, composable Bash tools, self‑improvement via fork‑test‑merge, and safety via sandboxing and spend‑capped API keys.

  • Project
    Spielewoy/autoprompt-skill

    Autoprompt‑Skill is a Node‑based CLI that wraps multiple LLM coding agents (Claude, Codex, OpenCode, etc.) to automate the write‑test‑review loop. Install via npm, pick a provider, and run `autoprompt activate PROVIDER -- "<goal>"` (optionally with `path=` and concurrency flags). Benchmarks on Terminal‑Bench 2.1 show a 45 % drop in failures (73/89 solves vs. 60/89) at the cost of higher runtime and token usage.

  • Project
    zilliztech/VectorDBBench

    VectorDBBench is a Python CLI tool that benchmarks insertion, vector search, filtered search, and full‑text BM25 retrieval across many open‑source and cloud vector databases. It ships with standard ANN datasets (SIFT, GIST, Cohere, OpenAI embeddings) and newer multimodal Hugging Face datasets, reports latency/recall/QPS and cloud cost, and offers a visual UI for comparing results.

  • Project
    volcengine/SearchCLI

    SearchCLI is a command‑line client for Volcengine’s AI Search service. It lets you manage datasets, create search apps, and run search, recommendation, and chat‑style retrieval from the terminal. The tool also supports LLM‑based relevance judging and provides “Viking skills” – installable command bundles that external AI agents can invoke, enabling automated data onboarding, configuration, and quality‑verification workflows.