AGENTS.md

FOR AI AGENTS

Welcome! This document helps you navigate the WebMCP Examples repository efficiently.

Start here: CONTRIBUTING.md - Development standards and best practices

Quick Navigation

Project Overview

• README.md - What these examples demonstrate, quick start guide
• CONTRIBUTING.md - How to contribute new examples or improve existing ones

Current Examples (Modern WebMCP API)

Vanilla JavaScript/TypeScript

• vanilla/README.md - Shopping cart example using @mcp-b/global
• Location: /vanilla
• Key file: vanilla/src/main.ts - Entry point with WebMCP tool registration
• API used: navigator.modelContext.registerTool()

React + TypeScript

• react/README.md - Task manager using @mcp-b/react-webmcp
• Location: /react
• Key file: react/src/App.tsx - React component with useWebMCP hooks
• API used: useWebMCP() hook

Rails + Stimulus

• rails/README.md - Bookmarks manager using Stimulus controllers
• Location: /rails
• Key file: rails/app/javascript/controllers/bookmarks_webmcp_controller.ts - Stimulus controller with WebMCP tools
• API used: navigator.modelContext.registerTool() in Stimulus

Angular + TypeScript

• angular/README.md - Note manager using @mcp-b/global with Angular services
• Location: /angular
• Key file: angular/src/app/services/webmcp.service.ts - Angular service with tool registration
• API used: navigator.modelContext.registerTool() via service

Phoenix LiveView (Elixir)

• phoenix-liveview/README.md - Counter + items with server-side state
• Location: /phoenix-liveview
• Key files:
  • lib/webmcp_demo_web/live/counter_live.ex - LiveView with state management
  • assets/js/app.js - WebMCP hook registration
• API used: navigator.modelContext.registerTool() via LiveView hooks

Legacy Examples (Deprecated - DO NOT USE)

• relegated/README.md - Old examples using deprecated MCP SDK
• Warning: These use the legacy @modelcontextprotocol/sdk API
• Status: Kept for reference only, not recommended for new projects

Documentation

• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community standards
• CHANGELOG.md - Version history and changes

Common Development Tasks

Running an Example

# Navigate to the example
cd vanilla  # or react, rails, angular
cd vanilla  # or react, rails, phoenix-liveview

# Install dependencies
pnpm install  # For JS examples
# OR
mix setup     # For Phoenix example

# Start development server
pnpm dev      # For JS examples
# OR
mix phx.server  # For Phoenix example

Adding a New Example

1. Check existing examples first to avoid duplication
2. Choose the right location:
   • /vanilla for pure TypeScript/JavaScript
   • /react for React-based examples
   • /rails for Rails with Stimulus examples
   • /angular for Angular-based examples
3. Create self-contained directory with:
   • README.md - Documentation
   • package.json - Dependencies
   • src/ - Source code
   • vite.config.ts - Build config
4. Use modern WebMCP API:
   • Vanilla: @mcp-b/global package
   • React: @mcp-b/react-webmcp package
5. Follow patterns in existing examples
6. Document thoroughly - explain what WebMCP concepts are demonstrated

See CONTRIBUTING.md for detailed guidelines.

Code Quality

# Type-check
pnpm typecheck

# Lint
pnpm lint

# Build
pnpm build

Key Patterns

Modern WebMCP Tool Registration

Vanilla TypeScript:

import '@mcp-b/global';

navigator.modelContext.registerTool({
  name: 'my_tool',
  description: 'What this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: 'Description' }
    }
  },
  async execute(args) {
    return {
      content: [{ type: 'text', text: 'Result' }]
    };
  }
});

React with Hooks:

import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

useWebMCP({
  name: 'my_tool',
  description: 'What this tool does',
  inputSchema: {
    param: z.string().describe('Description')
  },
  handler: async ({ param }) => {
    return { success: true };
  }
});

File Locations

Example Structure

Each example follows this structure:

example-name/
├── README.md          # What it demonstrates, how to run
├── package.json       # Dependencies (@mcp-b/* packages)
├── vite.config.ts     # Vite configuration
├── tsconfig.json      # TypeScript config
├── index.html         # HTML entry point
└── src/
    ├── main.ts(x)     # Application entry point
    └── ...            # Additional source files

Key Files by Example

Vanilla Example:

• Entry: vanilla/src/main.ts
• Config: vanilla/vite.config.ts
• Types: vanilla/src/types.ts

React Example:

• Entry: react/src/main.tsx
• Root: react/src/App.tsx
• Config: react/vite.config.ts

Rails Example:

• Entry: rails/app/javascript/application.ts
• Controller: rails/app/javascript/controllers/bookmarks_webmcp_controller.ts
• Config: rails/vite.config.ts

Angular Example:

• Entry: angular/src/main.ts
• Root: angular/src/app/app.component.ts
• WebMCP: angular/src/app/services/webmcp.service.ts
• Config: angular/angular.json Phoenix LiveView Example:
• Entry: phoenix-liveview/lib/webmcp_demo/application.ex
• LiveView: phoenix-liveview/lib/webmcp_demo_web/live/counter_live.ex
• WebMCP Hook: phoenix-liveview/assets/js/app.js
• Config: phoenix-liveview/config/config.exs

WebMCP Package Documentation

• @mcp-b/global - Core WebMCP polyfill for vanilla JS
• @mcp-b/react-webmcp - React hooks for WebMCP
• @mcp-b/transports - Transport layer (used internally)
• @mcp-b/core - Core functionality (used internally)

External Resources

WebMCP Documentation

• WebMCP Introduction - What is WebMCP
• Quick Start - Get started in 2 minutes
• Concepts - Core concepts explained
• Examples - Additional examples

MCP Resources

• Model Context Protocol - MCP overview
• MCP Specification - Protocol spec
• MCP UI Resources - UI resource types

Tools

• MCP-B Chrome Extension - Required for testing

Prerequisites

• Node.js: 18 or higher (see .nvmrc)
• pnpm: Package manager (for JS examples)
• Elixir: 1.14+ (for Phoenix example)
• MCP-B Extension: Chrome extension for testing WebMCP tools
• Browser: Chrome or Chromium-based browser

Workflow for AI Agents

When working on this repository:

1. Understand the context:

   • Read README.md for project overview
   • Check CONTRIBUTING.md for standards
   • Review existing examples for patterns

2. Make changes:

   • Follow TypeScript strict mode
   • Use modern WebMCP API (never deprecated SDK)
   • Document all public APIs with JSDoc
   • Keep code self-documenting

3. Quality checks:

   • Run pnpm typecheck - must pass
   • Run pnpm lint - must pass
   • Run pnpm build - must succeed
   • Test manually with MCP-B extension

4. Documentation:

   • Update README if changing functionality
   • Add comments explaining WebMCP concepts
   • Include examples in JSDoc

Important Notes

• Never use deprecated APIs from /relegated - these are for reference only
• Always use the latest packages: @mcp-b/global and @mcp-b/react-webmcp
• Follow the single source of truth principle - don't duplicate information
• Keep examples simple - focus on demonstrating one concept clearly
• Test with the extension - every example must work with MCP-B Chrome Extension

Questions?

• Check docs.mcp-b.ai for WebMCP documentation
• Review existing examples for patterns
• Read CONTRIBUTING.md for detailed guidelines
• Open a GitHub issue if you need help

---

Remember: This file is a navigation hub. Detailed information lives in linked documentation to maintain a single source of truth.