Ref

Instructions

Implementation Reference

• index.ts:263-333 (handler)

  The handler function that implements the core logic of 'ref_search_documentation'. It sends a query to the Ref API endpoint '/search_documentation' and formats the results based on the client type (OpenAI or default).

  async function doSearch(query: string, mcpClient: string = 'unknown', sessionId?: string) {
    const url = getRefUrl() + '/search_documentation?query=' + encodeURIComponent(query)
    console.error('[search]', url)
  
    if (!getApiKey()) {
      return {
        content: [
          {
            type: 'text',
            text: 'Ref is not correctly configured. Reach out to hello@ref.tools for help.',
          },
        ],
      }
    }
  
    try {
      const response = await axios.get(url, {
        headers: getAuthHeaders(sessionId),
      })
  
      const data = response.data
  
      if (data.docs.length === 0) {
        return {
          content: [{ type: 'text', text: 'No results found' }],
        }
      }
  
      // Return different formats based on client type
      if (mcpClient === 'openai-mcp') {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(data.docs.map(toDeepResearchShape)),
            },
          ],
        }
      } else {
        return {
          content: data.docs.map((doc: any) => ({
            type: 'text' as const,
            text: `overview: ${doc.overview || ''}
  url: ${doc.url}
  moduleId: ${doc.moduleId || ''}`,
          })),
        }
      }
    } 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 search documentation',
            },
          ],
        }
      }
  
      console.error('[search-error]', error)
      return {
        content: [
          {
            type: 'text',
            text: `Error during documentation search: ${axios.isAxiosError(error) ? error.message : (error as Error).message}`,
          },
        ],
      }
    }
  }

• index.ts:65-81 (schema)

  The Tool definition including name, description, inputSchema (with 'query' parameter), and annotations for 'ref_search_documentation'.

  const searchTool: Tool = {
    name: toolConfig.searchToolName,
    description: `Search for documentation on the web or github as well from private resources like repos and pdfs. Use Ref '${toolConfig.readToolName}' to read the content of a url.`,
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: `Query for documentation. Should include programming language and framework or library names. Searches public only docs by default, include ref_src=private to search a user's private docs.`,
        },
      },
      required: ['query'],
    },
    annotations: {
      readOnlyHint: true,
    },
  }

• index.ts:34-37 (registration)

  Configuration object that sets the tool name to 'ref_search_documentation' for default clients.

  const DEFAULT_TOOL_CONFIG: ToolConfig = {
    searchToolName: 'ref_search_documentation',
    readToolName: 'ref_read_url',
  }

• index.ts:119-121 (registration)

  Registration of the tool in the ListToolsRequestSchema handler, exposing 'ref_search_documentation' in the tools list.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [searchTool, readTool],
  }))

• index.ts:198-204 (registration)

  Registration of the tool handler in the CallToolRequestSchema: maps calls to 'ref_search_documentation' to the doSearch function.

  if (request.params.name === toolConfig.searchToolName) {
    console.error('[search_documentation] arguments', request.params.arguments)
    const input = request.params.arguments as {
      query: string
    }
    return doSearch(input.query, mcpClient, sessionId)
  }