# bkelson/-claude-chatgpt-bridge architecture

> Architecture diagram of the GitHub repository bkelson/-claude-chatgpt-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bkelson/-claude-chatgpt-bridge
- Repository: https://github.com/bkelson/-claude-chatgpt-bridge

## Overview

This repository implements a Claude–ChatGPT MCP bridge: model clients access tools for shared files, inbox messaging, conversation logging, and bridge status. Claude can connect through MCP over stdio; ChatGPT can use an OAuth-protected HTTP/SSE gateway that forwards requests to the MCP server. A separate file-watching orchestrator coordinates multi-round debates and synthesis. Storage paths are inferred from source references; the shared directory is not present in the supplied tree. The OAuth and runtime descriptions are based on sampled excerpts, so unsampled details are omitted.

Main entry points: [`src/index.ts`](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts) (MCP server), [`src/oauth-server.ts`](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts) (OAuth HTTP gateway), [`orchestrator.js`](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/orchestrator.js) (Debate orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bridge["MCP Bridge"]
  node_mcp["MCP server<br/>[index.ts]"]
  node_stdio["Stdio transport<br/>[index.ts]"]
  node_statustool["Status tool<br/>[index.ts]"]
end

subgraph group_sharing["Shared Data"]
  node_filetools["File tools<br/>[index.ts]"]
  node_inboxtools["Inbox tools<br/>[index.ts]"]
  node_logtools["Conversation tools<br/>[index.ts]"]
  node_files[("Shared files<br/>[index.ts]")]
  node_inboxes[("Model inboxes<br/>[index.ts]")]
  node_conversation[("Conversation log<br/>[index.ts]")]
end

subgraph group_access["Remote Access"]
  node_gateway["OAuth HTTP gateway<br/>[oauth-server.ts]"]
  node_tokencheck["Token validation<br/>[oauth-server.ts]"]
  node_metadata["OAuth metadata<br/>[oauth-server.ts]"]
  node_sse["SSE sessions<br/>[oauth-server.ts]"]
end

subgraph group_debate["Debate Automation"]
  node_debate["Debate orchestrator<br/>[orchestrator.js]"]
  node_debatefiles[("Debate files<br/>[orchestrator.js]")]
end

node_claude(("Claude client"))
node_chatgpt(("ChatGPT client"))
node_auth0{{"Auth0"}}

node_claude -->|"uses"| node_stdio
node_stdio -->|"connects"| node_mcp
node_chatgpt -->|"sends requests"| node_gateway
node_gateway -->|"checks tokens"| node_tokencheck
node_tokencheck -.->|"checks claims against"| node_auth0
node_gateway -->|"serves"| node_metadata
node_gateway -->|"opens sessions"| node_sse
node_gateway -->|"forwards MCP requests"| node_mcp
node_mcp -->|"registers"| node_filetools
node_mcp -->|"registers"| node_inboxtools
node_mcp -->|"registers"| node_logtools
node_mcp -->|"registers"| node_statustool
node_filetools -->|"reads and writes"| node_files
node_inboxtools -->|"reads and writes"| node_inboxes
node_logtools -->|"reads and writes"| node_conversation
node_statustool -->|"counts"| node_files
node_statustool -->|"counts unread"| node_inboxes
node_debate -->|"watches and writes"| node_debatefiles

click node_mcp "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_stdio "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_filetools "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_inboxtools "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_logtools "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_statustool "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_files "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_inboxes "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_conversation "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts"
click node_gateway "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts"
click node_tokencheck "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts"
click node_metadata "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts"
click node_sse "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts"
click node_debate "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/orchestrator.js"
click node_debatefiles "https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/orchestrator.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_stdio,node_statustool,node_claude,node_chatgpt toneBlue
class node_filetools,node_inboxtools,node_logtools,node_files,node_inboxes,node_conversation toneAmber
class node_gateway,node_tokencheck,node_metadata,node_sse toneMint
class node_debate,node_debatefiles toneRose
class node_auth0 toneIndigo
```

## Components

### MCP Bridge

- [MCP server](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Stdio transport](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Status tool](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`

### Shared Data

- [File tools](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Inbox tools](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Conversation tools](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Shared files](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Model inboxes](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`
- [Conversation log](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/index.ts): `src/index.ts`

### Remote Access

- [OAuth HTTP gateway](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts): `src/oauth-server.ts`
- [Token validation](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts): `src/oauth-server.ts`
- [OAuth metadata](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts): `src/oauth-server.ts`
- [SSE sessions](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/src/oauth-server.ts): `src/oauth-server.ts`

### Debate Automation

- [Debate orchestrator](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/orchestrator.js): `orchestrator.js`
- [Debate files](https://github.com/bkelson/-claude-chatgpt-bridge/blob/main/orchestrator.js): `orchestrator.js`

### Other components

- **Claude client**
- **ChatGPT client**
- **Auth0**

## Connections

- Claude client → Stdio transport: uses
- Stdio transport → MCP server: connects
- ChatGPT client → OAuth HTTP gateway: sends requests
- OAuth HTTP gateway → Token validation: checks tokens
- Token validation → Auth0: checks claims against
- OAuth HTTP gateway → OAuth metadata: serves
- OAuth HTTP gateway → SSE sessions: opens sessions
- OAuth HTTP gateway → MCP server: forwards MCP requests
- MCP server → File tools: registers
- MCP server → Inbox tools: registers
- MCP server → Conversation tools: registers
- MCP server → Status tool: registers
- File tools → Shared files: reads and writes
- Inbox tools → Model inboxes: reads and writes
- Conversation tools → Conversation log: reads and writes
- Status tool → Shared files: counts
- Status tool → Model inboxes: counts unread
- Debate orchestrator → Debate files: watches and writes