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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_keyword_research"
}
}Input 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), };