快速开始：AI Agent 集成

将你的 AI 编程助手（Cursor 或 Claude Code）接入 SoloKit SEO，只需 3 步。配置完成后，可以直接用自然语言让 Agent 发现并修复 SEO 问题，无需手动调用 API。

---

第一步：生成 API Key

前往 Dashboard → API 密钥，点击创建 Key。

重要：创建后立即复制完整 Key（sk_live_xxx），它只显示一次。

---

第二步：接入 Agent

根据你的使用场景选择接入方式。

方式 A：HTTP 直连（推荐，无需安装）

不需要克隆代码，不需要运行任何进程，直接用 URL 接入。

Cursor — 在项目根目录创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "solokit-seo": {
      "type": "streamableHttp",
      "url": "https://seo.solokit.run/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_你的Key"
      }
    }
  }
}

"type": "streamableHttp" 必须填写，否则 Cursor 会报 Invalid URL protocol 错误。

Claude Code — 编辑 ~/.claude.json：

{
  "mcpServers": {
    "solokit-seo": {
      "url": "https://seo.solokit.run/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_你的Key"
      }
    }
  }
}

保存后重启 Agent，solokit-seo 工具会自动出现。

---

方式 B：Skill URL（零配置）

如果是支持直接读取 URL 的 Agent（Claude Code、Cursor、Codex 等），不用提前配置，直接粘贴：

Read https://seo.solokit.run/SKILL.md and follow the instructions to fix my SEO issues.

Agent 会获取 Skill 文件、学习工作流程，并在需要时引导你完成配置。

---

方式 C：Coze 扣子技能（在扣子里用）

如果你在 扣子（Coze） 平台使用 Agent，可以安装 SoloKit 官方技能：

1. 在扣子「技能市场」搜索 SoloKit SEO 助手（或直接打开技能详情页）。
2. 点击添加到智能体，创建你的智能体或选择已有智能体。
3. 首次使用时，按提示填入你自己的 API Key（每个使用者填自己的，互不影响）。
4. 即可让扣子 Agent 直接查询站点、SEO 问题、行动计划，并运行 GEO 探测。

技能已封装 SoloKit 的公开 REST API（seo.solokit.run/api/public/**），Agent 通过技能内部脚本直连，不依赖 MCP 或 CLI。

---

方式 D：命令行 CLI（面向终端 / 脚本 / Agent）

@solokit/cli 是把 SoloKit API 封装成 Agent 友好命令行的工具，适合终端脚本、cron、以及 Claude Code / Codex / Cursor 等 shell 型 Agent 直接调用。

# 全局安装（或直接用 npx，无需安装）
npm i -g @solokit/cli

# 设置 API Key（也可用 --key 参数）
export SOLOKIT_API_KEY=sk_live_你的Key

# 常用命令（全部支持 --json 让 Agent 解析）
solokit seo whoami                     # 身份与配额
solokit seo sites list                 # 站点列表
solokit seo issues list --priority high  # 高优先级问题
solokit seo plans list                 # 行动计划

Agent 友好契约：退出码 0=成功 / 1=错误 / 2=用法 / 3=鉴权 / 4=限流 / 5=上游，失败时输出 {error,message,hint,docs} 结构，方便 Agent 自动判断下一步。

---

方式 E：本地进程（离线或内网环境）

适合无法访问外网或自部署的场景，需要先克隆仓库。

# 获取项目绝对路径
pwd
# 例如：/Users/alice/solokit

Cursor / Claude Code 配置：

{
  "mcpServers": {
    "solokit-seo": {
      "command": "node",
      "args": ["/Users/alice/solokit/mcp-server/dist/index.js"],
      "env": {
        "SOLOKIT_API_KEY": "sk_live_你的Key",
        "SOLOKIT_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

---

第三步：直接对话

配置完成后，用自然语言交流即可，无需任何命令：

帮我查看所有高优先级的 SEO 问题

站点 2 有什么问题？告诉我当前值和建议值

把问题 42 标记为已修复

Agent 会自动调用平台 API 并返回结构化结果。

---

可用 MCP 工具

接入后，Agent 可调用以下工具：

回答探针的界面操作按场景写在 AI 回答探针。不要把四率合成一个总分。

---

示例对话

你：   列出站点 1 所有高优先级的 SEO 问题。
Agent：[调用 list_seo_issues] 发现 3 个问题：
       - title：/about 页面标题 92 字符（建议最多 60）
       - description：/pricing 页面缺少 meta description
       - h1：/blog 页面存在多个 h1 标签

你：   修复 title 问题并标记为完成。
Agent：[修改文件，然后调用 update_issue_status]
       完成。标题已缩短至 54 字符，问题已标记为 completed。

---

直接调用 REST API

不使用 MCP 时，也可以用任何 HTTP 客户端直接调用：

# 列出站点
curl -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  https://seo.solokit.run/api/public/sites

# 获取高优先级待处理问题
curl -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  "https://seo.solokit.run/api/public/seo-issues?priority=high&status=pending"

# 标记问题已修复
curl -X PATCH \
  -H "Authorization: Bearer $SOLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed", "note": "标题已缩短至 54 字符"}' \
  https://seo.solokit.run/api/public/seo-issues/42

完整 API 文档：GET /api/openapi

---

常见问题

---

下一步

• API 密钥管理 — 管理权限和有效期
• AI 回答探针 — 按场景测提及 / 推荐 / 引用
• Agent 管理 — 配置 AI 分析 Agent
• 网站管理 — 添加和管理你的网站