Ref

Instructions

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',
  }