Browser Tool Calling Protocol (BTCP) JavaScript/TypeScript client for connecting browser extensions to AI agents.

This is a proof-of-concept implementation of the BTCP Specification, enabling AI agents to discover and invoke tools directly within browsers through client-defined interfaces.

• HTTP Streaming (SSE + POST) - More bandwidth efficient than WebSocket
• JSON-RPC 2.0 protocol for message exchange
• Tool registration and discovery
• Tool execution with customizable handlers
• Integration with btcp-browser-agent for browser automation
• Auto-reconnection support
• Works in both Node.js and browser environments

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    AI Agent     │────▶│   BTCP Server   │◀────│  Browser Client │
│  (Tool Caller)  │     │ (Message Broker)│     │  (Tool Provider)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │  POST /message        │  SSE /events          │  POST /message
        │  SSE  /events         │                       │  SSE  /events
        └───────────────────────┴───────────────────────┘

Communication:
  • Server → Client: SSE (Server-Sent Events) - efficient streaming
  • Client → Server: HTTP POST - only when needed

npm install btcp-client

npm run build
npm run server

import { BTCPClient } from 'btcp-client';

const client = new BTCPClient({
  serverUrl: 'http://localhost:8765',
  debug: true,
});

// Register a custom tool handler
client.getExecutor().registerHandler('greet', async (args) => {
  return `Hello, ${args.name}!`;
});

// Connect and register tools
await client.connect();
await client.registerTools([
  {
    name: 'greet',
    description: 'Greet a person by name',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      }
    }
  }
]);

console.log(`Session ID: ${client.getSessionId()}`);

// Agent connects to the same server
const agent = new BTCPAgent(sessionId);
await agent.connect();
await agent.joinSession();

// Call tools on the browser
const result = await agent.callTool('greet', { name: 'World' });
// Result: "Hello, World!"

The main client class for browser-side tool providers.

const client = new BTCPClient({
  serverUrl: 'http://localhost:8765', // Server URL (HTTP, not WS)
  sessionId: 'my-session',            // Optional session ID
  debug: true,                         // Enable debug logging
  autoReconnect: true,                // Auto-reconnect on disconnect
  reconnectDelay: 1000,               // Reconnection delay (ms)
  maxReconnectAttempts: 5,            // Max reconnection attempts
  connectionTimeout: 10000,           // Connection timeout (ms)
});

• connect(): Promise<void> - Connect to the BTCP server via SSE
• disconnect(): void - Disconnect from the server
• isConnected(): boolean - Check connection status
• getSessionId(): string - Get the session ID
• registerTools(tools: BTCPToolDefinition[]): Promise<void> - Register tools
• getExecutor(): ToolExecutor - Get the tool executor
• on(event, handler) - Add event listener
• off(event, handler) - Remove event listener

• connect - Connected to server
• disconnect(code, reason) - Disconnected from server
• error(error) - Error occurred
• toolCall(request) - Tool call received
• toolsList(request) - Tools list requested

Handles tool execution with optional browser agent integration.

const executor = client.getExecutor();

// Register a custom handler
executor.registerHandler('myTool', async (args) => {
  return { result: args.value * 2 };
});

// Set browser agent for DOM automation
executor.setBrowserAgent(browserAgent);

import {
  createRequest,
  createResponse,
  createTextContent,
  createImageContent,
  parseMessage,
  serializeMessage,
} from 'btcp-client';

// Create a text response
const content = createTextContent('Hello, World!');

// Create an image response
const image = createImageContent(base64Data, 'image/png');

When a browser agent is configured, the following tools are automatically available:

# Build the project
npm install
npm run build

# Terminal 1: Start the server
npm run server

# Terminal 2: Start the browser client
npm run example

# Terminal 3: Run the agent (pass the session ID from terminal 2)
npm run agent -- <session-id>

• sessionId - Session identifier (required)
• clientType - browser or agent
• version - Protocol version

• Content-Type: application/json
• X-Session-ID: <session-id>

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/register",
  "params": {
    "tools": [
      {
        "name": "greet",
        "description": "Greet a person",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" }
          }
        }
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": { "name": "World" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "content": [
      { "type": "text", "text": "Hello, World!" }
    ],
    "isError": false
  }
}

For use in a Chrome extension:

// In your extension's content script or background script
import { BTCPClient } from 'btcp-client';
import { BrowserAgent } from 'btcp-browser-agent';

const agent = new BrowserAgent();
await agent.launch();

const client = new BTCPClient({
  serverUrl: 'http://localhost:8765',
  debug: true
});
client.getExecutor().setBrowserAgent(agent);

await client.connect();
await client.registerTools(client.getExecutor().getToolDefinitions());

1. Lower bandwidth - SSE is unidirectional, no frame overhead
2. Better proxy/CDN support - HTTP works everywhere
3. Simpler protocol - Standard HTTP semantics
4. Auto-reconnect built-in - EventSource handles reconnection
5. No handshake overhead - Direct HTTP connection

MIT