# VibeWise MCP

Universal [MCP](https://modelcontextprotocol.io) port of [VibeWise](https://github.com/nykooi1/vibe-wise), a Claude Code plugin that puts learning and design first.

One gate for **every** MCP-capable coding agent: Claude Code, Cursor, Codex CLI, Antigravity, and others:

- The agent asks **your** approach before building; you shape the design.
- Your decisions and the project map are recorded locally in `.vibe-wise/`.
- Code is written only after you approve an implementation checkpoint (`vibe_confirm`).
- No account, backend, or telemetry. Notes are local Markdown.

## How the gate works

```
you describe the task
        │
        ▼
Build checkpoint ── agent asks how YOU would approach it ── your reasoning recorded
        │
        ▼
Design checkpoint ── proposal + tradeoffs ── "Confirm and continue" records it (no code)
        │
        ▼
Implementation checkpoint ── exact code changes ── "Implement this step" authorizes code
        │
        ▼
agent writes code, runs checks, gives an Implementation report
```

The three checkpoints are not mandatory stops; when the design is already clear the
Implementation checkpoint confirms it too. The pending decision lives in
`.vibe-wise/progress.md`, survives restarts and compaction, and is the ledger the
tools read and write: restarting a session is never approval.

## Tools

| Tool | Purpose |
| --- | --- |
| `vibe_status` | Check the gate: active, stage, pending decision, what to do next |
| `vibe_start` | Activate learning mode; create `.vibe-wise/`; onboard or resume |
| `vibe_onboard_answer` | Record one onboarding answer; get the next question |
| `vibe_checkpoint` | Open `build` / `design` / `implement` checkpoint |
| `vibe_confirm` | Record the user's decision: `confirm` / `discuss` / `approach` |
| `vibe_report` | Record the implementation report after approved coding |
| `vibe_map_update` | Update the evidence-based project map |
| `vibe_pause` | Pause / resume the gate ("Learning mode: paused") |
| `vibe_reset` | Preview + token-confirmed reset with automatic backup |
| `vibe_read_notes` | Read all notes + parsed gate state (session restoration) |

## State (`.vibe-wise/` in your project)

```
.vibe-wise/
  profile.md        learner profile, preferences, "Learning mode: active/paused"
  progress.md       learning events + "## Pending decision" (the gate ledger)
  project-map.md    evidence-based system map, confirmed designs, approved work
  backups/          automatic backups created by vibe_reset
```

Add `.vibe-wise/` to `.gitignore` if you don't want the notes in Git; the server
never edits `.gitignore` silently.

## Install

Requires Node.js 20+. Build once:

```bash
npm install && npm run build
```

### Claude Code

```bash
claude mcp add vibe-wise -- node /absolute/path/to/vibe-wise-mcp/dist/server.js
```

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vibe-wise": { "command": "node", "args": ["/absolute/path/to/vibe-wise-mcp/dist/server.js"] }
  }
}
```

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.vibe-wise]
command = "node"
args = ["/absolute/path/to/vibe-wise-mcp/dist/server.js"]
```

### Antigravity (agy)

`~/.gemini/settings.json` (or the Antigravity MCP settings file):

```json
{
  "mcpServers": {
    "vibe-wise": { "command": "node", "args": ["/absolute/path/to/vibe-wise-mcp/dist/server.js"] }
  }
}
```

### Generic MCP client

Command: `node <repo>/dist/server.js`, stdio transport, no env vars needed.

## Usage

In any agent, after installing the server:

1. `Please run vibe_status, then vibe_start for this project` (one-time setup).
2. Then just ask for what you want built. The agent opens a Build checkpoint and
   asks for **your** approach before writing anything.
3. Say "pause learning" anytime; resume with `vibe_start` (`action=resume`).
4. "Reset learning" restarts onboarding; the previous notes are backed up first.

The server exposes its behavior guide as an MCP resource
(`vibewise://guides/behavior`); agents that read resources get the full
teaching contract, others get it through tool guidance.

## Development

```bash
npm run build   # tsc -> dist/
npm test        # node:test unit/behavior tests (dist/test/*.test.js)
node src/test/smoke.mjs   # end-to-end MCP protocol smoke test over stdio
```

Port of VibeWise by nykooi1 (MIT). State format and teaching behavior follow the
original plugin; enforcement moved from prompts to the tool layer.

## License

MIT, see [LICENSE](LICENSE).