webmcp-react: Instructions file for Codex

AGENTS.md

This file is for AI agents contributing to the webmcp-react library. For integrating webmcp-react into your app, see the skills/ directory.

Reference

• WebMCP standard: https://github.com/webmachinelearning/webmcp — the W3C spec this library implements
• API reference: docs/api.md — this library's full API docs

Commands

Task	Command
Install	pnpm install
Build	pnpm build
Test	pnpm test
Test (watch)	pnpm test:watch
Test (single file)	pnpm test -- path/to/file.test.tsx
Type check	pnpm typecheck
Lint	pnpm lint
Lint + fix	pnpm lint:fix
Full check before PR	pnpm build && pnpm typecheck && pnpm lint && pnpm test

Project Structure

src/                    ← core library (your focus)
├── index.ts            ← public API exports
├── types.ts            ← all TypeScript types
├── context.tsx         ← WebMCPProvider + useWebMCPStatus hook
├── hooks/
│   └── useMcpTool.ts   ← main hook for tool registration
├── polyfill/           ← document.modelContext polyfill
│   ├── index.ts        ← installPolyfill / cleanupPolyfill + polyfill marker
│   ├── registry.ts     ← in-memory tool storage
│   ├── execute.ts      ← shared execution engine (signals, serialization, errors)
│   ├── testing-shim.ts ← DEPRECATED wrapper over execute.ts (removed in 2.0.0)
│   └── validation.ts   ← input validation against JSON Schema
└── utils/
    ├── schema.ts       ← Zod → JSON Schema conversion + schema fingerprinting
    └── warn.ts         ← dev-only fire-once warnings

Other directories (don't modify unless explicitly asked):

• extension/ — Chrome extension that bridges web tools to desktop MCP clients
• examples/playground/ — Wordle demo showcasing dynamic tool registration
• examples/nextjs/ — Next.js integration example
• skills/ — agent skills for consumers of the library
• docs/api.md — full API reference

Architecture Decisions — Don't "Fix" These