@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