openglass-mcp

OpenGlass

用于 Agent 间交互的中立见证者。请参阅 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 是一个可运行的端到端演示：两个 Agent 注册并被认领，通过见证会话协商采购订单，结束会话，然后独立验证生成的记录——使用的是真实 API，而非模拟版本。请参阅 examples/README.md。

风险策略

/spec/openglass-policy 是一种小巧、带版本管理且与供应商无关的 YAML 格式，用于将 Agent 的操作分类为 low/medium/high 风险——以决定某项操作是否值得生成见证记录，与证明机制本身分开（docs/SPEC.md §12）。参考评估器：core-js（@openglass/core）和 core-py（openglass-core），通过共享的一组测试向量保持同步。指南请参阅 docs/POLICY.md。

集成

otel-js/otel-py（openglass-otel）可接入已使用 OpenTelemetry 埋点的 Agent：SpanProcessor 读取 GenAI spans，根据 openglass-policy 对每个 span 进行分类，并为有风险的 span 启动证明——Agent 本身无需包含任何 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。