Lunoo Rankings

lunoo-mcp

Lunoo 的公共 Model Context Protocol（MCP）服务，是一个排名平台，涵盖超过 2,600 个类别中的 231,000 多项内容，评分范围为 0-10 分。

用日常语言查询排名，范围涵盖动漫、笔记本电脑、软件、旅行、书籍以及数千个其他类别。该服务会解析最接近的实时类别，返回带有 Lunoo 链接的评分项目；对于不支持的查询，则会拒绝作答，而不是捏造结果。

概览

这是一个只读的公共代理，通过 Lunoo 的公共 Web API 提供服务。无需身份验证、数据库访问或 API 密钥，也不产生费用。

• 实时端点：https://lunoo.com/mcp（Streamable HTTP，JSON-RPC 2.0）
• 传输方式：通过 HTTP 进行无状态 POST
• 缓存：浏览页面缓存 24 小时，排名和项目缓存 15 分钟
• 超时：每次上游请求 10 秒
• 覆盖范围：2,677 多个类别和 231,982 多个已排名项目，已于 2026-08-21 验证
• 隐私：不会存储原始提示词、工具参数或工具结果。请参阅 https://lunoo.com/privacy
• 安全性：全部三个工具均为只读，并公开 MCP 只读注解

安全与滥用控制

• 服务默认监听 127.0.0.1，以便反向代理仅公开指定的 HTTPS 路由。
• 每个客户端每分钟最多可发送 120 个 MCP 请求。
• 同时运行的 MCP 请求不超过 20 个，同时运行的上游 Lunoo 请求不超过 12 个。
• JSON 请求体限制为 32 KB，JSON-RPC 批次限制为 20 条消息，工具输入不得超过文档规定的长度。
• 内存缓存最多包含 256 个条目，并会逐出旧键。
• 用户输入会编码到固定的 Lunoo 路径中，无法据此选择任意上游主机。
• 服务不会执行命令、运行用户代码、读取本地文件或公开环境变量。

自行托管的部署应将 Node 端口保持为私有，并通过 HTTPS 反向代理公开 /mcp。不要直接公开端口 8972。

快速开始

Claude 自定义连接器

打开 Claude 的连接器设置，选择 添加自定义连接器，然后输入：

Name: Lunoo Rankings
URL: https://lunoo.com/mcp

无需身份验证。可以使用类似 Find the best laptop for video editing using Lunoo 的请求进行测试。

Claude Code

在项目的 .claude/settings.json 中：

{
  "mcpServers": {
    "lunoo": {
      "url": "https://lunoo.com/mcp"
    }
  }
}

或者在任何 Claude Code 会话中运行：

claude mcp add --transport http lunoo https://lunoo.com/mcp

通用 HTTP 客户端

向 https://lunoo.com/mcp 发送 JSON-RPC 2.0 请求。示例：

curl -X POST https://lunoo.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

本地开发（自行托管）

npm install
npm start
# Server listens on http://localhost:8972

健康检查：

curl http://localhost:8972/healthz
# {"ok":true,"service":"lunoo-mcp"}

工具

find_niche

将日常语言请求解析为实时排名类别。最多返回 10 个匹配结果，包含置信度、匹配词、项目数量和带跟踪参数的 Lunoo 链接。

输入：

{
  "query": "string - normal-language request, e.g. 'best laptop for video editing'"
}

输出： 包含 slug、显示名称、Lunoo URL 和 JSON 端点 URL 的细分领域数组。

请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find_niche",
    "arguments": { "query": "anime" }
  },
  "id": 1
}

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "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]"
      }
    ]
  },
  "id": 1
}

get_rankings

根据类别 slug 或日常语言请求获取排名项目。返回解析后的类别、匹配说明、评分元数据和排名靠前的项目。

输入：

{
  "niche": "string - niche slug, e.g. 'anime'",
  "limit": "number? - items to return, 1-50, default 10"
}

输出： 细分领域元数据及排名项目，包含排名、名称、评分（0-10）、描述、URL 和置信度标签。

请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_rankings",
    "arguments": { "niche": "anime", "limit": 3 }
  },
  "id": 2
}

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "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}"
      }
    ]
  },
  "id": 2
}

get_item

根据 slug 提取项目的结构化元数据（JSON-LD）。解析嵌入在项目页面中的所有 schema.org 块。

输入：

{
  "slug": "string - item slug, e.g. 'frieren-beyond-journeys-end'"
}

输出： 项目 URL 及已解析 JSON-LD 对象数组（BreadcrumbList、AggregateRating 等）。

请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_item",
    "arguments": { "slug": "frieren-beyond-journeys-end" }
  },
  "id": 3
}

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "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}"
      }
    ]
  },
  "id": 3
}

MCP 初始化

该服务实现 Model Context Protocol v2025-03-26。使用以下内容初始化：

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  },
  "id": 0
}

响应包含服务端能力、协议版本和说明。

缓存行为

结果会缓存在 https://lunoo.com/mcp 的实时服务中：

• 浏览页面（供 find_niche 使用）：24 小时
• 排名 JSON（供 get_rankings 使用）：15 分钟
• 项目页面（供 get_item 使用）：15 分钟

自行托管时，缓存存储在每个服务实例的内存中，并会在重启后清除。

错误处理

发生故障（404、超时、网络错误）时，工具会返回：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Niche \"invalid-slug\" not found (404). Try find_niche to discover available niches."
    }
  ]
}

不会抛出未处理的异常；所有错误均符合 JSON-RPC 规范。

引用

链接到 Lunoo 上的完整排名页面：

https://lunoo.com/best/{slug}

示例：https://lunoo.com/best/anime

请参阅 https://lunoo.com/llms.txt，了解如何在 LLM 输出中引用 Lunoo 排名。

自托管部署

前置条件

Node 18+、npm

安装

git clone https://github.com/PeakProductivity/lunoo-mcp.git
cd lunoo-mcp
npm install

运行

npm start
# or with custom port:
PORT=9000 npm start

生产环境设置

1. 使用进程管理器（PM2、systemd 等）：

pm2 start server.mjs --name lunoo-mcp

2. 配置反向代理（nginx）：

location /mcp {
  proxy_pass http://localhost:8972;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
}

3. 定期监控缓存大小和日志。

CORS 策略

在线服务仅接受来自已配置 Claude 来源的浏览器请求。来自任意浏览器来源的请求都会被拒绝。未携带 Origin 标头的服务端 MCP 客户端请求会被接受。

自托管实例使用相同的安全默认设置。必要时，可通过逗号分隔的 MCP_ALLOWED_ORIGINS 环境变量覆盖浏览器允许来源列表。

API 端点

方法	路径	描述
POST	/mcp	JSON-RPC 2.0 端点
GET	/healthz	健康检查

支持

发现排名有问题？请在 Lunoo 上报告：https://lunoo.com

许可证

MIT。请参阅 LICENSE 文件。

链接

• Lunoo：https://lunoo.com
• 仓库：https://github.com/PeakProductivity/lunoo-mcp
• 引用指南：https://lunoo.com/llms.txt