# Codex MCP Persistent Bridge

Local Codex App Server + persistent bridge experiment.

## Purpose

This project explores a local integration path:

```text
AI client / MCP client
          │ MCP stdio
          ▼
core/codex_mcp_bridge.py
          │ WebSocket
          ▼
Codex App Server
          │
          ▼
Local project workspace
```

The MCP bridge exposes `ask_codex(prompt: str)`. It forwards requests to a local Codex App Server and returns the final text response.

The project also contains a long-running persistent service:

```text
tests/persistent_test.py
          │ TCP JSON Lines :4600
          ▼
core/persistent_bridge.py
          │ WebSocket :4500
          ▼
Codex App Server
```

The persistent service keeps one `CodexSession` alive between requests. The first request creates a thread; later requests reuse the WebSocket connection and `thread_id`.

## Repository layout

```text
codex-mcp-persistent-bridge/
├── core/
│   ├── codex_mcp_bridge.py
│   └── persistent_bridge.py
├── tests/
│   └── persistent_test.py
├── docs/
│   └── Codex_MCP_Bridge_Development_Log.md
├── README.md
├── requirements.txt
├── start_persistent_bridge.ps1
└── .gitignore
```

Runtime logs are written under `logs/` when the startup script uses redirected output. The directory and log files are excluded from Git.

## Installation

Open a terminal at the project root and create an environment if needed:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

The startup script currently uses the Python interpreter from the verified local setup. When moving the project to another machine, review that interpreter setting before starting the service.

## Startup

From the project root:

```powershell
.\start_persistent_bridge.ps1
```

The script:

1. Starts `codex app-server --listen ws://127.0.0.1:4500` when the App Server is not already listening.
2. Waits for TCP port `4500`.
3. Starts `core/persistent_bridge.py`.
4. Waits for TCP port `4600`.
5. Prints the process IDs and keeps both child processes alive.

Press `Ctrl+C` in the startup window to stop the child processes started by the script.

## Persistent session test

With the service running, open another terminal at the project root:

```powershell
python .\tests\persistent_test.py
```

The test sends three requests over one TCP connection. Expected diagnostic behavior is:

```text
CALL 0
current thread_id = None
created new thread_id = <id>

CALL 1
current thread_id = <id>

CALL 2
current thread_id = <id>
```

The exact ID is generated by Codex. The important result is that the ID remains the same for all three calls.

## MCP stdio entry point

`core/codex_mcp_bridge.py` remains the standard MCP entry point and exposes `ask_codex(prompt: str)`. A compatible MCP host should launch it with its configured Python interpreter and a project-root-relative configuration, for example:

```json
{
  "mcpServers": {
    "codex-mcp-bridge": {
      "command": "<python-interpreter>",
      "args": ["<project-root>/core/codex_mcp_bridge.py"],
      "env": {
        "CODEX_APP_SERVER_URL": "ws://127.0.0.1:4500",
        "CODEX_MCP_WORKDIR": "<project-root>"
      }
    }
  }
}
```

The stdio entry point and the long-running TCP service are separate launch modes. The persistent service exists to keep the Session alive after a short-lived client exits; it does not change the MCP tool interface or the WebSocket protocol.

## Known limitations

- The project is a local Codex App Server and MCP bridge experiment, not a hosted service.
- ChatGPT Desktop has not been verified to provide a direct local MCP connection for this project.
- ChatGPT Web cannot automatically access a local process just because the process listens on `127.0.0.1`.
- The persistent service currently uses a local TCP JSON Lines interface; it is not itself a replacement for the standard MCP stdio entry point.
- The current setup assumes the local Codex CLI, Python dependencies, permissions and App Server are available in the host environment.
- The bridge uses local execution settings that should be reviewed before any broader or write-enabled deployment.

## Development record

The engineering history, failed attempts and debugging conclusions are recorded in [docs/Codex_MCP_Bridge_Development_Log.md](docs/Codex_MCP_Bridge_Development_Log.md).