Phrases MCP Server

Instructions

Implementation Reference

• src/index.ts:21-42 (handler)

  The handler function that executes the 'get-all-phrases' tool logic: fetches all phrases from the mock API, handles empty list, formats as 'phrase: "author"' list, and returns markdown-compatible text content.

  async () => {
      const phrases = await makeMockAPIRequest<Phrase[]>("GET");
      let resultText = "";
  
      if (!phrases || phrases.length === 0) {
          resultText = "No phrases found.";
      } else {
          const formatted = phrases.map(
              (p) => `${p.phrase}: "${p.name}"`
          ).join("\n");
          resultText = `Here are all the phrases:\n\n${formatted}`;
      }
  
      return {
          content: [
              {
                  type: "text",
                  text: resultText
              }
          ]
      }
  }

• src/index.ts:17-43 (registration)

  The server.tool registration for 'get-all-phrases', including name, description, empty schema, and inline handler.

  server.tool(
      "get-all-phrases",
      "Returns a list of all phrases.",
      {},
      async () => {
          const phrases = await makeMockAPIRequest<Phrase[]>("GET");
          let resultText = "";
  
          if (!phrases || phrases.length === 0) {
              resultText = "No phrases found.";
          } else {
              const formatted = phrases.map(
                  (p) => `${p.phrase}: "${p.name}"`
              ).join("\n");
              resultText = `Here are all the phrases:\n\n${formatted}`;
          }
  
          return {
              content: [
                  {
                      type: "text",
                      text: resultText
                  }
              ]
          }
      }
  );

• src/index.ts:20-20 (schema)

  Empty Zod schema for input parameters (tool takes no arguments).

  {},

• src/helpers/makeMockAPIRequest.ts:28-62 (helper)

  Supporting helper function that performs HTTP requests to the mock API. Used in handler as makeMockAPIRequest<Phrase[]>("GET") to retrieve all phrases.

  export async function makeMockAPIRequest<T>(
      method: HTTPMethod,
      options: RequestOptions = {}
  ): Promise<T | null> {
      const { path, queryParams, body } = options;
      let url = BASE_URL;
  
      if (path) url += path;
      if (method === "GET" && queryParams) {
          const query = new URLSearchParams(queryParams).toString();
          url += `?${query}`;
      }
  
      const headers: HeadersInit = {
          "Content-Type": "application/json",
      };
  
      const fetchOptions: RequestInit = {
          method,
          headers,
          body: body && method !== "GET" && method !== "DELETE"
              ? JSON.stringify(body)
              : undefined,
      };
  
      try {
          const response = await fetch(url, fetchOptions);
          if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
          if (method === "DELETE" || response.status === 204) return null;
          return await response.json();
      } catch (err) {
          console.error(`Error on ${method} ${url}:`, err);
          return null;
      }
  }

• src/helpers/makeMockAPIRequest.ts:3-7 (schema)

  Type definition for Phrase used in the generic type for fetching Phrase[].

  export interface Phrase {
      id: number;
      name: string;
      phrase: string;
  }