openglass-mcp

OpenGlass

エージェント間のやり取りを中立的に見届けます。docs/SPEC.md と CLAUDE.md をご覧ください。

ローカルで実行する

docker compose up --build -d --wait
curl -k https://localhost/health     # {"status":"ok","checks":{"mongo":"ok","s3":"ok"}}

Caddy は内部 CA の証明書を使用して https://localhost を配信します。-k は証明書の検証をスキップします。代わりに CA を信頼するには、次のようにします。

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert caddy-root.crt https://localhost/health

サービス	URL	備考
web	https://localhost/	Next.js
api	https://localhost/health, /v1/*	Fastify。起動のたびに migrate を実行します。
mcp	https://localhost/mcp
mongo	mongodb://localhost:27017/openglass?directConnection=true	mongo:7、単一ノードのレプリカセット rs0
minio	http://localhost:9001（コンソール）	バケット openglass-records、Object Lock は有効です。ユーザー openglass / openglass-dev-secret。
mailpit	http://localhost:8025	送信メールをすべて受信します

MinIO は公式イメージを公開しなくなったため、compose ではリリースに固定した、メンテナンスされているコミュニティビルド pgsty/minio を使用します。

動作を見る

examples/witnessed-negotiation は、実行可能なエンドツーエンドのデモです。2 つのエージェントが登録し、割り当てを受け、見届けられたセッションで発注書について交渉し、セッションを終了して、作成された記録をそれぞれ独立して検証します。モックではなく、実際の API を使用します。examples/README.md をご覧ください。

リスクポリシー

/spec/openglass-policy は、エージェントのアクションを low／medium／high リスクに分類するための、バージョン管理された小規模なベンダー中立 YAML 形式です。アクションに見届けられた記録を残す価値がある「タイミング」を判断するものであり、アテステーションの仕組み自体とは分離されています（docs/SPEC.md §12）。リファレンス評価器は core-js（@openglass/core）と core-py（openglass-core）です。共通のテストベクトルセットを使って同期を保っています。ガイドについては docs/POLICY.md をご覧ください。

インテグレーション

otel-js/otel-py（openglass-otel）は、すでに OpenTelemetry で計装されているエージェントに組み込めます。SpanProcessor が GenAI スパンを読み取り、それぞれを openglass-policy に照らして分類し、リスクのあるものについてアテステーションを開始します。エージェント自体に OpenGlass 固有のコードは必要ありません。実行可能なデモについては examples/otel-integration をご覧ください。langchain-py（openglass-langchain）も、BaseCallbackHandler を介して LangChain のツール呼び出しに同じ仕組みを提供します。詳しくは examples/langchain-integration をご覧ください。/integrations/_template は、各インテグレーションが必ず合格しなければならない適合性テストを含む、フレームワーク固有の新しいインテグレーションを始めるためのテンプレートです。

公開されている /integrations ページは、リクエストを募る場です。各フレームワークのカード（静的カタログ apps/api/data/integrations.yaml を参照）、投票とリクエストフォーム（GitHub OAuth ではなく既存のオーナーログインで制限されています。その理由については、これを追加した PR をご覧ください）、およびステータスを更新する /integrations/admin の管理者ビューがあります。管理者アクセスには ADMIN_EMAILS 環境変数（オーナーのメールアドレスをカンマ区切りで指定）が必要です。設定されるまでは、誰も管理者ではありません。

scripts/adoption-review.ts は、この掲示板の最新データを使ってレポートを生成する実行可能なスクリプトです（投票ランキング、次に優先すべき 3 つのフレームワーク、新しいリクエスト）。無人で定期実行するのではなく、必要に応じて自分で実行するか、独自の cron から実行してください。

node --experimental-strip-types scripts/adoption-review.ts
# optionally: OG_ADMIN_SESSION_COOKIE="og_session=..." to include the request queue (admin-only)

開発とテスト

corepack enable
pnpm install
pnpm -r build
pnpm -r typecheck
pnpm -r test          # starts a throwaway mongo:7 container (needs Docker)

同じテストを異なる MongoDB で実行する

データベースは MONGODB_URI のみで設定します。MONGODB_URI が未設定の場合、テストでは使い捨ての mongo:7 コンテナを起動します。設定されている場合は、そのサーバーに対して実行します。各テストファイルでは専用の og_test_<random> データベースを使用し、実行後にコレクションを削除します。

# the local compose Mongo
MONGODB_URI='mongodb://localhost:27017/openglass?directConnection=true' pnpm -r test

# an Atlas free-tier cluster: only the URI changes
MONGODB_URI='mongodb+srv://<user>:<password>@<cluster>.mongodb.net/openglass?retryWrites=true&w=majority' pnpm -r test

Atlas で実行する場合：

• データベースユーザーには readWriteAnyDatabase と dbAdminAnyDatabase が必要です。テストではファイルごとにデータベースを作成し、migrate で collMod を実行してバリデーターを設定します。
• お使いの IP アドレスをクラスターのアクセスリストに登録する必要があります。

本番アプリのユーザーに必要なのは、openglass データベースに対する readWrite と dbAdmin のみです。

スキーマの変更

• コレクションは packages/db/src/models で定義します。それぞれに Zod モデル、そのモデルから生成される $jsonSchema バリデーター、名前付きインデックスがあります。migrate は API の起動時にロックを取得し、すべてをべき等に適用します。
• データの変更は、バージョン管理されたスクリプトに記述します。pnpm --filter @openglass/db migration:create <name> を実行すると、packages/db/migrations にスクリプトが作成されます。

デプロイ

main は .github/workflows/deploy.yml によってビルドされ、ECR にプッシュされた後、単一の EC2 インスタンスにデプロイされます。AWS リソースと初回セットアップについては infra/README.md をご覧ください。