chatgpt-mcp/README.md

# ChatGPT MCP Server

A local MCP (Model Context Protocol) server that gives Claude Code access to specialized ChatGPT review and advisory tools.

The server provides structured second-opinion workflows for:

- General questions and alternative viewpoints
- Implementation plan reviews
- Code reviews
- Debugging investigations
- Architecture reviews

Claude Code remains the primary coding agent. ChatGPT acts only as an advisor and reviewer.

---

## Purpose

This project combines the strengths of both models:

- **Claude Code** performs implementation, editing, refactoring, testing, and repository operations.
- **ChatGPT** provides independent analysis, review, risk assessment, debugging assistance, and architectural feedback.

The goal is to improve decision quality without introducing autonomous behaviour.

---

## Non-Goals

The server must not:

- Modify files
- Run shell commands
- Access Git automatically
- Deploy anything
- Send entire repositories by default
- Send secrets
- Make autonomous decisions

ChatGPT only returns analysis and recommendations.

---

## Architecture

```text
Claude Code
    ↓
MCP Tool
    ↓
Input Validation
    ↓
Context Budget Enforcement
    ↓
Prompt Builder
    ↓
Provider Factory (createChatProvider)
    ↓
OpenAI Provider → OpenAI Responses API
    ↓
Advisory Response
```

The provider layer is configurable via `CHATGPT_MCP_PROVIDER` env var. Two providers are available:

| Value    | Description                                                    | Use case                                    |
| -------- | -------------------------------------------------------------- | ------------------------------------------- |
| `openai` | Default — calls ChatGPT via OpenAI API                       | Automated second-opinion queries            |
| `manual` | Copy-paste — wraps prompts in a ready-to-copy format         | Manual ChatGPT Web/Business as advisor      |

For the **manual** provider, set `CHATGPT_MCP_PROVIDER=manual`. Each tool call returns a copy-ready prompt block you can paste into ChatGPT Web or ChatGPT Business. This turns Claude Code into an orchestrator: it builds the perfect prompt and formats it for you to hand off to ChatGPT as a second-opinion advisor — all without API calls, quotas, or cost.

The factory pattern enables future providers (Ollama, Anthropic, custom) without touching tool handlers.

All responses are advisory only.

---

## Available MCP Tools

| Tool                  | Purpose                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `ask_chatgpt`         | General second-opinion questions, alternatives, risks, trade-offs, and clarification.                                                     |
| `review_plan`         | Reviews implementation plans for missing steps, sequencing issues, unsafe assumptions, scope creep, and test gaps.                        |
| `review_code`         | Reviews code snippets, patches, and diffs for correctness, bugs, maintainability, security concerns, and testing opportunities.           |
| `debug_issue`         | Analyses errors, logs, failed tests, and stack traces to identify likely root causes and propose safe investigation steps.                |
| `architecture_review` | Reviews architecture decisions, system design, trade-offs, maintainability, operational risk, vendor lock-in, and future evolution paths. |

---

## Features

### OpenAI Integration

- OpenAI Responses API
- Configurable model selection
- Dependency-injected design for testability
- Structured error handling
- Safe error messages without secret leakage

### Prompt System

- Shared base prompt layer
- Tool-specific prompt builders
- Consistent advisory behaviour
- Structured response guidance

### Input Protection

- Zod-based validation
- Context budget enforcement
- File size limits
- Log size limits
- Secret redaction utilities

### MCP Integration

- MCP stdio server
- Tool discovery via `tools/list`
- Structured tool responses
- Claude Code integration

### Testing

- 523+ automated tests
- Unit-tested utilities
- Prompt builder coverage
- OpenAI integration coverage
- Tool handler orchestration coverage
- MCP registration verification

---

## Requirements

- Node.js 20+
- OpenAI API key
- Claude Code (or another MCP-compatible client)

---

## Installation

Install dependencies:

```bash
npm install
```

Set your OpenAI API key:

```bash
export OPENAI_API_KEY=sk-your-key
```

Optional environment variables:

```bash
export OPENAI_MODEL=gpt-5.1
export OPENAI_TEMPERATURE=0.2
```

---

## Running Tests

```bash
npm test
```

---

## Running the MCP Server

Start the stdio MCP server:

```bash
npm start
```

The server communicates over stdin/stdout and is intended to be launched by an MCP client rather than directly by users.

---

## Claude Code Configuration

Configure Claude Code to discover the MCP server.

Create either:

- Global configuration: `~/.claude/settings.json`
- Project-local configuration: `.claude/settings.local.json`

Example:

```json
{
  "mcpServers": {
    "chatgpt-mcp": {
      "command": "npm",
      "args": ["start"]
    }
  }
}
```

After opening the project in Claude Code, the server should be automatically discovered and the five MCP tools should become available.

---

## Current Status

### MVP Complete

Implemented:

- OpenAI Responses API integration
- Shared validation and safety utilities
- Context budget management
- Five prompt builders
- Five tool handlers
- MCP stdio server
- Registration of all five MCP tools
- Claude Code integration documentation
- Comprehensive automated test suite (523+ tests)

### Next Steps

Planned future work includes:

- Real-world workflow validation
- Prompt refinements
- Additional context-loading features
- Improved operational diagnostics
- Production hardening

---

## Development Philosophy

Keep the system simple.

- Prefer local-first solutions
- Minimise moving parts
- Avoid unnecessary abstractions
- Favour small, testable modules
- Keep ChatGPT advisory-only
- Keep Claude Code in control

The objective is not autonomous development. The objective is better engineering decisions through independent review.