Skip to content

README.md

Latest commit

 

History

History
212 lines (165 loc) · 6.25 KB

README.md

File metadata and controls

212 lines (165 loc) · 6.25 KB

MCP Web Bridge Demo

Connect Claude Code to any web application using the Model Context Protocol (MCP)

This demo shows how to build a browser extension that enables Claude Code (or any MCP client) to interact with web applications directly. The example includes a simple e-commerce shop that Claude can control via natural language commands.

Example

🎯 What This Demonstrates

  • MCP Server: A Node.js server that implements the MCP protocol
  • Browser Extension: Bridges between the MCP server and web applications
  • Web App Integration: How to expose your app's functionality to MCP clients

🏗️ Architecture

┌─────────────────┐                 ┌───────────────────────────┐
│   Claude Code   │◄─── stdio ─────►│  MCP Server               │
│   (MCP Client)  │                 │  (WebSocket port 3456)    │
└─────────────────┘                 └───────────┬───────────────┘
                                                │ WebSocket
                                    ┌───────────▼───────────────┐
                                    │  Browser Extension        │
                                    │  (Chrome content script)  │
                                    └───────────┬───────────────┘
                                                │ window.postMessage
                                    ┌───────────▼───────────────┐
                                    │  Web Application          │
                                    │  window.__MCP_BRIDGE__    │
                                    └───────────────────────────┘

How It Works

  1. Claude Code communicates with the MCP server via stdio (standard input/output)
  2. MCP Server runs a WebSocket server on localhost:3456
  3. Browser Extension connects to this WebSocket and injects into web pages
  4. Web App exposes window.__MCP_BRIDGE__ with tools Claude can call

📁 Project Structure

mcp-web-bridge-demo/
├── web-app/              # Demo e-commerce shop
│   ├── index.html        # Main HTML
│   ├── styles.css        # Styling
│   ├── store.js          # State management
│   ├── app.js            # UI rendering
│   └── mcp-bridge.js     # MCP tool definitions
├── extension/            # Chrome browser extension
│   ├── manifest.json     # Extension manifest
│   ├── background.js     # Service worker
│   ├── content.js        # Content script (WebSocket connection)
│   ├── page-script.js    # Page script (bridge access)
│   └── icons/            # Extension icons
└── mcp-server/           # Node.js MCP server
    ├── package.json
    └── index.js          # MCP protocol handler

🚀 Quick Start

1. Start the Web App

cd web-app
# Serve with any static file server
npx serve -p 8080
# Or use Python
python3 -m http.server 8080

Open http://localhost:8080 in Chrome.

2. Install the Browser Extension

  1. Open chrome://extensions/ in Chrome
  2. Enable Developer mode (top right toggle)
  3. Click Load unpacked
  4. Select the extension/ folder

3. Install and Run the MCP Server

cd mcp-server
npm install

4. Configure Claude Code

Add to your ~/.claude.json (in the project's mcpServers section):

{
  "mcpServers": {
    "demo-shop": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-web-bridge-demo/mcp-server/index.js"]
    }
  }
}

Or use the CLI:

claude mcp add --transport stdio demo-shop -- node /path/to/mcp-server/index.js

5. Use It!

Restart Claude Code and try:

> List all products in the shop
> Add the wireless headphones to my cart
> What's in my cart?
> Search for electronics
> Checkout

🛠️ Available Tools

The demo shop exposes these MCP tools:

Tool Description
listProducts List products with optional search/category filter
getProduct Get details about a specific product
searchProducts Search and update the UI
addToCart Add a product to the cart
removeFromCart Remove a product from the cart
updateCartQuantity Change quantity of a cart item
getCart Get current cart contents
clearCart Empty the cart
checkout Complete the purchase

🔧 Adapting for Your App

1. Create Your MCP Bridge

In your web app, create a bridge object:

window.__MCP_BRIDGE__ = {
  isReady: true,
  handleRequest: async (request) => {
    // Handle MCP protocol requests
    // See web-app/mcp-bridge.js for full example
  },
  getTools: () => [
    // Your tool definitions
  ],
};

// Notify extension when ready
window.dispatchEvent(new CustomEvent('mcp-bridge-ready'));

2. Define Your Tools

const TOOLS = [
  {
    name: 'myTool',
    description: 'What this tool does',
    inputSchema: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: 'Description' },
      },
      required: ['param1'],
    },
  },
];

3. Update Extension Manifest

Add your domain to manifest.json:

{
  "host_permissions": ["https://your-app.com/*"],
  "content_scripts": [{
    "matches": ["https://your-app.com/*"],
    ...
  }]
}

🐛 Troubleshooting

Extension not connecting?

  • Check that the web app is open in Chrome
  • Look for [MCP Extension] logs in browser console (F12)
  • Verify the MCP server is running ([mcp-web-bridge] in terminal)

Tools not showing in Claude?

  • Check /mcp in Claude Code to see if the server is listed
  • Restart Claude Code after adding the MCP server config
  • Look for errors in the MCP server output

Requests timing out?

  • Make sure window.__MCP_BRIDGE__ exists in your web app
  • Check that isReady: true is set
  • Verify the bridge's handleRequest function works