{
  "markdown": "# lunoo-mcp\n\nPublic Model Context Protocol (MCP) server for Lunoo, a rankings platform covering more than 231,000 items across more than 2,600 categories on a 0-10 scale.\n\nAsk for rankings in normal language, from anime and laptops to software, travel, books, and thousands of other categories. The server resolves the closest live category, returns scored items with Lunoo links, and refuses unsupported queries instead of inventing a result.\n\n## Overview\n\nThis is a read-only public proxy over Lunoo's public web API. No authentication required, no database access, no API keys, no cost.\n\n- **Live endpoint**: https://lunoo.com/mcp (Streamable HTTP, JSON-RPC 2.0)\n- **Transport**: Stateless POST over HTTP\n- **Caching**: Browse page 24h, rankings and items 15 minutes\n- **Timeout**: 10 seconds per upstream request\n- **Coverage**: 2,677+ categories and 231,982+ ranked items, verified on 2026-08-21\n- **Privacy**: No raw prompts, tool arguments, or tool results are stored. See https://lunoo.com/privacy\n- **Safety**: All three tools are read-only and expose MCP read-only annotations\n\n## Security and abuse controls\n\n- The server listens on `127.0.0.1` by default so a reverse proxy can expose only the intended HTTPS route.\n- Each client is limited to 120 MCP requests per minute.\n- No more than 20 MCP requests and 12 upstream Lunoo requests run at once.\n- JSON bodies are limited to 32 KB, JSON-RPC batches to 20 messages, and tool inputs to documented lengths.\n- The in-memory cache is limited to 256 entries and evicts old keys.\n- User input is encoded into fixed Lunoo paths. It cannot select an arbitrary upstream host.\n- The server does not execute commands, evaluate user code, read local files, or expose environment variables.\n\nSelf-hosted deployments should keep the Node port private and expose `/mcp` through an HTTPS reverse proxy. Do not publish port 8972 directly.\n\n## Quick Start\n\n### Claude custom connector\n\nOpen Claude's connector settings, choose **Add custom connector**, and enter:\n\n```text\nName: Lunoo Rankings\nURL: https://lunoo.com/mcp\n```\n\nNo authentication is required. Test with a request such as `Find the best laptop for video editing using Lunoo`.\n\n### Claude Code\n\nIn your project's `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"lunoo\": {\n      \"url\": \"https://lunoo.com/mcp\"\n    }\n  }\n}\n```\n\nOr run from any Claude Code session:\n\n```bash\nclaude mcp add --transport http lunoo https://lunoo.com/mcp\n```\n\n### Generic HTTP Client\n\nPost JSON-RPC 2.0 requests to https://lunoo.com/mcp. Example:\n\n```bash\ncurl -X POST https://lunoo.com/mcp \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/list\",\n    \"id\": 1\n  }'\n```\n\n### Local Development (self-hosted)\n\n```bash\nnpm install\nnpm start\n# Server listens on http://localhost:8972\n```\n\nHealth check:\n\n```bash\ncurl http://localhost:8972/healthz\n# {\"ok\":true,\"service\":\"lunoo-mcp\"}\n```\n\n## Tools\n\n### find_niche\n\nResolve a normal-language request to live ranking categories. Returns up to 10 matches with confidence, matched terms, item counts, and tracked Lunoo links.\n\n**Input:**\n```json\n{\n  \"query\": \"string - normal-language request, e.g. 'best laptop for video editing'\"\n}\n```\n\n**Output:** Array of niches with slug, display name, Lunoo URL, and JSON endpoint URL.\n\n**Example Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"find_niche\",\n    \"arguments\": { \"query\": \"anime\" }\n  },\n  \"id\": 1\n}\n```\n\n**Example Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"isError\": false,\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"[\\n  {\\n    \\\"slug\\\": \\\"anime\\\",\\n    \\\"name\\\": \\\"anime\\\",\\n    \\\"url\\\": \\\"https://lunoo.com/best/anime\\\",\\n    \\\"rankings_json\\\": \\\"https://lunoo.com/best/anime.json\\\"\\n  },\\n  ...\\n]\"\n      }\n    ]\n  },\n  \"id\": 1\n}\n```\n\n### get_rankings\n\nFetch ranked items for a category slug or a normal-language request. Returns the resolved category, match explanation, score metadata, and top items.\n\n**Input:**\n```json\n{\n  \"niche\": \"string - niche slug, e.g. 'anime'\",\n  \"limit\": \"number? - items to return, 1-50, default 10\"\n}\n```\n\n**Output:** Niche metadata plus ranked items with rank, name, score (0-10), description, URL, and confidence label.\n\n**Example Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_rankings\",\n    \"arguments\": { \"niche\": \"anime\", \"limit\": 3 }\n  },\n  \"id\": 2\n}\n```\n\n**Example Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"isError\": false,\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"{\\n  \\\"name\\\": \\\"anime\\\",\\n  \\\"url\\\": \\\"https://lunoo.com/best/anime\\\",\\n  \\\"item_count\\\": 1847,\\n  \\\"updated_at\\\": \\\"2026-07-02T08:15:00Z\\\",\\n  \\\"score_scale\\\": \\\"0-10\\\",\\n  \\\"ranking_method\\\": \\\"Consensus-based scoring\\\",\\n  \\\"top_items\\\": [\\n    {\\n      \\\"rank\\\": 1,\\n      \\\"name\\\": \\\"Frieren: Beyond Journey's End\\\",\\n      \\\"score\\\": 9.15,\\n      \\\"url\\\": \\\"https://lunoo.com/item/frieren-beyond-journeys-end\\\",\\n      \\\"description\\\": \\\"A fantasy adventure about a thousand-year journey...\\\"\\n    },\\n    ...\\n  ]\\n}\"\n      }\n    ]\n  },\n  \"id\": 2\n}\n```\n\n### get_item\n\nExtract structured metadata (JSON-LD) for an item by slug. Parses all schema.org blocks embedded on the item page.\n\n**Input:**\n```json\n{\n  \"slug\": \"string - item slug, e.g. 'frieren-beyond-journeys-end'\"\n}\n```\n\n**Output:** Item URL and array of parsed JSON-LD objects (BreadcrumbList, AggregateRating, etc.).\n\n**Example Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_item\",\n    \"arguments\": { \"slug\": \"frieren-beyond-journeys-end\" }\n  },\n  \"id\": 3\n}\n```\n\n**Example Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"isError\": false,\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"{\\n  \\\"url\\\": \\\"https://lunoo.com/item/frieren-beyond-journeys-end\\\",\\n  \\\"structured_data\\\": [\\n    {\\n      \\\"@context\\\": \\\"https://schema.org\\\",\\n      \\\"@type\\\": \\\"AggregateRating\\\",\\n      \\\"ratingValue\\\": 9.15,\\n      \\\"ratingCount\\\": 847\\n    },\\n    ...\\n  ]\\n}\"\n      }\n    ]\n  },\n  \"id\": 3\n}\n```\n\n## MCP Initialization\n\nThe server implements Model Context Protocol v2025-03-26. Initialize with:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2025-03-26\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"my-client\",\n      \"version\": \"1.0.0\"\n    }\n  },\n  \"id\": 0\n}\n```\n\nResponse includes server capabilities, protocol version, and instructions.\n\n## Caching Behavior\n\nResults are cached locally in the live service at https://lunoo.com/mcp:\n- Browse page (used by find_niche): 24 hours\n- Rankings JSON (used by get_rankings): 15 minutes\n- Item pages (used by get_item): 15 minutes\n\nWhen self-hosting, cache is in-memory per server instance and cleared on restart.\n\n## Error Handling\n\nOn failure (404, timeout, network error), tools return:\n\n```json\n{\n  \"isError\": true,\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"Niche \\\"invalid-slug\\\" not found (404). Try find_niche to discover available niches.\"\n    }\n  ]\n}\n```\n\nNever throws unhandled exceptions; all errors are JSON-RPC compliant.\n\n## Citation\n\nLink to full rankings pages on Lunoo as:\n\n```\nhttps://lunoo.com/best/{slug}\n```\n\nExample: https://lunoo.com/best/anime\n\nSee https://lunoo.com/llms.txt for how to cite Lunoo rankings in LLM outputs.\n\n## Self-Hosted Deployment\n\n### Prerequisites\n\nNode 18+, npm\n\n### Installation\n\n```bash\ngit clone https://github.com/PeakProductivity/lunoo-mcp.git\ncd lunoo-mcp\nnpm install\n```\n\n### Running\n\n```bash\nnpm start\n# or with custom port:\nPORT=9000 npm start\n```\n\n### Production Setup\n\n1. Use a process manager (PM2, systemd, etc.):\n\n```bash\npm2 start server.mjs --name lunoo-mcp\n```\n\n2. Reverse proxy (nginx):\n\n```nginx\nlocation /mcp {\n  proxy_pass http://localhost:8972;\n  proxy_set_header Host $host;\n  proxy_set_header X-Real-IP $remote_addr;\n}\n```\n\n3. Monitor cache size and logs periodically.\n\n## CORS Policy\n\nThe live service accepts browser requests only from the configured Claude origins. Requests from arbitrary browser origins are rejected. Server-side MCP clients without an `Origin` header are accepted.\n\nSelf-hosted instances use the same safe defaults. Override the browser allowlist with the comma-separated `MCP_ALLOWED_ORIGINS` environment variable when necessary.\n\n## API Endpoints\n\n| Method | Path       | Description            |\n|--------|------------|------------------------|\n| POST   | `/mcp`     | JSON-RPC 2.0 endpoint  |\n| GET    | `/healthz` | Health check           |\n\n## Support\n\nFound an issue with a ranking? Report it on Lunoo: https://lunoo.com\n\n## License\n\nMIT. See LICENSE file.\n\n## Links\n\n- Lunoo: https://lunoo.com\n- Repository: https://github.com/PeakProductivity/lunoo-mcp\n- Citation Guide: https://lunoo.com/llms.txt\n",
  "bytes": 8889,
  "sha": "f77576b572bec756635cd2fa48c9ff62de5e3d6893c1bd1713d026fd7a159032",
  "repo_slug": "peakproductivity/lunoo-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_lunoo_rankings_33dcf35b/readme"
}