research_keyword

Instructions

Implementation Reference

• src/tools/keywordResearch.js:22-22 (handler)

  The handler for 'research_keyword': sends a POST request to /keyword-research via the SurfRank API client.

  handler: async (input) => api.post('/keyword-research', input),

• src/tools/keywordResearch.js:10-21 (schema)

  Input schema for 'research_keyword': accepts keyword (required), country (optional ISO-2), and websiteId (optional).

  inputSchema: {
    type: 'object',
    properties: {
      keyword: { type: 'string', description: 'The keyword / prompt to research' },
      country: { type: 'string', description: 'ISO-2 country code (optional)' },
      websiteId: {
        type: 'string',
        description: 'Associate the research with a project (optional but recommended)',
      },
    },
    required: ['keyword'],
  },

• src/index.js:31-39 (registration)

  Tool registration: keywordResearchTools is spread into ALL_TOOLS and indexed by name in toolByName map.

  const ALL_TOOLS = [
    ...projectTools,
    ...keywordTools,
    ...reportTools,
    ...quickTestTools,
    ...keywordResearchTools,
    ...competitorTools,
    ...opportunityTools,
  ];

• src/tools/keywordResearch.js:3-48 (registration)

  The tool definition object with name 'research_keyword', description, inputSchema, and handler is exported as part of keywordResearchTools array.

  export const keywordResearchTools = [
    {
      name: 'research_keyword',
      description:
        'Research a keyword across every configured AI engine. Returns volume, intent, related ' +
        'prompts, and competitor mentions. Cost: ~0.5 credits × engines. If the API key is scoped ' +
        'to a project, `websiteId` must be passed and must match that scope.',
      inputSchema: {
        type: 'object',
        properties: {
          keyword: { type: 'string', description: 'The keyword / prompt to research' },
          country: { type: 'string', description: 'ISO-2 country code (optional)' },
          websiteId: {
            type: 'string',
            description: 'Associate the research with a project (optional but recommended)',
          },
        },
        required: ['keyword'],
      },
      handler: async (input) => api.post('/keyword-research', input),
    },
    {
      name: 'list_keyword_research',
      description: 'List past keyword research runs, optionally filtered by project.',
      inputSchema: {
        type: 'object',
        properties: {
          websiteId: { type: 'string' },
          page: { type: 'number', description: '1-based page index' },
          limit: { type: 'number', description: 'Results per page (default 20)' },
        },
      },
      handler: async ({ websiteId, page, limit }) =>
        api.get('/keyword-research', { websiteId, page, limit }),
    },
    {
      name: 'get_keyword_research',
      description: 'Get a single keyword-research run by ID.',
      inputSchema: {
        type: 'object',
        properties: { researchId: { type: 'string' } },
        required: ['researchId'],
      },
      handler: async ({ researchId }) => api.get(`/keyword-research/${researchId}`),
    },
  ];

• src/client.js:78-83 (helper)

  The api.post method (line 80) that the handler delegates to, which calls the SurfRank public API.

  export const api = {
    get: (path, query) => request('GET', path, { query }),
    post: (path, body) => request('POST', path, { body }),
    patch: (path, body) => request('PATCH', path, { body }),
    delete: (path) => request('DELETE', path),
  };