@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