VibeWise MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VibeWise MCP Please run vibe_status, then vibe_start for this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VibeWise MCP
Universal MCP port of VibeWise, 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 reportThe 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.
Related MCP server: piia-engram
Tools
Tool | Purpose |
| Check the gate: active, stage, pending decision, what to do next |
| Activate learning mode; create |
| Record one onboarding answer; get the next question |
| Open |
| Record the user's decision: |
| Record the implementation report after approved coding |
| Update the evidence-based project map |
| Pause / resume the gate ("Learning mode: paused") |
| Preview + token-confirmed reset with automatic backup |
| 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_resetAdd .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:
npm install && npm run buildClaude Code
claude mcp add vibe-wise -- node /absolute/path/to/vibe-wise-mcp/dist/server.jsCursor
~/.cursor/mcp.json:
{
"mcpServers": {
"vibe-wise": { "command": "node", "args": ["/absolute/path/to/vibe-wise-mcp/dist/server.js"] }
}
}Codex CLI
~/.codex/config.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):
{
"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:
Please run vibe_status, then vibe_start for this project(one-time setup).Then just ask for what you want built. The agent opens a Build checkpoint and asks for your approach before writing anything.
Say "pause learning" anytime; resume with
vibe_start(action=resume)."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
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 stdioPort 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.
Available Tools
10 toolsvibe_checkpointA
VibeWise: open a checkpoint BEFORE doing the work. kind=build: ask how the USER would approach the problem (their reasoning first, never your design). kind=design: present the agreed design + tradeoffs for confirmation. kind=implement: present the exact code changes for approval - the only gate that authorizes writing code.
Inputs: kind (required), name (required), proposal, projectPath, +2 more.
vibe_confirmA
VibeWise: resolve the open checkpoint with the USER's decision. option=confirm for 'Confirm and continue' (design) or 'Implement this step' (implement); option=discuss when they asked questions; option=approach + userText to record the user's own build-stage reasoning. Without this tool's record, code must not be written.
Inputs: option (required), userText, projectPath.
vibe_map_updateC
VibeWise: update the evidence-based project map (purpose, components, flow, boundaries, unknowns). Mark unknowns as unknown.
Inputs: purpose, mainFlow, unknowns, components, +4 more.
vibe_onboard_answerB
VibeWise: record one onboarding answer from the user and get the next question. Never answer these yourself.
Inputs: field (required), value (required), projectPath, questionStyle, +2 more.
vibe_pauseB
VibeWise: pause learning mode (gate off) at the user's request, or resume it.
Inputs: resume, projectPath.
vibe_read_notesB
VibeWise: read all learning notes (.vibe-wise/*.md) plus the parsed gate state. Use for session restoration and compaction recovery; search ALL of progress.md for pending decisions.
Inputs: projectPath.
vibe_reportA
VibeWise: record the implementation report after approved coding: what changed, how it works, why it fits the design, and real verification results.
Inputs: summary (required), projectPath, verification.
vibe_resetA
VibeWise: restart learning from scratch. Call without confirm for a preview token; back up + reset only after the user explicitly confirms, passing the token back.
Inputs: confirm, projectPath.
vibe_startB
VibeWise: activate learning-first mode (creates .vibe-wise/, runs onboarding one question at a time, or resumes a paused/pending state). Call before the first build task.
Inputs: action, projectPath.
vibe_statusA
VibeWise: check the learning gate for this project - active mode, current checkpoint stage, pending decision, and what you must do next. Call this before starting any coding work and whenever unsure whether coding is allowed.
Inputs: projectPath.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools map to distinct lifecycle stages (start, checkpoint, confirm, report, reset), but vibe_status and vibe_read_notes both surface gate/state info, and vibe_pause's 'resume' overlaps with vibe_start's 'resumes a paused/pending state'. Descriptions mostly disambiguate these, so confusion risk is low.
Every tool uses the same vibe_ prefix with a consistent snake_case noun/verb (vibe_status, vibe_start, vibe_checkpoint, vibe_map_update). No camelCase or mixed conventions, so the pattern is fully predictable.
10 tools is well within the ideal 3-15 range and each corresponds to a distinct step of the learning-gate workflow. No tool feels redundant or filler.
The surface covers the full learning lifecycle: activation, onboarding, checkpoints, confirmation, reporting, map maintenance, pause/resume, reset, and state reading. Minor gap: no explicit way to answer/close an onboarding session or query individual notes, but agents can work around these.
Related MCP Connectors
Coordinate coding agents through MCP using existing AI plans, saved work, and independent checks.
The project brain for AI coding agents — memory, decisions, sprints, knowledge base via MCP.
Source control for coding agents: declare an intent, settle overlaps before code, verify each push.
Project management shared by people and AI agents, with persistent project state through MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAdds a human-in-the-loop checkpoint to MCP-capable AI coding agents, enabling them to pause and request user feedback before executing actions.16 npm72MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP-compatible coding tools to start from one portable, local-first identity and knowledge layer containing the user's approved preferences, quality standards, lessons, decisions, and project context. It stores this in local files the user owns and can inspect, edit, or override, with governance over AI-proposed writes and no cloud account required.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP-compatible coding agents to start from one portable, local-first identity and long-term knowledge layer, so preferences, quality bars, lessons, decisions, and project context carry across tools instead of being relearned per session. Everything the AI writes stays in local files the user can inspect, edit, approve, or override.-
- FlicenseNot gradedqualityAmaintenanceEnables a local-first, user-owned AI work identity layer that lets multiple MCP coding tools share approved preferences, quality standards, lessons, decisions, and project context, with local files you can inspect, edit, and override.-