MCP Context Card

mcp-context-card

自分のカードを作りましょう。または、あなたのプロジェクトに追加しましょう。 プロジェクトのコンテキスト、メモリー、アイデンティティを扱う、不可欠な MCP サーバーです。あらゆる MCP クライアントから見つけられ、ひと目で読める1枚のカードとして表示されます。

ライト	ダーク

自分のプロジェクトの名刺を表示しましょう — プロジェクトのフォルダーでこれを実行します。context-card.html を作成し、ブラウザーで開きます。表面には名前、肩書き、ひとこと紹介が表示されます。裏返すと、About、Context、Memory、Discoveryが表示されます。

npx mcp-context-card card

コンテキスト — プロジェクトの AGENTS.md を、全体またはセクション単位で提供します。

メモリー — セッションをまたいで保持される事実をファイルに保存します。

アイデンティティ — このサーバー自身の .fafa（agent.fafa、なければ .well-known/fafa）を基に、このサーバーが何者かを示します。

検出情報は、エコシステムですでに使われている2つの仕組み、Server Card の _meta ブロックと ai-catalog.json の兄弟エントリーを通じて提供されます。

どれを選ぶか

目的
AGENTS.md を追加する — まだない場合	author_agents_md が、リポジトリの実際の情報を基に下書きを作成します
AGENTS.md を改善する — すでにあるものを、できる限りよくしたい場合	同じツールが自動で対応します。project.faf を追加すると、目標、対象者、理由を含む BEST 版にアップグレードされます
新しい MCP サーバーのベースを用意する — コンテキスト、メモリー、アイデンティティが組み込まれています	そのまま起動できます。独自のツールを書く前から、ホストはこの3つを備えています
コンテキスト、メモリー、ID を追加して MCP を改善する — すでに MCP サーバーを運用している場合	既存のサーバーと並行して実行できます。移行は不要で、組み合わせて利用できます

ベース MCP として、またはほかの MCP の拡張として

コンテキスト、メモリ、アイデンティティは不可欠です。すべての MCP ホストには、プロジェクトの指示を理解し、セッションをまたいで事実を記憶し、自分が何者かを説明できるエージェントが必要です。mcp-context-card は、この3つを一度に実現します。

• ベース MCP としてセットアップできます。 ホストから接続するだけで、独自のツールを1つも作成する前に、エージェントはセクションごとに提供される AGENTS.md、再起動後も保持される remember / recall / forget メモリ、そして whoami アイデンティティを利用できます。
• 既存の MCP を拡張することもできます。 すでに利用しているサーバー（filesystem、git、データベース、独自のサーバーなど）と一緒に実行すれば、そのエージェントに、これまでなかったコンテキスト、メモリ、アイデンティティの検出機能が加わります。移行は不要で、組み合わせて使えます。

ツールは10個。エコシステムで利用できる2つの検出手段（Server Card の _meta、ai-catalog.json）と、レンダリングされたカードを備えています。MIT ライセンスで、npm で公開されています。

組み合わせて使えます。

• 提供・検出・レンダリング — このサーバー
• より優れたものを作成し、正確さを保つ — agents-md-facts（事実レイヤー向けに author_agents_md がラップし、project.faf がある場合は独自の BEST レイヤーを追加します）
• ファイル・シェル・git — server-filesystem、server-git / github‑mcp‑server、テストランナーの MCP

ベンダーに依存しません。コンテキストはプレーンな Markdown（AGENTS.md）です。メモリとアイデンティティの形式は、入れ替え可能な例です。読み書きするのは独自の3つのファイル（AGENTS.md、project.fafm、agent.fafa または .well-known/fafa）と、リクエスト時に保存する context-card.html だけです。汎用のファイルアクセス、シェル、検索機能はありません。

カード

ページ上部のスクリーンショットは、まさにこれです。同じ情報源を、自己完結型の HTML ページにビジネスカードとして表示したものです。人が見るためのもので、読んだり、スクリーンショットを撮ったり、PR に貼り付けたり、ステータスページに載せたりできます。

• **表面：**名前、タイトル（何であるかとそのバージョン：「MCP server」、「A2A agent」など。プロジェクトの .fafa に記載された実行元に基づきます）、一文の説明（説明の冒頭部分）。
• **裏面（Flip）：**About（全体のプロフィール）、Skills（.fafa に機能が記載されている場合）、Context（AGENTS.md）、Memory、Discovery のタブがあります。長い内容はカード内でスクロールできます。
• 横向きまたは縦向き：▭ ▯ ボタンで表示を切り替えます。--portrait ／ ?layout=portrait で設定できます。
• **ライトまたはダークのカード：**カードの色は、印刷したカードのように独自のものです。--theme ／ ?theme= で設定できます（デフォルト：OS の設定に従います）。◐ で切り替えられます。カードの周囲のページは常に OS の設定に従います。

表裏の切り替え、タブ、表示の切り替えには通常の 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 はデフォルトで tl;dr 形式です。5 つの情報をそれぞれ、保存されている最初の文だけに切り詰めるため、プロジェクトにどれだけの情報が記録されていても小さく保たれます。detail: "full" を指定すると、すべての情報を省略せずに表示します。サーバーの指示により、モデルは HTML をチャットに貼り付けず、こちらを表示します。

ライト、ダーク、または自動。色は所有者が決めます。プロジェクトの .fafa（metadata.cards.accent: "#0066cc"）に設定するか、--accent または ?accent で任意の 16 進数カラーコードを渡します。指定がなければ、カードは黒または白のインクで描画されます。色が推測されることはありません。 このリポジトリ自身のカードはこちらで確認できます：自動 · ライト · ダーク （.fafa で宣言されている AAIF オレンジを使用）。

セットアップに追加する

まだ AGENTS.md がありませんか？

author_agents_md ツールで作成できます。リポジトリの実際の情報（ビルド／テストコマンド、エントリーポイント、ツールチェーンの規約など）に基づく BETTER なもの（agents-md-facts 経由）、または project.faf がある場合は BEST なものを作成します。後者には同じ情報に加え、構造化された目標、対象者、その理由がセクションとして先頭に加わります。設定は不要です。実際の内容に応じて段階が決まります。 （この段階分けの詳細はこちら。）

セッション外で情報レイヤーを作成または正確な状態に保つには：

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

カードを見る

コマンドを 1 つ実行するだけです。ホストも設定も不要で、プロジェクトのディレクトリから実行します。

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" } を設定します。これが常に優先されます。ID の設定は任意です。HTTP を使う場合は、代わりに次のようにします。 PORT=8080 npx mcp-context-card。Node ≥22 が必要です。

HTTP モードはデフォルトでローカルのみです。これは MCP transports 仕様の要件に従ったものです。127.0.0.1 にバインドし、外部のブラウザーオリジンからのアクセスを 403 で拒否し、このマシンに再バインドされた DNS 名も拒否します。HOST=0.0.0.0 にすると外部に公開されます（コンテナーまたはホスト環境へのデプロイ）。認証もレート制限もないため、公開するサーバーはご自身で用意したものの背後に置いてください。 メモリーはセッションデータです。公開されたサーバーでは /card に件数のみが表示され、MCP_CONTEXT_CARD_PUBLISH_MEMORY=1 を設定しない限り、project.fafm が提供されたり一覧表示されたりすることはありません。詳細： docs/TRANSPORT.md。

command: "npx" の起動に失敗する場合（spawn npx ENOENT — ホストプロセスがシェルの PATH を継承しない Cursor で発生しています）は、command に node を指定し、インストール済みの dist/bin.js を使ってください。詳しくは docs/WIRING.md を参照してください。トランスポートの選択については docs/TRANSPORT.md を参照してください。

すでに実行している MCP を拡張する場合：ほとんどのホストでは mcpServers に複数のエントリーを追加できます。server-filesystem、server-git、または独自のサーバーと並べて context-card を追加すると、ほかに何も変更することなく、そのホスト内のすべてのエージェントがコンテキスト、メモリー、ID の検出機能を利用できます。

識別子について

AI Catalog では各エントリーに urn:air:{domain}:{namespace}:{name} という名前を付けます。ドメインはご自身で決めます。これはプロジェクトの .fafa から取得されます。npx faf-cli card init（または --domain example.com）を実行すると、agent.id: urn:air:example.com:agent:<short-name> が書き込まれます。その後、カタログには urn:air:example.com:context:<short-name> などが公開され、コードを変更する必要はありません。このリポジトリの .fafa では faf.one を指定しています。これはこのリポジトリの例であり、ご自身のものにはご自身のドメインを指定します。

.fafa がない場合、ドメインは自動的に作成されません。提供されるカタログでは、配信元のホスト（ローカルで実行する場合は localhost）が使われ、静的な .well-known/ai-catalog.json ではプレーンな <short-name>:<namespace> ID が使われます。

この仕組みが必要な理由

AGENTS.md は、リポジトリでの作業方法をコーディングエージェントに伝えるための事実上の標準です。しかし、クライアントはそのファイルの存在を 知っている 必要があり、内容全体をコンテキストに読み込まなければなりません。サーバーが「ここに私の AGENTS.md があります。私が覚えていることはこれです。私が誰かはこれです」と伝える標準的な方法はありません。そのため、これに対応するサーバーはそれぞれ独自の形式を作り込むことになります。

mcp-context-card は、すでに存在する仕組みを通じて、これら 3 つすべてに対応します。

1. Server Card _meta（SEP‑2127） — 用途ごとにリバース DNS 形式のキーを 1 つ用意し、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）を参照します。メモリーと ID には、まだ事実上の標準がありません。そのため、ここでは .fafm と .fafa を例として使っています。それぞれ 1 つの実装例です。ご自身のものに置き換えてください。

ワイヤーレベルの詳細は 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 形式のカードと完全版へのリンクを返します

7 つのツールは読み取り専用です。remember と forget はメモリファイルに書き込み、save_context_card は context-card.html に書き込むため、この 3 つは破壊的操作としてマークされており、ホストは実行前に確認を求めることができます。各ツールにはタイトルと 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 を確認します。

Linux、macOS、Windows で 210 件のテストを実行し、CI でカバレッジの基準を適用しています。 npm run wjttc を実行すると、プロトコルと Server Card の準拠から、stdio/HTTP の同等性、パッケージの公開状態まで、7 段階の WJTTC 認定スイートを実行します。2 つのテストでは実際の子プロセスを起動し、再起動後も記憶した事実が保持されることを確認します。一方は既存の project.fafm に対して、もう一方はまだ project.fafm がないプロジェクトから開始します。また、stdio と HTTP のツールサーフェスが一致することを確認するテストと、各ツールのタイトルおよび動作ヒントが実際の動作と一致することを確認するテストもあります。 src/conformance/discovery.ts は、あらゆるサーバーの Server Card、AI Catalog、トランスポートセキュリティを仕様に照らして、一度に MUST または SHOULD を 1 つずつ確認します。

構成

パス	内容
src/server.ts	10 個のツールと 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 により 1 つの HTML ページとして描画されます
src/memory.ts	ファイルベースの remember / recall / forget
src/identity.ts	whoami（.fafa → package.json の順にフォールバック）と _meta ブロック
src/server-card.ts	MCP Server Card（SEP-2127、スキーマ v1）
src/catalog-gen.ts	Server Card と関連エントリーを含む ai-catalog.json を書き込みます
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 を同梱しています。