From cbaad9fdb41bea6b947090ba0a1ca6cac3c47782 Mon Sep 17 00:00:00 2001 From: robbond Date: Fri, 12 Jun 2026 13:25:47 +0100 Subject: [PATCH] docs: refresh README for MVP completion --- README.md | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 219 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2b8a6b8..7b1d9e3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,29 @@ # ChatGPT MCP Server -A local MCP server that allows Claude Code to ask ChatGPT for focused second-opinion help. +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 -ChatGPT acts as a reviewer, planner, debugging assistant, and architecture advisor. -Claude Code remains the primary coding agent with full control over files, commands, and decisions. +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 @@ -15,11 +33,205 @@ The server must not: - Run shell commands - Access Git automatically - Deploy anything -- Send whole repositories by default +- Send entire repositories by default - Send secrets - Make autonomous decisions -## Status +ChatGPT only returns analysis and recommendations. -Phase 0 complete — repository skeleton created. -Implementation in progress. +--- + +## Architecture + +```text +Claude Code + ↓ +MCP Tool + ↓ +Input Validation + ↓ +Context Budget Enforcement + ↓ +Prompt Builder + ↓ +OpenAI Responses API + ↓ +Advisory Response +``` + +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.