AI とエージェント

Pointsman は、人やスクリプトだけでなく、AI エージェントからも使えるように作っています。エージェントは自分で判断する代わりにプロファイルに判定を頼み、その判定は記録されます。

このサイトの作り方

Pointsman のコードとこのドキュメントの多くは、AI の助けを借りて書いています。何を取り入れるかは人が決めます。どの変更もプルリクエストにして人がレビューしてマージし、CI が確かめます(テスト、生成するリファレンスのページ、全ページの英語版と日本語版が同じ構成であること、すべてのリンク)。誤りを見つけたら、Issue でお知らせください。

このサイトを読む AI のツール向け

• 最初に読むもの: llms.txt。ドキュメントの全ページを 1 行ずつ説明した短い索引です(英語)。
• すべてを 1 つのファイルで: llms-full.txt。英語の全ページの本文です。
• API: コードから生成した HTTP API と MCP ツール。
• このサイトの robots.txt では、検索、AI の回答、AI の学習のどれにも使ってよいとしています。

AI アシスタントをつなぐ

Pointsman のデプロイは、どれも /mcp で MCP(Model Context Protocol。AI アシスタントがツールを呼び出すための仕組み)を提供します。

• 人は GitHub でサインインします。入れるのは、そのデプロイが許可した GitHub の組織のメンバーだけです。組織に属しているかはサインインのときに確かめるため、組織を離れた人も最大 7 日間は使えます(詳細、英語)。Geolonia 自身のデプロイは https://mcp.pointsman.net/mcp にあり、Geolonia のチームが使っています。ご自身で Pointsman を使うときは、デプロイして、そのアドレスを使ってください。
• スクリプトや CI は、API トークン(Authorization: Bearer <token>)で MCP か HTTP API を使います。トークンはクライアントごとにあり、使えるプロファイルを限定できます。API トークンの入れ替えも参照してください。

Claude Code では、次のコマンドでサーバーを追加します。

claude mcp add --transport http pointsman https://<your deployment>/mcp

Claude Desktop と claude.ai では、コネクターの設定で、同じ URL のカスタムコネクターとして追加します。API トークンを使う場合も含めた詳細は、MCP サーバー(英語)のページにあります。

エージェントにできること、できないこと

エージェントにできること:

• 使えるプロファイルのうち MCP で公開されているものを一覧し、平易な文で読めます(explain_profile)。
• プロファイルに判定を頼み、あとからその判定を読み直せます。
• 変更したポリシーを、これまでの判定で試せます(リプレイ)。このとき何も変更しません。
• GitHub でサインインした人として使うときは、判定の回答を訂正できます。

エージェントにできないこと:

• プロファイルやルールは変えられません。プロファイルは、人が自分たちの設定用リポジトリから公開します。

• クライアントの範囲外のプロファイルは使えません。範囲外のプロファイルは、存在しないものとして扱われます。

• MCP では、記録されない判定はできません。MCP での判定はすべて、頼んだクライアントの名前で記録されます(人の場合は github:<login>)。HTTP API ではテスト用トークンの判定は記録されませんが、MCP はテスト用トークンを受け付けません。

• MCP ではレビューを決められません。アクションが review の判定は人の確認を待ち、MCP にはそれを決めるツールがありません。

  ただし HTTP API では、そのプロファイルを使えるトークンを持つクライアントならレビューを決められます(レビューとコールバック、英語)。誰が決めたかとして送る名前も確かめられません。そのようなトークンは、レビューする人が使うツールにだけ渡し、エージェントには渡さないでください。

外部の人が書いた入力を扱うプロファイルでは、AI の回答は判定を厳しくする方向にしか使いません。その理由も参照してください。

アシスタントとプロファイルを書く

アシスタントがプロファイルの下書きを書き、Pointsman 自身のツールで確かめます。スキーマ、文章にしたルール、テストケース、これまでの判定でのリプレイです。内容を承認するのは人です。詳しくは AI アシスタントとプロファイルを書くを参照してください。