codex-control-chrome-mcp 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [Unreleased]
+
+## [1.0.1] - 2026-06-26
+
+### Added
+
+- Open source governance files.
+- CI and npm trusted publishing workflows.
+- Node.js test coverage for framing, RPC, and installer behavior.
+
+### Changed
+
+- Runtime package name and version are now read from `package.json` instead of being hard-coded in implementation files.
+
+## [1.0.0] - 2026-06-26
+
+### Added
+
+- Initial npm package.
+- MCP stdio server.
+- Chrome Native Messaging host bridge.
+- Native host install and uninstall commands with manifest backup.
+- Basic Chrome tab, navigation, screenshot, CDP, and event MCP tools.
+- Skill documentation for Agent tool usage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iola1999
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,55 +1,159 @@
 # Codex Control Chrome MCP
 
-Expose the Codex Chrome extension flow to other Agent tools through MCP.
+[![npm version](https://img.shields.io/npm/v/codex-control-chrome-mcp.svg)](https://www.npmjs.com/package/codex-control-chrome-mcp)
+[![CI](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Expose the Codex Chrome Extension flow to other Agent tools through MCP.
+
+This project lets MCP clients control the user's normal Chrome profile through the installed [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg). It is useful when an Agent needs existing tabs, cookies, logged-in sessions, installed extensions, screenshots, console/network events, or raw Chrome DevTools Protocol commands.
+
+This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.
 
 - NPM: [codex-control-chrome-mcp](https://www.npmjs.com/package/codex-control-chrome-mcp)
 - GitHub: [iola1999/codex-control-chrome-mcp](https://github.com/iola1999/codex-control-chrome-mcp)
 - Chrome Extension: [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)
 - Skill: [`skills/codex-control-chrome-mcp/SKILL.md`](./skills/codex-control-chrome-mcp/SKILL.md)
 
-Current implementation is an early Node.js prototype with:
+## Status
+
+The current implementation provides:
 
 - official `@modelcontextprotocol/sdk` stdio server
 - Chrome Native Messaging host mode
-- MCP stdio server mode
 - install/uninstall commands with manifest backup
 - JSON-RPC bridge socket under `/tmp/codex-browser-use`
-- basic Chrome tab/CDP MCP tools
+- Chrome tab, navigation, screenshot, CDP, and event MCP tools
+- bundled skill documentation for Agent tool ordering
 
-Install the Chrome native host:
+## Platform Support
 
-```bash
-npx -y codex-control-chrome-mcp@latest install-native-host
-```
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Tested | Primary supported platform. |
+| Linux | Experimental | Manifest path targets Google Chrome under `~/.config/google-chrome`. |
+| Windows | Unsupported | Native Messaging registration uses registry keys on Windows and is not implemented yet. |
 
-The user must also have the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) installed and enabled in the Chrome profile they want to automate.
+Node.js 20 or newer is required. npm Trusted Publishing for releases uses Node.js 24 in GitHub Actions.
 
-Uninstall and restore the previous Codex native host manifest:
+## Quick Start
+
+Install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome profile you want to automate.
+
+Install the Chrome native host:
 
 ```bash
-npx -y codex-control-chrome-mcp@latest uninstall-native-host
+npx -y codex-control-chrome-mcp@latest install-native-host
 ```
 
-Intended Agent config:
+Configure your Agent to use the MCP stdio server:
 
 ```json
 {
   "type": "stdio",
   "command": "npx",
-  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"]
+  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"],
+  "startup_timeout_sec": 30
 }
 ```
 
+Check status:
+
+```bash
+npx -y codex-control-chrome-mcp@latest status
+```
+
+Uninstall and restore the previous Codex native host manifest:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+## Agent Skill
+
 If your Agent supports skills, install or reference the bundled skill folder:
 
 ```text
 skills/codex-control-chrome-mcp
 ```
 
-The skill documents the recommended MCP tool order for status checks, tab claiming, CDP commands, screenshots, events, and tab finalization.
+The skill documents the recommended MCP tool order for:
+
+- status checks
+- tab listing and claiming
+- CDP attach and command execution
+- screenshots
+- network and console event reads
+- tab finalization
+
+## Security Notes
+
+This project controls the user's normal Chrome profile. MCP clients connected to it can inspect page contents and send raw CDP commands to claimed tabs.
 
-Read:
+Only install and run it on machines and Chrome profiles you own or are explicitly authorized to automate. Do not send browser cookies, password stores, profile databases, tokens, or private session files in issues or logs.
+
+See [SECURITY.md](./SECURITY.md) for the security model and reporting process.
+
+## How It Works
+
+The Codex Chrome Extension does not need an external Chrome remote debugging port. It uses Chrome Native Messaging and the extension's `chrome.debugger` permission:
+
+```text
+Chrome extension
+  -> chrome.runtime.connectNative("com.openai.codexextension")
+  -> codex-control-chrome-mcp native host
+  -> local MCP bridge socket
+  -> chrome.debugger.attach / chrome.debugger.sendCommand
+  -> CDP
+```
+
+Because the control entrypoint is inside the normal Chrome profile, existing cookies, logged-in sessions, tabs, and extensions can be reused.
+
+Read more:
 
 - [Architecture](./docs/architecture.md)
 - [Install And Uninstall](./docs/install.md)
 - [Official Socket Probe Notes](./docs/socket-probe.md)
+- [Release Process](./docs/release.md)
+
+## Development
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Run checks:
+
+```bash
+npm run ci
+```
+
+Run the MCP server locally:
+
+```bash
+node ./bin/codex-control-chrome-mcp.js --stdio
+```
+
+Run native host mode locally for development:
+
+```bash
+node ./bin/codex-control-chrome-mcp.js --native-host
+```
+
+## Troubleshooting
+
+If `status` shows no bridge sockets, reload Chrome or the Codex Chrome Extension after installing the native host.
+
+If Codex App integration stops working, uninstall this native host to restore the backed-up manifest:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+If tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest published npm version.
+
+## Reporting a Vulnerability
+
+Please report security issues privately by emailing `iola1999@foxmail.com`.
+
+Include:
+
+- affected version
+- operating system
+- Chrome version and profile type
+- MCP client name and version
+- reproduction steps
+- relevant `codex-control-chrome-mcp status` output with sensitive paths or data redacted
+
+Do not include browser cookies, password-store data, session databases, or other private Chrome profile files in reports.
+
+## Security Model
+
+This project controls the user's normal Chrome profile through the Codex Chrome Extension and Chrome DevTools Protocol. That can expose sensitive browser state, including logged-in sessions and page contents.
+
+The trusted boundary is the local user account. Only install and run this tool on machines and Chrome profiles you own or are explicitly authorized to automate.
+
+This project is not affiliated with OpenAI, Codex, Google, or Chrome. It reuses the installed Codex Chrome Extension native messaging host name so the extension can connect to this local bridge.
+
+## Known Security Tradeoffs
+
+- The native host manifest for `com.openai.codexextension` is replaced during install and restored during uninstall.
+- The local bridge socket is intended for same-user local access only.
+- MCP clients connected to this server can send raw CDP commands to claimed tabs.
+- The project does not attempt to enforce per-site or per-command policy.
+
+For operational details, see `docs/architecture.md` and `docs/install.md`.

package/docs/install.md

@@ -17,6 +17,16 @@ The current implementation provides:
 
 Do not run install on a machine where Codex Chrome integration is important unless you are ready to test proxy mode or restore from backup.
 
+This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.
+
+## Platform Support
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Tested | Primary supported platform. |
+| Linux | Experimental | Uses the Google Chrome user-level Native Messaging host directory. |
+| Windows | Unsupported | Chrome Native Messaging registration uses registry keys on Windows and is not implemented yet. |
+
 ## Install
 
 First install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome profile you want to automate.
@@ -43,6 +53,7 @@ The installer:
 2. Backs it up in the same directory with a timestamped suffix.
 3. Writes a new manifest pointing to this project's CLI.
 4. Records restore metadata in `~/.codex-control-chrome-mcp/install-state.json`.
+5. Records the previous host path for proxy mode when available.
 
 Example manifest path on macOS:
 
@@ -50,6 +61,12 @@ Example manifest path on macOS:
 ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.openai.codexextension.json
 ```
 
+Example manifest path on Linux:
+
+```text
+~/.config/google-chrome/NativeMessagingHosts/com.openai.codexextension.json
+```
+
 ## MCP Client Config
 
 Use stdio mode from other Agent tools:
@@ -117,3 +134,24 @@ If the extension is missing, install the [Codex Chrome Extension](https://chrome
 Stopping the MCP stdio process does not uninstall the native host. Uninstall explicitly to restore the original manifest.
 
 The MCP stdio server uses the official `@modelcontextprotocol/sdk` package and must not write logs to stdout. Use stderr for diagnostics.
+
+## Troubleshooting
+
+If `status` shows no sockets:
+
+1. Confirm Chrome is running with the profile where the extension is installed.
+2. Reload or disable/enable the Codex Chrome Extension.
+3. Run `npx -y codex-control-chrome-mcp@latest status`.
+4. Check that the active manifest path points to `~/.codex-control-chrome-mcp/native-host-launcher`.
+
+If Codex App integration is affected, uninstall this project:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+If the recorded backup is stale or manually changed, inspect the manifest and use `--force` only when you intentionally want to restore/remove the current project manifest.
+
+## Publishing
+
+This package is published from GitHub Actions through npm Trusted Publishing. See [Release Process](./release.md).

package/docs/release.md

@@ -0,0 +1,54 @@
+# Release Process
+
+Releases are published from GitHub Actions through npm Trusted Publishing.
+
+## Trusted Publishing Setup
+
+Configure the npm package settings:
+
+- Package: `codex-control-chrome-mcp`
+- Publisher: GitHub Actions
+- Organization or user: `iola1999`
+- Repository: `codex-control-chrome-mcp`
+- Workflow filename: `publish.yml`
+- Environment name: leave blank unless you add a GitHub deployment environment
+- Allowed action: `npm publish`
+
+Trusted Publishing requires a GitHub-hosted runner, OIDC permission, npm CLI 11.5.1 or newer, and Node.js 22.14.0 or newer. The publish workflow uses Node.js 24 and installs the latest npm before publishing.
+
+## Publish A New Version
+
+1. Update `package.json` version.
+2. Update `CHANGELOG.md`.
+3. Run checks locally:
+
+```bash
+npm run ci
+```
+
+4. Commit and push to `main`.
+5. Create and push a matching tag:
+
+```bash
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+The tag must match the package version exactly. For example, `package.json` version `1.0.1` must use tag `v1.0.1`.
+
+## What The Workflow Does
+
+The `publish.yml` workflow:
+
+1. Installs dependencies with `npm ci`.
+2. Verifies the tag matches `package.json`.
+3. Runs `npm run ci`.
+4. Publishes with `npm publish`.
+
+No long-lived `NPM_TOKEN` is required.
+
+## GitHub Release
+
+After the npm publish workflow succeeds, create a GitHub Release from the same tag and copy the relevant section from `CHANGELOG.md` into the release notes.
+
+Do not create a new GitHub Release for a tag if the npm publish failed.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "codex-control-chrome-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "codex-control-chrome-mcp": "bin/codex-control-chrome-mcp.js"
@@ -32,13 +33,18 @@
     "src",
     "docs",
     "skills",
-    "README.md"
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "start": "node ./bin/codex-control-chrome-mcp.js --stdio",
     "native-host": "node ./bin/codex-control-chrome-mcp.js --native-host",
     "status": "node ./bin/codex-control-chrome-mcp.js status",
-    "check": "node --check ./bin/codex-control-chrome-mcp.js && node --check ./src/*.js"
+    "check": "node --check ./bin/codex-control-chrome-mcp.js && node --check ./src/*.js && node --check ./test/*.test.js",
+    "test": "node --test",
+    "ci": "npm run check && npm test && npm pack --dry-run"
   },
   "engines": {
     "node": ">=20"

package/src/installer.js

@@ -8,19 +8,20 @@ import {
   INSTALL_STATE_PATH,
   nativeHostManifestPath,
 } from "./constants.js";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 
-const PACKAGE_NAME = "codex-control-chrome-mcp";
-const PACKAGE_VERSION = "1.0.0";
 const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
 
-export async function installNativeHost({ binPath, proxy = true } = {}) {
-  const manifestPath = nativeHostManifestPath();
+export async function installNativeHost({ binPath, proxy = true, paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, appStateDir, configPath, installStatePath } = paths;
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
-  await fs.mkdir(APP_STATE_DIR, { recursive: true });
+  await fs.mkdir(appStateDir, { recursive: true });
 
-  const hostPath = binPath ? await createLocalLauncher(path.resolve(binPath)) : await createNpxLauncher();
+  const hostPath = binPath
+    ? await createLocalLauncher(path.resolve(binPath), appStateDir)
+    : await createNpxLauncher(appStateDir);
   const existing = await readJsonIfExists(manifestPath);
-  const previousState = await readJsonIfExists(INSTALL_STATE_PATH);
+  const previousState = await readJsonIfExists(installStatePath);
   const previousBackup = previousState?.backupPath
     ? await readJsonIfExists(previousState.backupPath)
     : null;
@@ -69,14 +70,14 @@ export async function installNativeHost({ binPath, proxy = true } = {}) {
     officialHostPath,
     proxy,
   };
-  await fs.writeFile(APP_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-  await fs.writeFile(INSTALL_STATE_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.writeFile(installStatePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
   return config;
 }
 
-export async function uninstallNativeHost({ force = false } = {}) {
-  const manifestPath = nativeHostManifestPath();
-  const state = await readJsonIfExists(INSTALL_STATE_PATH);
+export async function uninstallNativeHost({ force = false, paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, installStatePath } = paths;
+  const state = await readJsonIfExists(installStatePath);
   const manifest = await readJsonIfExists(manifestPath);
 
   if (!manifest && !state?.backupPath) {
@@ -99,12 +100,21 @@ export async function uninstallNativeHost({ force = false } = {}) {
 }
 
 export async function nativeHostInstallStatus() {
-  const manifestPath = nativeHostManifestPath();
+  const { manifestPath, installStatePath } = defaultInstallPaths();
   const manifest = await readJsonIfExists(manifestPath);
-  const state = await readJsonIfExists(INSTALL_STATE_PATH);
+  const state = await readJsonIfExists(installStatePath);
   return { manifestPath, manifest, state };
 }
 
+function defaultInstallPaths() {
+  return {
+    manifestPath: nativeHostManifestPath(),
+    appStateDir: APP_STATE_DIR,
+    configPath: APP_CONFIG_PATH,
+    installStatePath: INSTALL_STATE_PATH,
+  };
+}
+
 async function backupManifest(manifestPath) {
   const stamp = new Date().toISOString().replace(/[:.]/g, "-");
   const backupPath = path.join(
@@ -115,11 +125,11 @@ async function backupManifest(manifestPath) {
   return backupPath;
 }
 
-async function createNpxLauncher() {
+async function createNpxLauncher(appStateDir) {
   if (process.platform === "win32") {
     throw new Error("NPX native host launcher installation is not implemented for Windows yet.");
   }
-  const launcherPath = path.join(APP_STATE_DIR, "native-host-launcher");
+  const launcherPath = path.join(appStateDir, "native-host-launcher");
   const script = `#!/usr/bin/env sh
 exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host "$@"
 `;
@@ -132,14 +142,14 @@ function isProjectManifest(manifest) {
   return manifest?.description === MANIFEST_DESCRIPTION;
 }
 
-async function createLocalLauncher(binPath) {
+async function createLocalLauncher(binPath, appStateDir) {
   if (process.platform === "win32") {
     return binPath;
   }
   if (!binPath.endsWith(".js")) {
     return binPath;
   }
-  const launcherPath = path.join(APP_STATE_DIR, "native-host-local-launcher");
+  const launcherPath = path.join(appStateDir, "native-host-local-launcher");
   const script = `#!/usr/bin/env sh
 exec ${shellQuote(process.execPath)} ${shellQuote(binPath)} "$@"
 `;

package/src/mcp-server.js

@@ -4,12 +4,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { connectBridge, listBridgeSockets } from "./bridge-client.js";
 import { nativeHostManifestPath } from "./constants.js";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 
 export async function runMcpServer() {
   const runtime = new ChromeUseRuntime();
   const server = new McpServer({
-    name: "codex-control-chrome-mcp",
-    version: "1.0.0",
+    name: PACKAGE_NAME,
+    version: PACKAGE_VERSION,
   });
 
   registerTools(server, runtime);

package/src/package-meta.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+export const PACKAGE_NAME = packageJson.name;
+export const PACKAGE_VERSION = packageJson.version;