get-search-terms

Instructions

Implementation Reference

• src/index.ts:1664-1699 (handler)

  Handler function that makes an API request to the WordPress site's Jetpack stats endpoint for search terms, processes the response data, formats it into a readable text output, and returns it as MCP content or an error message.

    async ({ siteUrl, username, password, siteId, period = "week", limit = 10 }) => {
      try {
        const searchData = await makeWPRequest<any>({
          siteUrl,
          endpoint: `sites/${siteId}/stats/search-terms`,
          auth: { username, password },
          params: { period, limit }
        });
        
        const searchTermsText = Array.isArray(searchData.search_terms) && searchData.search_terms.length > 0
          ? searchData.search_terms.map((term: any) => 
              `"${term.term || "Unknown"}"
  Views: ${term.views || 0}
  ---`
            ).join("\n")
          : "No search terms found or search terms are encrypted";
        
        return {
          content: [
            {
              type: "text",
              text: `Search Terms for site #${siteId} (${period}):\n\n${searchTermsText}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving search terms: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    }

• src/index.ts:1656-1663 (schema)

  Zod schema defining the input parameters for the get-search-terms tool, including required credentials, site details, and optional period and limit for the stats query.

  {
    siteUrl: z.string().url().describe("WordPress site URL"),
    username: z.string().describe("WordPress username"),
    password: z.string().describe("WordPress application password"),
    siteId: z.number().describe("WordPress site ID"),
    period: z.enum(["day", "week", "month", "year"]).optional().describe("Time period for stats"),
    limit: z.number().min(1).max(100).optional().describe("Maximum number of search terms to return"),
  },

• src/index.ts:1653-1700 (registration)

  Registration of the 'get-search-terms' tool using McpServer.tool(), including the tool name, description, input schema, and handler function reference.

  server.tool(
    "get-search-terms",
    "View search terms used to find the site",
    {
      siteUrl: z.string().url().describe("WordPress site URL"),
      username: z.string().describe("WordPress username"),
      password: z.string().describe("WordPress application password"),
      siteId: z.number().describe("WordPress site ID"),
      period: z.enum(["day", "week", "month", "year"]).optional().describe("Time period for stats"),
      limit: z.number().min(1).max(100).optional().describe("Maximum number of search terms to return"),
    },
    async ({ siteUrl, username, password, siteId, period = "week", limit = 10 }) => {
      try {
        const searchData = await makeWPRequest<any>({
          siteUrl,
          endpoint: `sites/${siteId}/stats/search-terms`,
          auth: { username, password },
          params: { period, limit }
        });
        
        const searchTermsText = Array.isArray(searchData.search_terms) && searchData.search_terms.length > 0
          ? searchData.search_terms.map((term: any) => 
              `"${term.term || "Unknown"}"
  Views: ${term.views || 0}
  ---`
            ).join("\n")
          : "No search terms found or search terms are encrypted";
        
        return {
          content: [
            {
              type: "text",
              text: `Search Terms for site #${siteId} (${period}):\n\n${searchTermsText}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving search terms: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    }
  );