claude-chrome-mcp: Instructions file for Codex

AGENTS.md - Developer Guide

Developer guidance for AI agents working on this codebase.

Project Overview

MCP server that bridges the Claude Chrome Extension with MCP clients via Chrome native messaging protocol.

Project Rules

• Use Bun exclusively (no npm)
• No emoji in output or documentation
• No ASCII boxes in output
• PRs and development happen on main branch
• release branch is the default branch (for installation)

Essential Commands

bun run build                # Compile TypeScript to dist/
bun run dev                  # Watch mode
bun test                     # Run all tests
bun test/unit/<name>.test.js # Run specific test

bun install                  # Install dependencies
bun run build && bun link    # Local dev setup

claude-chrome-mcp --install  # Register native host (auto-generates token)
claude-chrome-mcp --status   # Check installation and view token
claude-chrome-mcp --uninstall # Remove installation

Code Style (Critical)

Imports:

• MUST use .js extension for imports even in .ts files:

  import { ChromeMcpServer } from './server.js';  // Correct
  import { ChromeMcpServer } from './server';     // Wrong
  

• ESM syntax only (no require)
• Named imports, no default exports

TypeScript:

• Strict mode enabled - explicit types required
• Use unknown instead of any
• Zod schemas for runtime validation

Naming:

• Classes/Interfaces: PascalCase
• Functions/Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Files: kebab-case

Formatting:

• 2-space indentation
• Single quotes for strings
• Semicolons required
• JSDoc comments for exported functions/classes

Architecture

graph LR
    A[MCP Client] -->|HTTP POST /mcp| B[MCP Server]
    B -->|Chrome Protocol| C[Chrome Extension]
    C -->|CDP| D[Browser]
    B -->|stdin/stdout| C

Key files:

• src/mcp-server.ts - HTTP server, registers tools, manages sessions
• src/chrome-protocol.ts - Chrome native messaging (length-prefixed JSON on stdin/stdout)
• src/tools.ts - 14 browser tools with Zod schemas
• src/instructions.ts - Server instructions (~600 words, delivered in MCP initialize)
• src/install.ts - Installation (creates wrapper + manifest, detects Bun/Node runtime)