@vibecodetown/mcp-server 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeCoding Team
+
+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,269 @@
+# @vibecode/mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@vibecode/mcp-server.svg)](https://www.npmjs.com/package/@vibecode/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-140%20passing-brightgreen.svg)](#testing)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+**Vibe PM** - AI Project Manager for Non-Technical Founders
+
+MCP (Model Context Protocol) server that transforms AI coding assistants into project managers who protect your codebase from chaos.
+
+## Features
+
+- **7 PM-focused tools** (`vibe_pm.*`) for structured project management
+- **Natural language interface** - no CLI commands to learn
+- **Automatic context tracking** - no run_id management
+- **PM-friendly output** - GO/FIX/BLOCK instead of technical jargon
+- **Self-healing bootstrap** - automatic engine binary download
+
+## Installation
+
+### One-line Install
+
+```bash
+curl -fsSL https://vibecode.town/install.sh | sh
+```
+
+### Manual Install
+
+```bash
+npm install -g @vibecode/mcp-server
+```
+
+### Add to Claude Code
+
+```bash
+claude mcp add vibecode npx @vibecode/mcp-server
+```
+
+### Add to Cursor
+
+Copy `AGENTS.md` to `.cursorrules` in your project root.
+
+## Quick Start
+
+Just talk to your AI assistant naturally:
+
+```
+You: "나 당근마켓 같은 거 만들고 싶어. 시작해줘."
+
+Vibe PM: "네, 대표님. 중고거래 앱 접수했습니다.
+         시작하기 전에 하나만 결재해 주세요.
+         속도가 중요한가요, 퀄리티가 중요한가요?"
+
+You: "속도가 중요해."
+
+Vibe PM: "알겠습니다. MVP 모드로 작업 지시서를 뽑았습니다.
+         이제 제가 알아서 코드를 짜겠습니다..."
+```
+
+## Tools (vibe_pm.* - Recommended)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `vibe_pm.briefing` | Start or resume project | User says "시작해줘" or describes idea |
+| `vibe_pm.get_decision` | Fetch approval items | Before any implementation |
+| `vibe_pm.submit_decision` | Submit approval | After user chooses A/B/C |
+| `vibe_pm.create_work_order` | Generate work order | After decisions are made |
+| `vibe_pm.inspect_code` | Review implementation | After coding is complete |
+| `vibe_pm.status` | Check project status | User asks "상태", "어디까지?" |
+| `vibe_pm.repair_plan` | Generate fix request | When inspect returns FIX/BLOCK |
+
+## Workflow
+
+```
+briefing → get_decision → submit_decision → create_work_order → implement → inspect_code
+```
+
+1. **Briefing**: AI receives your idea and structures it
+2. **Decision**: You approve scope/approach (A/B/C choices)
+3. **Work Order**: AI gets clear implementation guidelines
+4. **Implementation**: AI writes code following the work order
+5. **Inspection**: AI validates the implementation
+
+## Review Results
+
+| Result | Meaning | Action |
+|--------|---------|--------|
+| **GO** | All good | Proceed to next task |
+| **FIX** | Minor issue | AI fixes automatically |
+| **BLOCK** | Major risk | Review and fix required |
+
+## One-click Bootstrap
+
+On first tool call, the server automatically:
+1. Downloads pinned engine binaries from GitHub Releases
+2. Verifies SHA256 checksums
+3. Caches them locally
+4. Executes tools using cached paths (no PATH dependency)
+
+### Engines (auto-installed)
+
+| Engine | Purpose |
+|--------|---------|
+| spec-high | Decision validation & bridge generation |
+| vibecoding-helper | Orchestrator CLI |
+| clinic | Code verification |
+
+### Cache Location
+
+| Platform | Path |
+|----------|------|
+| Linux | `~/.cache/vibecode/engines/` |
+| macOS | `~/Library/Caches/vibecode/engines/` |
+| Windows | `%LOCALAPPDATA%\vibecode\engines\` |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/vibecode/vibecoding-helper
+cd vibecoding-helper/adapters/mcp-ts
+npm install
+
+# Build
+npm run build
+
+# Run in dev mode (watch)
+npm run dev
+
+# Start server
+npm start
+
+# Type check
+npm run typecheck
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- tests/cache.test.ts
+```
+
+### Test Coverage
+
+| Module | Coverage |
+|--------|----------|
+| `src/cache/` | 100% |
+| `src/security/` | ~93% |
+| `src/tools/vibe_pm/` | ~85% |
+
+### Test Structure
+
+```
+tests/
+├── cache.test.ts              # TieredCache unit tests
+├── security.test.ts           # Input validation & path policy
+├── tools.test.ts              # Tool handler tests
+├── performance.test.ts        # Benchmark tests
+└── e2e/
+    ├── engine-integration.test.ts   # Engine + cache flow
+    └── security-scenarios.test.ts   # Attack scenario tests
+```
+
+## Claude Desktop Config
+
+```json
+{
+  "mcpServers": {
+    "vibecode": {
+      "command": "npx",
+      "args": ["@vibecode/mcp-server"]
+    }
+  }
+}
+```
+
+Or with local build:
+
+```json
+{
+  "mcpServers": {
+    "vibecode": {
+      "command": "node",
+      "args": ["<ABSOLUTE_PATH>/adapters/mcp-ts/build/index.js"]
+    }
+  }
+}
+```
+
+## Health Check
+
+Call `vibecode.doctor` to check engine status:
+
+```json
+{
+  "status": "OK",
+  "engines": {
+    "spec-high": { "version": "1.0.0", "path": "~/.cache/vibecode/..." },
+    "vibecoding-helper": { "version": "1.0.0", "path": "..." },
+    "clinic": { "version": "2.3.0", "path": "..." }
+  }
+}
+```
+
+## Legacy Tools (Deprecated)
+
+For backward compatibility, legacy tool names are supported:
+
+| Legacy | New |
+|--------|-----|
+| `vibecode.one_loop` | `vibe_pm.inspect_code` |
+| `vibecode.show_ask_queue` | `vibe_pm.get_decision` |
+| `vibecode.answer` | `vibe_pm.submit_decision` |
+| `vibecode.show_decisions` | `vibe_pm.status` |
+| `spec_high.clinic_bridge` | `vibe_pm.create_work_order` |
+| `spec_high.validate` | `vibe_pm.inspect_code` |
+| `clinic.verify` | `vibe_pm.inspect_code` |
+
+## Error Handling
+
+Installation failures return structured errors:
+
+```json
+{
+  "status": "ERROR",
+  "reason": "sha_mismatch",
+  "message": "Downloaded file doesn't match expected checksum"
+}
+```
+
+Common reasons:
+- `sha_mismatch`: Checksum verification failed
+- `download_failed`: Network error
+- `bin_not_found_after_extract`: Archive extraction issue
+- `lock_timeout`: Another installation in progress
+
+## Architecture
+
+```
+User (natural language)
+    ↓
+AI Agent (Claude/Cursor/Codex)
+    ↓ AGENTS.md rules
+MCP Server (@vibecode/mcp-server)
+    ↓ vibe_pm.* tools
+Bootstrap Layer
+    ↓ auto-download if missing
+Engine Binaries (cached)
+    ↓
+SSOT Files (runs/<run_id>/...)
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://vibecode.town/docs)
+- [GitHub](https://github.com/vibecode/vibecoding-helper)
+- [Issues](https://github.com/vibecode/vibecoding-helper/issues)

package/build/auth/gate.js

@@ -0,0 +1,225 @@
+const AUTH_PROXY_URL = process.env.VIBE_AUTH_PROXY_URL || 'https://auth.vibe-pm.dev';
+export class AuthGate {
+    cache;
+    verifier;
+    constructor(cache, verifier) {
+        this.cache = cache;
+        this.verifier = verifier;
+    }
+    /**
+     * Check if a feature is allowed for the current user
+     */
+    async check(feature) {
+        // Get cached token
+        const cached = await this.cache.get();
+        if (!cached) {
+            return { allowed: false, reason: 'no_token' };
+        }
+        // Verify token is still valid
+        const result = await this.verifier.verify(cached.token);
+        if (!result.success) {
+            // Clear invalid token
+            await this.cache.clear();
+            if (result.error === 'expired_token') {
+                return { allowed: false, reason: 'expired_token' };
+            }
+            return { allowed: false, reason: 'invalid_token' };
+        }
+        const { entitlements, policy } = result.token;
+        // Check if feature is enabled
+        if (!entitlements[feature]) {
+            return {
+                allowed: false,
+                reason: 'feature_disabled',
+                entitlements,
+                policy,
+            };
+        }
+        return {
+            allowed: true,
+            entitlements,
+            policy,
+        };
+    }
+    /**
+     * Check multiple features at once
+     */
+    async checkAll(features) {
+        const results = new Map();
+        // Get token once for all checks
+        const cached = await this.cache.get();
+        if (!cached) {
+            for (const feature of features) {
+                results.set(feature, { allowed: false, reason: 'no_token' });
+            }
+            return results;
+        }
+        const verifyResult = await this.verifier.verify(cached.token);
+        if (!verifyResult.success) {
+            await this.cache.clear();
+            const reason = verifyResult.error === 'expired_token' ? 'expired_token' : 'invalid_token';
+            for (const feature of features) {
+                results.set(feature, { allowed: false, reason });
+            }
+            return results;
+        }
+        const { entitlements, policy } = verifyResult.token;
+        for (const feature of features) {
+            if (entitlements[feature]) {
+                results.set(feature, { allowed: true, entitlements, policy });
+            }
+            else {
+                results.set(feature, { allowed: false, reason: 'feature_disabled', entitlements, policy });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get current entitlements (if token is valid)
+     */
+    async getEntitlements() {
+        const cached = await this.cache.get();
+        if (!cached) {
+            return null;
+        }
+        const result = await this.verifier.verify(cached.token);
+        if (!result.success || !result.token) {
+            return null;
+        }
+        return {
+            entitlements: result.token.entitlements,
+            policy: result.token.policy,
+        };
+    }
+    /**
+     * Exchange a license key for an access token
+     */
+    async exchangeToken(licenseKey, appVersion) {
+        try {
+            const response = await fetch(`${AUTH_PROXY_URL}/v1/auth/exchange`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    client_type: 'mcp_local',
+                    license_key: licenseKey,
+                    app_version: appVersion,
+                }),
+            });
+            const data = (await response.json());
+            if (!response.ok) {
+                return {
+                    success: false,
+                    error: data.error || 'exchange_failed',
+                };
+            }
+            if (typeof data.access_token !== 'string' || !data.access_token.trim()) {
+                return {
+                    success: false,
+                    error: 'missing_access_token',
+                };
+            }
+            // Cache the token
+            const accessToken = data.access_token;
+            const verifyResult = await this.verifier.verify(accessToken);
+            if (!verifyResult.success || !verifyResult.token) {
+                return {
+                    success: false,
+                    error: 'invalid_response_token',
+                };
+            }
+            await this.cache.set({
+                token: accessToken,
+                expiresAt: verifyResult.token.expiresAt,
+                entitlements: verifyResult.token.entitlements,
+                policy: verifyResult.token.policy,
+                subjectId: verifyResult.token.subjectId,
+                cachedAt: Math.floor(Date.now() / 1000),
+            });
+            return {
+                success: true,
+                entitlements: verifyResult.token.entitlements,
+                policy: verifyResult.token.policy,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: 'network_error',
+            };
+        }
+    }
+    /**
+     * Refresh the token if needed
+     * Returns true if refresh was successful or not needed
+     */
+    async refreshIfNeeded(appVersion) {
+        const cached = await this.cache.get();
+        if (!cached) {
+            return false; // No token to refresh
+        }
+        // Check if refresh is needed (within 5 minutes of expiry)
+        if (!this.cache.needsRefresh(cached, 300)) {
+            return true; // No refresh needed
+        }
+        // Respect explicit offline mode
+        if ((process.env.VIBECODE_OFFLINE || '').trim() === '1') {
+            return false;
+        }
+        try {
+            const response = await fetch(`${AUTH_PROXY_URL}/v1/auth/refresh`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${cached.token}`,
+                },
+                body: JSON.stringify({
+                    client_type: 'mcp_local',
+                    app_version: appVersion,
+                }),
+            });
+            const data = (await response.json());
+            if (!response.ok) {
+                // Clear cached token on hard auth failure
+                await this.cache.clear();
+                return false;
+            }
+            if (typeof data.access_token !== 'string' || !data.access_token.trim()) {
+                return false;
+            }
+            const accessToken = data.access_token;
+            const verifyResult = await this.verifier.verify(accessToken);
+            if (!verifyResult.success || !verifyResult.token) {
+                return false;
+            }
+            await this.cache.set({
+                token: accessToken,
+                expiresAt: verifyResult.token.expiresAt,
+                entitlements: verifyResult.token.entitlements,
+                policy: verifyResult.token.policy,
+                subjectId: verifyResult.token.subjectId,
+                cachedAt: Math.floor(Date.now() / 1000),
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if user is authenticated (has valid token)
+     */
+    async isAuthenticated() {
+        const cached = await this.cache.get();
+        if (!cached) {
+            return false;
+        }
+        const result = await this.verifier.verify(cached.token);
+        return result.success;
+    }
+    /**
+     * Log out (clear cached token)
+     */
+    async logout() {
+        await this.cache.clear();
+    }
+}

package/build/auth/index.js

@@ -0,0 +1,55 @@
+/**
+ * Auth module for MCP client
+ *
+ * Provides:
+ * - Token caching and persistence
+ * - Offline JWT verification
+ * - Feature gating based on entitlements
+ */
+export { TokenCache } from './token_cache.js';
+export { TokenVerifier } from './token_verifier.js';
+export { AuthGate } from './gate.js';
+export { PUBLIC_KEY } from './public_key.js';
+// Re-export convenience functions
+import { TokenCache } from './token_cache.js';
+import { TokenVerifier } from './token_verifier.js';
+import { AuthGate } from './gate.js';
+let _cache = null;
+let _verifier = null;
+let _gate = null;
+/**
+ * Get singleton TokenCache instance
+ */
+export function getTokenCache() {
+    if (!_cache) {
+        _cache = new TokenCache();
+    }
+    return _cache;
+}
+/**
+ * Get singleton TokenVerifier instance
+ */
+export function getTokenVerifier() {
+    if (!_verifier) {
+        _verifier = new TokenVerifier();
+    }
+    return _verifier;
+}
+/**
+ * Get singleton AuthGate instance
+ */
+export function getAuthGate() {
+    if (!_gate) {
+        _gate = new AuthGate(getTokenCache(), getTokenVerifier());
+    }
+    return _gate;
+}
+/**
+ * Check if a feature is available for the current user
+ * Convenience function that uses the singleton gate
+ */
+export async function checkFeature(feature) {
+    const gate = getAuthGate();
+    const result = await gate.check(feature);
+    return result.allowed;
+}

package/build/auth/public_key.js

@@ -0,0 +1,27 @@
+/**
+ * Auth Proxy public key for JWT verification
+ *
+ * This key is used to verify JWT tokens offline.
+ * It is safe to embed in the client as it can only verify, not sign.
+ *
+ * Algorithm: ES256 (ECDSA P-256)
+ *
+ * To update this key:
+ * 1. Generate new key pair on the auth proxy server
+ * 2. Copy the public key here
+ * 3. Release new client version
+ */
+const ENV_PUBLIC_KEY = (process.env.VIBECODE_AUTH_PUBLIC_KEY || process.env.VIBE_AUTH_PUBLIC_KEY || "").trim();
+export const PUBLIC_KEY = ENV_PUBLIC_KEY ||
+    `-----BEGIN PUBLIC KEY-----
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE
+REPLACE_WITH_YOUR_PRODUCTION_PUBLIC_KEY
+-----END PUBLIC KEY-----`;
+/**
+ * JWT issuer for verification
+ */
+export const JWT_ISSUER = (process.env.VIBECODE_AUTH_JWT_ISSUER || process.env.VIBE_AUTH_JWT_ISSUER || 'vibe-auth').trim();
+/**
+ * JWT audience for verification
+ */
+export const JWT_AUDIENCE = (process.env.VIBECODE_AUTH_JWT_AUDIENCE || process.env.VIBE_AUTH_JWT_AUDIENCE || 'vibe-client').trim();