altimateguide

Altimateguide Agent MCP Server

一个小型 MCP 服务，可让 AI Agent 向 Altimateguide 目录提交工具以供编辑审核；还可以选择为其获得一个 dofollow 链接。

**范围：**此服务仅与公开的 Altimateguide HTTP API 通信。它不持有任何数据库凭据，也不会授予提交或拥有列表以外的访问权限。所有内容都必须经编辑审核后才会发布，而且提交者无法自行授予 dofollow 链接——付费列表只有在服务端验证付款后，才会成为 dofollow 候选项。未经验证的列表会保持 nofollow，并在 15–20 个工作日内审核；已验证且已付费的列表会在 2–7 个工作日内审核。

工具

工具	功能
start_login	发送一次性登录码邮件（POST /api/auth/request-code）。
complete_login	将登录码换取账户 API 令牌并保存（POST /api/agent/token）。
start_agentid_login	在无需电子邮箱收件箱的情况下开始 AgentID 登录——返回 authorizeUrl 和 flowId（POST /api/agent/agentid/start）。
complete_agentid_login	轮询 AgentID 登录状态，并在登录完成后保存账户令牌（GET /api/agent/agentid/poll）。
whoami	报告本地是否已配置令牌。
list_categories	获取有效的类别 slug（GET /api/agent/categories）。
check_duplicate	预先检查名称/URL 是否与已发布工具或待处理队列中的项目重复（GET /api/agent/check）。
submit_tool	提交列表以供编辑审核（POST /api/agent/submit）。
get_submission	轮询提交状态（GET /api/agent/submissions/{id}）。
update_listing	编辑你拥有的列表信息——只更改你传入的字段（PATCH /api/agent/listing/{slug}）。
get_listing_stats	查看你所拥有列表的访问量、点赞数、收藏数和评论数，并提供 7 天和 30 天统计窗口（GET /api/agent/stats）。
upgrade_listing	为你拥有的列表选择 sayabout、徽章或付费方案（POST /api/agent/listing）。

它还将类别列表和编辑政策作为资源公开，提供 submit_listing 提示词以及类别 slug 补全。服务端的 instructions 会为模型概述工作流。

submit_tool 参数

• name（字符串，必填）——工具名称
• url（字符串，必填）——规范的 http(s) URL
• description（字符串，可选）——中性描述，至少 20 个字符
• categories（数组，可选）——来自 list_categories 的 slug
• categorySuggestions（数组，可选）——没有合适类别时提供的自由文本提示（会记录下来供审核者参考）
• features（数组，可选）——{ label, description? } 项
• pros / cons（数组，可选），pricing / freePlan / freeTrial（可选）
• proof（字符串，可选）——none（默认）| sayabout | badge
• verificationUrl（字符串）——使用 sayabout/badge 时必填
• externalId（字符串，可选）——用于幂等重放的自定义 ID（省略时根据 URL 生成）
• source（字符串，可选）——来源 ID（默认为 agent:mcp）
• resubmit（布尔值，可选）——若此 URL 的先前提交已被拒绝，则设为 true 以重新提交；系统会生成新的幂等键，而不是重放被拒绝的记录

类别为可选项。类别未知或缺失都不会导致提交失败——系统会将其记录下来供审核者参考，与网站的信息流处理流程完全一致。此处不会提交付费（dofollow）列表；请使用 upgrade_listing 并设置 path: "paid"，它会返回一个 Dodo 结账 URL，付款将在服务端验证。

完整的请求/响应规范：https://altimateguide.com/openapi.json。

审核时间

处理时长和链接级别均取决于 proof：

proof	链接	审核时间
paid（通过 upgrade_listing）	dofollow	2 个工作日内
sayabout	dofollow	2 个工作日内
badge	dofollow	5–7 个工作日
none（默认）	nofollow	15–20 个工作日

已验证和付费的提交会优先于未经验证的提交进行审核。submit_tool 的响应包含 review_eta；未经验证的响应还包含一个指向 upgrade_listing 的 upgrade 提示，以便 Agent 向用户展示更快的 dofollow 选项。

配置

• ALTIMATEGUIDE_AGENT_TOKEN — 可选。账户 API 令牌（可在 https://altimateguide.com/account 创建，或使用 complete_login 工具生成）。设置后，该令牌优先于已存储的令牌。
• ALTIMATEGUIDE_API_URL — 可选；覆盖 API 基础 URL（默认值为 https://altimateguide.com）。
• ALTIMATEGUIDE_CONFIG_DIR — 可选；指定 complete_login 存储令牌的位置 （默认值为 ~/.config/altimateguide）。

安装与使用

npx -y altimateguide-agent-mcp        # run directly (stdio)

也可以从本地检出目录运行：

npm install
npm run build      # tsc -> dist/
npm run dev        # stdio server via tsx (for local testing)

Claude Desktop / 其他 MCP 客户端

{
  "mcpServers": {
    "altimateguide": {
      "command": "npx",
      "args": ["-y", "altimateguide-agent-mcp"]
    }
  }
}

可以通过 env.ALTIMATEGUIDE_AGENT_TOKEN 提供令牌，也可以在运行时调用 start_login + complete_login 获取令牌（Agent 需要能够访问其注册时使用的邮箱）。

（从本地检出目录运行时，请使用 "command": "node" 和 "args": ["/absolute/path/to/dist/index.js"]。）

开发

npm run check   # tsc --noEmit
npm run lint    # eslint
npm test        # vitest
npm run build   # tsc -> dist/
npm run bundle  # build a .mcpb (Smithery / Claude Desktop)

注册目录

通过 server.json（MCP Registry 清单）列出。它是一个标准的 stdio 服务，因此也兼容社区目录（Glama、PulseMCP、mcp.so、mcp.directory）。

项目结构

.
├── src/
│   ├── index.ts        # stdio server: tool registry + resources/prompts/completions
│   ├── api.ts          # shared fetch client (timeout, retry, error mapping)
│   ├── auth.ts         # start_login / complete_login / whoami
│   ├── categories.ts   # list_categories + matching
│   ├── submit.ts       # submit_tool
│   ├── listing.ts      # check_duplicate / get_submission / upgrade_listing
│   ├── credentials.ts  # token storage (~/.config/altimateguide)
│   ├── schema.ts       # zod -> JSON Schema helper
│   └── version.ts      # package version
├── test/               # vitest
├── server.json         # MCP Registry manifest
├── mcpb/manifest.json  # .mcpb bundle manifest
├── package.json
└── tsconfig.json

安全与权限

此服务是面向公共 Altimateguide HTTP API 的轻量本地客户端——不访问数据库、不启动子进程，也不执行后台任务。以下是其全部功能范围（供应链扫描器报告的范围也相同）：

• 网络 — 仅向 ALTIMATEGUIDE_API_URL 中的基础 URL 发出 HTTPS 请求（默认值为 https://altimateguide.com）。它调用的端点仅限于 工具 中列出的端点（/api/auth/…、/api/agent/…、/openapi.json）。不进行遥测，也不调用第三方服务。
• 环境变量 — 读取 ALTIMATEGUIDE_AGENT_TOKEN、 ALTIMATEGUIDE_API_URL 和 ALTIMATEGUIDE_CONFIG_DIR。不会写入任何环境变量。
• 文件系统 — 仅涉及一个文件：位于 ${ALTIMATEGUIDE_CONFIG_DIR:-~/.config/altimateguide}/credentials.json 的账户令牌文件，创建时权限为 0600。不会触及其他路径。
• 不启动子进程，也不访问数据库 — 它不会启动任何进程，也不持有数据库凭据。

凭据：ALTIMATEGUIDE_AGENT_TOKEN 环境变量始终优先于已存储的文件，因此 CI 式配置可以注入令牌，而无需将令牌写入磁盘。

未经编辑审核，不会发布任何内容；付费列表只有在服务器端验证付款后，才会成为 dofollow 候选项。

许可证

MIT — 参见 LICENSE。