ref_read_url
Extracts and converts webpage content into markdown format using a provided URL. Ideal for processing documentation links from 'ref_search_documentation' results for easy reading and integration.
Instructions
Read the content of a url as markdown. The entire exact URL from a Ref 'ref_search_documentation' result should be passed to this tool to read it.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL of the webpage to read. |
Implementation Reference
- index.ts:335-401 (handler)The `doRead` function implements the core logic of the `ref_read_url` tool. It fetches the content of the provided URL from the Ref API, converts it to markdown, handles client-specific response formats (OpenAI DeepResearch vs standard), manages authentication, and gracefully handles errors including 401 unauthorized.async function doRead(url: string, mcpClient: string = 'unknown', sessionId?: string) { try { const readUrl = getRefUrl() + '/read?url=' + encodeURIComponent(url) console.error('[read]', readUrl) if (!getApiKey()) { return { content: [ { type: 'text', text: 'Ref is not correctly configured. Reach out to hello@ref.tools for help.', }, ], } } const response = await axios.get(readUrl, { headers: getAuthHeaders(sessionId), }) const data = response.data // Return different formats based on client type if (mcpClient === 'openai-mcp') { const result: DeepResearchShape = { id: url, title: data.title || '', text: data.content || '', url, } return { content: [ { type: 'text', text: JSON.stringify(result), }, ], } } else { return { content: [{ type: 'text', text: data.content || '' }], } } } catch (error) { if (axios.isAxiosError(error) && error.response?.status === 401) { return { content: [ { type: 'text', text: 'Please verify your email at https://ref.tools/dashboard to read URLs', }, ], } } console.error('[read-error]', error) return { content: [ { type: 'text', text: `Error reading URL: ${axios.isAxiosError(error) ? error.message : (error as Error).message}`, }, ], } } }
- index.ts:83-99 (schema)Defines the schema for the `ref_read_url` tool, including name (`ref_read_url` via config), description, input schema requiring a `url` string, and `readOnlyHint` annotation.const readTool: Tool = { name: toolConfig.readToolName, description: `Read the content of a url as markdown. The EXACT url from a '${toolConfig.searchToolName}' result should be passed to this tool.`, inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'The URL of the webpage to read.', }, }, required: ['url'], }, annotations: { readOnlyHint: true, }, }
- index.ts:119-121 (registration)Registers the `ref_read_url` tool (as `readTool`) in the MCP `listTools` response, making it discoverable to clients.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [searchTool, readTool], }))
- index.ts:206-209 (registration)Dispatches `callTool` requests for `ref_read_url` (matching `toolConfig.readToolName`) to the `doRead` handler function within the MCP `callTool` request handler.if (request.params.name === toolConfig.readToolName) { const input = request.params.arguments as { url: string } return doRead(input.url, mcpClient, sessionId) }
- index.ts:34-37 (registration)Configures the tool name `ref_read_url` for the default (non-OpenAI) client setup, used in tool definitions and dispatch logic.const DEFAULT_TOOL_CONFIG: ToolConfig = { searchToolName: 'ref_search_documentation', readToolName: 'ref_read_url', }