MCP Context Card

mcp-context-card

获取一张，或添加到你自己的名片中。 为项目提供上下文、记忆和身份信息的必备 MCP 服务——任何 MCP 客户端都能发现它，并以一张易读的卡片呈现。

浅色	深色

查看你自己项目的名片——在项目文件夹中运行此命令。它会生成context-card.html并在浏览器中打开。正面是名片：名称、头衔、一句话简介。翻到背面，可查看 About、Context、Memory 和 Discovery。

npx mcp-context-card card

上下文——项目的AGENTS.md，可整体提供，也可一次提供一个章节。

记忆——以文件形式保存、可跨会话留存的事实。

身份——此服务自身的身份信息，来自其.fafa文件（agent.fafa，否则使用.well-known/fafa）。

发现功能通过生态系统中已有的两个入口实现：Server Card 的_meta块和ai-catalog.json同级条目。

选择一项

你的需求是……
添加AGENTS.md——你还没有	author_agents_md会根据仓库中的实际信息起草一份
改进AGENTS.md——你已经有一份，想把它做到最好	同一个工具会自动完成——添加project.faf，它就会将文档升级为 BEST：包含目标、适用对象和原因
获取新的 MCP 服务基础框架——内置上下文、记忆和身份信息	直接部署此服务；无需编写自己的工具，主机就已具备这三项功能
为你的 MCP 添加上下文、记忆和身份信息——你已经在运行 MCP 服务	与现有服务一起运行；无需迁移，可组合使用

作为基础 MCP，或为任何其他服务扩展

上下文、记忆和身份至关重要——每个 MCP 宿主都需要一个 Agent，它了解项目说明，能跨会话记住事实，并能说明自己的身份。mcp-context-card 一次性提供这三项能力：

• 将其部署为基础 MCP。 让宿主连接到它，Agent 就能按章节获取 AGENTS.md，使用重启后仍能保留的 remember / recall / forget 记忆，并通过 whoami 获取身份信息——这一切都不需要先编写任何自有工具。
• 也可以用它扩展任何现有 MCP。 让它与已有服务并行运行——无论是文件系统、git、数据库还是自有服务——Agent 就能获得原本不具备的上下文、记忆和身份发现能力。无需迁移；可组合使用。

十个工具，以及生态系统中已有的两个发现入口（Server Card _meta、ai-catalog.json），还有一个渲染后的 卡片。采用 MIT 许可证，发布于 npm。

它可组合使用：

• 提供 · 发现 · 渲染 — 本服务
• 编写更好的内容，并保持真实 — agents-md-facts（author_agents_md 为事实层封装了它；如果存在 project.faf，还会添加其自有的 BEST 层）
• 文件 · Shell · git — server-filesystem、server-git / github‑mcp‑server，以及测试运行器的 MCP

无供应商绑定——上下文采用纯 Markdown（AGENTS.md）；记忆和身份格式只是可替换的示例。它只读写自己的三个文件（AGENTS.md、project.fafm 和 agent.fafa 或 .well-known/fafa），以及按请求保存的 context-card.html——不提供通用文件访问、Shell 或搜索功能。

名片

本页顶部的截图正是这个内容：将相同来源呈现为一张商务名片，放在一个独立的 HTML 页面中。面向人的视图：阅读、截图、放进 PR，或放到状态页上。

• **正面：**名称、标题（它是什么及其版本：MCP server、A2A agent，以及项目的 .fafa 中声明的运行位置）和一句简介（描述的开头）。
• 背面（翻转）：包含关于（完整身份信息）、技能（.fafa 列出能力时显示）、上下文（AGENTS.md）、记忆和发现的标签页。长内容会在名片内滚动。
• 横向或纵向：▭ ▯ 按钮可切换视图；使用 --portrait / ?layout=portrait 设置。
• **浅色或深色名片：**名片使用独立配色，就像一张印刷名片。使用 --theme / ?theme= 设置（默认跟随你的操作系统），按 ◐ 切换。名片周围的页面始终跟随你的操作系统。

翻转、标签页和视图切换都由纯 CSS 实现，因此关闭脚本后仍可使用。一个小型内嵌脚本负责添加“全部展开”功能、在背面打开 #section 链接，并在打印时展开所有版块。使用 --expanded / ?expand=all 可将正反两面平铺呈现，并展开所有版块，方便截图或打印。

npx mcp-context-card card            # at a terminal: writes context-card.html and opens it
npx mcp-context-card card --portrait # the tall view
npx mcp-context-card card --expanded # both faces flat, every section open
npx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdout
GET /card                            # live, on the HTTP transport
GET /card?layout=portrait&theme=light&accent=%230066cc

在聊天中，支持 MCP Apps 的宿主会在 render_context_card 运行时内嵌显示名片；模型收到的是简短摘要，而不是页面。在其他情况下，save_context_card 会将 context-card.html 写入项目；服务在本地运行时会在浏览器中打开该文件，并以 Markdown 回复名片内容（身份信息、AGENTS.md 版块、记忆、发现）、完整名片链接，以及可供复制的地址。默认情况下，Markdown 是一份简要摘要：列出五条事实，每条仅保留存储内容的首句，因此无论项目记录了多少内容，摘要都能保持精简。detail: "full" 会列出每条事实的完整内容。服务说明会告诉模型优先展示这份摘要，而不是把 HTML 粘贴到聊天中。

浅色、深色或自动。配色由所有者决定：在项目的 .fafa 中设置（metadata.cards.accent: "#0066cc"），或通过 --accent 或 ?accent 传入任意十六进制颜色。若未指定，名片会以黑色或白色墨色绘制；不会猜测颜色。 本仓库自己的名片，在线查看：自动 · 浅色 · 深色 （采用其 .fafa 声明的 AAIF 橙色）。

添加到你的设置中

还没有 AGENTS.md？

author_agents_md 工具可编写一份文件——有仓库中的真实信息时为更好（构建/测试命令、入口点、工具链约定，通过 agents-md-facts 获取）；存在 project.faf 时则为最佳：在这些相同信息之外，还会将其中结构化的目标、适用对象和原因作为一个版块放在前面。无需配置——级别取决于实际已有的内容。 （此工具遵循的分级说明。）

要在会话之外编写事实层或确保其准确无误：

npx agents-md-facts          # author / refresh AGENTS.md
npx agents-md-facts --check  # fail if missing or stale (CI, pre-commit)

查看名片

只需一条命令，无需宿主或配置——在项目目录中运行：

npx mcp-context-card card

在终端中运行时，它会写入 context-card.html 并在浏览器中打开。通过管道传输或重定向（> card.html、脚本、CI）时，它会改为将原始 HTML 写入 stdout；--stdout 也可在终端中强制执行此行为。--expanded 会展开所有版块。

将其接入宿主

goose、Claude Desktop、Cursor 或任何 stdio 宿主：

{
  "mcpServers": {
    "context-card": {
      "command": "npx",
      "args": ["-y", "mcp-context-card"]
    }
  }
}

无需配置路径：服务会询问宿主你所在的项目（MCP 根目录——goose 会发送其会话的工作目录），然后在该目录包含 AGENTS.md 时，将其作为回退目录。如果找不到，则使用服务启动时所在的目录。list_context_sources 会报告它选择的项目及选择方式。若要固定使用某个项目，可设置 "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }；该设置始终优先。身份信息为可选项。若要改用 HTTP： PORT=8080 npx mcp-context-card。需要 Node ≥22。

按照 MCP 传输规范的要求，HTTP 模式默认仅限本地访问：它会绑定到 127.0.0.1，对外部浏览器来源返回 403，并拒绝指向本机的 DNS 名称。 设置 HOST=0.0.0.0 可将其对外开放（用于容器或托管部署）。它没有身份验证或速率限制，因此对外开放的服务应由你自行置于其他服务之后。 记忆属于会话数据：对外开放的服务只会在 /card 显示记忆数量，且绝不会提供或列出 project.fafm，除非你设置了 MCP_CONTEXT_CARD_PUBLISH_MEMORY=1。详情见： docs/TRANSPORT.md。

如果 command: "npx" 无法启动（spawn npx ENOENT——Cursor 上出现过此问题，因为其宿主进程不会继承 shell 的 PATH），请将 command 指向 node 和已安装的 dist/bin.js——参见 docs/WIRING.md。传输方式见 docs/TRANSPORT.md。

扩展你已在运行的 MCP：大多数宿主接受多个 mcpServers 条目——在 server-filesystem、server-git 或你自己的服务旁添加 context-card，该宿主中的每个 Agent 就都能发现上下文、记忆和身份，其他内容无需更改。

你的标识符

AI Catalog 会将每个条目命名为 urn:air:{domain}:{namespace}:{name}，其中 domain 由你决定。它来自项目的 .fafa：运行 npx faf-cli card init（或使用 --domain example.com），它会写入 agent.id: urn:air:example.com:agent:<short-name>。随后，你的 catalog 会发布 urn:air:example.com:context:<short-name> 等条目，无需更改代码。 本仓库自己的 .fafa 中写的是 faf.one；这是我们的示例，你的 .fafa 则会写入你自己的 domain。

若没有 .fafa，系统不会生成 domain：服务提供的 catalog 会使用提供服务的主机名（本地运行时为 localhost），静态的 .well-known/ai-catalog.json 则使用普通的 <short-name>:<namespace> ID。

为什么

AGENTS.md 是告知编码 Agent 如何在仓库中工作的事实标准。但客户端必须知道该文件存在，并将其全部读入上下文。目前没有标准方式让服务端声明“这是我的 AGENTS.md，这是我记住的内容，这是我的身份”——因此每个需要这些信息的服务端都会自行设计一套方案。

mcp-context-card 通过现有机制提供这三项信息：

1. Server Card _meta（SEP‑2127）——每项关注点使用一个反向 DNS 命名空间键，可在带内通过 MCP 资源读取，也可通过 GET /mcp/server-card 获取（1.x 版本的 /.well-known/mcp/server-card 仍会响应）。
2. ai-catalog.json——包含 Server Card，以及按媒体类型索引的同级条目，可通过 GET /.well-known/ai-catalog.json 获取。

上下文项指向 AGENTS.md（text/markdown）。记忆和身份尚无事实标准，因此此处示例分别采用 .fafm 和 .fafa——各举一种实现；你可以换成自己的格式。

线缆层面的详情见 docs/MECHANISMS.md。

工具

工具	用途
author_agents_md	起草一份 AGENTS.md——基于仓库事实（通过 agents-md-facts）效果更好；存在 project.faf 时效果最佳——可直接放入项目
read_agents_md	返回项目的 AGENTS.md——全文，或按标题返回一个章节
list_agents_md_sections	返回各级标题，让客户端只拉取一个章节，而非整个文件
remember	写入一条事实，确保下次会话仍然存在
recall	读取之前会话中存储的事实
forget	删除或更正过时的事实
whoami	此服务的名称、供应商、版本、状态和许可证
list_context_sources	此项目发布的内容、采用的媒体类型及发布渠道
render_context_card	将整张卡片作为独立的 HTML 页面（也可通过 GET /card 获取）；支持 MCP Apps 的主机可以内嵌显示
save_context_card	将卡片写入项目中的 context-card.html 并在浏览器中打开；返回 Markdown 格式的卡片以及完整版本的链接

其中七个工具只读。remember 和 forget 会写入记忆文件，save_context_card 会写入 context-card.html，因此这三个工具标记为具有破坏性，主机可以在运行前询问。每个工具都带有标题和 MCP 工具注释。

演示

npm run demo 会通过两种传输方式，实时演示上下文、记忆、身份和发现：

1. 上下文 — 列出 AGENTS.md 章节，然后只拉取 ## Test。
2. 记忆 — 使用 remember() 记住一条事实，停止服务进程，再启动一个新进程，然后 recall() 同一条事实。只有文件会将事实保留下来。
3. 身份 — 调用 whoami()，并从实时客户端读取 Server Card 的 _meta 块。
4. 发现 — 调用 list_context_sources()，然后通过无状态 HTTP 使用同一服务及其 .well-known 路由和 GET /card。

210 项测试在 Linux、macOS 和 Windows 上运行，并在 CI 中设有覆盖率门槛。 npm run wjttc 会运行 WJTTC 认证套件（共七个层级，从协议和 Server Card 一致性到 stdio/HTTP 一致性及已发布的软件包）。其中两项会启动一个真实的子进程并检查记忆的事实能否在重启后保留——一项针对现有的 project.fafm，另一项从从未有过该文件的项目开始；另一项会检查 stdio 和 HTTP 工具接口是否一致，还有一项会根据每个工具的实际行为检查其标题和行为提示。 src/conformance/discovery.ts 会根据规范检查任意服务的 Server Card、AI Catalog 和传输安全性，一次检查一项 MUST 或 SHOULD 要求。

目录结构

路径	内容
src/server.ts	十个工具 + Server Card 和卡片资源
src/agents-md.ts	读取并按章节拆分 AGENTS.md
src/author.ts	author_agents_md——借助 agents-md-facts 效果更好；存在 project.faf 时效果最佳
src/md.ts	一个无需依赖的精简 Markdown → HTML 渲染器
src/render-card.ts	卡片——将身份信息、AGENTS.md、记忆和发现信息读入卡片；agent-business-card 会将其绘制为一个 HTML 页面
src/memory.ts	基于文件的 remember / recall / forget
src/identity.ts	whoami（.fafa → 回退到 package.json）+ _meta 块
src/server-card.ts	MCP Server Card（SEP-2127，schema v1）
src/catalog-gen.ts	写入 ai-catalog.json：Server Card 及其同级条目
src/transport/http.ts	无状态 Streamable HTTP 应用（Hono）
src/transport/guard.ts	Origin 和 Host 检查（防 DNS 重绑定）
src/conformance/discovery.ts	可移植的 Server Card / AI Catalog / 传输检查器
src/bin.ts	入口点——stdio · --http · card · --help · --version

相关内容

• 服务卡片 SEP‑2127 · ai-catalog · AGENTS.md
• mcp-project-context — 早期仅关注上下文问题的尝试
• text/markdown (AGENTS.md) · application/vnd.fafm+yaml · application/vnd.fafa+yaml

许可证

MIT。

这个仓库以身作则，使用自己提供的内容——它的 AGENTS.md 是一份真实且最新的文件，并且仓库还附带了一个 project.faf，作为其背后的结构化源文件。