Search Intent MCP

Instructions

Implementation Reference

• src/index.ts:73-130 (handler)

  The handler function that performs the search intent analysis by calling the external API, processing the response, and returning formatted content or error.

  async ({ query }) => {
    try {
      const response = await fetch(
        "https://aisearchintent.com/api/search-intent",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${getApiKey()}`,
          },
          body: JSON.stringify({ query }),
        }
      );
  
      if (!response.ok) {
        throw new Error(`API request failed: ${response.statusText}`);
      }
  
      // 解析完整的响应结构
      const apiResponse = (await response.json()) as SearchIntentApiResponse;
  
      // 验证响应状态
      if (apiResponse.code !== 0) {
        throw new Error(`API error: ${apiResponse.message}`);
      }
  
      // 直接返回数据部分的 JSON
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(apiResponse.data, null, 2),
          },
        ],
        isError: false,
        _meta: {
          latency: Date.now(),
          version: "1.0.0",
        },
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error analyzing search intent: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
        _meta: {
          errorType: error instanceof Error ? error.name : "Unknown",
          timestamp: new Date().toISOString(),
        },
      };
    }
  }

• src/index.ts:50-131 (registration)

  Registration of the 'search_intent_analysis' tool with MCP server, including description, input schema, and handler reference.

  server.tool(
    "search_intent_analysis",
    `A tool for analyzing search intent and user behavior.
  
  Features:
  - Analyze search query intent
  - Identify relevant topic categories
  - Provide search suggestions
  - Offer reference links
  
  Examples:
  "iphone 15" → Product research/purchase intent
  "python tutorial" → Learning intent
  
  Response format:
  - query: Original search term
  - intent: Search intention
  - categories: Related categories
  - suggestions: Related search terms
  - references: Reference links`,
    {
      query: z.string().describe("Enter a search term to analyze"),
    },
    async ({ query }) => {
      try {
        const response = await fetch(
          "https://aisearchintent.com/api/search-intent",
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Bearer ${getApiKey()}`,
            },
            body: JSON.stringify({ query }),
          }
        );
  
        if (!response.ok) {
          throw new Error(`API request failed: ${response.statusText}`);
        }
  
        // 解析完整的响应结构
        const apiResponse = (await response.json()) as SearchIntentApiResponse;
  
        // 验证响应状态
        if (apiResponse.code !== 0) {
          throw new Error(`API error: ${apiResponse.message}`);
        }
  
        // 直接返回数据部分的 JSON
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(apiResponse.data, null, 2),
            },
          ],
          isError: false,
          _meta: {
            latency: Date.now(),
            version: "1.0.0",
          },
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error analyzing search intent: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
          isError: true,
          _meta: {
            errorType: error instanceof Error ? error.name : "Unknown",
            timestamp: new Date().toISOString(),
          },
        };
      }
    }
  );

• src/index.ts:70-72 (schema)

  Input schema for the tool using Zod validation for the 'query' parameter.

  {
    query: z.string().describe("Enter a search term to analyze"),
  },

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

  TypeScript interface defining the structure of the API response for search intent analysis.

  interface SearchIntentApiResponse {
    code: number;
    message: string;
    data: {
      query: string;
      intent: string;
      possibleCategories: string[];
      reasoning: string;
      references: Array<{
        url: string;
        title: string;
      }>;
      groundingMetadata: {
        searchSuggestions: string[];
      };
    };
  }

• src/index.ts:34-41 (helper)

  Helper function to retrieve the API key from environment variables, used in the handler.

  function getApiKey(): string {
    const apiKey = process.env.SEARCH_INTENT_API_KEY;
    if (!apiKey) {
      console.error("SEARCH_INTENT_API_KEY environment variable is not set");
      process.exit(1);
    }
    return apiKey;
  }