docs: refresh README for MVP completion

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.
+This project combines the strengths of both models:
-Claude Code remains the primary coding agent with full control over files, commands, and decisions.
+
+- **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.