.FAF Context

主页： wolfe-jam.github.io/faf-mcp

.FAF Context 是面向 IDE 的 FAF MCP 服务。在代码库中放置一个 project.faf，即可据此生成每个 AI 工具的上下文文件——AGENTS.md、.cursorrules、GEMINI.md、CLAUDE.md——并进行评分，让你明确知道该把精力放在哪里。它使用终端所用的同一个 faf-cli，通过 stdio 在本地运行。它所属的 FAF 生态系统在 npm 和 PyPI 上的下载量已轻松突破 10 万次（实时数量）。

⭐ 为你添加书签，也帮助其他开发者找到它。

---

4.1.0 新功能 — 指令版

faf-mcp 现在会告诉模型各工具如何协同工作：在 initialize 中提供服务端指令（642 个字符），并内置 faf-cli 8.5.0，能够识别技能仓库。

• 服务端指令。 编辑器的 AI 连接时，服务端会说明各工具如何协同工作：一次处理一个项目，从 faf_doctor 或 faf_score 开始，向用户询问需要人工提供的答案，并说明 project.faf 是 CLAUDE.md、AGENTS.md、.cursorrules 和 GEMINI.md 的来源。
• 内置 faf-cli 8.5.0。 faf_init 和 faf_auto 会检测技能仓库：包含 SKILL.md 的文件夹会被识别为 skills（10 个槽位），而 Claude Code 插件清单会被识别为 skills-plugin（14 个槽位）。
• hono 安全提示已处理（serveStatic 双重解码）。

4.0.1

faf-mcp --version 和 --help 现在会显示结果并退出。此前，这两个选项都会启动服务端。

• --version（-v）会输出版本号；--help（-h）会输出用法说明和客户端配置。其他任何参数仍会像以前一样启动服务端，因此客户端配置无需更改。

4.0.0 — Always33 版本

一个引擎，一个数字：faf-mcp 4 使用 faf-cli 8 的 always-33 内核评分——与 faf-cli、claude-faf-mcp 7 和 faf-kernel 给出的分数相同。

• always-33 引擎。 每个工具都使用 faf-cli 8.0.0 评分——全部 33 个 Mk4 插槽，一个 Rust 内核，仅此一份。实时检查结果：faf-python-sdk 56、mcp-context-card 56、faf-cli ✪ 100。
• 你的 21 个插槽，以及可查看的 12 个企业插槽。 企业插槽（infra、app、ops）会标记为 slotignored，除非你的 app-type 会用到它们。faf_score 根据全部 33 个插槽评分；slotignored 插槽不会计入分母。
• 从 3.x 升级： 不包含这 12 个标记的 .faf 现在会按 33 个插槽评分。运行 faf_auto——它会写入这些标记，并让你的分数恢复。

3.0.2 — Compose 版本

工具言行一致：faf_git 使用 faf-cli 评分并在覆盖前询问，faf_sync 会预览每项更改，导入操作会说明何时没有写入任何内容。

• faf_git 只有一个评分器。 它会报告 faf-cli 对其创建文件的评分，写入 faf-cli 会评分的插槽，并在替换现有的 project.faf 前询问。
• faf_sync 会预览每项更改。 试运行会列出它将更新的每个字段，并注明 apply: true。
• **导入操作会说明何时没有写入任何内容，**而且在没有 project.faf 时使用 merge: true 会明确报错。
• 描述、注释和错误信息与代码一致。 工具输出中没有 CLI 命令或终端颜色代码。

3.0.1 将 faf_bi_sync 重命名为 faf_claude，并让 faf_init 写入与 faf init 相同的内容。完整历史记录见 CHANGELOG。

Compose 版本（3.0）

组合，而非移植：faf-mcp 3.0 在进程内运行 faf-cli 7.12——一个评分器、一套渲染器、一个注入器——本包提供的每个数字、文件和说明都真实可靠。本地 stdio、29 个工具、Node 22+。

• 组合 faf-cli 7.12。 AGENTS.md、GEMINI.md、.cursorrules 和 CLAUDE.md 均由 faf-cli 自带的渲染器、仓库增强功能和块注入器写入——与 faf export 和 faf sync 写入的字节完全相同。faf_auto 会运行 faf-cli 自带的更新链。手动移植的渲染器、v3 之前的 CLAUDE.md 模板和本地注入器都已移除。
• 一个评分函数。 faf_auto、faf_go、faf_dna、faf_doctor 和 faf_claude 都会报告 faf-cli 对磁盘上字节的评分——没有本地启发式算法、冻结的初始评分，也没有“0%”。
• 不调用 shell 命令。 which faf 检测器、exec 回退机制和“请先安装 faf-cli”横幅都已移除；src/ 下没有任何内容导入 child_process。PATH 中存在无关的 faf 不再是问题。
• 每个工具契约都与其处理程序一致。 描述准确说明工具的功能，架构仅声明实际读取的标志，错误会附带原因。
• Mk3 引擎已删除。 44 个无法访问的模块，约 15,900 行；压缩包体积减半。prebuild 会清理 dist/，确保已删除内容不再打包。
• 资源 URI 为 faf://context 和 faf://status；本次发布中仍可通过 claude-faf:// 别名读取。
• Node 22 或更高版本。 18 和 20 已停止维护；CI 矩阵使用 22 和 24，并通过守卫确保最低版本要求准确无误。

---

定义一次，同步到各处。

你维护着 .cursorrules。队友使用 AGENTS.md。团队中有人刚切换到 Gemini。每款 AI 工具都需要自己的上下文文件——而它们表达的内容都一样，只是格式不同。

faf-mcp 是专为 Cursor、Windsurf、Cline、VS Code 和所有非 Claude 平台打造的 MCP 服务。 在代码仓库中使用一个 .faf 文件，同步到团队所需的所有格式。

面向 Cursor 和 IDE Agent 的上下文： faf-cli（v7.12）负责生成此服务同步的文件——bunx faf export --agents，无需安装，且与 Git 原生集成。参见 面向 Cursor 和 IDE Agent 的 FAF-CLI 👀。

                      project.faf
                           │
          ┌────────┬───────┴───────┬────────────┐
          ▼        ▼               ▼            ▼
      CLAUDE.md  AGENTS.md  .cursorrules  GEMINI.md
      (Claude)   (Codex)      (Cursor)    (Gemini)

快速开始

Cursor — 一键安装：

其他平台：

bunx faf-mcp

添加到你的 MCP 配置中：

{"mcpServers": {"faf": {"command": "bunx", "args": ["faf-mcp"]}}}

平台	配置文件
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	Cline MCP 设置
VS Code	MCP 扩展配置
Claude Desktop	使用 claude-faf-mcp

---

运行

faf-mcp 通过 stdio 在本地运行。将 IDE 指向以下任一命令。

方式	命令
npm	npx faf-mcp
Bun	bunx faf-mcp

---

互操作工具

工具	平台	操作
faf_agents	OpenAI Codex	导入/导出/同步 AGENTS.md
faf_cursor	Cursor IDE	导入/导出/同步 .cursorrules
faf_gemini	Google Gemini	导入/导出/同步 GEMINI.md
faf_conductor	Conductor	导入/导出目录结构
faf_git	GitHub	从任意仓库 URL 创建 .faf

# MCP tool calls — ask your IDE's AI
# Write all four formats from project.faf
faf_claude { all: true }

# Author .faf from any GitHub repo
faf_git { url: "https://github.com/facebook/react" }

核心层级： 默认显示 15 个必备工具；设置 FAF_TOOLS=all 可使用完整的 29 个工具（无论哪种方式，每个工具都可以按名称调用） · 26 个测试套件 · 7 个内置解析器

---

永久同步

project.faf 是唯一数据源。faf-mcp 会在毫秒内根据它生成每个工具的上下文文件。

project.faf  ──── 8ms ───→  CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md
                    Single source of truth

• faf_claude { all: true } 一次性写入全部四种格式
• faf_agents、faf_cursor 和 faf_gemini 也可以导入现有文件：merge: true 会将其合并到 project.faf
• faf 管理区块之外的内容会逐字节保留
• 适用于不同团队、分支和会话

AI 助手会遗忘，也会偏离。每次开启新会话，AI 都会重新开始猜测。只有一个数据源，才能确保上下文永不过时。

---

层级系统：从盲目到优化

层级	分数	状态
✪ TROPHY	100%	AI 从不需要猜测
★ GOLD	99%+	距离 TROPHY 只差 1 格
◆ SILVER	95%+	已接近——继续努力
◇ BRONZE	85%+	过渡阶段——继续努力
● GREEN	70%+	过渡阶段——继续努力
● YELLOW	55%+	AI 靠抛硬币做决定
○ RED	<55%	AI 两眼一抹黑
♡ WHITE	0%	完全没有上下文

**达到 55% 时，AI 有一半时间都在猜。**达到 100% 时，AI 得到优化。

---

use>faf | 提示词模式

每个提示词都以「Use FAF」开头，以调用 MCP 工具：

Use FAF to initialize my project
Use FAF to score my AI-readiness
Use FAF to sync my context
Use FAF to enhance my project

适用于所有平台——阻止网页搜索，强制使用工具。

---

29 个 MCP 工具

默认显示的 15 个核心工具：

工具	用途
faf_init	创建新的 project.faf（使用 faf_auto 增强现有文件）
faf_auto	一键设置：初始化或合并、检测技术栈、生成 CLAUDE.md、评分
faf_go	引导式访谈，补充缺失的人类上下文和目标字段，直至达到 100%
faf_score	AI 就绪度评分（0-100%）和等级；details:true 会逐项显示字段明细
faf_doctor	诊断低分原因：缺失文件、字段数量、配置问题，并为每项提供修复方法
faf_check	将每个人类上下文字段评定为空 / 通用 / 良好
faf_trust	使用 faf-cli 的验证器验证必填字段和 about.* 块
faf_sync	将 project.faf 与 package.json 对齐（试运行；apply:true 时写入）
faf_context	设置或显示当前项目路径
faf_about	用通俗语言介绍 IANA 注册的 .faf 格式
互操作工具
faf_claude	根据 project.faf 写入 CLAUDE.md（all:true 还会写入 AGENTS.md、.cursorrules、GEMINI.md）
faf_agents	将 AGENTS.md 导入 project.faf，或根据 project.faf 写入 AGENTS.md
faf_cursor	将 .cursorrules 导入 project.faf，或根据 project.faf 写入 .cursorrules
faf_gemini	将 GEMINI.md 导入 project.faf，或根据 project.faf 写入 GEMINI.md
faf_git	根据公开 GitHub 仓库 URL 创建 project.faf

设置 FAF_TOOLS=all 可使用另外 14 个工具： faf_status · faf_what · faf_guide · faf_debug · faf_clear · faf_list · faf_read（读取允许根目录内的文件：当前工作目录、操作系统临时目录或 FAF_ALLOWED_ROOTS）· faf_write（在相同根目录内写入文件）· faf_readme · faf_human_add · faf_quick · faf_formats · faf_dna · faf_conductor

基于 faf-cli 构建。 每个工具都会在进程内调用随附的 faf-cli——使用相同的评分器、相同的渲染器，以及 CLI 使用的相同块注入器。不会通过 shell 调用 PATH 中的 faf。

---

生态系统

• claude-faf-mcp — Claude Desktop
• faf-cli — 终端 CLI
• faf-wasm — WASM SDK（评分耗时 <5ms）
• faf-wasm-gen — Rust→WASM project.faf 编写引擎，适用于浏览器 / 边缘环境（faf-wasm 的编写功能姊妹项目）
• faf-trinity — 参考 MCP 服务，集中提供全部三种 IANA FAF 格式（上下文 / 记忆 / Agent）
• faf.one — 官方网站
• docs/SKILLS-OVER-MCP.md — J1 Agent Skill faf-ide（stdio · skills/list · 摘要）

---

如果 faf-mcp 对你有所帮助，不妨为仓库点个星——这能帮助其他人发现它。

引用

如果你在研究或生产环境中使用 faf-mcp 或 .faf / .fafa 格式，请引用格式论文：

Wolfe, J. (2025). 格式驱动的 AI 上下文架构：用于持久化项目理解的 .faf 标准. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). 为什么 Agent 需要护照：.fafa——Agent 时代的可移植身份. Zenodo. https://doi.org/10.5281/zenodo.21951641

BibTeX

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

许可证

MIT 许可证 — 免费且开源

---

零偏移。永久同步。为 AI 优化。 ✪

“它如此合乎逻辑，以至于如果它不存在，AI 也会自己创造出来” — Claude