# 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
Manual Provider   →  Copy-ready prompt output
Ollama Provider   →  Ollama /api/chat
    ↓
Advisory Response
```

The provider layer is configurable via `CHATGPT_MCP_PROVIDER` env var (defaults to `"openai"`). Three 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      |
| `ollama` | Local AI — uses Ollama `/api/chat` with Qwen3 model          | Offline/local second-opinion via local LLM  |

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.

For the **ollama** provider, set `CHATGPT_MCP_PROVIDER=ollama` and ensure Ollama is running locally. The provider uses Qwen3 via Ollama's OpenAI-compatible `/api/chat` endpoint with no additional dependencies. This turns Claude Code into an orchestrator: it builds the perfect prompt and sends it directly to your local model — all without cloud API calls, quotas, or cost.

The factory pattern enables future providers (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

### Local AI Provider (Ollama)

- Uses Ollama `/api/chat` endpoint via native `fetch()` — zero new dependencies
- Default model: `qwen3:latest` on `http://localhost:11434`
- Configurable temperature, timeout, and base URL
- Produces the same structured advisory responses as OpenAI provider

### 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

- 706 automated tests across 22 files
- Unit-tested utilities
- Prompt builder coverage
- OpenAI integration coverage
- Tool handler orchestration coverage
- MCP registration verification
- Manual export provider coverage (56 tests)

---

## Requirements

- Node.js 22+
- OpenAI API key **OR** Ollama (with `qwen3:latest` model pulled) **OR** use `manual` provider for zero-API workflow
- Claude Code (or another MCP-compatible client)

---

## Quick Start

For the fastest onboarding, use the interactive setup helper:

```bash
npm install
npm run setup     # Choose a provider and configure .env (interactive)
npm test          # Verify everything works
npm start         # Start the MCP server
```

The setup helper guides you through choosing between `openai`, `manual`, or `ollama` providers, then creates your `.env` and optionally `.claude/settings.local.json`.

See [docs/SETUP.md](./docs/SETUP.md) for full documentation.

---

## Installation

Install dependencies:

```bash
npm install
```

Set your OpenAI API key:

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

Optional environment variables:

```bash
# Provider selection (default: openai)
export CHATGPT_MCP_PROVIDER=openai   # or "manual" or "ollama"

# OpenAI provider settings
export OPENAI_MODEL=gpt-5.1
export OPENAI_TEMPERATURE=0.2
export OPENAI_MAX_OUTPUT_TOKENS=2000

# Ollama provider settings (used when CHATGPT_MCP_PROVIDER=ollama)
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=qwen3:latest
export OLLAMA_TEMPERATURE=0.2
export OLLAMA_TIMEOUT=60

# General settings
export CHATGPT_MCP_LOG_LEVEL=info
export CHATGPT_MCP_MAX_INPUT_CHARS=30000
```

---

## 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.

---

## V1 Milestone

**Status: V1 Complete**

### Implemented

- OpenAI provider (GPT-5.1 via Responses API)
- Manual Export provider (copy-paste-ready prompts for ChatGPT Web)
- Ollama provider (local AI via `qwen3.6:35b-a3b`)
- Provider abstraction layer with factory pattern
- Context budget enforcement and secret redaction
- 5 MCP review tools (`ask_chatgpt`, `review_plan`, `review_code`, `debug_issue`, `architecture_review`)
- Interactive local setup helper (`npm run setup`)
- 706 automated tests across 22 test files

### Capabilities

The ChatGPT MCP Server provides structured second-opinion workflows for:

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

All responses are advisory-only. Claude Code remains the primary coding agent.

---

## Current Status

### MVP Complete

Implemented:

- OpenAI Responses API integration
- Ollama local AI provider (`qwen3:latest`) — zero new dependencies
- Three configurable providers: `openai`, `manual`, `ollama`
- 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 (701 tests across 22 files)
- Interactive local setup helper (`npm run setup`)

### 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.