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

All planned phases are complete. No pending work remains.

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	28	✅
test/tools/debug-issue.test.js	28	✅
test/tools/architecture-review.test.js	28	✅

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 (Phase 7)

• All 579 tests pass across 20 test files (end of Phase 7)

Post-multiphase verification

• All 706 tests pass across 22 test files (all phases complete)
• 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 (Phase 8)

• All 706 tests pass across 22 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 10) — 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

Task 5.1 through 5.5 - MCP Server and Tool Registration ✅

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

Key details from Phase 5:

• MCP stdio server in src/server.js with initialize handshake ✅
• All tools use shared baseInputSchema with dependency injection via { loadConfig, createProvider } (Phase 6)
• Error formatting normalized — single "Error:" prefix across all tools ✅
• Claude Code discovery configured via .claude/settings.local.json ✅

Completed (Task 10.3) — Local Setup Helper ✅

scripts/setup.js

• Interactive onboarding helper (~280 lines, zero dependencies, Node.js built-ins only)
• Provider selection: [1] openai, [2] manual, [3] ollama
• Provider-specific prompts (OpenAI API key with masked input; Ollama URL, model, temperature, timeout)
• Clean .env file generation with confirmation prompt
• Preserves non-conflicting keys in existing .env files
• Optional .claude/settings.local.json creation with MCP server config
• Graceful non-TTY handling (visible input mode warning)
• No network calls, no secrets printed, user-confirmation required

Files added/modified

File	Action	Purpose
scripts/setup.js	Created	Interactive setup helper
test/setup/setup.test.js	Created	33 tests (provider validation, config generation, file I/O)
docs/SETUP.md	Created	Full documentation for the setup helper
package.json	Modified	Added "setup": "node scripts/setup.js" script
README.md	Modified	Quick-start section + test count update
TASKS.md	Modified	Phase 10 entry and Task 10.3 details
PROJECT_STATE.md	Modified	Test count updated to 701/22 files

Test results (Task 10.3)

• Before: 668 tests across 21 test files
• After: 706 tests across 22 test files (+38 new)
• All passing, zero regressions

Smoke tests

• npm run setup — starts and runs in non-TTY mode ✅
• MCP initialize → chatgpt-mcp v0.1.0 ✅
• MCP tools/list → 5 tools with correct schemas ✅

V1 Milestone Complete

All planned phases are implemented and tested. The project is at v1.0.0 status with:

• 3 providers (openai, manual, ollama)
• 5 MCP tools registered
• 701 automated tests across 22 test files
• Interactive setup helper
• Complete documentation

Future work opportunities (low priority):

• Anthropic provider adapter
• Streaming responses
• Response caching
• Cost tracking per tool call
• 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.