149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
# 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._
|