docs: refresh README for MVP completion
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user