# Local Setup Helper — Documentation

## Overview

The setup helper is a small interactive onboarding tool for the ChatGPT MCP Server. It reduces configuration friction when choosing between the three supported providers: `openai`, `manual`, and `ollama`.

**Run it with:**

```bash
npm run setup
```

## What it does

1. **Asks you to choose a provider** — OpenAI, Manual Export, or Ollama
2. **Prompts for provider-specific settings** — API keys, model names, URLs, etc.
3. **Writes a clean `.env` file** — with your selected configuration (asks confirmation first)
4. **Optionally creates `.claude/settings.local.json`** — so Claude Code discovers the MCP server automatically

## What it does NOT do

- No network requests of any kind
- No OpenAI API key validation against remote servers
- No Ollama model auto-discovery or health checking
- No config migration from previous formats
- No changes to global Claude Code settings (only project-local)
- No external dependencies beyond Node.js built-ins
- No secrets printed to console

## Provider selection guide

| Provider | Best for | Requires API key? | Cost |
|----------|----------|-------------------|------|
| `openai` | Automated second-opinion queries with best-in-class reasoning | Yes (`OPENAI_API_KEY`) | ~$0.003–$0.01 per call |
| `manual` | Zero-cost, manual copy-paste workflow | No | $0 |
| `ollama` | Local/private AI via Ollama's `/api/chat` endpoint | No | $0 (local compute) |

See [TASK 10.0 validation report](../TASKS.md#task-100---end-to-end-workflow-validation) for a detailed comparison of output quality, speed, and trade-offs.

## How it works

### .env generation

The helper generates a **clean** `.env` file with only the keys relevant to your chosen provider:

- `CHATGPT_MCP_PROVIDER=<selected>` — always written
- `OPENAI_API_KEY`, `OPENAI_MODEL` — for `openai` provider only
- `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, `OLLAMA_TEMPERATURE`, `OLLAMA_TIMEOUT` — for `ollama` provider only

If an existing `.env` file is detected, non-conflicting keys are preserved in a separate section. Provider-specific keys from the old file are **not** carried over.

### .claude/settings.local.json generation

Optionally creates (or overwrites) a project-local Claude Code discovery config:

```json
{
  "mcpServers": {
    "chatgpt-mcp": {
      "command": "npm",
      "args": ["start"]
    }
  }
}
```

You will be prompted before any file is created or overwritten. Existing files that are **not** `settings.local.json` (e.g., other MCP servers) are never modified.

## Safety rules

1. **No secrets printed.** API key input uses terminal masking; if displayed, it shows as `sk-***`.
2. **Confirmation required.** You must explicitly confirm before any file is written.
3. **No network calls.** The helper only reads/writes local files and prompts for input.
4. **No global settings changes.** Only `.claude/settings.local.json` (project-local).
5. **Git-safe.** Both `.env` and `.claude/` are in `.gitignore` — nothing is committed.

## Troubleshooting

### "Setup helper requires an interactive terminal"

The helper detects whether stdin is a TTY. If you're piping or running in CI, configure manually via `.env`:

```bash
echo "CHATGPT_MCP_PROVIDER=openai" >> .env
echo "OPENAI_API_KEY=sk-your-key" >> .env
```

### I want to change providers later

Either edit `.env` directly:

```bash
nano .env  # change CHATGPT_MCP_PROVIDER and the provider-specific keys
```

Or re-run `npm run setup` — it will generate a new clean `.env`.

### My Ollama model isn't found

The default Ollama model is `qwen3:latest` (alias for `qwen3.6:35b-a3b`). If yours isn't available, check with:

```bash
ollama list
```

Then set `OLLAMA_MODEL` in `.env` to one of your installed models.

### The setup script was accidentally interrupted

No changes are written until you confirm at the end. If only partial writes happened, restore from git:

```bash
git checkout -- .env .claude/
```

## Manual configuration reference

If you prefer to configure manually without the helper, create or edit `.env` with:

### OpenAI

```env
CHATGPT_MCP_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-5.1
OPENAI_TEMPERATURE=0.2
OPENAI_MAX_OUTPUT_TOKENS=2000
```

### Manual Export

```env
CHATGPT_MCP_PROVIDER=manual
```

### Ollama

```env
CHATGPT_MCP_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:latest
OLLAMA_TEMPERATURE=0.2
OLLAMA_TIMEOUT=60
```

---

_This helper is intentionally small (one file, zero dependencies). See the [TASK 10.2 design](../TASKS.md#task-102-local-setup-helper) for the full specification._