commit 56fb7417eabd58f56665f534c2cb00bb87975b0a
Author: robbond <rob@rdbsolutions.co.uk>
Date:   Tue Jun 9 17:12:31 2026 +0100

    docs: add project architecture and planning documents

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..0716831
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,8 @@
+node_modules/
+dist/
+coverage/
+.env
+.env.*
+.DS_Store
+.vscode/
+.idea/
diff --git a/AGENT_HANDOFF.md b/AGENT_HANDOFF.md
new file mode 100644
index 0000000..3e94fa1
--- /dev/null
+++ b/AGENT_HANDOFF.md
@@ -0,0 +1,13 @@
+# AGENT_HANDOFF.md
+
+Read ARCHITECTURE.md before making changes.
+
+Rules:
+
+- Work incrementally.
+- Keep changes small.
+- Do not implement multiple phases at once.
+- Do not add features not described in ARCHITECTURE.md.
+- Update documentation when appropriate.
+- Claude Code is the implementation agent.
+- ChatGPT MCP is advisory only.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..cc65ab6
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,867 @@
+# ARCHITECTURE.md
+
+# ChatGPT MCP Server Architecture
+
+## 1. Project Purpose
+
+The ChatGPT MCP Server is a local MCP server that allows Claude Code to ask ChatGPT for focused second-opinion help.
+
+Claude Code remains the primary coding agent.
+
+ChatGPT acts only as:
+
+- Reviewer
+- Planner
+- Debugging assistant
+- Architecture advisor
+- Risk checker
+- Task decomposition helper
+
+The server must not:
+
+- Modify files
+- Run shell commands
+- Access Git automatically
+- Deploy anything
+- Send whole repositories by default
+- Send secrets
+- Make autonomous decisions
+
+---
+
+## 2. Local AI Workflow
+
+This project uses a hybrid local/cloud assistant model.
+
+```text
+Claude Code
+  ↓
+Local Ollama model: Qwen3.6:35b-a3b
+  ↓
+Primary coding, editing, testing, and implementation
+```
+
+When Claude Code wants an external second opinion:
+
+```text
+Claude Code
+  ↓
+Local ChatGPT MCP Server
+  ↓
+OpenAI Responses API
+  ↓
+ChatGPT review response
+  ↓
+Claude Code
+```
+
+ChatGPT is advisory only.
+
+Claude Code remains responsible for:
+
+- Coding
+- File edits
+- Running tests
+- Applying changes
+- Git operations
+- Final decisions
+
+---
+
+## 3. Technical Stack
+
+Use a simple JavaScript MVP.
+
+```text
+Node.js 22+
+JavaScript ESM
+MCP SDK
+OpenAI SDK
+OpenAI Responses API
+Zod
+Vitest
+stdio transport
+Local macOS execution
+Environment variables
+```
+
+Use JavaScript instead of TypeScript to keep the first version simple and reviewable.
+
+TypeScript can be added later only if the project grows enough to justify it.
+
+---
+
+## 4. High-Level Architecture
+
+```text
+Claude Code
+  |
+  | MCP stdio
+  v
+src/server.js
+  |
+  v
+MCP tool router
+  |
+  v
+Tool handler
+  |
+  v
+Input validation with Zod
+  |
+  v
+Secret redaction
+  |
+  v
+Context size checks
+  |
+  v
+Prompt builder
+  |
+  v
+OpenAI Responses API
+  |
+  v
+Structured advisory response
+```
+
+The MCP server is a bridge and prompt wrapper. It is not an autonomous agent.
+
+---
+
+## 5. Repository Structure
+
+```text
+chatgpt-mcp/
+├── README.md
+├── ARCHITECTURE.md
+├── TASKS.md
+├── PROJECT_STATE.md
+├── AGENT_HANDOFF.md
+├── package.json
+├── .env.example
+├── .gitignore
+├── src/
+│   ├── server.js
+│   ├── tools/
+│   │   ├── ask-chatgpt.js
+│   │   ├── review-plan.js
+│   │   ├── review-code.js
+│   │   ├── debug-issue.js
+│   │   ├── architecture-review.js
+│   │   └── schemas.js
+│   ├── openai/
+│   │   ├── client.js
+│   │   └── responses.js
+│   ├── prompts/
+│   │   ├── base.js
+│   │   ├── ask-chatgpt.js
+│   │   ├── review-plan.js
+│   │   ├── review-code.js
+│   │   ├── debug-issue.js
+│   │   └── architecture-review.js
+│   ├── config/
+│   │   ├── env.js
+│   │   └── defaults.js
+│   └── utils/
+│       ├── redact.js
+│       ├── context-budget.js
+│       ├── errors.js
+│       └── logging.js
+├── context/
+│   ├── project-context.md
+│   ├── mcp-context.md
+│   ├── openai-context.md
+│   ├── claude-context.md
+│   ├── security-context.md
+│   ├── user-context.md
+│   ├── infrastructure-context.md
+│   ├── development-context.md
+│   ├── repository-context.md
+│   ├── current-environment.md
+│   └── company-context.md
+└── test/
+    ├── tools/
+    ├── prompts/
+    ├── utils/
+    └── fixtures/
+```
+
+---
+
+## 6. MCP Tools
+
+Start with five focused tools.
+
+### 6.1 `ask_chatgpt`
+
+General second-opinion question.
+
+Use for:
+
+- General advice
+- Alternatives
+- Risks
+- Clarification
+- Breaking down tasks
+
+### 6.2 `review_plan`
+
+Reviews a proposed implementation plan before Claude Code acts.
+
+Use for:
+
+- Missing steps
+- Unsafe assumptions
+- Scope creep
+- Better sequencing
+- Test gaps
+
+### 6.3 `review_code`
+
+Reviews focused snippets, patches, or diffs.
+
+Use for:
+
+- Correctness
+- Bugs
+- Maintainability
+- Security issues
+- Tests
+- Simpler approaches
+
+### 6.4 `debug_issue`
+
+Reviews errors, logs, failed tests, or stack traces.
+
+Use for:
+
+- Likely root causes
+- Debugging steps
+- Minimal experiments
+- What not to change yet
+
+### 6.5 `architecture_review`
+
+Reviews architecture decisions and trade-offs.
+
+Use for:
+
+- Local vs cloud trade-offs
+- Simplicity
+- Maintainability
+- Operational risk
+- Vendor lock-in
+- Future extension paths
+
+---
+
+## 7. Tool Input Schema
+
+All tools should share a common shape.
+
+```js
+{
+  question: string,
+  context?: string,
+  constraints?: string[],
+  expectedOutput?: string,
+  projectSummary?: string,
+  taskSummary?: string,
+  relevantFiles?: [
+    {
+      path: string,
+      content: string,
+      language?: string
+    }
+  ],
+  logs?: string
+}
+```
+
+Rules:
+
+- `question` is required.
+- Context must be focused.
+- Do not send whole repositories.
+- Do not send secrets.
+- Do not send `.env` files.
+- Do not send unrelated large files.
+
+---
+
+## 8. Tool Output Format
+
+Default output should be structured and concise.
+
+```text
+Summary:
+...
+
+Recommendation:
+...
+
+Key Concerns:
+1. ...
+2. ...
+
+Suggested Next Steps:
+1. ...
+2. ...
+
+Confidence:
+Low | Medium | High
+
+Notes:
+...
+```
+
+For code review, include:
+
+```text
+Issues by Severity:
+...
+
+Suggested Fixes:
+...
+
+Test Suggestions:
+...
+```
+
+For debugging, include:
+
+```text
+Likely Causes:
+...
+
+Fast Checks:
+...
+
+Minimal Safe Experiments:
+...
+
+What Not To Do Yet:
+...
+```
+
+---
+
+## 9. Context Model
+
+Use layered context.
+
+```text
+1. Company/development preferences
+2. Project context
+3. Claude Code role context
+4. Current task context
+5. Specific question
+6. Relevant snippets/logs
+```
+
+For MVP, do not automatically load every context file.
+
+Recommended MVP behaviour:
+
+- Use built-in base prompt rules.
+- Accept focused context from Claude Code tool calls.
+- Keep automatic context loading disabled by default.
+
+Later enhancement:
+
+- Optional loading of selected files from `/context`.
+- Never load secrets or environment files.
+
+---
+
+## 10. Prompt Rules
+
+All prompts must reinforce:
+
+- Claude Code is the primary coding agent.
+- ChatGPT is advisory only.
+- ChatGPT must not claim to have run commands or tests.
+- ChatGPT must not ask for secrets.
+- ChatGPT must not request the whole repo.
+- ChatGPT should prefer small, reviewable changes.
+- ChatGPT should call out uncertainty.
+
+---
+
+## 11. Base Prompt
+
+```text
+You are ChatGPT acting as a second-opinion assistant for Claude Code.
+
+Claude Code is the primary coding agent and is currently backed by a local Ollama coding model.
+
+You are not responsible for editing files, running commands, deploying, committing code, or making autonomous decisions.
+
+Your role:
+- Review plans
+- Review code snippets
+- Analyse architecture
+- Debug issues
+- Identify risks
+- Suggest safer implementation approaches
+- Break work into smaller steps
+
+Rules:
+- Be concise and actionable.
+- Use only the context provided.
+- Do not assume access to the full repository.
+- Do not request secrets.
+- Do not recommend sending entire repositories.
+- Prefer small reviewable changes.
+- Prefer simple architecture.
+- Prefer local/self-hosted options where practical.
+- Call out uncertainty clearly.
+- Avoid over-engineering.
+- Do not pretend to have executed code or tests.
+```
+
+---
+
+## 12. OpenAI Integration
+
+Use OpenAI as a second-opinion provider only.
+
+```text
+Provider: OpenAI
+API: Responses API
+Model: configurable
+Temperature: low
+Output: structured text
+```
+
+Environment variables:
+
+```env
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-5.1
+OPENAI_TEMPERATURE=0.2
+OPENAI_MAX_OUTPUT_TOKENS=2000
+```
+
+The OpenAI integration should be isolated behind:
+
+```text
+src/openai/client.js
+src/openai/responses.js
+```
+
+This makes it easier to add other providers later, including Ollama.
+
+---
+
+## 13. Configuration
+
+Use `.env.example`:
+
+```env
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-5.1
+OPENAI_TEMPERATURE=0.2
+OPENAI_MAX_OUTPUT_TOKENS=2000
+
+CHATGPT_MCP_LOG_LEVEL=info
+CHATGPT_MCP_ENABLE_FILE_CONTEXT=false
+CHATGPT_MCP_CONTEXT_DIR=./context
+CHATGPT_MCP_MAX_INPUT_CHARS=30000
+CHATGPT_MCP_MAX_FILE_CHARS=12000
+CHATGPT_MCP_MAX_FILES=5
+CHATGPT_MCP_MAX_LOG_CHARS=10000
+CHATGPT_MCP_REDACT_SECRETS=true
+```
+
+Rules:
+
+- Fail fast if `OPENAI_API_KEY` is missing.
+- Do not hardcode secrets.
+- Do not read `.env` content into prompts.
+- Keep context loading disabled by default.
+
+---
+
+## 14. Security Rules
+
+The server must never automatically include:
+
+```text
+.env
+.env.*
+*.pem
+*.key
+id_rsa
+id_ed25519
+.ssh/*
+node_modules/*
+dist/*
+build/*
+coverage/*
+.git/*
+```
+
+Redact likely secrets before API calls.
+
+Patterns to redact:
+
+- API keys
+- Tokens
+- Passwords
+- Bearer tokens
+- Private keys
+- SSH keys
+- PEM blocks
+- Database URLs with credentials
+- Git credentials
+
+Replacement:
+
+```text
+[REDACTED]
+```
+
+Logging must not include:
+
+- Full prompts
+- Source code
+- Secrets
+- Environment variables
+- Full OpenAI responses by default
+
+---
+
+## 15. Context Size Management
+
+MVP should use character limits.
+
+Recommended defaults:
+
+```text
+Max total input: 30000 chars
+Max single file: 12000 chars
+Max files: 5
+Max logs: 10000 chars
+```
+
+Priority when trimming:
+
+1. Repeated logs
+2. Long file snippets
+3. General context
+4. Project summary
+
+Never silently drop the main question.
+
+If context is still too large, reject with:
+
+```text
+Input is too large for a focused review. Please retry with only the specific files, diff, or error section relevant to the question.
+```
+
+---
+
+## 16. Logging
+
+Log safe metadata only:
+
+- Tool name
+- Timestamp
+- Model
+- Input size
+- Output size
+- Duration
+- Success/failure
+- Error type
+
+Use stderr for MVP.
+
+No database.
+
+No telemetry.
+
+No external logging service.
+
+---
+
+## 17. Error Handling
+
+### Configuration errors
+
+Example:
+
+```text
+Configuration error: OPENAI_API_KEY is missing.
+```
+
+### Validation errors
+
+Example:
+
+```text
+Validation error: question is required.
+```
+
+### Context errors
+
+Example:
+
+```text
+Input is too large. Provide a smaller focused snippet.
+```
+
+### OpenAI errors
+
+Handle:
+
+- Authentication failure
+- Rate limits
+- Timeout
+- Model unavailable
+- Network failure
+
+Return safe messages only.
+
+Do not expose stack traces unless debug mode is explicitly enabled.
+
+---
+
+## 18. Claude Code MCP Configuration
+
+Production-style local config:
+
+```json
+{
+  "mcpServers": {
+    "chatgpt-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/chatgpt-mcp/src/server.js"],
+      "env": {
+        "OPENAI_API_KEY": "your-openai-api-key",
+        "OPENAI_MODEL": "gpt-5.1"
+      }
+    }
+  }
+}
+```
+
+Development config:
+
+```json
+{
+  "mcpServers": {
+    "chatgpt-mcp": {
+      "command": "npm",
+      "args": ["run", "dev:mcp"],
+      "cwd": "/absolute/path/to/chatgpt-mcp",
+      "env": {
+        "OPENAI_API_KEY": "your-openai-api-key"
+      }
+    }
+  }
+}
+```
+
+The server runs locally on macOS using stdio.
+
+It does not need to be deployed for the MVP.
+
+---
+
+## 19. Development Workflow
+
+Use the normal Gitea workflow.
+
+```text
+Feature branch
+→ Commit
+→ Pull request
+→ Merge
+```
+
+Branch examples:
+
+```text
+feature/TASK-001
+fix/TASK-002
+docs/TASK-003
+```
+
+Commit examples:
+
+```text
+feat: add ask_chatgpt tool
+fix: redact bearer tokens
+docs: update MCP setup instructions
+test: add prompt builder tests
+chore: initialise project
+```
+
+Rules:
+
+- One task per change.
+- Keep changes small.
+- Update docs when behaviour changes.
+- Do not add hidden behaviour.
+- Do not add automatic repository scanning in MVP.
+- Do not add deployment automation until the local MVP works.
+
+---
+
+## 20. Testing Strategy
+
+Use Vitest.
+
+Test areas:
+
+- Config loading
+- Secret redaction
+- Context budget checks
+- Prompt construction
+- Tool schema validation
+- OpenAI wrapper with mocked responses
+- Error formatting
+
+Manual smoke tests:
+
+1. Start MCP server locally.
+2. Confirm Claude Code can discover tools.
+3. Call `ask_chatgpt`.
+4. Call `review_plan`.
+5. Call `review_code`.
+6. Call `debug_issue`.
+7. Confirm no files were modified by the MCP server.
+8. Confirm fake secrets are redacted.
+
+---
+
+## 21. MVP Scope
+
+Smallest useful MVP:
+
+```text
+Node.js JavaScript project
+MCP stdio server
+OpenAI Responses API wrapper
+Config loader
+Secret redaction
+Context size checks
+ask_chatgpt tool
+README setup instructions
+```
+
+Do not build all advanced features first.
+
+After the MVP works, add the other tools one at a time.
+
+---
+
+## 22. Recommended Implementation Order
+
+1. Create repository skeleton.
+2. Add package.json.
+3. Add `.env.example`.
+4. Add config loader.
+5. Add redaction utility.
+6. Add context budget utility.
+7. Add OpenAI client wrapper.
+8. Add base prompt.
+9. Add `ask_chatgpt`.
+10. Add MCP stdio server.
+11. Test with Claude Code.
+12. Add `review_plan`.
+13. Add `review_code`.
+14. Add `debug_issue`.
+15. Add `architecture_review`.
+16. Add README examples.
+17. Add tests.
+18. Update PROJECT_STATE.md.
+
+---
+
+## 23. Future Roadmap
+
+Near term:
+
+- Add all five MCP tools.
+- Add structured response formatting.
+- Add better tests.
+- Add context file opt-in loading.
+
+Medium term:
+
+- Add optional Ollama provider.
+- Add model-per-tool config.
+- Add cost tracking.
+- Add timeout/retry tuning.
+- Add local-only mode for sensitive reviews.
+
+Later:
+
+- Add Dockerfile.
+- Add Jenkins validation pipeline.
+- Add Gitea pull request workflow.
+- Add safe project summary generation.
+- Add optional OpenHands integration.
+- Add provider abstraction for OpenAI/Ollama/local models.
+
+---
+
+## 24. Key Risks
+
+### Risk: Secret leakage
+
+Mitigation:
+
+- Explicit context only.
+- Redaction.
+- No automatic `.env` loading.
+- Safe logging.
+
+### Risk: Too much context
+
+Mitigation:
+
+- Character limits.
+- File count limits.
+- Focused tool inputs.
+- Reject oversized requests.
+
+### Risk: ChatGPT overrules Claude Code
+
+Mitigation:
+
+- Prompt says advisory only.
+- Claude Code remains executor.
+- Responses include assumptions and confidence.
+
+### Risk: Over-engineering
+
+Mitigation:
+
+- JavaScript MVP.
+- One tool first.
+- No automatic repo scanning.
+- No deployment work until local MVP works.
+
+### Risk: Conflicting advice between Qwen and ChatGPT
+
+Mitigation:
+
+- Treat ChatGPT as second opinion only.
+- Use it for risk checks and alternatives.
+- Claude Code decides what to implement.
+
+---
+
+## 25. Decision Summary
+
+Use JavaScript, not TypeScript, for the MVP.
+
+Use Claude Code with local Ollama/Qwen as the main coding assistant.
+
+Use ChatGPT through MCP only as a focused external reviewer.
+
+Keep the system local-first, simple, explicit, and non-mutating.
diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md
new file mode 100644
index 0000000..2fbd612
--- /dev/null
+++ b/PROJECT_STATE.md
@@ -0,0 +1,18 @@
+# PROJECT_STATE.md
+
+## Project
+
+ChatGPT MCP Server
+
+## Status
+
+Planning complete.
+Implementation not started.
+
+## Current Phase
+
+Phase 0 - Repository Setup
+
+## Next Task
+
+Create repository skeleton.
diff --git a/TASKS.md b/TASKS.md
new file mode 100644
index 0000000..b08be07
--- /dev/null
+++ b/TASKS.md
@@ -0,0 +1,20 @@
+# TASKS.md
+
+## Phase 0 - Repository Setup
+
+### Task 0.1 - Create repository skeleton
+
+Create:
+
+- README.md
+- ARCHITECTURE.md
+- TASKS.md
+- PROJECT_STATE.md
+- AGENT_HANDOFF.md
+- src/
+- test/
+- context/
+
+Do not implement functionality yet.
+
+Status: Pending
diff --git a/context/claude-context.md b/context/claude-context.md
new file mode 100644
index 0000000..36bacbb
--- /dev/null
+++ b/context/claude-context.md
@@ -0,0 +1,21 @@
+# Claude Code Integration
+
+Claude Code is the primary coding agent.
+
+ChatGPT acts as:
+
+- Reviewer
+- Architect
+- Advisor
+- Debugging assistant
+
+ChatGPT should not take control of task execution.
+
+Claude remains responsible for:
+
+- Coding
+- Testing
+- File changes
+- Git operations
+
+ChatGPT provides guidance only.
diff --git a/context/mcp-context.md b/context/mcp-context.md
new file mode 100644
index 0000000..6e6b78a
--- /dev/null
+++ b/context/mcp-context.md
@@ -0,0 +1,24 @@
+# MCP Design Principles
+
+Tools should be focused.
+
+Prefer:
+
+- One question
+- One answer
+- Explicit context
+
+Avoid:
+
+- Automatically sending entire repositories
+- Automatically sending secrets
+- Large uncontrolled context windows
+
+All tools should support:
+
+- Question
+- Context
+- Constraints
+- Expected output format
+
+Responses should be concise and actionable.
diff --git a/context/openai-context.md b/context/openai-context.md
new file mode 100644
index 0000000..d4341ab
--- /dev/null
+++ b/context/openai-context.md
@@ -0,0 +1,26 @@
+# OpenAI Integration
+
+Provider:
+
+OpenAI
+
+Interface:
+
+Responses API
+
+Model Selection:
+
+Configurable
+
+Default Behaviour:
+
+- Low temperature
+- Deterministic outputs
+- Structured responses
+
+Requirements:
+
+- API key via environment variable
+- Rate limit awareness
+- Error handling
+- Retry logic
diff --git a/context/project-context.md b/context/project-context.md
new file mode 100644
index 0000000..b2bd5d4
--- /dev/null
+++ b/context/project-context.md
@@ -0,0 +1,28 @@
+# Project Context
+
+Project Name:
+ChatGPT MCP
+
+Purpose:
+
+Allow Claude Code to query ChatGPT through MCP tools.
+
+Primary Use Cases:
+
+- Architecture review
+- Plan review
+- Code review
+- Debugging assistance
+- Risk identification
+- Task decomposition
+
+Non-Goals:
+
+- Autonomous coding
+- Source control management
+- Deployment automation
+- Replacing Claude Code
+
+Success Criteria:
+
+Claude Code can invoke MCP tools and receive useful second-opinion responses from ChatGPT.
diff --git a/context/user-context.md b/context/user-context.md
new file mode 100644
index 0000000..c3d4d4f
--- /dev/null
+++ b/context/user-context.md
@@ -0,0 +1,29 @@
+# User Context
+
+Primary User:
+
+Rob
+
+Environment:
+
+- MacBook Pro
+- Claude Code
+- VS Code
+- Gitea
+- Jenkins
+- Docker
+- Ollama
+
+Preferences:
+
+- Self-hosted where practical
+- Small reviewable changes
+- Backlog-driven development
+- Clear documentation
+- Simple architecture
+
+Avoid:
+
+- Unnecessary complexity
+- Large rewrites
+- Vendor lock-in