agentbridge-protocol: Instructions file for Claude Code

CLAUDE.md

Working notes for Claude Code (and other AI agents) operating on this repository. Keep this file under 200 lines so the entire thing fits in any session's startup context.

What this project is

AgentBridge is an AI-native action layer for web apps. Web apps publish a machine-readable manifest at /.well-known/agentbridge.json describing their structured actions (with input schemas, risk levels, confirmation rules). AI agents discover and invoke those actions through an MCP server that enforces safety guarantees.

Architecture

agentbridge/
├── packages/
│   ├── core/       Zod schemas, types, manifest validation, audit log
│   ├── sdk/        defineAgentAction, manifest builder, route handler wrapper
│   ├── scanner/    0–100 readiness scoring, structured checks, Playwright probe
│   ├── openapi/    OpenAPI 3.x → AgentBridge manifest converter
│   └── cli/        @marmarlabs/agentbridge-cli — scan, validate, init, generate, mcp-config
├── apps/
│   ├── demo-app/   Next.js fake order app (port 3000) — manifest + actions
│   ├── studio/     Next.js dashboard (port 3001) — scan, exercise, audit
│   └── mcp-server/ stdio MCP server — tools, resources, prompts, confirmation tokens
├── spec/           JSON Schema + markdown manifest spec + example manifests
├── examples/       Integration examples (nextjs-basic, openapi-store, mcp-client-config)
├── docs/           Quickstart, MCP setup, OpenAPI import, roadmap
└── data/           Local audit/confirmation/idempotency JSON (gitignored)

Package responsibilities

Publishable packages are scoped @marmarlabs/agentbridge-*; apps keep an unscoped name and stay private. The @agentbridge scope is unowned on npm and is intentionally not used.