@vernikr/gemini-mcp 0.10.1 → 0.12.0

package/README.md

@@ -11,6 +11,52 @@ massive-body chunked analysis with consolidation. Python core `gemini-mcp-gatewa
 <https://aistudio.google.com/app/apikey> — several keys = several times the quota
 (20 requests/day per key×model).
 
+## Quick start
+
+### If you're human
+
+```bash
+pnpm dlx @vernikr/gemini-mcp setup
+```
+
+Answer the questions (pick **1 Simple** unless you run a server; keys: hidden paste,
+a file, or skip). The wizard finishes with a short numbered checklist — paste one
+JSON block into your MCP client (or let it write that for you: add
+`--write-client freebuff|claude|cursor`), restart the client, send your agent the
+printed verify prompt. Fleet (pick **2**): it also deploys your VPS end-to-end
+(clone → provision → keys → healthcheck) and prints the final block with your real
+host already inside.
+
+### If you're an AI agent
+
+One shot, no TTY, machine-readable. Exit code `0` + `"ok": true` = done; otherwise
+every failure carries `error`/`deploy_error`/`clients_failed[].fix` naming the exact
+remedy — apply it and re-run the same command (idempotent).
+
+```bash
+# direct (no server); keys from a file — never from shell history
+npx -y @vernikr/gemini-mcp setup --backend direct \
+  --keys-file /abs/path/keys.txt --write-client freebuff --json
+
+# fleet (shared-quota server); clones/provisions/health-checks by itself
+npx -y @vernikr/gemini-mcp setup --backend router --vps-host <ip> \
+  [--vps-user root] [--projects-dir ~/projects] [--keys-file /abs/path/keys.txt] \
+  --write-client freebuff --json
+```
+
+Fleet prerequisites you must verify first (each failure message tells you how):
+`git ls-remote https://github.com/vernikr/gemini-mcp` succeeds (private repos —
+GitHub auth), `ssh <user>@<ip> 'echo ok'` succeeds (key auth), bash+rsync present,
+macOS/Linux. What is left for the human — relay exactly these two manual actions
+from the JSON: **restart the MCP client fully**, then **send the agent the prompt in
+`verify_prompt`** (tool `quota_status`, MCP server `gemini`).
+
+Analyzing a FILE (agent): never read it yourself and never inline its contents into a
+prompt. Call `file_upload_ticket(filename, size_bytes)` → HTTP PUT the raw bytes to
+`upload_url` → `analyze_file(upload_id, task)`. Extraction (pandoc), chunking and quota
+are server-side; `quota_status` repeats this recipe in its `file_flow` field, and raw
+RTF/PDF/DOCX payloads in text tools fail fast with a `raw_document_inlined` fix.
+
 ## Wiring — 2 options
 
 ### A · Wizard (recommended): `setup`, then paste one JSON block
@@ -29,8 +75,9 @@ What it does — and what it does NOT:
   side itself — clone/update repos, provision, push keys, healthcheck — and ends with
   the same paste-once JSON (`--vps-host`, `--vps-user`, `--projects-dir` skip prompts);
 - probes keys live (listModels — zero quota spent) and prints fingerprints, never keys;
-- **prints** the ready `mcpServers` JSON for your client — it does **not** edit any
-  client config itself (formats differ per client; you paste the block once).
+- **prints** the ready `mcpServers` JSON for your client — paste it once, or pass
+  `--write-client freebuff|claude_desktop|cursor` and the wizard merges the `gemini`
+  entry into the client's config file itself (`.bak` backup kept).
 
 After the wizard the client JSON needs no env/keys — the gateway auto-discovers
 `~/.config/gemini-mcp/`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vernikr/gemini-mcp",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "One-command Gemini free-tier MCP gateway: quota-aware model routing, massive-body chunked analysis, file ingest (RTF/DOCX→Markdown), async tickets. Thin bootstrap for the Python core gemini-mcp-gateway.",
   "bin": {
     "gemini-mcp": "bin/gemini-mcp.js"