vibe-gate-mcp 0.1.0

package/.env.example

@@ -0,0 +1,51 @@
+# =============================================================================
+# Vibe-Gate — copy to `.env` next to this package (or set the same keys in MCP env)
+# NEVER commit real keys. Required: pick ONE provider + its API key.
+# =============================================================================
+
+# --- Required: Critic provider ---
+# One of: openai | anthropic | google | minimax | opencode
+CRITIC_PROVIDER=openai
+
+# --- Required: API key for the chosen provider (uncomment ONE block) ---
+
+# OpenAI
+OPENAI_API_KEY=
+
+# Anthropic
+# ANTHROPIC_API_KEY=
+
+# Google Gemini
+# GOOGLE_GENERATIVE_AI_API_KEY=
+
+# MiniMax (direct)
+# MINIMAX_API_KEY=
+
+# OpenCode (https://opencode.ai/auth)
+# OPENCODE_API_KEY=
+# OPENCODE_PLAN=go
+
+# --- Optional: model / persona ---
+# CRITIC_MODEL=gpt-5.4
+# CRITIC_PERSONA=clean-code-monk
+#   personas: security-first | performance-freak | clean-code-monk
+
+# --- Workspace (usually set by the IDE, not here) ---
+# Cursor: "VIBE_WORKSPACE_ROOT": "${workspaceFolder}" in mcp.json
+# VIBE_WORKSPACE_ROOT=
+
+# --- Human unlock (OPTIONAL opt-in — not recommended for default AI↔AI flow) ---
+# Prefer Critic resubmit over human intervention. Only enable if you want an extra
+# gate on log_human_decision after true max-round DEADLOCK.
+# VIBE_HUMAN_CONFIRMATION_TOKEN=replace-with-a-long-random-secret
+
+# --- Debug (optional) ---
+# DEBUG=1
+
+# =============================================================================
+# OpenCode Go example (subscription):
+#   CRITIC_PROVIDER=opencode
+#   OPENCODE_API_KEY=YOUR_OPENCODE_API_KEY
+#   OPENCODE_PLAN=go
+#   CRITIC_MODEL=minimax-m3
+# =============================================================================

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-28
+
+Initial release of `vibe-gate-mcp`.
+
+### Added
+
+- **MCP server (stdio)** with tools:
+  - `submit_phase_review` — Implementer → Critic adversarial review
+  - `log_human_decision` — human deadlock decisions → `.vibe/preferences.log`
+- **Preferred payload: `files[]`** — workspace-relative source paths; MCP reads disk and builds FILE:…CONTENT: (`SEMANTIC_DIFF_SOURCE_FILES` limits)
+- **Payload sources:** `semanticDiffPath` (pre-built payload file) or inline `semanticDiff` — exactly one source
+- **`updateStatus` / `PHASE_STATUS_POLICY`** — skip `.vibe/status.json` for probes (`mcp-smoke-`, `vibe-gate-probe-`)
+- **npm CLI:** `bin` → `dist/index.mjs` (shebang); `npx -y vibe-gate-mcp`
+- **Config:** Critic providers (OpenAI, Anthropic, Google, MiniMax, OpenCode); personas; Zod-validated env
+- **Conflict loop:** up to 3 rounds; DEBT logging; project preferences
+- **Docs & examples:** INSTALLATION, USAGE, SEMANTIC_DIFF_PAYLOAD, VARIABLES, Cursor mcp.json templates, `.env.example`
+
+### Quality
+
+- TypeScript strict, ESLint + SonarJS (cognitive complexity ≤ 15), Vitest, Husky (dev checkout only)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibe-Gate Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Vibe-Gate (MCP)
+
+An **Adversarial Quality Gate** for AI-assisted IDEs: the IDE agent and a Critic LLM debate code; the human decides only on deadlock.
+
+## Quick start (npm / npx)
+
+### 1. Critic API key
+
+Create a `.env` where you run vibe-gate **or** put the same keys in MCP `env`.
+
+Copy from the package’s [`.env.example`](.env.example):
+
+```bash
+# Minimal OpenAI example
+CRITIC_PROVIDER=openai
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+
+# Or OpenCode (https://opencode.ai/auth)
+# CRITIC_PROVIDER=opencode
+# OPENCODE_API_KEY=...
+# OPENCODE_PLAN=go
+# CRITIC_MODEL=minimax-m3
+```
+
+| Provider      | `CRITIC_PROVIDER` | Required key env                                |
+| ------------- | ----------------- | ----------------------------------------------- |
+| OpenAI        | `openai`          | `OPENAI_API_KEY`                                |
+| Anthropic     | `anthropic`       | `ANTHROPIC_API_KEY`                             |
+| Google Gemini | `google`          | `GOOGLE_GENERATIVE_AI_API_KEY`                  |
+| MiniMax       | `minimax`         | `MINIMAX_API_KEY`                               |
+| OpenCode      | `opencode`        | `OPENCODE_API_KEY` (+ optional `OPENCODE_PLAN`) |
+
+Full list: [docs/project/VARIABLES.md](docs/project/VARIABLES.md).
+
+### 2. Cursor MCP (any consumer repo)
+
+Project or user [`.cursor/mcp.json`](examples/cursor-mcp.project.json):
+
+```json
+{
+  "mcpServers": {
+    "vibe-gate": {
+      "command": "npx",
+      "args": ["-y", "vibe-gate-mcp"],
+      "env": {
+        "VIBE_WORKSPACE_ROOT": "${workspaceFolder}",
+        "CRITIC_PROVIDER": "openai",
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Prefer keys in a local `.env` next to the package or in the consumer project under `VIBE_WORKSPACE_ROOT` (never commit secrets). MCP `env` overrides `.env`.
+
+### 3. Call the tool (agents)
+
+```json
+{
+  "phaseId": "phase-1-§3",
+  "report": "What changed, why, file:line — no TODOs",
+  "files": ["src/a.ts", "src/b.ts"],
+  "round": 1
+}
+```
+
+**Prefer `files[]`** — MCP reads disk and builds FILE:…CONTENT:. See [docs/SEMANTIC_DIFF_PAYLOAD.md](docs/SEMANTIC_DIFF_PAYLOAD.md).
+
+## Local development (this repo)
+
+```bash
+corepack yarn install
+npm run build
+npm test
+cp .env.example .env   # fill Critic key
+npm start              # stdio MCP
+```
+
+User MCP while developing: [examples/cursor-mcp.user-local-dev.json](examples/cursor-mcp.user-local-dev.json) (`node dist/index.mjs` + `VIBE_WORKSPACE_ROOT=${workspaceFolder}`).
+
+After `npm run build`, **restart** the vibe-gate MCP server in the IDE.
+
+## Publish
+
+```bash
+npm pack --dry-run    # inspect the exact tarball contents
+npm publish           # package name: vibe-gate-mcp
+```
+
+Consumers then use `npx -y vibe-gate-mcp` as above.
+
+## Payload sources — prefer `files[]`
+
+| Priority | Field              | Use                    |
+| -------- | ------------------ | ---------------------- |
+| 1        | `files[]`          | Normal batches         |
+| 2        | `semanticDiffPath` | Pre-built payload file |
+| 3        | `semanticDiff`     | Tiny inline payloads   |
+
+Probes: `updateStatus: false` or `phaseId` prefixes `mcp-smoke-` / `vibe-gate-probe-`.
+
+## Documentation
+
+| Doc                                                            | Description               |
+| -------------------------------------------------------------- | ------------------------- |
+| [docs/INSTALLATION.md](docs/INSTALLATION.md)                   | Install + multi-repo MCP  |
+| [docs/USAGE.md](docs/USAGE.md)                                 | First run                 |
+| [docs/SEMANTIC_DIFF_PAYLOAD.md](docs/SEMANTIC_DIFF_PAYLOAD.md) | `files[]` contract        |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)             | Stale MCP, path errors    |
+| [docs/project/VARIABLES.md](docs/project/VARIABLES.md)         | Env SSoT                  |
+| [examples/](examples/)                                         | Cursor mcp.json templates |