# ![rtfd-pi logo](https://github.com/aserper/rtfd-pi/raw/master/logo.png?v=4)
[![Tests](https://img.shields.io/github/actions/workflow/status/aserper/rtfd-pi/ci.yml?style=for-the-badge&logo=github&label=Tests)](https://github.com/aserper/rtfd-pi/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/rtfd-pi?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/rtfd-pi)
[![License: MIT](https://img.shields.io/npm/l/rtfd-pi?style=for-the-badge)](https://github.com/aserper/rtfd-pi/blob/master/LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet?style=for-the-badge)](https://pi.dev/packages)

[![GitHub stars](https://img.shields.io/github/stars/aserper/rtfd-pi?style=social)](https://github.com/aserper/rtfd-pi/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/aserper/rtfd-pi?style=social)](https://github.com/aserper/rtfd-pi/forks)


Native [pi](https://github.com/earendil-works/pi-coding-agent) extension port of the [RTFD](https://github.com/aserper/RTFD) MCP server — feed your coding agent up-to-date documentation from PyPI, npm, crates.io, GoDocs, DockerHub, GitHub, GCP, Zig, and LogScale, without a cloud service or API key.

RTFD runs entirely on your machine. Queries go straight to the source, and the documentation you fetch never leaves your system. This extension brings that same functionality to the pi coding agent as a **native extension** — no MCP server process, no `mcp.json` entry, just a symlink and pi auto-discovers it.

## Why?

LLMs hallucinate APIs and ship outdated code because their training data is months or years old. RTFD gives agents access to the *actual* current documentation for a library, image, or service, so generated code uses correct, version-specific APIs instead of guessed ones.

- **Accurate**: fetch live READMEs, metadata, and version info straight from the source.
- **Private**: runs locally; your queries go directly to the upstream registry, nothing in the middle.
- **No API keys**: uses public endpoints (optional `GITHUB_TOKEN` / `gh` for higher rate limits).
- **10 providers, 30+ tools**: one provider per ecosystem, plus cross-ecosystem aggregation and chunked streaming.

## Providers & tools

| Provider | Example tools |
|----------|---------------|
| **PyPI** | `pypi_metadata`, `fetch_pypi_docs` |
| **npm** | `npm_metadata`, `fetch_npm_docs` |
| **crates.io** | `search_crates`, `crates_metadata` |
| **GoDocs** | `godocs_metadata`, `fetch_godocs_docs` |
| **Zig** | `zig_docs` |
| **DockerHub** | `search_docker_images`, `docker_image_metadata`, `fetch_docker_image_docs`, `fetch_dockerfile` |
| **GitHub** | `github_repo_search`, `github_code_search`, `fetch_github_readme`, `get_repo_tree`, `list_repo_contents`, `get_file_content`, `get_commit_diff`, `list_github_packages`, `get_package_versions` |
| **GCP** | `search_gcp_services`, `fetch_gcp_service_docs` |
| **LogScale** | `search_logscale_docs`, `list_logscale_functions`, `logscale_syntax`, `logscale_function` |
| **Aggregator** | `search_library_docs` (PyPI + npm + crates + GoDocs + GitHub at once) |
| **Server** | `get_cache_info`, `get_cache_entries`, `get_next_chunk` |

Large responses are chunked with a continuation token — call `get_next_chunk` to retrieve the next slice.

## Install

### Prerequisites

- The [pi coding agent](https://github.com/earendil-works/pi-coding-agent) (peer dependency).
- Node.js with npm.

### From npm (recommended)

```bash
pi install npm:rtfd-pi
```

Restart pi (or run `/reload`) and the tools are available — no `-e` flag or `mcp.json` entry needed. Pi installs the package under `~/.pi/agent/npm/` and auto-discovers the extension via the `pi.extensions` manifest.

### From git

```bash
pi install git:github.com/aserper/rtfd-pi
# or
pi install https://github.com/aserper/rtfd-pi
```

### As a local extension (developer setup)

```bash
git clone https://github.com/aserper/rtfd-pi.git ~/projects/rtfd-pi
cd ~/projects/rtfd-pi
npm install

# Link into pi's extensions directory so pi auto-discovers it
ln -s ~/projects/rtfd-pi ~/.pi/agent/extensions/rtfd-pi
```

Restart pi and the tools are available — no `-e` flag or `mcp.json` entry needed.

## Configuration

All configuration is via environment variables (read by the pi process). Defaults match the original RTFD MCP server.

| Variable | Default | Purpose |
|----------|---------|---------|
| `RTFD_FETCH` | `true` | Set `false` to disable all content fetching (metadata-only mode). |
| `RTFD_CACHE_ENABLED` | `true` | Enable the in-memory response cache. |
| `RTFD_CACHE_TTL` | `604800` | Cache TTL in seconds (1 week). |
| `RTFD_CHUNK_TOKENS` | provider-specific | Max tokens per chunked response. |
| `GITHUB_TOKEN` | — | GitHub token for higher rate limits. |
| `GITHUB_AUTH` | `token` | `token` (use `GITHUB_TOKEN`), `cli` (use `gh auth token`), `auto` (token then `gh`), or `disabled`. |

### GitHub auth tip

For the GitHub provider's tools to work with higher rate limits, set:

```bash
export GITHUB_AUTH=auto        # falls back to `gh auth token` if GITHUB_TOKEN is unset
# or, explicitly:
export GITHUB_TOKEN=gho_...    # a personal access token
```

If `gh` is installed and authenticated, `GITHUB_AUTH=auto` will pick up its token automatically.

## Development

```bash
npm test              # run the vitest suite
npm run test:watch    # watch mode
npm run test:unit     # shared/ unit tests only
npm run typecheck     # tsc --noEmit
```

The test suite includes parity tests against the original Python RTFD server's output shape, plus golden-fixture tests for the providers with recorded cassettes (PyPI, npm, crates).

### Project layout

```
src/
  providers/      # one file per ecosystem (pypi, npm, crates, github, ...)
  shared/         # http, cache, chunking, env, tokens, content extraction
  tools/          # server-level tools: search_library_docs, cache admin, get_next_chunk
  index.ts        # extension factory — registers all provider + server tools
tests/
  parity/         # parity tests vs. the python RTFD server
fixtures/         # recorded HTTP cassettes (pypi, npm, crates)
docs/             # PORT-SPEC, PLAN, AUDIT-FINDINGS
```

## How it works

Each provider exposes its upstream API as a set of pi tools. The shared HTTP client and cache are singletons, so all providers share one cache and one chunking manager. `search_library_docs` fans out across PyPI, npm, crates.io, GoDocs, and GitHub in a single call. Large responses are token-counted and chunked; `get_next_chunk` retrieves successive slices via a shared continuation-token store.

## Security note

This extension grants agents access to unverified content from external sources (GitHub, PyPI, etc.). That introduces risks including **indirect prompt injection**. Use `RTFD_FETCH=false` to restrict to metadata-only lookups, and review fetched content before acting on it in autonomous modes.

## Releasing

Releases are automated through GitHub Actions. To publish a new version to npm:

```bash
npm version patch   # or minor / major — bumps package.json, commits, tags vX.Y.Z
git push --follow-tags
```

Pushing the `v*` tag triggers the [Release workflow](.github/workflows/release.yml), which runs typecheck + tests, then publishes to npm with provenance. GitHub and npm versions stay in lockstep because the tag matches `package.json`.

The `NPM_TOKEN` repo secret must be set (see [GitHub Actions secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)) with a granular npm access token that has publish rights to `rtfd-pi`.

## License

MIT — see [LICENSE](LICENSE).