search

Instructions

Implementation Reference

• src/index.ts:153-194 (handler)

  The async handler function for the 'search' tool. It performs the search request, handles errors and empty results, formats the results into markdown using formatResultItem, and returns structured text content.

  async ({ query }) => {
    const searchData = await makeSearchRequest(query);
  
    if (!searchData) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to retrieve search results",
          },
        ],
      };
    }
  
    const results = searchData || [];
  
    if (results.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No results found for "${query}"`,
          },
        ],
      };
    }
  
    // Format the results as text
    const formattedResults = results
      .slice(0, MAX_RESULTS)
      .map(formatResultItem)
      .join("\n---\n\n");
  
    return {
      content: [
        {
          type: "text",
          text: `Search results for "${query}":\n\n${formattedResults}`,
        },
      ],
    };
  }

• src/index.ts:9-12 (schema)

  Zod schema defining the input parameter 'query' for the search tool, requiring a string of at least 2 characters.

  export const SearchQuerySchema = z
    .string()
    .min(2, "Search query must be at least 2 characters")
    .describe("The search query to look for on barnsworthburning.net");

• src/index.ts:147-152 (registration)

  Registration of the 'search' tool on the MCP server, specifying the tool name, description, and input schema.

  server.tool(
    "search",
    "Search barnsworthburning.net for the given query",
    {
      query: SearchQuerySchema,
    },

• src/index.ts:121-144 (helper)

  Helper function that makes the HTTP request to the barnsworthburning.net search API, parses the JSON response using SearchResultsSchema, and returns the results or null on error.

  async function makeSearchRequest(
    query: string
  ): Promise<SearchResultItem[] | null> {
    const headers = {
      "User-Agent": USER_AGENT,
      Accept: "application/json",
    };
  
    try {
      const url = `${SEARCH_API_BASE}?q=${encodeURIComponent(query)}`;
      const response = await fetch(url, { headers });
  
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      const json = await response.json();
      const parsed = SearchResultsSchema.parse(json);
      return parsed.results;
    } catch (error) {
      console.error("Error making search request:", error);
      return null;
    }
  }

• src/index.ts:56-112 (helper)

  Helper function that formats a single SearchResultItem into a rich markdown string including title, metadata, extract, notes, and relationships.

  function formatResultItem(item: SearchResultItem) {
    const {
      title,
      id,
      creators,
      source,
      extract,
      format,
      spaces,
      connections,
      parent,
      children,
      notes,
      extractedOn,
      lastUpdated,
    } = item;
  
    let content = `## ${title ?? id}\n\n`;
  
    if (format) {
      content += `**Format:** ${format}\n`;
    }
    if (creators) {
      content += `**By:** ${creators.map((c) => c.name).join(", ")}\n`;
    }
    if (source) {
      content += `**Source:** ${source}\n`;
    }
    content += `**Created:** ${extractedOn.toLocaleDateString()}\n`;
    content += `**Updated:** ${lastUpdated.toLocaleDateString()}\n`;
  
    if (extract) {
      content += `\n${extract}\n`;
    }
    if (notes) {
      content += `\n*Curator's Note:*\n\n${notes}\n`;
    }
    content += `\n`;
    if (parent) {
      content += `**Parent Record:** ${parent.name}\n`;
    }
    if (children && children.length > 0) {
      content += `**Child Records:**\n${children
        .map((c) => `- ${c.name}`)
        .join("\n")}\n\n`;
    }
    if (connections && connections.length > 0) {
      content += `**See also:**\n${connections
        .map((c) => `- ${c.name}`)
        .join("\n")}\n\n`;
    }
    if (spaces && spaces.length > 0) {
      content += `**Tagged:** ${spaces.map((s) => `#${s.name}`).join(", ")}\n`;
    }
  
    return content;
  }