docs: prepare v1 milestone release
This commit is contained in:
+148
@@ -0,0 +1,148 @@
|
||||
# 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._
|
||||
Reference in New Issue
Block a user