SEO-MCP 文档（V3.0.0）——仅保留 ai_content_detect

本版本目标：精简为单一工具 ai_content_detect，用于在内容生成后、SEO质检前进行AI痕迹检测。其他工具（标题生成/内容指导/质检/模板版本管理）已移除对外暴露。

一、工具概述

• 名称：ai_content_detect
• 描述：AI内容生成检测：在内容生成后、SEO质检前进行AI痕迹检测，返回 percent、linesscore、mintxt，并给出 pass/review/fail 与下一步动作建议
• 依赖环境变量：SEO_MCP_AI_DETECT_API_KEY（5118接口密钥）

二、安装与运行

推荐使用 npx 直接运行指定版本：

"seo-mcp": {
  "timeout": 60,
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "[email protected]"],
  "env": {
    "SEO_MCP_AI_DETECT_API_KEY": "YOUR_5118_API_KEY"
  }
}

或本地依赖：

npm install --save-dev [email protected]

"seo-mcp": {
  "timeout": 60,
  "type": "stdio",
  "command": "node",
  "args": ["./node_modules/seo-mcp-server/dist/index.js"],
  "env": {
    "SEO_MCP_AI_DETECT_API_KEY": "YOUR_5118_API_KEY"
  }
}

三、ListTools 与 CallTool

- ListTools 仅返回 ai_content_detect
- CallTool 仅支持 name=ai_content_detect，参数：
  - content: string（必填，建议≥100字）
  - locale?: string（默认 zh-CN）
  - thresholds?: { maxPercent?: number; reviewPercent?: number; minLineScore?: number }
- 返回字段：
  - percent: number；mintxt: 0|1；linesscore: {idx,score,txt}[]
  - decision: "pass"|"review"|"fail"; pass: boolean
  - next_actions: string[]; suggestions: string[]
  - diagnostics: { parser: "strict"|"relaxed"; raw: string; notes: string[] }

四、判定规则（默认阈值）

• maxPercent（默认35）：percent ≤ 35 → pass
• reviewPercent（默认55）：35 < percent ≤ 55 → review
• minLineScore（默认3）：任一段 score < 3 → 至少 review
• mintxt != 0 → fail（长度不足）
• errcode != "0" → fail（接口错误）

详细Schema与示例见 V2.1-schema.md。

五、示例调用（MCP CallTool）

请求：

{
  "name": "ai_content_detect",
  "arguments": {
    "content": "待检测文本……",
    "locale": "zh-CN",
    "thresholds": { "maxPercent": 35, "reviewPercent": 55, "minLineScore": 3 }
  }
}

返回（示例）：

{
  "percent": 43,
  "mintxt": 0,
  "linesscore": [{ "idx": 1, "score": 3, "txt": "..." }],
  "decision": "review",
  "pass": false,
  "next_actions": ["remove_template_phrases", "add_verifiable_details"],
  "suggestions": ["存在边界风险段落，请按建议最小改写后复验"],
  "diagnostics": { "parser": "relaxed", "raw": "...", "notes": ["relaxed parse applied"] }
}

六、版本与回滚

• 3.0.0 为“仅 ai_content_detect”精简版本；若需恢复完整生成/质检能力，请回滚到 2.2.1。
• 回滚方式：将依赖版本切换为 [email protected]，并恢复原配置。

七、FAQ

• Q：为什么只剩一个工具？
  • A：满足“生成后、质检前”的AI痕迹硬性前置检查需求，减少配置与维护复杂度。
• Q：是否仍需要配置模板？
  • A：无需。本版不再依赖模板系统的对外能力。
• Q：API Key 如何配置？
  • A：通过环境变量 SEO_MCP_AI_DETECT_API_KEY 注入。

八、FAQ

• Q：老项目未适配 next_action 会受影响吗？
  • A：不会。next_action 可忽略；原有字段不变。
• Q：fix_instructions 一定要实现自动修复吗？
  • A：不要求；可展示给人工编辑使用。
• Q：为什么不新增业务专用MCP？
  • A：为保持通用性与简洁性，业务差异放在调用侧（System Prompt/编排），MCP仅提供通用能力与最小辅助信息。

九、MCP宿主配置（推荐）

为确保宿主环境（如CodeBuddy）能稳定加载指定版本的seo-mcp-server，避免因全局安装的老旧版本或PATH环境问题导致加载失败（如Connection closed错误），推荐以下两种配置方式：

方案A：使用npx强制加载指定版本（推荐）

此方法无需本地安装，npx会自动下载并运行指定版本的包，是解决版本冲突和环境问题的最快方式。

配置示例：

"seo-mcp": {
  "timeout": 60,
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "[email protected]"],
  "env": {
    "SEO_MCP_AI_DETECT_API_KEY": "YOUR_5118_API_KEY"
  }
}

注意：args中的版本号（@2.2.1）应与您需要使用的版本保持一致。

方案B：使用项目本地依赖（更稳定）

此方法将seo-mcp-server作为项目的开发依赖进行管理，通过node直接执行本地node_modules中的脚本，隔离性最好。

步骤：

1. 在您的项目根目录执行安装：

   npm install --save-dev [email protected]

2. 更新您的MCP配置文件，使用相对路径指向node_modules中的启动脚本。

配置示例：

"seo-mcp": {
  "timeout": 60,
  "type": "stdio",
  "command": "node",
  "args": ["./node_modules/seo-mcp-server/dist/index.js"],
  "env": {
    "SEO_MCP_AI_DETECT_API_KEY": "YOUR_5118_API_KEY"
  }
}

注意：此方法要求您的宿主环境工作目录在项目根目录，以便相对路径./node_modules/...能被正确解析。