robbond/chatgpt-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bc9eb4e04003c2d25fb6e1200140ceda032428fa
chatgpt-mcp/README.md
T

279 lines
7.8 KiB
Markdown
Raw Blame History

# 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. 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
- 644 automated tests across 21 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 20+
- 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)
---
## 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.
---
## 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 (644 tests across 21 files)
### 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.
Reference in New Issue View Git Blame Copy Permalink