> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @mcp-b/extension-tools

> MCP wrappers for 62+ Chrome Extension APIs enabling protocol-based browser control. Manifest V3 compatible with comprehensive TypeScript definitions and Zod validation.

<Note>
  This is a **Developer Resource** for building Chrome extensions with WebMCP. If you're looking to use the MCP-B Extension, see the [Extension Overview](/extension/index).
</Note>

## Overview

The `@mcp-b/extension-tools` package provides Model Context Protocol (MCP) wrappers for Chrome Extension APIs. It enables standardized, protocol-based access to browser extension functionalities, allowing MCP clients to interact with Chrome's extensive API surface.

## Prerequisites

* **Chrome Extension** with Manifest V3
* **@mcp-b/transports** package installed
* **@modelcontextprotocol/sdk** installed
* **Required Chrome permissions** in manifest.json
* **TypeScript 5.0+** (recommended)
* Understanding of Chrome Extension APIs and MCP protocol

## Installation

```bash theme={null}
npm install @mcp-b/extension-tools
```

## Key Features

* MCP wrappers for 62+ Chrome Extension APIs
* Full TypeScript support with comprehensive type definitions
* Zod-based input validation and schema generation
* Structured error handling and response formatting
* Compatible with Manifest V3 extensions

## Architecture

The package wraps Chrome Extension APIs into MCP-compatible tools, enabling remote procedure calls through the MCP protocol. Each Chrome API is wrapped in its own tools class that extends `BaseApiTools`.

## Basic Usage

### Setting Up in Background Script

```typescript theme={null}
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { TabServerTransport } from '@mcp-b/transports';
import { 
  TabsApiTools,
  StorageApiTools,
  BookmarksApiTools 
} from '@mcp-b/extension-tools';

// Create MCP server
const server = new McpServer({
  name: 'chrome-extension-server',
  version: '1.0.0'
});

// Register Chrome API tools
const tabsTools = new TabsApiTools(server, {
  createTab: true,
  updateTab: true,
  removeTabs: true,
  queryTabs: true
});
tabsTools.register();

const storageTools = new StorageApiTools(server, {
  getStorageData: true,
  setStorageData: true,
  removeStorageData: true
});
storageTools.register();

// Set up transport
const transport = new TabServerTransport({
  allowedOrigins: ['*']
});

// Connect server to transport
await server.connect(transport);
```

### Client-Side Usage

```typescript theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { TabClientTransport } from '@mcp-b/transports';

const transport = new TabClientTransport({
  targetOrigin: window.location.origin
});

const client = new Client({
  name: 'web-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Call Chrome API through MCP
const tabs = await client.callTool({
  name: 'query_tabs',
  arguments: {
    active: true,
    currentWindow: true
  }
});

const newTab = await client.callTool({
  name: 'create_tab',
  arguments: {
    url: 'https://example.com',
    active: true
  }
});
```

## Available API Wrappers

### Core Browser APIs

#### TabsApiTools

```typescript theme={null}
const tabsTools = new TabsApiTools(server, {
  createTab: true,        // chrome.tabs.create
  updateTab: true,        // chrome.tabs.update
  removeTabs: true,       // chrome.tabs.remove
  queryTabs: true,        // chrome.tabs.query
  getTab: true,           // chrome.tabs.get
  duplicateTab: true,     // chrome.tabs.duplicate
  highlightTabs: true,    // chrome.tabs.highlight
  moveTabs: true          // chrome.tabs.move
});
```

#### WindowsApiTools

```typescript theme={null}
const windowsTools = new WindowsApiTools(server, {
  createWindow: true,     // chrome.windows.create
  updateWindow: true,     // chrome.windows.update
  removeWindow: true,     // chrome.windows.remove
  getWindow: true,        // chrome.windows.get
  getAllWindows: true,    // chrome.windows.getAll
  getCurrentWindow: true  // chrome.windows.getCurrent
});
```

#### StorageApiTools

```typescript theme={null}
const storageTools = new StorageApiTools(server, {
  getStorageData: true,    // chrome.storage.local.get
  setStorageData: true,    // chrome.storage.local.set
  removeStorageData: true, // chrome.storage.local.remove
  clearStorage: true,      // chrome.storage.local.clear
  getBytesInUse: true      // chrome.storage.local.getBytesInUse
});
```

### Content & Scripting APIs

#### ScriptingApiTools

```typescript theme={null}
const scriptingTools = new ScriptingApiTools(server, {
  executeScript: true,     // chrome.scripting.executeScript
  insertCSS: true,         // chrome.scripting.insertCSS
  removeCSS: true,         // chrome.scripting.removeCSS
  registerContentScripts: true,
  unregisterContentScripts: true
});
```

### Data Management APIs

#### BookmarksApiTools

```typescript theme={null}
const bookmarksTools = new BookmarksApiTools(server, {
  createBookmark: true,    // chrome.bookmarks.create
  removeBookmark: true,    // chrome.bookmarks.remove
  updateBookmark: true,    // chrome.bookmarks.update
  searchBookmarks: true,   // chrome.bookmarks.search
  getBookmarkTree: true    // chrome.bookmarks.getTree
});
```

#### HistoryApiTools

```typescript theme={null}
const historyTools = new HistoryApiTools(server, {
  searchHistory: true,     // chrome.history.search
  addUrl: true,            // chrome.history.addUrl
  deleteUrl: true,         // chrome.history.deleteUrl
  deleteRange: true,       // chrome.history.deleteRange
  deleteAll: true          // chrome.history.deleteAll
});
```

#### DownloadsApiTools

```typescript theme={null}
const downloadsTools = new DownloadsApiTools(server, {
  download: true,          // chrome.downloads.download
  pauseDownload: true,     // chrome.downloads.pause
  resumeDownload: true,    // chrome.downloads.resume
  cancelDownload: true,    // chrome.downloads.cancel
  searchDownloads: true    // chrome.downloads.search
});
```

### System APIs

#### SystemApiTools

```typescript theme={null}
// CPU information
const cpuTools = new SystemCpuApiTools(server, {
  getCpuInfo: true         // chrome.system.cpu.getInfo
});

// Memory information
const memoryTools = new SystemMemoryApiTools(server, {
  getMemoryInfo: true      // chrome.system.memory.getInfo
});

// Display information
const displayTools = new SystemDisplayApiTools(server, {
  getDisplayInfo: true,    // chrome.system.display.getInfo
  getDisplayLayout: true   // chrome.system.display.getDisplayLayout
});
```

## Real-World Example: Extension Connector

Here's an example of connecting to an MCP extension:

```typescript theme={null}
// background.ts
import { ExtensionClientTransport } from '@mcp-b/transports';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const TARGET_EXTENSION_ID = 'your-mcp-extension-id';
const PORT_NAME = 'mcp';

async function connectToMcpExtension() {
  const transport = new ExtensionClientTransport({
    extensionId: TARGET_EXTENSION_ID,
    portName: PORT_NAME,
  });
  
  const client = new Client({
    name: 'extension-client',
    version: '1.0.0'
  }, {
    capabilities: {}
  });
  
  await client.connect(transport);
  
  // Now you can call tools exposed by the MCP extension
  const tools = await client.listTools();
  console.log('Available tools:', tools);
  
  // Call a specific tool
  const tabs = await client.callTool({
    name: 'query_tabs',
    arguments: { active: true }
  });
  
  return { client, tools, tabs };
}
```

## Tool Registration Options

Each API tools class accepts configuration options to control which tools are registered:

```typescript theme={null}
interface TabsApiToolsOptions {
  createTab?: boolean;
  updateTab?: boolean;
  removeTabs?: boolean;
  queryTabs?: boolean;
  getTab?: boolean;
  duplicateTab?: boolean;
  highlightTabs?: boolean;
  moveTabs?: boolean;
  reloadTab?: boolean;
  captureVisibleTab?: boolean;
  executeScript?: boolean;
  insertCSS?: boolean;
  removeCSS?: boolean;
  detectLanguage?: boolean;
  setZoom?: boolean;
  getZoom?: boolean;
  setZoomSettings?: boolean;
  getZoomSettings?: boolean;
}
```

## Input Validation

All tools use Zod schemas for input validation:

```typescript theme={null}
// Example: TabsApiTools validation schema
const createTabSchema = z.object({
  windowId: z.number().optional(),
  index: z.number().optional(),
  url: z.string().optional(),
  active: z.boolean().optional(),
  pinned: z.boolean().optional(),
  openerTabId: z.number().optional()
});

// The tool automatically validates inputs before execution
```

## Error Handling

The package provides structured error responses:

```typescript theme={null}
try {
  const result = await client.callTool({
    name: 'create_tab',
    arguments: { url: 'invalid-url' }
  });
} catch (error) {
  // Error includes structured information
  console.error({
    tool: error.tool,
    message: error.message,
    validationErrors: error.validationErrors
  });
}
```

## Security Considerations

### Manifest Permissions

Ensure your extension manifest includes required permissions:

```json theme={null}
{
  "manifest_version": 3,
  "permissions": [
    "tabs",
    "storage",
    "bookmarks",
    "history",
    "downloads"
  ],
  "host_permissions": [
    "<all_urls>"
  ],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}
```

### Tool Access Control

Control which tools are exposed:

```typescript theme={null}
// Only register specific tools based on permissions
chrome.permissions.contains({
  permissions: ['tabs']
}, (hasPermission) => {
  if (hasPermission) {
    const tabsTools = new TabsApiTools(server, {
      queryTabs: true,  // Read-only operations
      createTab: false, // Disable creation
      removeTabs: false // Disable deletion
    });
    tabsTools.register();
  }
});
```

## Complete API List

The package provides wrappers for 62+ Chrome APIs including:

* **Browser Control**: tabs, windows, browserAction, pageAction
* **Storage**: storage, cookies, sessions
* **Content**: bookmarks, history, downloads, topSites
* **Communication**: runtime, messaging, notifications
* **DevTools**: debugger, devtools
* **System**: system.cpu, system.memory, system.storage, system.display
* **Identity**: identity, oauth2
* **Enterprise**: enterprise.platformKeys, enterprise.deviceAttributes
* **Privacy**: privacy, contentSettings
* **Network**: proxy, vpnProvider, webRequest
* **Management**: management, permissions, commands

## TypeScript Support

Full TypeScript definitions are provided:

```typescript theme={null}
import type { 
  TabsApiToolsOptions,
  StorageApiToolsOptions,
  BookmarksApiToolsOptions 
} from '@mcp-b/extension-tools';

// Type-safe tool configuration
const options: TabsApiToolsOptions = {
  createTab: true,
  updateTab: true,
  removeTabs: false // Explicitly disable dangerous operations
};
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="@mcp-b/transports" icon="arrows-left-right" href="/packages/transports">
    Extension transport layer
  </Card>

  <Card title="Extension Guide" icon="puzzle-piece" href="/extension/index">
    MCP-B browser extension
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/concepts/overview">
    Extension architecture
  </Card>

  <Card title="Security Guide" icon="shield-halved" href="/security">
    Extension security best practices
  </Card>
</CardGroup>

**See also:**

* [Advanced Patterns](/advanced) - Extension development patterns
* [Troubleshooting](/troubleshooting) - Extension-specific issues
* [Glossary](/concepts/glossary) - Extension terminology

## External Resources

* [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - Core MCP SDK
* [Chrome Extension API Reference](https://developer.chrome.com/docs/extensions/reference/) - Official Chrome docs
* [MCP Protocol Specification](https://modelcontextprotocol.io) - Protocol details
* [GitHub Repository](https://github.com/WebMCP-org/npm-packages) - Source code