このサイトを訪れるのは、もう人間だけではありません。インストール手順を探すコーディングエージェント、「Crafter Station とは何か」に答えるアシスタント、そして引用する価値があるかを判断するクローラー。先週、彼らにとってこのサイトを読めるものにする層をリリースしました。この記事はその地図です。
すべての土台にある原則は短いものです。読むのは開かれている、書くのは違う。以下はすべて公開されていて、認証は要りません。エージェントが状態を変えられる二つの操作は、一本の認証された経路だけを通ります。最後に説明します。
まずここから#
どの入口も、ロケールの接頭辞なしの予測可能なアドレスにあります。
| 欲しいもの | 取得先 |
|---|---|
| エージェント向けの README | /agents.md |
| ドキュメント全ページの一行インデックス | /llms.txt |
| ドキュメント全ページの全文 | /llms-full.txt |
| ドキュメント 1 ページの markdown | /llms.mdx/{slug}?lang={locale} |
| 各読み取りエンドポイントの機械可読な記述 | /openapi.json |
| MCP による構造化アクセス | /mcp |
| MCP マニフェスト | /.well-known/mcp.json |
最初に読むべきは agents.md です。コーディングエージェントがリポジトリに期待する AGENTS.md と同じ形をしていますが、記述しているのはコードベースではなくウェブサイトです。何があるのか、どこから取得するのか、そしてユーザーが読むことではなく動くことを求めたときに何をすべきか。
MCP サーバー#
/mcp は Streamable HTTP 上のステートレスな Model Context Protocol サーバーです。JSON-RPC 2.0 を POST すると JSON が返ります。サーバー起点のストリームも、維持すべきセッションもありません。だからこそ、ページと同じデプロイ上の普通の route handler として動かせます。
curl -s https://crafter.run/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Claude Code へは一行で追加できます。
claude mcp add --transport http crafter https://crafter.run/mcpツールはすべて読み取り専用です。現在は八つあります。
search_docs、list_docs、get_doc。npm に公開している CLI のドキュメント用。list_oss_repos。オープンソースのカタログを、スター数とイシュー数のライブ値付きで。list_productsとlist_team。何を作っていて、誰が作っているか。list_shipsとlist_crafters。コミュニティのディレクトリ。
いずれも任意の locale を受け取り、既定は英語です。サーバーは agents.md、二つの llms ファイル、OpenAPI ドキュメント、参加手順も MCP リソースとして公開しているので、リソースを扱えるクライアントはプロトコルの外に出ずに同じ地図を手に入れられます。
単一の情報源#
私たちが一番気にしているのは、個々の入口そのものではありません。それらが互いに矛盾しえない、ということです。
agents.md、openapi.json、.well-known/mcp.json は、どれも同じツール定義のリストからレンダリングされます。ツールを追加するとは、そのリストに一度追加することです。README も OpenAPI 記述もマニフェストも、次のビルドで自動的に追随します。手で保守された API ドキュメントが API から乖離していく様を十分に見てきたので、二つ目のコピーは提出を待っているバグだと分かっています。
鮮度も同じです。サイトマップの lastmod はビルド時刻ではなく実際の編集日を追います。すべての URL に「今」を刻むサイトマップは、クローラーにその項目を完全に無視することを教えてしまうからです。
クロール#
robots.txt は主要な AI クローラーとアシスタントの user agent を名指しで、全速で、待機なしに許可しています。ラテンアメリカでの開発について誰かが尋ねたとき、引用される情報源でありたいからです。扉を閉ざしていては引用されません。
見返りにお願いすることはいつもと同じです。引用したものには出典を示し、使ったページにリンクしてください。
書き込みについてのたった一つのルール#
ユーザーがエージェントに頼みうる操作のうち、書き込みを伴うものは二つあります。Crafter プロフィールの作成と、コミュニティディレクトリへの Ship の公開です。どちらもウェブサイトを経由しません。どちらも @crafter/cli パッケージを通ります。このパッケージが PKCE 付きの OAuth 2.0 authorization code フローを端から端まで所有しています。
CLI はユーザー自身のブラウザを開き、得られたトークンを OS の資格情報ストアに保存します。それを操作するエージェントが、パスワードもメールのコードもトークンも目にすることはありません。ユーザーがまだ持っていない資格情報をコマンドが必要とする場合、正しい振る舞いは、ユーザー自身に crafter login を実行してもらい、待つことです。安全に関するルールを含む完全な手順は /join/agent.md にあります。
このブログも同じです#
いま読んだことはすべて、あなたが読んでいるこのページにも当てはまります。どの記事にも、自分の URL に .md を付けた markdown の双子があります。Accept: text/markdown で求めても同じものが返ります。記事の本文をまるごと運ぶ Atom フィード があり、全記事の markdown インデックス もあります。モデルは何も取得する前に、何を読むかを決められます。
エージェントを作っていて、この地図に足りないものがあれば、リポジトリ がイシューを受け付けています。