@feniix/pi-ref-tools

Ref.tools MCP extension for pi — token-efficient documentation search and URL reading via Ref's Model Context Protocol.

Startup is silent in both regular and fullscreen modes. The MCP connection initializes lazily on the first tool call.

Features

• Documentation Search (ref_search_documentation): Search indexed technical documentation for APIs, libraries, and frameworks
• URL Reading (ref_read_url): Fetch and read documentation URLs as optimized markdown
• Configurable Output Limits: Client-side byte and line truncation with adjustable maximums
• Flexible Configuration: JSON config files, environment variables, and CLI flags
• MCP Protocol Support: JSON-RPC 2.0 with server-sent events for response streaming

Install

pi install npm:@feniix/pi-ref-tools

Ephemeral (one-off) use:

pi -e npm:@feniix/pi-ref-tools

Configuration

You need a Ref API key from ref.tools/keys.

Option 1: Environment Variable

export REF_API_KEY="your_key"

Option 2: Settings File

Use pi's standard settings locations for non-secret configuration:

• project: .pi/settings.json
• global: ~/.pi/agent/settings.json

Under the pi-ref-tools key:

{
  "pi-ref-tools": {
    "url": "https://api.ref.tools/mcp",
    "timeoutMs": 30000,
    "protocolVersion": "2025-06-18",
    "maxBytes": 51200,
    "maxLines": 2000
  }
}

Best practice: use settings.json for non-secret defaults only. Keep REF_API_KEY in an environment variable, or use --ref-mcp-config-file / REF_MCP_CONFIG_FILE to point to a custom private JSON config file when you need to persist secrets outside your project. Legacy aliases --ref-mcp-config and REF_MCP_CONFIG are still accepted but deprecated.

Option 3: CLI Flags

pi --ref-mcp-api-key=your_key

Config Resolution Order

1. --ref-mcp-config-file flag path
2. REF_MCP_CONFIG_FILE environment variable
3. legacy --ref-mcp-config flag path (deprecated)
4. legacy REF_MCP_CONFIG environment variable (deprecated)
5. .pi/settings.json under pi-ref-tools (project-level)
6. ~/.pi/agent/settings.json under pi-ref-tools (global)

Tools

ref_search_documentation

Search indexed technical documentation. Best for API docs, library references, and framework guides.

Parameter	Type	Required	Description
query	string	yes	Search query. Include language/framework names for best results.
piMaxBytes	integer	no	Client-side max bytes override (clamped by config).
piMaxLines	integer	no	Client-side max lines override (clamped by config).

ref_read_url

Read a documentation URL and return optimized markdown. Pass the exact URL from a search result or any documentation page.

Parameter	Type	Required	Description
url	string	yes	The exact URL of the documentation page to read.
piMaxBytes	integer	no	Client-side max bytes override (clamped by config).
piMaxLines	integer	no	Client-side max lines override (clamped by config).

CLI Flags

Flag	Env Variable	Default	Description
--ref-mcp-url	REF_MCP_URL	https://api.ref.tools/mcp	MCP endpoint URL
--ref-mcp-api-key	REF_API_KEY	—	API key (sent as x-ref-api-key header)
--ref-mcp-timeout-ms	REF_MCP_TIMEOUT_MS	30000	HTTP timeout in ms
--ref-mcp-protocol	REF_MCP_PROTOCOL_VERSION	2025-06-18	MCP protocol version
--ref-mcp-config-file	REF_MCP_CONFIG_FILE	—	Custom config file path
--ref-mcp-config	REF_MCP_CONFIG	—	Deprecated alias for the config file path
--ref-mcp-max-bytes	REF_MCP_MAX_BYTES	51200	Max output bytes
--ref-mcp-max-lines	REF_MCP_MAX_LINES	2000	Max output lines

Output Truncation

Default limits: 51,200 bytes, 2,000 lines. Per-call overrides via piMaxBytes/piMaxLines parameters are clamped to the configured maximums. Truncated content is saved to temporary files with paths included in responses.

Requirements

• pi v0.51.0 or later
• Ref API key from ref.tools/keys

Uninstall

pi remove npm:@feniix/pi-ref-tools

License

MIT