NameWheel

NameWheel MCP 服务

一个开源（MIT）MCP 服务，用于公平随机抽选：从名单中抽取姓名、随机分组、生成转盘链接，以及核验认证抽选。它通过 stdio 在你自己的机器上运行（Node.js 20+ 或 Docker），同一份代码也可以作为托管的 Streamable HTTP 服务运行，地址为 https://mcp.namewheel.org/mcp。

在支持显示 MCP Apps 的客户端（Claude、ChatGPT 等）中，NameWheel 转盘会在聊天中直接旋转并显示结果。需要让其他人日后核验结果时，它会执行一次认证抽选，并生成永久公开的证明页面。

在本地运行（stdio）

git clone https://github.com/namewheel/mcp && cd mcp
npm install && npm run build
node dist/stdio.js

或使用 Docker：

docker build -t namewheel-mcp .
docker run -i --rm namewheel-mcp

在你的机器上运行的内容：

• 抽取获胜者（spin_wheel）：在此进程中使用 Node 的加密随机数生成器（crypto.randomInt）。无需联网。
• 分组（make_teams）和转盘链接（open_wheel_link）：在本地计算。无需联网。
• 核验认证抽选（verify_draw）：下载抽选的公开记录和 NameWheel 的公钥，然后在本地重新计算所有内容：SHA-256 承诺、HMAC-SHA256 获胜者和 Ed25519 签名。
• 限额（check_plan）：在本地查询。

只有 certified_draw、freeze_list 和 my_draws 会调用 NameWheel API，因为认证抽选会发布到 namewheel.org 上的公开证明页面。这些工具使用你自己的免费 API 密钥：

NAMEWHEEL_API_KEY=nw_live_... node dist/stdio.js
docker run -i --rm -e NAMEWHEEL_API_KEY=nw_live_... namewheel-mcp

在 namewheel.org/mcp 一键创建密钥。没有密钥时，服务仍会启动，以上所有功能也都可用。

Claude Desktop、Cursor、Cline、Windsurf 及其他可启动本地服务的客户端：

{
  "mcpServers": {
    "namewheel": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/stdio.js"],
      "env": { "NAMEWHEEL_API_KEY": "nw_live_..." }
    }
  }
}

env 块为可选项。

工具

工具	功能	运行位置
spin_wheel	从名单中随机抽取一位或多位获胜者，并在聊天中显示转盘。	本地
make_teams	将姓名随机分成若干队伍或人数相等的小组。	本地
open_wheel_link	生成 namewheel.org 链接，打开时会加载姓名并显示完整转盘。	本地
verify_draw	根据认证抽选的代码或链接进行核验：重新计算获胜者，并检查承诺和 Ed25519 签名。	获取公开记录后，在本地
check_plan	查看此连接可执行的操作，以及今天剩余的认证抽选次数。	本地（使用密钥时：读取你的方案）
certified_draw	TrueSpin 认证抽选：在转盘旋转前封存获胜者，并发布到公开证明页面（namewheel.org/v/CODE）。	NameWheel API，你的密钥
freeze_list	在抽选前将名单锁定并公开（namewheel.org/f/CODE）。	NameWheel API，你的密钥
my_draws	查看你的认证抽选和已冻结名单，以及证明链接。	NameWheel API，你的密钥

认证抽选会在证明页面上公开标题、所有候选项和获胜者。工具描述中明确说明了这一点，因此助手会在执行前告知用户。

此服务还提供 5 个提示词（pick_student、split_teams、certified_draw_with_proof、make_a_decision、verify_a_draw）和 2 个资源（namewheel://truespin，介绍认证抽选的工作方式；以及 namewheel://limits）。

或使用托管服务（无需安装）

同一服务也运行在 https://mcp.namewheel.org/mcp（Streamable HTTP）。无需账户：每个连接每分钟可调用 30 次，每天可调用 500 次。认证抽选需要免费的 NameWheel 账户，并通过客户端显示的登录流程连接。

**Claude（网页、桌面、移动端）：**设置、连接器、添加自定义连接器，然后粘贴 https://mcp.namewheel.org/mcp。

Claude Code

claude mcp add --transport http namewheel https://mcp.namewheel.org/mcp

**ChatGPT（网页）：**设置、应用（开发者模式），添加 https://mcp.namewheel.org/mcp。

Codex CLI

codex mcp add namewheel --url https://mcp.namewheel.org/mcp

Cursor：在 Cursor 中安装，或使用 ~/.cursor/mcp.json：

{ "mcpServers": { "namewheel": { "url": "https://mcp.namewheel.org/mcp" } } }

VS Code：在 VS Code 中安装，或使用 .vscode/mcp.json：

{ "servers": { "namewheel": { "type": "http", "url": "https://mcp.namewheel.org/mcp" } } }

Windsurf，使用 ~/.codeium/windsurf/mcp_config.json：

{ "mcpServers": { "namewheel": { "serverUrl": "https://mcp.namewheel.org/mcp" } } }

Gemini CLI，使用 ~/.gemini/settings.json：

{ "mcpServers": { "namewheel": { "httpUrl": "https://mcp.namewheel.org/mcp" } } }

若要在不使用登录流程的情况下使用账户，请将密钥作为 Authorization: Bearer nw_live_... 或 x-api-key: nw_live_... 发送。

自行运行 HTTP 服务

npm install && npm run build
NAMEWHEEL_API_URL=https://namewheel.org PUBLIC_URL=https://your-host.example MCP_JWT_SECRET=<random hex> node dist/index.js

设置项：PORT（默认值 8791）、HOST（默认值 127.0.0.1）、PUBLIC_URL（客户端访问的地址，用于 OAuth 元数据）、NAMEWHEEL_API_URL、MCP_JWT_SECRET（用于签署访问令牌）、STATE_DIR（OAuth 客户端、令牌和访客调用计数器的存储目录，默认值为 /var/lib/namewheel-mcp）。

HTTP 服务是一个 OAuth 2.1 授权服务（支持 PKCE、动态客户端注册、客户端 ID 元数据文档、RFC 9728 和 8414 元数据）。无需账户的工具不需要登录。当客户端调用需要账户的工具时，服务会返回 401，客户端会显示其连接流程；连接页面会要求提供 NameWheel API 密钥，并将连接绑定到该密钥。在 NameWheel 控制面板中删除密钥（设置、API 密钥）会断开所有使用该密钥的助手。密钥只能用于运行认证抽选、冻结名单、读取套餐以及列出自己的抽选记录；不能更改账户、付款信息或数据。

认证抽选的运作方式

1. NameWheel 的服务生成一个秘密值，并在揭晓任何内容之前仅发布其 SHA-256 指纹。
2. 连接会加入自己的随机数。
3. 以该秘密值为密钥，对该随机数和条目列表的指纹计算 HMAC-SHA256，得出获胜者。
4. 转盘结束后，秘密值会被公开，记录由 NameWheel 的 Ed25519 密钥签名（公钥）。
5. 证明页面会列出同一账户对同一名单进行的所有认证抽选，因此可以看出是否反复重抽直到心仪对象获胜。

规范：namewheel.org/truespin-spec。独立验证器：namewheel/truespin-verifier。verify_draw 会执行相同的检查（src/verify.ts）。

聊天内转盘

spin_wheel、make_teams、certified_draw 和 verify_draw 会关联一个 MCP Apps 视图（ui://namewheel/wheel-v1.html、text/html;profile=mcp-app）。它是 widget/wheel.html 中的一个独立 HTML 文件：不含外部脚本、字体或请求。不支持 MCP Apps 的客户端会获得相同的文本结果。

隐私

转盘抽选、分组和转盘链接都不会存储姓名。认证抽选和冻结名单由 NameWheel 存储，并像网站上一样发布在其证明页面上。托管服务会按 IP 地址统计无需账户的调用次数，并保留 30 天的请求日志（工具、条目数量、客户端名称、地址、结果；绝不记录姓名）。政策：namewheel.org/privacy。

许可证

MIT。NameWheel 和 TrueSpin 是 Outline Technologies LLC 的名称。