feat: add one-click installers for major AI coding clients

.github/workflows/ci.yml

@@ -37,3 +37,86 @@ jobs:
 
       - name: Repository checks
         run: npm run check
+
+  bootstrap-linux:
+    name: Bootstrap / Linux
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      TEST_REF: ${{ github.event.pull_request.head.ref || github.ref_name }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20.x
+
+      - name: Run isolated bootstrap
+        shell: bash
+        run: |
+          set -euo pipefail
+          temp_home="$(mktemp -d)"
+          export HOME="$temp_home"
+          export JEV_MCP_CONFIG_HOME="$temp_home/.jev-mcp"
+          export JEV_MCP_RUNTIME_DIR="$temp_home/.jev-mcp/runtime"
+          export JEV_MCP_GIT_REF="$TEST_REF"
+
+          bash scripts/install.sh cursor --skip-key
+
+          test -f "$temp_home/.cursor/mcp.json"
+          test -f "$temp_home/.jev-mcp/runtime/dist/cli.js"
+          grep -q '"jev"' "$temp_home/.cursor/mcp.json"
+          grep -q 'dist/cli.js' "$temp_home/.cursor/mcp.json"
+          ! grep -q 'TYPESAFE_API_KEY' "$temp_home/.cursor/mcp.json"
+          ! test -f "$temp_home/.jev-mcp/.env"
+
+  bootstrap-windows:
+    name: Bootstrap / Windows
+    runs-on: windows-latest
+    timeout-minutes: 12
+    env:
+      TEST_REF: ${{ github.event.pull_request.head.ref || github.ref_name }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20.x
+
+      - name: Run isolated bootstrap
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $tempHome = Join-Path $env:RUNNER_TEMP "jev-mcp-user"
+          New-Item -ItemType Directory -Force -Path $tempHome | Out-Null
+
+          $env:HOME = $tempHome
+          $env:USERPROFILE = $tempHome
+          $env:JEV_MCP_CONFIG_HOME = Join-Path $tempHome ".jev-mcp"
+          $env:JEV_MCP_RUNTIME_DIR = Join-Path $env:JEV_MCP_CONFIG_HOME "runtime"
+          $env:JEV_MCP_GIT_REF = $env:TEST_REF
+
+          ./scripts/install.ps1 -Target cursor -SkipKey
+
+          $config = Join-Path $tempHome ".cursor/mcp.json"
+          $cli = Join-Path $env:JEV_MCP_RUNTIME_DIR "dist/cli.js"
+          if (-not (Test-Path $config)) { throw "Cursor MCP config was not created." }
+          if (-not (Test-Path $cli)) { throw "Managed jev-mcp runtime was not built." }
+
+          $text = Get-Content $config -Raw
+          $parsed = $text | ConvertFrom-Json
+          $entry = $parsed.mcpServers.jev
+          if ($null -eq $entry) { throw "Jev MCP entry missing." }
+          if ($entry.args[0] -ne $cli) {
+            throw "Durable runtime path mismatch: $($entry.args[0])"
+          }
+          if ($text -match 'TYPESAFE_API_KEY') { throw "Credential leaked into client config." }
+          if (Test-Path (Join-Path $env:JEV_MCP_CONFIG_HOME ".env")) {
+            throw "Skip-key smoke test unexpectedly created a credential file."
+          }

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable project changes are documented here.
 
 ## Unreleased
 
+- Added cross-platform bootstrap installers that create/update a durable local
+  runtime at `~/.jev-mcp/runtime` instead of relying on npm Git-package
+  execution at every MCP startup.
+- Added one-command setup for Codex, Claude Code, Kimi Code, ZCode, Cursor,
+  Gemini CLI, Windsurf-compatible config, generic `.agents`, and
+  project-scoped VS Code MCP configuration.
+- Added a user-level `~/.jev-mcp/.env` credential store so GUI clients do not
+  need API keys embedded in MCP configuration.
+- Added safe JSON config merging with local backups and absolute local
+  Node/runtime launch paths.
+- Added installer unit tests, Linux/Windows bootstrap smoke checks, CLI smoke
+  checks, and dedicated client/install documentation.
+
 - Redesigned the English and Chinese project homepages around quick onboarding,
   tool boundaries, privacy, and a clear host-model/Jev authority model.
 - Added quick-start, FAQ, troubleshooting, examples, support, governance,

README.md

@@ -7,7 +7,7 @@
 
 **Unofficial, community-maintained MCP server for TypeSafe AI Jev.**
 
-[简体中文](README.zh-CN.md) · [Quick start](docs/QUICKSTART.md) · [Examples](examples/README.md) · [Security](SECURITY.md) · [FAQ](docs/FAQ.md)
+[简体中文](README.zh-CN.md) · [One-click install](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md) · [Examples](examples/README.md) · [Security](SECURITY.md) · [FAQ](docs/FAQ.md)
 
 `jev-mcp` exposes TypeSafe AI's Jev decision model as four conservative,
 read-only MCP tools for **bounded probabilistic decisions**.
@@ -92,15 +92,59 @@ Successful responses include local metadata similar to:
 
 That metadata is added by this MCP server; it is not Jev model output.
 
-## 60-second install
+## One-command install
 
-Requirements:
+No manual MCP JSON/TOML editing is required. The bootstrap installs a shared
+runtime at `~/.jev-mcp/runtime`, asks for the TypeSafe key with hidden input,
+and configures the selected client.
 
-- Node.js 20+
-- a TypeSafe API key / applicable TypeSafe access and credits
-- an MCP host that can launch a local stdio server
+macOS / Linux:
 
-Clone and set up:
+```bash
+# Codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+
+# Claude Code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+
+# Kimi Code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+
+# ZCode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+
+# Cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+
+# Gemini CLI
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+```
+
+Windows PowerShell (replace `codex` with another target as needed):
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+```
+
+To configure every detected user-level client:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+```
+
+The key is stored only in `~/.jev-mcp/.env`; client MCP configs contain no
+TypeSafe credential. Existing JSON configs are backed up before modification.
+
+Supported targets: Codex, Claude Code, Kimi Code, ZCode, Cursor, Gemini CLI,
+Windsurf-compatible config, generic `.agents/mcp.json`, and project-scoped
+VS Code/Copilot Agent configuration.
+
+See [Installation](docs/INSTALLATION.md) for Windows commands, updates,
+uninstall, `--skip-key`, and advanced controls.
+
+### Source install
+
+For contributors or users who prefer a local checkout:
 
 ```bash
 git clone https://github.com/Afloat16/jev-mcp.git
@@ -116,12 +160,6 @@ cd jev-mcp
 ./setup.ps1
 ```
 
-The setup script reads the API key without echoing it, stores it only in the
-local gitignored `.env` file when needed, installs dependencies, and runs local
-checks.
-
-For a more explicit walkthrough, see [Quick start](docs/QUICKSTART.md).
-
 ## Codex configuration
 
 Add this to `~/.codex/config.toml` and replace the path:
@@ -166,9 +204,9 @@ structured output, orchestration, explicit thresholds, or shared agent workflows
 | `JEV_MODEL` | no | `jev-latest` | Jev model override |
 | `TYPESAFE_BASE_URL` | no | `https://api.typesafe.ai` | API base URL |
 | `TYPESAFE_TIMEOUT_MS` | no | `15000` | Request timeout, 250–120000 ms |
-| `JEV_ENV_FILE` | no | project `.env` | Alternate env file path |
+| `JEV_ENV_FILE` | no | auto | Explicit env file; otherwise project `.env`, then `~/.jev-mcp/.env` |
 
-Existing process environment variables override values loaded from `.env`.
+Existing process environment variables override file values. Without `JEV_ENV_FILE`, a checkout-local `.env` is loaded before the installer-managed `~/.jev-mcp/.env`.
 
 ### Secret-handling rules
 
@@ -227,6 +265,8 @@ should be documented in [CHANGELOG.md](CHANGELOG.md) and migration notes.
 
 ## Documentation
 
+- [One-click installation](docs/INSTALLATION.md)
+- [Supported AI clients](docs/CLIENTS.md)
 - [Quick start](docs/QUICKSTART.md)
 - [Architecture](docs/ARCHITECTURE.md)
 - [Security and privacy model](docs/SECURITY-MODEL.md)

README.zh-CN.md

@@ -7,7 +7,7 @@
 
 **非官方、社区维护的 TypeSafe AI Jev MCP Server。**
 
-[English](README.md) · [快速开始](docs/QUICKSTART.md) · [示例](examples/README.md) · [安全说明](SECURITY.md) · [FAQ](docs/FAQ.md)
+[English](README.md) · [一键安装](docs/INSTALLATION.md) · [快速开始](docs/QUICKSTART.md) · [示例](examples/README.md) · [安全说明](SECURITY.md) · [FAQ](docs/FAQ.md)
 
 `jev-mcp` 将 TypeSafe AI 的 Jev 决策模型暴露为 4 个保守、只读的 MCP 工具，
 用于**边界明确的概率决策**。
@@ -72,16 +72,59 @@ API key 只放在本地进程环境变量或被 Git 忽略的 `.env` 文件中
 
 四个工具均声明为只读，不会修改文件、执行 shell、部署基础设施，也不会切换你选择的模型。
 
-## 60 秒安装
+## 一条命令安装
 
-要求：
-
-- Node.js 20+
-- TypeSafe API key / 可用的 TypeSafe 账户与额度
-- 支持启动本地 stdio MCP server 的客户端
+无需手工修改 MCP JSON/TOML。安装器会把共享运行时安装到
+`~/.jev-mcp/runtime`，隐藏输入 TypeSafe key，并自动配置目标 AI。
 
 macOS / Linux：
 
+```bash
+# Codex
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- codex
+
+# Claude Code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- claude-code
+
+# Kimi Code
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- kimi
+
+# ZCode
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- zcode
+
+# Cursor
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- cursor
+
+# Gemini CLI
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash -s -- gemini
+```
+
+Windows PowerShell（把 `codex` 换成其他目标即可）：
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.ps1))) -Target codex
+```
+
+自动配置检测到的用户级客户端：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/main/scripts/install.sh | bash
+```
+
+TypeSafe key 只保存在本机 `~/.jev-mcp/.env`，不会写入各 AI 的 MCP 配置；
+修改已有 JSON 配置前会自动保存备份。
+
+当前支持 Codex、Claude Code、Kimi Code、ZCode、Cursor、Gemini CLI、
+Windsurf 兼容配置、通用 `.agents/mcp.json`，以及项目级
+VS Code/Copilot Agent 配置。
+
+完整 Windows 命令、更新、卸载、`--skip-key` 和高级参数见
+[安装说明](docs/INSTALLATION.md)。
+
+### 从源码安装
+
+适合贡献者或希望固定本地 checkout 的用户：
+
 ```bash
 git clone https://github.com/Afloat16/jev-mcp.git
 cd jev-mcp
@@ -96,10 +139,6 @@ cd jev-mcp
 ./setup.ps1
 ```
 
-安装脚本会静默读取 API key，需要时写入本地 gitignored `.env`，安装依赖并运行本地检查。
-
-更详细步骤见 [快速开始](docs/QUICKSTART.md)。
-
 ## Codex 配置
 
 加入 `~/.codex/config.toml`，并替换绝对路径：
@@ -142,9 +181,9 @@ MCP 真正有价值的地方是**稳定工具边界**：结构化输出、可重
 | `JEV_MODEL` | 否 | `jev-latest` | Jev 模型覆盖 |
 | `TYPESAFE_BASE_URL` | 否 | `https://api.typesafe.ai` | API 地址 |
 | `TYPESAFE_TIMEOUT_MS` | 否 | `15000` | 250–120000 ms 请求超时 |
-| `JEV_ENV_FILE` | 否 | 项目 `.env` | 其他 env 文件路径 |
+| `JEV_ENV_FILE` | 否 | 自动 | 显式 env 文件；否则先项目 `.env`，再 `~/.jev-mcp/.env` |
 
-进程环境变量优先于 `.env` 中的同名值。
+进程环境变量优先于文件中的同名值。未指定 `JEV_ENV_FILE` 时，会先读取项目 `.env`，再读取安装器管理的 `~/.jev-mcp/.env`。
 
 ### 密钥规则
 
@@ -188,6 +227,8 @@ npm run inspect
 
 ## 文档
 
+- [一键安装](docs/INSTALLATION.md)
+- [支持的 AI 客户端](docs/CLIENTS.md)
 - [快速开始](docs/QUICKSTART.md)
 - [架构](docs/ARCHITECTURE.md)
 - [安全与隐私模型](docs/SECURITY-MODEL.md)

docs/CLIENTS.md

@@ -0,0 +1,61 @@
+# Supported AI clients
+
+The installer targets common MCP-capable coding agents while keeping the
+TypeSafe credential outside every client config.
+
+| Client | Installer ID | Scope | Integration |
+| --- | --- | --- | --- |
+| OpenAI Codex CLI + IDE extension | `codex` | user | official `codex mcp` CLI |
+| Anthropic Claude Code | `claude-code` | user | official `claude mcp` CLI |
+| Kimi Code | `kimi` | user | `~/.kimi-code/mcp.json` |
+| ZCode | `zcode` | user | `~/.zcode/cli/config.json` |
+| Cursor | `cursor` | user | `~/.cursor/mcp.json` |
+| Gemini CLI | `gemini` | user | `~/.gemini/settings.json` |
+| Windsurf-compatible config | `windsurf` | user | Windsurf MCP config |
+| Generic agents config | `agents` | user | `~/.agents/mcp.json` |
+| VS Code / Copilot Agent | `vscode` | project | `.vscode/mcp.json` |
+
+## Shared runtime model
+
+All configured clients point to the same managed local runtime:
+
+```text
+~/.jev-mcp/runtime
+```
+
+and the same local credential store:
+
+```text
+~/.jev-mcp/.env
+```
+
+This has three advantages:
+
+- no API key is duplicated into multiple AI configuration files;
+- clients do not need network access just to start the MCP server;
+- rerunning the bootstrap updates one shared runtime for every configured
+  client.
+
+## Design rules
+
+The installer:
+
+- never embeds the TypeSafe API key in an AI client's MCP config;
+- backs up existing JSON configuration before modification;
+- preserves unrelated keys in existing JSON configuration;
+- uses an official client CLI when that is the safer documented path;
+- uses absolute local Node/runtime paths for stable stdio startup;
+- never sends a TypeSafe API request during installation;
+- configures Kimi for deferred Jev tool loading.
+
+## New client requests
+
+When adding another client, prefer in this order:
+
+1. an official client CLI for MCP registration;
+2. an officially documented user-level configuration file;
+3. an industry-standard generic MCP file;
+4. a clearly labeled compatibility path when no first-party mechanism exists.
+
+Every new target should include installer tests, a bootstrap smoke test where
+practical, and a check that no credential is written to client config.

docs/FAQ.md

@@ -29,9 +29,11 @@ change the host model selected by the user.
 
 ## Does the API key get sent to the host model?
 
-The server reads the key from its local environment and uses it as an
-Authorization header for the configured API request. The tool output does not
-intentionally include the credential.
+The server reads the key from its local process environment or a local
+credential file. The one-command installer stores the shared key in
+`~/.jev-mcp/.env` and does not place it in AI client MCP configuration. The
+server uses the key only as the Authorization header for the configured API
+request; tool output does not intentionally include the credential.
 
 Do not put credentials into tool `state`, prompts, screenshots, logs, issues,
 or examples.