chatgpt-mcp/AGENT_HANDOFF.md

# AGENT_HANDOFF.md

## Completed

### Phase 0 — Repository Setup
- Repository skeleton (TASK 0.1)
- package.json with dependencies (TASK 0.2)

### Phase 1 — Core Utilities
- Configuration loader (`src/config/env.js`) — TASK 1.1
- Secret redaction utility (`src/utils/redact.js`) — TASK 1.2
- Context budget utility (`src/utils/context-budget.js`) — TASK 1.3
- Safe logging helper (`src/utils/logging.js`) — TASK 1.4

### Phase 2 — OpenAI Integration
- OpenAI client wrapper (`src/openai/client.js`) — TASK 2.1
- Response builder (`src/openai/responses.js`) — TASK 2.2
- Error handling and edge cases (tests) — TASK 2.3

### Phase 3 — Tool Inputs and Prompts
- Zod input validation schemas (`src/tools/schemas.js`, tests) — TASK 3.1
- Base prompt template (`src/prompts/base.js`, tests) — TASK 3.2
- ask_chatgpt prompt builder (`src/prompts/ask-chatgpt.js`, tests) — TASK 3.3
- review_plan prompt builder (`src/prompts/review-plan.js`, tests) — TASK 3.4
- review_code prompt builder (`src/prompts/review-code.js`, tests) — TASK 3.5
- debug_issue prompt builder (`src/prompts/debug-issue.js`, tests) — TASK 3.6
- architecture_review prompt builder (`src/prompts/architecture-review.js`, tests) — TASK 3.7

## Next Phase

### Phase 4 - Tool Handlers

Build the MCP tool handlers that:
1. Register each tool with the MCP server.
2. Validate input using `schemas.js`.
3. Call the appropriate prompt builder.
4. Send the prompt to OpenAI via `responses.js`.
5. Return structured advisory output to Claude Code.

## Completed (Phase 4)

All five MCP tool handlers are complete:

| Handler | File | Tests |
|---------|------|-------|
| handleAskChatGpt | `src/tools/ask-chatgpt.js` | ✅ 27 |
| handleReviewPlan | `src/tools/review-plan.js` | ✅ 28 |
| handleReviewCode | `src/tools/review-code.js` | ✅ 28 |
| handleDebugIssue | `src/tools/debug-issue.js` | ✅ 28 |
| handleArchitectureReview | `src/tools/architecture-review.js` | ✅ 28 |

Total: 139 orchestration-only tests, all passing.

## Completed (Phase 5)

**All five MCP tools registered:** ask_chatgpt, review_plan, review_code, debug_issue, architecture_review.

## Completed (Phase 6) — Provider Abstraction ✅

Decoupled tool handlers from OpenAI implementation via a provider abstraction layer:

### src/providers/factory.js
- `createChatProvider(config)` validates `chatgptMcpProvider` against whitelist
- Defaults to `"openai"` for any falsy/unknown value (null, NaN, numeric)
- Throws with descriptive message on unrecognized provider names

### src/providers/openai.js
- `openaiProvider.send(input, config)` — thin adapter wrapping OpenAI modules
- Internally calls `createOpenAIClient(config)` then `sendOpenAIResponse(client, params)`
- Params include: input as system messages array, model, temperature, maxOutputTokens from config

### Handler changes (all 5)
- Old interface: `{ loadConfig, createOpenAIClient, sendOpenAIResponse }`
- New interface: `{ loadConfig, createProvider }`
- Each handler calls `provider = deps.createProvider(config)` then `provider.send(budget.input, config)`
- Handler logic unchanged — only dependency injection changed

### CHATGPT_MCP_PROVIDER env var
- Defaults to `"openai"` when not set
- Accepts any string at loadConfig time; validation happens in factory at provider creation
- Currently only `"openai"` is whitelisted; others throw at createChatProvider() time

## Completed (Phase 7) — Tests ✅

### Handler tests updated (5 files, all using `{ loadConfig, createProvider }` mock pattern)
| File | Tests | Status |
|------|-------|--------|
| test/tools/ask-chatgpt.test.js | 27 | ✅ |
| test/tools/review-plan.test.js | 28 | ✅ |
| test/tools/review-code.test.js | 27 | ✅ |
| test/tools/debug-issue.test.js | 28 | ✅ |
| test/tools/architecture-review.test.js | 27 | ✅ |

### New provider/config tests (3 files)
| File | Tests | Status |
|------|-------|--------|
| test/providers/factory.test.js | ~30 | ✅ covers default, whitelist, edge cases |
| test/providers/openai.test.js | 27 | ✅ covers all send delegation paths |
| test/config/env.test.js | +4 (added section) | ✅ covers chatgptMcpProvider env var |

### Final verification
- All 579 tests pass across 20 test files (up from ~523)
- `npm start` → tools/list shows same 5 tools, unchanged schemas
- Zero regression in existing test coverage

## Completed (Phase 8) — Manual Export Provider ✅

### src/providers/manual-export.js
- `manualExportProvider.send(request, config)` — zero-API-cost provider
- Wraps pre-built prompt in copy/paste-ready format for ChatGPT Web (`https://chatgpt.com`)
- Detects tool name from input fields: `debug_issue`, `review_code`, `architecture_review`, `review_plan`, `ask_chatgpt`
- Adds box-delimited display with `│` prefixes, corner delimiters (┌ ┐ └ ┘)
- Includes instructions section (5 numbered steps), metadata section (tool, provider, length)
- Warns on prompts over 30k characters
- Handles empty/missing prompt gracefully with advisory message
- Preserves unicode, markdown code blocks, JSON, special HTML characters exactly

### Factory integration
- `"manual"` added to SUPPORTED_PROVIDERS whitelist in `src/providers/factory.js`
- `CHATGPT_MCP_PROVIDER=manual` switches all tool handlers to manual export mode
- Defaults to `"openai"` when not set — OpenAI behaviour unchanged
- Same provider interface: `{ send(request, config) => Promise<{ content: string }> }`

### Tests added (Phase 8)
| File | Tests | Coverage |
|------|-------|----------|
| test/providers/manual-export.test.js | 56 | structure, tool detection, unicode, long prompts, edge cases, repeatability, visual layout |
| test/providers/factory.test.js | +9 manual provider tests | factory integration with "manual" |

### Final verification
- All 644 tests pass across 21 test files, zero regressions
- `npm start` → tools/list shows same 5 tools, unchanged schemas
- No `chat.openai.com` references in codebase — only `chatgpt.com`
- MCP initialize handshake succeeds with chatgpt-mcp v0.1.0

## Completed (Phase 9) — Ollama Provider ✅

### src/providers/ollama.js
- `ollamaProvider.send(reviewRequest, config)` — local AI provider using Ollama `/api/chat` endpoint
- Uses native `fetch()` for HTTP calls — zero new dependencies
- Implements same provider interface as openai and manual: `{ send(request, config) => Promise<{ content: string }> }`

### Provider details
- **Request format**: OpenAI-compatible chat API (`model`, `messages`, `stream`, `options`)
- **Response parsing**: Extracts `data.message.content` from Ollama response
- **Error categories**: `OllamaTimeoutError`, `OllamaModelNotFoundError` (404), `OllamaValidationError` (422), `OllamaApiNotAvailableError` (501), `OllamaRequestError` (fallback)
- **Base URL normalization**: Strips trailing slashes for safe path concatenation

### Environment variables
| Variable | Default | Description |
|----------|---------|-------------|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama API endpoint |
| `OLLAMA_MODEL` | `qwen3:latest` | Model name for chat requests |
| `OLLAMA_TEMPERATURE` | `0.2` | Sampling temperature |
| `OLLAMA_TIMEOUT` | `60` | Request timeout in seconds |

### Factory integration
- `"ollama"` added to SUPPORTED_PROVIDERS whitelist in `src/providers/factory.js`: `Set(["openai", "manual", "ollama"])`
- `CHATGPT_MCP_PROVIDER=ollama` switches all tool handlers to local Ollama mode
- Defaults to `"openai"` when not set — OpenAI behaviour unchanged
- Same provider interface as openai and manual providers

### Current provider status
| Provider | Env Value | Type | Requires API key? |
|----------|-----------|------|-------------------|
| `openai` | `CHATGPT_MCP_PROVIDER=openai` | Cloud (OpenAI Responses API) | Yes (`OPENAI_API_KEY`) |
| `manual` | `CHATGPT_MCP_PROVIDER=manual` | Local (copy-paste) | No |
| `ollama` | `CHATGPT_MCP_PROVIDER=ollama` | Local (Ollama /api/chat) | No |

## Completed (Phase 5)

**All five MCP tools registered:** ask_chatgpt, review_plan, review_code, debug_issue, architecture_review.

### Task 5.1 - MCP server skeleton ✅

Minimal MCP stdio server in `src/server.js`. MCP initialize handshake succeeds. No tools registered yet.

### Task 5.2 - Register ask_chatgpt MCP tool ✅

`ask_chatgpt` is now registered as an MCP tool on the server (`src/server.js`).

**Registration details:**
- Uses shared `baseInputSchema` (question required + context, constraints, expectedOutput, projectSummary, taskSummary, relevantFiles, logs optional).
- External deps injected via dependency injection: `{ loadConfig, createProvider }` — provider abstraction (Phase 6).
- Returns structured MCP tool result: `{ content: [{ type: "text", text }], isError, warnings }`.

**Smoke test results (all passing):**
- initialize → server returns `chatgpt-mcp` v0.1.0 ✅
- tools/list → exposes `ask_chatgpt` with correct schema ✅
- tools/call (happy path, mocked OpenAI) → `{ content: [...], isError: false }` with answer ✅
- tools/call (minimal input `{ question: "hi" }`) → works ✅
- tools/call (full input, all 10 schema fields) → handled correctly ✅
- tools/call (missing OPENAI_API_KEY) → structured MCP error `"Error: Configuration error: OPENAI_API_KEY is missing."` ✅
- tools/call (invalid API key) → structured MCP error `"OpenAI API error (OpenAIAuthError): 401"` ✅
- All 523 unit tests pass across 18 test files ✅

**Production code (`src/server.js`):** ~39 lines, single `ask_chatgpt` tool registered with MCP via Stdio transport.

### Task 5.3 - Register remaining MCP tools ✅

Four additional MCP tools registered on the server (`src/server.js`):

| Tool | Handler |
|------|---------|
| `review_plan` | handleReviewPlan |
| `review_code` | handleReviewCode |
| `debug_issue` | handleDebugIssue |
| `architecture_review` | handleArchitectureReview |

**All five MCP tools now registered:** ask_chatgpt, review_plan, review_code, debug_issue, architecture_review.

**Smoke test results (all passing):**
- initialize → server returns `chatgpt-mcp` v0.1.0 ✅
- tools/list → 5 tools total ✅
- tools/call reaches handlers for all 5 tools ✅
- missing OPENAI_API_KEY → structured tool errors: `"Error: Configuration error: OPENAI_API_KEY is missing."` ✅
- npm test → 523 tests pass across 18 test files, no regressions ✅

**Implementation notes:**
- Each tool registered explicitly with its own `registerTool()` call — no registry abstraction.
- All handlers use existing modules only (no new imports or files).
- SDK quirk: `isError: true` wraps results in JSON-RPC error envelope (`code: -32603`).

### Task 5.4 - Normalize MCP tool error formatting ✅

MCP tool error formatting normalized in `src/server.js`. All 5 tool registrations now produce a single "Error:" prefix — no more duplicate `"Error: Error:"` strings.

**Changes:** Each tool callback normalizes the error text before returning:
- If `result.error` already starts with `"Error:"`, it is used as-is.
- Otherwise, `"Error: "` is prepended.
- `result.ok` responses are unchanged.

Smoke tests: npm test 523 passed ✅ · tools/list 5 tools ✅ · ask_chatgpt single prefix ✅ · review_plan single prefix ✅

### Task 5.5 - Claude Code MCP configuration and local end-to-end setup ✅

Project-local Claude Code discovery configured:
- `.claude/` added to `.gitignore` — no machine-specific paths in repo
- README.md updated with Setup, MCP Tools, and Running sections
- MCP config uses `"command": "npm"`, `"args": ["start"]` — platform-independent
- All 5 tools documented: `ask_chatgpt`, `review_plan`, `review_code`, `debug_issue`, `architecture_review`

## Next Pending

No pending tasks. MVP complete. Future work: Anthropic provider, streaming responses, cost tracking, Dockerfile, CI pipeline, safe project summary generation.

## General Rules

- Read ARCHITECTURE.md before making changes.
- 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.