用途
faf-mcp 是 FAF 生态中面向 IDE 一侧的 MCP 服务器，目标是为 Cursor、Windsurf、Cline、VS Code 以及其他非 Claude 平台的 AI 编程工具提供持久、统一的项目上下文。它解决的问题是：每个 AI 工具都需要自己的上下文文件（.cursorrules、AGENTS.md、GEMINI.md、CLAUDE.md 等），内容相同但格式各异，维护分散且容易过期。faf-mcp 的做法是在仓库中维护一份 project.faf，由它统一生成并同步到各格式。
主要能力
- 上下文同步：以 project.faf 为唯一来源，毫秒级写出各 AI 工具所需的上下文文件。
- 批量写出：faf_claude { all: true } 可一次写出四种格式。
- 反向导入：faf_agents、faf_cursor、faf_gemini 可导入已有文件，配合 merge: true 合并进 project.faf。
- 保留既有内容：faf 管理块之外的内容按字节原样保留。
- AI 就绪度评分：所有工具使用 faf-cli 8.0.0 的 always-33 内核评分，33 个 Mk4 槽位中，未使用（slotignored）的企业槽位（infra、app、ops）会从分母中剔除。
- 工具集分层：默认展示 15 个核心工具，设置 FAF_TOOLS=all 可启用全部 29 个；无论是否展示，所有工具都可按名称调用。
- 资源 URI：faf://context 与 faf://status，本版本中 claude-faf:// 仍可作为别名读取。
使用方式
- 本地 stdio 运行。将以下之一加入 MCP 配置： npx faf-mcp 或 bunx faf-mcp
- 提示词模式：在每次提示开头使用 "Use FAF" 调用 MCP 工具。
- 15 个默认核心工具：faf_init、faf_auto、faf_go、faf_git、faf_sync、faf_score、faf_doctor、faf_agents、faf_cursor、faf_gemini、faf_claude 等（官方列出共 15 个，此处不逐一臆测）。
- FAF_TOOLS=all 后额外开放 14 个：faf_status、faf_what、faf_guide、faf_debug、faf_clear、faf_list、faf_read（在允许根目录内读取文件：cwd、系统临时目录或 FAF_ALLOWED_ROOTS）、faf_write（在相同根目录内写入文件）、faf_readme、faf_human_add、faf_quick、faf_formats、faf_dna、faf_conductor。
4.0.0 版本要点（Always33）
faf-mcp 4 与 faf-cli 8 共用 always-33 内核评分，与 claude-faf-mcp 7、faf-kernel 给出同一分数。从 3.x 升级时，缺少 12 个标记的 .faf 会按 33 个槽位评分，运行 faf_auto 可写入标记并恢复评分。
3.0 系列能力
- faf_git 使用统一评分器，报告其生成文件的 faf-cli 分数，并在覆盖已有 project.faf 前询问。
- faf_sync 预览每项变更，dry run 会列出将更新的字段并提示 apply: true。
- 导入无写入时会明确告知；merge: true 但无 project.faf 时会明确失败。
- 不调用外部 shell：源码不导入 child_process，工具输出中不含 CLI 命令或终端颜色码。
- 由 faf-cli 7.12 的渲染器、仓库富化与块注入器生成文件，与 faf export、faf sync 写出的字节一致。
适用场景
- 团队使用多种 AI 编程工具（Cursor、Windsurf、Cline、VS Code、Gemini 等），需要统一上下文。
- 跨分支、跨会话、跨成员保持项目上下文一致，避免 AI 每次重新猜测。
- 希望量化上下文完整度（评分等级从 55% 的"猜测"到 100% 的"优化"），并据此补全。
限制与前提
- 需要 Node.js 22 或更新版本（18 与 20 已生命周期终止；CI 矩阵覆盖 22 与 24）。
- 通过 stdio 在本地运行。
- faf_read、faf_write 仅能在允许根目录内操作（cwd、系统临时目录或 FAF_ALLOWED_ROOTS）。
- 其余具体平台支持范围、收费与价格信息暂未提供。
