refdocs

refdocs answers documentation questions and turns web pages into something an agent can actually read. Search runs across public technical documentation and GitHub for the facts or code snippet behind a question, and any URL can be fetched and handed back as clean markdown instead of raw HTML.

It is one small program with two faces: a command-line tool for quick lookups, and a stdio MCP server that gives agents the same two operations as tools.

Configuration

Both operations require a Ref API key:

export REF_API_KEY="your-key-here"

The search endpoint defaults to https://api.ref.tools. Override it with REF_API_BASE_URL when you are pointing at another deployment. The key is checked before any request is made; when it is missing the tool fails with an error that names REF_API_KEY.

Install

npx @reneturcios/refdocs search "How do I stream a response with fetch?"

Or run the container image:

docker run -i -e REF_API_KEY ghcr.io/cloudcorprecords/refdocs

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Search the documentation
refdocs search "How do I use the cache API in Next.js?"
refdocs search "What does this error mean?" --json

# Read a page as markdown
refdocs read https://example.test/some/guide
refdocs read https://example.test/some/guide --json

# Check the configuration without making a request
refdocs check

refdocs --version

Exit codes: 0 on success, 1 when a lookup fails or the configuration is not ready (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/refdocs mcp

MCP client configuration:

{
  "mcpServers": {
    "refdocs": {
      "command": "npx",
      "args": ["-y", "@reneturcios/refdocs", "mcp"],
      "env": {
        "REF_API_KEY": "your-key-here"
      }
    }
  }
}

Tools

Search responses are parsed tolerantly: a bare array, a results list, and a documents list are all accepted. Reading plain-text URLs returns the text unchanged.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

Tests run entirely against a fake fetch function; no live API calls are made.

License

MIT — see LICENSE.