@feniix/pi-ref-tools

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

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