list_keyword_research
Retrieve a list of previous keyword research runs, filtered by project, to review past AI visibility analyses.
Instructions
List past keyword research runs, optionally filtered by project.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| websiteId | No | ||
| page | No | 1-based page index | |
| limit | No | Results per page (default 20) |
Implementation Reference
- src/tools/keywordResearch.js:35-36 (handler)The handler function for list_keyword_research. It calls api.get with the /keyword-research endpoint, passing optional websiteId, page, and limit query parameters.
handler: async ({ websiteId, page, limit }) => api.get('/keyword-research', { websiteId, page, limit }), - src/tools/keywordResearch.js:27-34 (schema)Input schema defining optional parameters: websiteId (string), page (number, 1-based), limit (number, default 20).
inputSchema: { type: 'object', properties: { websiteId: { type: 'string' }, page: { type: 'number', description: '1-based page index' }, limit: { type: 'number', description: 'Results per page (default 20)' }, }, }, - src/tools/keywordResearch.js:24-48 (registration)Tool definition object with name 'list_keyword_research', description, inputSchema, and handler — part of the keywordResearchTools array exported from this file.
{ 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/index.js:31-39 (registration)keywordResearchTools (including list_keyword_research) are spread into the ALL_TOOLS array which is then registered with the MCP server via ListToolsRequestSchema and CallToolRequestSchema handlers.
const ALL_TOOLS = [ ...projectTools, ...keywordTools, ...reportTools, ...quickTestTools, ...keywordResearchTools, ...competitorTools, ...opportunityTools, ]; - src/client.js:78-83 (helper)The api.get helper used by the handler to make the HTTP GET request to the SurfRank 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), };