# 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:

```bash
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

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

Or run the container image:

```bash
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

```bash
# 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:

```bash
npx -y @reneturcios/refdocs mcp
```

MCP client configuration:

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

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `ref_search_documentation` | `query` (string, required) — a full sentence or question to search for | Matching documentation results from public documentation and GitHub, each with its title, URL, and content or snippet when the upstream provides them. |
| `ref_read_url` | `url` (string, required) — the URL of the webpage to read | The page content converted to markdown: headings, links, lists, emphasis, and code blocks are kept in markdown form, while scripts, styles, and other non-content markup are dropped. |

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

```bash
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`.