claude-faf-mcp

claude-faf-mcp

主页： faf.one/mcp 网站： claude.faf.one

持久项目上下文与记忆，为你自动循环更新。 一键设置。30 秒。🐘 Nelly 永不遗忘。

FAF 定义。MD 指引。AI 编码。

⭐ 为你收藏，也帮助其他开发者发现它。

FAF 上下文摄取契约的 v0.2 兼容读取器。

🐘 三向同步 | .faf → MEMORY.md（faf_tri_sync），同时支持 .faf → CLAUDE.md（faf_sync）。

⚡ faf 提示词——从宿主的提示词列表中选择它（Claude Code 中显示为 /mcp__<server name>__faf）。它会为项目评分、根据仓库内容填充可填写的部分，只向你询问只有你能回答的问题，完成验证并同步。

7.0.0 是一次重大版本发布——评分可能会变化。 claude-faf-mcp 现在使用 faf-cli 8 的始终按 33 项评分引擎。缺少 12 个企业级 slotignored 标记的 .faf 会将它们计为空项（21 项已填 = 64%）：运行 faf_auto 即可写入这些标记。npx 配置和 SessionStart 钩子未固定版本，因此运行 npx -y claude-faf-mcp 的安装会在下次启动时升级到 7.x。所有变更都记录在 CHANGELOG 中。

Claude 的上下文： faf-cli 会根据评分后的 project.faf 生成此仓库的 CLAUDE.md——在此处使用 faf_sync，在 faf-cli 中使用 faf sync。请参阅 FAF-CLI for Claude Code 👀。

组合使用 faf-cli（版本固定在 package.json 中）。检测、评分、渲染及所有写入操作均由 faf-cli 自身的函数完成，并作为依赖项加载；claude-faf-mcp 不会分叉这些函数，也不会运行 PATH 中找到的 faf。

核心 14 个 MCP 工具（设置 FAF_TOOLS=all 时为 30 个）。采用 IANA 注册格式（application/vnd.faf+yaml · application/vnd.fafm+yaml）。

---

v7.1.0 新特性 — Instructions 版

claude-faf-mcp 现在会告诉 Claude 如何配合使用其工具：initialize 中的服务说明（637 个字符），以及 faf-cli 8.5.0，它能识别 skills 仓库。

• 服务说明。 Claude 连接时，服务会用五行简短说明介绍如何配合使用其工具：一次处理一个项目、先读取 project.faf、向用户询问由人提供的答案、project.faf 是信息来源、只有在用户要求时才记住。
• 内置 faf-cli 8.5.0。 faf_init 和 faf_auto 会检测 skills 仓库：包含 SKILL.md 的文件夹会将其识别为 skills（10 个槽位），Claude Code 插件清单会将其识别为 skills-plugin（14 个槽位）。
• --version 和 --help 会打印信息后退出，而不是启动服务。
• 已解决三项安全公告： MCP SDK、zod 和 hono。

Always33 版（7.0）

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

• always-33 引擎。 每个工具都使用 faf-cli 8.0.0 评分——全部 33 个 Mk4 槽位，共用一个 Rust 内核。实时验证结果：faf-python-sdk 为 56，mcp-context-card 为 56，faf-cli ✪ 100，与 faf-cli 和参考评分器给出的数字一致。
• 你的 21 个槽位，以及可见的 12 个企业槽位。 除非你的 app-type 会用到企业槽位（infra、app、ops），否则它们会标记为 slotignored。faf_score 会根据全部 33 个槽位评分；slotignored 槽位不会计入分母。
• 升级： 不含这 12 个标记的 .faf 现在会根据 33 个槽位评分。运行 faf_auto——它会写入这些标记，你的分数便会恢复（真实的 v7 时代文件从 56% → ✪ 100%）。

---

v6.0.0 — 实至名归的徽章版

每个徽章都实至名归，不冒领：claude-faf-mcp 6.0 组合使用 faf-cli，只改动自己写入的内容，并且每个工具都如实说明——分数只有一个，事实来自仓库，与 PATH 无关。

• 组合使用 faf-cli 7.13。 检测、评分、渲染和所有写入操作都使用 faf-cli 自带的函数。claude-faf-mcp 绝不会运行从 PATH 中找到的 faf。
• 只改动自己写入的内容。
  • 每次写入都是原子操作，并通过 faf-cli 的安全路径完成；如果文件链接到项目外部，则拒绝操作。
  • 编辑 project.faf 时会保留你的注释和精确值。
  • 你的 soul.fafm 和 Claude 自己的 MEMORY.md 笔记都会保持原样。
• 只有一个分数。 每个工具都显示 faf-cli 的分数，且只有达到 100% 才会显示 ✪。
• 事实来自仓库。 每个空槽位都会说明如何填充：
  • 仓库中的事实，由 faf_auto 写入；
  • 仓库中没有事实，由你通过 faf_go 填写；
  • 或 由你提供，适用于 6Ws。
• 如实说明的工具。
  • 每个标题、提示和架构都与工具的实际功能相符；运行前会拒绝无效参数。
  • Core 14：faf_setup 和 faf_tri_sync 加入默认列表。
• 适用于任何仓库，安全可靠。
  • 克隆仓库的符号链接不会进入 AI 的上下文。
  • faf_go 的回答不会污染对象。
  • 文件工具的操作范围不会超出当前项目。
• 运行什么，就随附什么。 .mcpb 会运行其中打包的服务；服务启动并通过检查后才会记录其 sha。支持 Node 22+，CI 覆盖 Ubuntu、macOS 和 Windows 上的 Node 22 和 24。
• 已弃用： faf_clear、faf_friday、faf_guide、faf_write、导入到 project.faf 的互操作模块，以及 faf_check 的 protect/unlock。归档标签 archive/cfm-v5-surface 会保留这些内容。

---

3W——3 个答案，仅此而已

每个伟大的产品都始于对 3W 的 3 个回答——为谁、做什么、为什么：

	为谁服务？	做什么？	为什么要构建它？
Uber	需要搭车的人	点一下按钮，车就到了	出租车服务太糟糕了
Airbnb	住不起酒店的旅行者	住进别人闲置的房间	有数百万间空房
Slack	被邮件淹没的团队	有条理的群组消息交流	决策淹没在讨论串中
Venmo	分摊账单的朋友	即时转账	总有人忘了还钱

模式都一样。每个成功的产品都从这里开始。.faf 会记录这些信息：

human_context:
  who: "people who need a ride across town"
  what: "tap a button, car arrives in minutes"
  why: "taxis are slow, expensive, and hard to find"

只需 30 秒。Claude 会据此构建你的 project.faf。之后的每次会话中，AI 都能更聪明地开始工作。

6W——让 AI 达到最佳状态

3W 能帮你起步。要让 AI 达到最佳状态，请补全整套信息——在哪里、何时、如何：

  where: "mobile app, iOS and Android"    # where does it live?
  when: "launch in 3 months"              # when is it shipping?
  how: "GPS matching, real-time pricing"  # how does it work?

3W 让 AI 启动项目。6W 则让 AI 达到 100% 优化。相同的 YAML，相同的文件。更多示例 → faf.one/ideas

---

快速开始

需要 Node 22 或更高版本。

Claude Desktop——一键安装

⬇ 下载 claude-faf-mcp-7.1.0.mcpb

在 Claude Desktop 中打开。该扩展会运行内置的服务（启动时无需 npx，也无需联网），并列出核心 14 个工具。

Claude Desktop——配置

将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "faf": { "command": "npx", "args": ["-y", "claude-faf-mcp"] }
  }
}

安装 npm install -g claude-faf-mcp 后，也可以使用已安装的二进制文件：{ "command": "claude-faf-mcp" }。如果 Claude Desktop 的 PATH 中有 Bun，也可以使用 { "command": "bunx", "args": ["claude-faf-mcp"] }。

Claude Code

claude mcp add faf -- npx -y claude-faf-mcp

固定版本

npx 配置和 SessionStart 钩子 faf_setup（通过 npx -y claude-faf-mcp --session-refresh 安装）都不会固定版本：它们会运行最新版本，因此无需重新安装即可获得修复，新主版本发布时也会自动更新。若要固定在某个主版本，请自行在配置中指定："args": ["-y", "claude-faf-mcp@6"]。.mcpb 会运行其构建时使用的版本。

接下来

运行 faf 提示词——Claude 会为你的项目评分，尽可能根据仓库内容补全信息，询问只有你才能回答的问题，然后验证并同步。

或者直接告诉 Claude 你的 3W：“我正在为 [谁] 构建 [什么]，因为 [为什么]”

faf-cli——适用于任何终端

npx faf-cli auto

相同的 .faf，适用于各种平台——Claude、Gemini、Grok、Cursor。在 npm 上查看 faf-cli →

---

工作原理

You → 3 answers → project.faf → AI reads it → every session → forever

project.faf  ──→  CLAUDE.md     (faf_sync)
project.faf  ──→  MEMORY.md     (faf_tri_sync 🐘)

语言、框架、包管理器、构建工具——faf-cli 会从现有文件中检测这些信息。只有人类上下文需要由你提供。

---

面向 Claude Code 团队

.faf 位于仓库中。你的上下文与代码同行——已提交、已版本化，搞定。

每次会话都有可靠依据。 只需安装一次原生 SessionStart hook（faf_setup——先预览，保留你的设置）。之后，每次 Claude Code 会话启动时都会显示一行心跳信息，而不是一片空白：

faf: context ✪ 100% — fresh · +7 intent the code can't carry

这行信息就是接力棒：Claude 已经了解你的技术栈和分数，而 +N 表示代码无法承载的意图——只有你才能提供或确认目标和六个 W。每次会话开始时，无需再解释“这个项目是什么”。

它天生就能扩展到整个团队：

commit project.faf  →  every teammate's Claude starts with the same context
git clone           →  a new dev's Claude is grounded before they write a line

• 单一事实来源。 faf_sync 根据 .faf 写入 CLAUDE.md——只写入由 faf 管理的区块，因此你自己的笔记会原样保留。添加 MEMORY.md 即可实现跨会话记忆（tri-sync 🐘）。
• 不会偏移。 分数是确定性的——相同的 .faf，在每台机器和 CI 上都会得到相同的分数。队友不会不知不觉比你缺少上下文。
• 本地运行。 无需账户，不采集遥测信息，也不会向 FAF 发送任何内容。唯一的网络操作是克隆你指定的仓库，而且只有在你提出请求时才会执行（隐私）。上下文属于你；它随仓库同行。

入职只需 git clone，即可获得可靠依据。 新队友通常需要四处询问才能了解的上下文，从首次克隆开始就已存在于仓库中，且机器可读。

---

评分：从盲目到优化

等级	分数	含义
✪ TROPHY	100%	黄金代码——AI 已优化
★ GOLD	99%+	上下文近乎完美
◆ SILVER	95%+	非常出色
◇ BRONZE	85%+	可用于生产环境
● GREEN	70%+	基础扎实
● YELLOW	55%+	AI 像抛硬币一样碰运气
○ RED	<55%	AI 工作时没有上下文
♡ WHITE	0%	完全没有上下文

分数为 55% 时，AI 有一半时间都在猜。分数为 100% 时，AI 了解你的项目。该分数对应 faf-cli 的 scoreFafYaml——对于同一个文件，faf score 始终输出 33 的数字。

---

MCP 工具 — 核心 14 个，设置 FAF_TOOLS=all 后为 30 个

默认情况下，claude-faf-mcp 会列出核心 14 个工具——你常用的生命周期工具。设置 FAF_TOOLS=all 即可同时列出扩展工具；无论采用哪种方式，都可以按名称调用每个工具。6.0.0 版本中已停用：faf_clear、faf_friday、faf_guide 和 faf_write（按名称调用会返回一行文字，说明应改用什么工具）、导入到 project.faf 的 AGENTS.md / .cursorrules / GEMINI.md / conductor，以及 faf_check 的保护/解锁功能。

每个工具都通过本软件包依赖的 faf-cli 运行。不会从你的 PATH 运行任何内容。

核心

工具	用途
faf_init	为文件夹创建 project.faf（faf-cli 会检测技术栈）
faf_auto	根据仓库自身文件填充 project.faf，然后读取 CLAUDE.md
faf_go	通过问答明确目标和 6W
faf_score	由 faf-cli 生成的 AI 就绪度评分（0-100%）
faf_bench	对 AI grounding 进行基准测试——冷启动与加载 .faf 后的效果对比，由机器评分并附上凭证
faf_doctor	诊断 project.faf：列出每项发现及可修复它的工具
faf_trust	验证 project.faf 并返回其评分的信任凭证
faf_sync	根据 project.faf 写入 CLAUDE.md——agents/cursor/gemini/copilot/all 还会写入 AGENTS.md / .cursorrules / GEMINI.md / copilot-instructions.md
faf_tri_sync	将 faf 内容块写入 Claude Code 为此项目加载的 MEMORY.md 🐘
faf_setup	在项目设置中安装 SessionStart hook（先预览）
faf_context	显示或设置当前项目；detail 会返回 .faf 文本
faf_etch	跨会话记住一项决策（项目灵魂文件 soul.fafm）
faf_recall	从项目灵魂文件中回忆记忆
faf_about	介绍 .faf 格式

扩展（FAF_TOOLS=all）

工具	用途
faf	从这里开始：查看项目、评分和达到 100% 的步骤（仅读取）
faf_quick	通过一行信息创建 project.faf：名称、目标、语言、框架、托管方式
faf_readme	从 README.md 读取 6W；apply 仅填充空缺项
faf_human_add	设置 project.faf 中的一个 6W 项
faf_formats	列出 faf-cli 在文件夹中找到的格式，以及 faf_auto 将写入的内容（试运行）
faf_git	根据仓库 URL 创建 project.faf（使用 git 克隆仓库——会使用网络）
faf_check	运行 faf-cli 的 validateFaf 并查看每个项目的状态
faf_dna	查看项目的 .faf-dna 血统信息（仅读取）
faf_status	查看项目是否有 .faf，并显示其开头几行
faf_agents	写入 AGENTS.md（OpenAI Codex 及其他 Agent）
faf_cursor	写入 .cursorrules（Cursor IDE）
faf_gemini	写入 GEMINI.md（Google Gemini CLI）
faf_conductor	写入 Google Conductor 的 conductor/ 文件
faf_read	读取当前项目中的文件
faf_list	列出当前项目中的文件夹内容
faf_debug	查看当前项目、写入权限以及捆绑的 faf-cli 版本

---

🐘 Nelly 从不遗忘

faf_sync 根据 .faf 写入 CLAUDE.md，让两者保持一致。

tri-sync 会添加 MEMORY.md，让你的 AI 在每次会话中都记得你的项目。

faf_sync = .faf → CLAUDE.md              ← written from .faf
tri-sync = .faf → MEMORY.md   (faf_sync writes CLAUDE.md)  ← Nelly never forgets 🐘

专业版功能，开发者免费使用。团队版和企业版：faf.one/pro（套餐）

---

.FAF 的定位

Model        Context          Protocol
─────        ───────          ────────
Claude    →   .faf        →    MCP
Gemini    →   .faf        →    MCP
Codex     →   .faf        →    MCP
Any LLM   →   .faf        →    MCP

已由 IANA 注册（application/vnd.faf+yaml）。一个文件，一种格式。定义一次，处处使用。

---

生态系统

软件包	平台	注册表
claude-faf-mcp（本项目）	Claude	npm
faf-cli	CLI	npm + Homebrew
gemini-faf-mcp	Google Gemini	PyPI
grok-faf-mcp	xAI Grok	npm
rust-faf-mcp	Rust	crates.io
faf-wasm	浏览器/Edge	npm
Chrome Extension	浏览器	Chrome Web Store

相同的 project.faf。相同的评分。相同的结果。不同的执行层。

---

质量

测试在 ubuntu、macOS 和 Windows 上使用 bun 运行；构建好的软件包会在这三个平台上的 Node 22 和 24 中打包、安装并启动。CI →

---

隐私

claude-faf-mcp 在你的机器上运行。没有分析、没有遥测、无需账户。它唯一的网络用途是 faf_git，并且只有在你要求它读取代码库时才会使用：它会从你提供的网址克隆代码库。它写入的文件列在**隐私政策 →**中。

---

如果 claude-faf-mcp 对你有帮助，欢迎为代码库点星——这有助于其他人发现它。

---

引用

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

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

Wolfe, J. (2026). 永久记忆与即时回忆：用于多配置文件 AI Agent 记忆的 .fafm 标准. Zenodo. https://doi.org/10.5281/zenodo.20348942

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{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@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 — 免费开源

---

FAF 系列

faf-cli	npx faf-cli init — 为任意项目创建 .faf
claude-faf-mcp	面向 Claude Desktop 的 MCP 服务
gemini-faf-mcp	面向 Gemini CLI 的 MCP 服务
grok-faf-mcp	面向 Grok 的 MCP 服务
faf-mcp	面向 Cursor、Windsurf、Cline、VS Code 的 MCP 服务
rust-faf-mcp	使用 Rust 编写的 MCP 服务
faf-skills	用于 .faf 的 Claude Code 技能
faf.one	博客、下载、文档
IANA: vnd.faf+yaml	上下文格式（2025-10-30）
IANA: vnd.fafm+yaml	记忆格式（2026-05-13）

格式 | 驱动 🏎️⚡️ wolfejam.dev

---

获取 CLI

faf-cli — 原版 AI 上下文 CLI。每位构建者的必备工具。

npx faf-cli auto

MCP 注册表： one.faf/claude-faf-mcp · 2 项 IANA 注册： vnd.faf+yaml（上下文） · vnd.fafm+yaml（记忆） · faf.one · npm

---

零配置。上下文随时可用——每次会话皆如此。