{"_id":"@autoranq/mcp-server","name":"@autoranq/mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@autoranq/mcp-server","version":"1.0.0","description":"Official MCP server for AutoRanq — plug AI clients (Claude Code, Cursor, ChatGPT, VS Code) into the AutoRanq SEO content platform.","type":"module","bin":{"autorank-mcp":"dist/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","dev":"tsx watch src/index.ts","start":"node dist/index.js","test":"vitest","test:coverage":"vitest run --coverage","type-check":"tsc --noEmit","lint":"eslint src --ext .ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0","tsx":"^4.0.0","typescript":"^5.0.0","vitest":"^1.0.0"},"engines":{"node":">=20.0.0"},"keywords":["mcp","model-context-protocol","autoranq","autorank","seo","ai","claude","cursor"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bartpropty/Autoranq.git","directory":"packages/mcp-server"},"homepage":"https://docs.autoranq.ai/mcp/","bugs":{"url":"https://github.com/bartpropty/Autoranq/issues"},"publishConfig":{"access":"public"},"_id":"@autoranq/mcp-server@1.0.0","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-EYKi5/KFLJ+erFVfXxZZb3yXlhs4qxJxoyvTUWpd1qIkbhc/+oIVE/5xcqV8kwBY/qUcVgkgLciuf91iN8qV5Q==","shasum":"a4e4c75325dcb1ae56577e079aaef795822736d6","tarball":"https://registry.npmjs.org/@autoranq/mcp-server/-/mcp-server-1.0.0.tgz","fileCount":58,"unpackedSize":130262,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEWNQDcuZO8BFwDiJJFbAiCimaBb7VQrFlUZujN4dEtYAiBd9uvJ8vh03NTU9oeim9oVs58UBxgqC+S+IqiPjJoXKg=="}]},"_npmUser":{"name":"bartpropty","email":"bartkorpershoek@gmail.com"},"directories":{},"maintainers":[{"name":"bartpropty","email":"bartkorpershoek@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.0.0_1779913376060_0.16950934899073333"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T20:22:55.819Z","1.0.0":"2026-05-27T20:22:56.218Z","modified":"2026-05-27T20:22:56.441Z"},"maintainers":[{"name":"bartpropty","email":"bartkorpershoek@gmail.com"}],"description":"Official MCP server for AutoRanq — plug AI clients (Claude Code, Cursor, ChatGPT, VS Code) into the AutoRanq SEO content platform.","homepage":"https://docs.autoranq.ai/mcp/","keywords":["mcp","model-context-protocol","autoranq","autorank","seo","ai","claude","cursor"],"repository":{"type":"git","url":"git+https://github.com/bartpropty/Autoranq.git","directory":"packages/mcp-server"},"bugs":{"url":"https://github.com/bartpropty/Autoranq/issues"},"license":"MIT","readme":"# AutoRank MCP Server\n\nA Model Context Protocol (MCP) server that enables Claude Code to programmatically interact with the AutoRank article generation platform.\n\n## Features\n\n- **20 Tools** across 7 categories for managing generations, recipes, prompts, costs, and more\n- **7 Resource URIs** for quick data access\n- **Stdio transport** for seamless Claude Code integration\n- **Type-safe** with Zod validation\n\n## Installation\n\nThe MCP server is automatically configured when you have the `.mcp.json` file in your project root. Claude Code will start the server when needed.\n\n### Prerequisites\n\n- Node.js >= 20.19.0\n- `AUTORANK_API_KEY` environment variable set\n\n### Manual Start (for testing)\n\n```bash\n# From the monorepo root\ncd packages/mcp-server\nAUTORANK_API_KEY=ar_live_xxx npx tsx src/index.ts\n```\n\n## Configuration\n\nThe server is configured in `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"autorank\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"packages/mcp-server/src/index.ts\"],\n      \"env\": {\n        \"AUTORANK_API_KEY\": \"${AUTORANK_API_KEY}\",\n        \"AUTORANK_API_URL\": \"http://localhost:3001\"\n      }\n    }\n  }\n}\n```\n\n## Tools Reference\n\n### Generation Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_generations` | List recent generations with filters (status, project, limit) |\n| `get_generation` | Get detailed generation info with step results and timing |\n| `get_generation_logs` | Fetch execution logs for a generation |\n| `retry_generation` | Retry failed generation from beginning or specific step |\n\n### Recipe Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_recipes` | List all article recipes with configurations |\n| `get_recipe` | Get recipe details with all steps |\n| `update_recipe_step` | Update a recipe step configuration |\n\n### Prompt Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_prompts` | List flow prompts with optional filtering |\n| `get_prompt` | Get prompt system/user templates |\n| `update_prompt` | Update prompt content |\n| `create_prompt` | Create new flow prompt (global or recipe-specific) |\n\n### Cost Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_cost_summary` | Get aggregated cost data for time period |\n| `get_cost_breakdown` | Get costs by model, step type, or project |\n\n### Recipe Lab Tools\n\n| Tool | Description |\n|------|-------------|\n| `test_recipe` | Run test generation using Recipe Lab |\n| `test_single_step` | Test single step with provided context |\n\n### Article Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_articles` | List articles with filters |\n| `get_article` | Get article content and metadata |\n\n### System Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_projects` | List all projects with optional stats |\n| `get_system_health` | Get system health and queue status |\n\n## Resources\n\nAccess data directly via resource URIs:\n\n| URI | Description |\n|-----|-------------|\n| `autorank://projects` | List all projects |\n| `autorank://projects/{id}` | Project details |\n| `autorank://articles/{id}` | Article content |\n| `autorank://generations/{id}` | Generation details |\n| `autorank://recipes/{id}` | Recipe with steps |\n| `autorank://prompts/{id}` | Prompt templates |\n| `autorank://costs/summary` | Current cost summary |\n\n## Usage Examples\n\n### List Recent Failed Generations\n\nAsk Claude:\n> \"Show me the last 10 failed generations\"\n\nClaude will use `list_generations` with `status: \"FAILED\"` and `limit: 10`.\n\n### Debug a Generation\n\nAsk Claude:\n> \"Why did generation abc123 fail?\"\n\nClaude will:\n1. Use `get_generation` to get details\n2. Use `get_generation_logs` to fetch error logs\n3. Analyze and explain the failure\n\n### Update a Recipe Step Model\n\nAsk Claude:\n> \"Change the CONTENT step in recipe xyz to use Claude 3.5 Sonnet\"\n\nClaude will use `update_recipe_step` with the appropriate configuration.\n\n### Test Recipe Changes\n\nAsk Claude:\n> \"Test the standard-seo-article recipe with keyword 'best coffee makers'\"\n\nClaude will use `test_recipe` from Recipe Lab to run a test generation.\n\n### Check Costs\n\nAsk Claude:\n> \"What are our AI costs this month by model?\"\n\nClaude will use `get_cost_breakdown` with `groupBy: \"model\"`.\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Type Check\n\n```bash\nnpm run type-check\n```\n\n### Project Structure\n\n```\npackages/mcp-server/\n├── src/\n│   ├── index.ts              # Entry point\n│   ├── server.ts             # MCP server setup\n│   ├── client/\n│   │   └── api-client.ts     # HTTP client for AutoRank API\n│   ├── tools/\n│   │   ├── index.ts          # Tool registry\n│   │   ├── generations.ts    # Generation management\n│   │   ├── recipes.ts        # Recipe management\n│   │   ├── prompts.ts        # Prompt management\n│   │   ├── costs.ts          # Cost tracking\n│   │   ├── recipe-lab.ts     # Recipe Lab testing\n│   │   └── articles.ts       # Article & system tools\n│   ├── resources/\n│   │   ├── index.ts          # Resource registry\n│   │   └── handlers.ts       # Resource handlers\n│   └── utils/\n│       ├── errors.ts         # Error handling\n│       └── validation.ts     # Zod schemas\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n## Authentication\n\nThe server uses API key authentication. Set your API key as an environment variable:\n\n```bash\nexport AUTORANK_API_KEY=ar_live_xxxxxxxxxxxxx\n```\n\nThe API key is sent via the `X-Api-Key` header to the AutoRank backend API.\n\n## Error Handling\n\nAll tools return structured responses:\n\n**Success:**\n```json\n{\n  \"content\": [{ \"type\": \"text\", \"text\": \"{...data...}\" }]\n}\n```\n\n**Error:**\n```json\n{\n  \"content\": [{ \"type\": \"text\", \"text\": \"Error message\" }],\n  \"isError\": true\n}\n```\n\n## Troubleshooting\n\n### Server Not Starting\n\n1. Check `AUTORANK_API_KEY` is set\n2. Ensure backend API is running at `AUTORANK_API_URL`\n3. Check Claude Code logs for errors\n\n### API Errors\n\n1. Verify API key has correct permissions\n2. Check if backend API is accessible\n3. Review error messages in tool responses\n\n### Type Errors\n\nIf you encounter TypeScript errors after SDK updates:\n\n```bash\ncd packages/mcp-server\nnpm install\nnpm run type-check\n```\n","readmeFilename":"README.md","_rev":"1-e19c3338327654a7fc553baca2ffc8fb"}