@vibe-assurance/cli 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+# @vibe-assurance/cli
+
+Connect Claude Code to your Vibe Assurance governance platform.
+
+## Installation
+
+```bash
+npm install -g @vibe-assurance/cli
+```
+
+## Quick Start
+
+1. **Login to Vibe Assurance:**
+   ```bash
+   vibe login
+   ```
+   This opens your browser for authentication.
+
+2. **Configure Claude Code:**
+   ```bash
+   vibe setup-claude
+   ```
+   This adds the Vibe Assurance MCP server to your Claude Code configuration.
+
+3. **Restart Claude Code** and start using governance tools!
+
+## Usage
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `vibe login` | Authenticate with Vibe Assurance |
+| `vibe logout` | Clear stored credentials |
+| `vibe mcp-server` | Start the MCP server (used by Claude Code) |
+| `vibe setup-claude` | Configure Claude Code to use Vibe Assurance |
+
+### Available Tools in Claude Code
+
+Once configured, Claude Code has access to these tools:
+
+| Tool | Description |
+|------|-------------|
+| `vibe_get_role` | Get an AI analyst role prompt |
+| `vibe_list_roles` | List available roles |
+| `vibe_get_context` | Get your governance context (CRs, risks, vulns) |
+| `vibe_get_template` | Get a document template |
+| `vibe_list_templates` | List available templates |
+| `vibe_store_artifact` | Store a created document |
+| `vibe_update_artifact` | Update an existing artifact |
+| `vibe_list_artifacts` | List your stored artifacts |
+| `vibe_get_artifact` | Get a specific artifact |
+| `vibe_delete_artifact` | Delete an artifact |
+
+### Example Session
+
+```
+User: Create a change request for adding user authentication
+
+Claude: I'll help you create a change request. Let me get your context first.
+
+[Calls vibe_get_context]
+[Calls vibe_get_role("implementation-planner")]
+[Calls vibe_get_template("change-request")]
+
+Based on your governance context, your next CR ID is CR-2026-001.
+
+[Creates the CR documents...]
+
+Done! Would you like me to store this in Vibe Assurance?
+
+User: Yes
+
+Claude: [Calls vibe_store_artifact(...)]
+
+Your CR-2026-001 has been stored! View it at:
+https://vibeassurance.app/governance/artifacts/CR-2026-001
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VIBE_API_URL` | `https://agent-platform-prod.azurewebsites.net` | API base URL |
+
+For development, you can point to a local instance:
+
+```bash
+VIBE_API_URL=http://localhost:3000 vibe login
+```
+
+### Credential Storage
+
+Credentials are stored securely using:
+- **macOS**: Keychain Access
+- **Windows**: Credential Manager
+- **Linux**: libsecret (if available)
+
+If the system keychain is unavailable, credentials fall back to `~/.vibe/credentials.json` with restricted permissions (600).
+
+## Requirements
+
+- **Node.js 18** or later
+- **Vibe Assurance account**
+- **Claude Code**
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+Run `vibe login` to authenticate. If you see this error during MCP server startup, your session may have expired.
+
+### MCP server not connecting
+
+1. Run `vibe setup-claude` again
+2. Restart Claude Code completely (not just reload)
+3. Check that `vibe` command is in your PATH
+
+### "Port 38274 is already in use"
+
+Another `vibe login` process is running. Wait for it to complete or terminate it.
+
+### Keychain access denied
+
+The CLI will automatically fall back to file-based storage. This is secure but less convenient.
+
+On Linux, install `libsecret` for keychain support:
+```bash
+# Ubuntu/Debian
+sudo apt-get install libsecret-1-dev
+
+# Fedora
+sudo dnf install libsecret-devel
+```
+
+### Debug mode
+
+To see detailed logs:
+```bash
+DEBUG=vibe* vibe mcp-server
+```
+
+## Uninstalling
+
+```bash
+# Remove the CLI
+npm uninstall -g @vibe-assurance/cli
+
+# Clear stored credentials
+vibe logout
+
+# Or manually:
+rm -rf ~/.vibe/
+```
+
+Then remove the MCP configuration from Claude Code:
+1. Open `~/.claude/mcp.json` (or your platform's config location)
+2. Remove the `vibeassurance` entry from `mcpServers`
+3. Restart Claude Code
+
+## Security
+
+- Credentials are stored in the OS keychain when available
+- Tokens are never logged or exposed in console output
+- All API communication uses HTTPS
+- Tokens auto-refresh when expired
+
+## License
+
+MIT
+
+## Related
+
+- [Vibe Assurance](https://vibeassurance.app) - Governance platform
+- [Claude Code](https://claude.ai/code) - AI coding assistant
+- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol

package/bin/vibe.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+// Load .env file if present (for local development)
+const path = require('path');
+require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
+const { program } = require('commander');
+const pkg = require('../package.json');
+
+// Commands
+const login = require('../src/commands/login');
+const logout = require('../src/commands/logout');
+const mcpServer = require('../src/commands/mcp-server');
+const setupClaude = require('../src/commands/setup-claude');
+
+program
+  .name('vibe')
+  .description('Vibe Assurance CLI - Connect Claude Code to your governance platform')
+  .version(pkg.version);
+
+program
+  .command('login')
+  .description('Authenticate with Vibe Assurance')
+  .action(login);
+
+program
+  .command('logout')
+  .description('Clear stored credentials')
+  .action(logout);
+
+program
+  .command('mcp-server')
+  .description('Start the MCP server for Claude Code')
+  .action(mcpServer);
+
+program
+  .command('setup-claude')
+  .description('Configure Claude Code to use the Vibe Assurance MCP server')
+  .action(setupClaude);
+
+program.parse();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vibe-assurance/cli",
+  "version": "1.0.0",
+  "description": "Vibe Assurance CLI - Connect Claude Code to your governance platform",
+  "main": "src/index.js",
+  "bin": {
+    "vibe": "./bin/vibe.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "vibe-assurance",
+    "governance",
+    "mcp",
+    "claude-code",
+    "compliance",
+    "security"
+  ],
+  "author": "Vibe Assurance",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeassurance/cli.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "dotenv": "^16.6.1",
+    "keytar": "^7.9.0",
+    "open": "^8.4.2",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0"
+  }
+}

package/src/api/client.js

@@ -0,0 +1,132 @@
+const axios = require('axios');
+const { getCredentials, storeCredentials, deleteCredentials } = require('../config/credentials');
+
+// Default to production URL, can be overridden via environment variable
+const API_BASE_URL = process.env.VIBE_API_URL || 'https://agent-platform-prod.azurewebsites.net';
+
+/**
+ * Create an authenticated axios instance with token refresh handling
+ * @returns {Promise<import('axios').AxiosInstance>}
+ */
+async function createClient() {
+  const creds = await getCredentials();
+  if (!creds || !creds.accessToken) {
+    throw new Error('Not authenticated. Run: vibe login');
+  }
+
+  const client = axios.create({
+    baseURL: API_BASE_URL,
+    headers: {
+      'Authorization': `Bearer ${creds.accessToken}`,
+      'Content-Type': 'application/json',
+      'User-Agent': 'vibe-cli/1.0.0'
+    },
+    timeout: 30000 // 30 second timeout
+  });
+
+  // Response interceptor for automatic token refresh on 401
+  client.interceptors.response.use(
+    response => response,
+    async error => {
+      const originalRequest = error.config;
+
+      // If 401 and we haven't tried refreshing yet
+      if (error.response?.status === 401 && !originalRequest._retry && creds.refreshToken) {
+        originalRequest._retry = true;
+
+        try {
+          const newTokens = await refreshToken(creds.refreshToken);
+          await storeCredentials(newTokens);
+
+          // Update the failed request with new token
+          originalRequest.headers['Authorization'] = `Bearer ${newTokens.accessToken}`;
+          return client(originalRequest);
+        } catch (refreshError) {
+          // Refresh failed - clear credentials and require re-login
+          await deleteCredentials();
+          throw new Error('Session expired. Please run: vibe login');
+        }
+      }
+
+      // Format error message
+      const errorMessage = error.response?.data?.error ||
+                          error.response?.data?.message ||
+                          error.message ||
+                          'Unknown error';
+      throw new Error(errorMessage);
+    }
+  );
+
+  return client;
+}
+
+/**
+ * Refresh access token using refresh token
+ * @param {string} refreshTokenValue
+ * @returns {Promise<Object>} New token object
+ */
+async function refreshToken(refreshTokenValue) {
+  const response = await axios.post(`${API_BASE_URL}/api/auth/refresh`, {
+    refreshToken: refreshTokenValue
+  });
+
+  return {
+    accessToken: response.data.token || response.data.accessToken,
+    refreshToken: response.data.refreshToken || refreshTokenValue,
+    expiresAt: response.data.expiresAt || new Date(Date.now() + 3600 * 1000).toISOString()
+  };
+}
+
+/**
+ * Make a GET request to the API
+ * @param {string} path - API path (e.g., '/api/mcp/roles')
+ * @returns {Promise<any>} Response data
+ */
+async function get(path) {
+  const client = await createClient();
+  const response = await client.get(path);
+  return response.data;
+}
+
+/**
+ * Make a POST request to the API
+ * @param {string} path - API path
+ * @param {Object} data - Request body
+ * @returns {Promise<any>} Response data
+ */
+async function post(path, data) {
+  const client = await createClient();
+  const response = await client.post(path, data);
+  return response.data;
+}
+
+/**
+ * Make a PUT request to the API
+ * @param {string} path - API path
+ * @param {Object} data - Request body
+ * @returns {Promise<any>} Response data
+ */
+async function put(path, data) {
+  const client = await createClient();
+  const response = await client.put(path, data);
+  return response.data;
+}
+
+/**
+ * Make a DELETE request to the API
+ * @param {string} path - API path
+ * @returns {Promise<any>} Response data
+ */
+async function del(path) {
+  const client = await createClient();
+  const response = await client.delete(path);
+  return response.data;
+}
+
+module.exports = {
+  get,
+  post,
+  put,
+  delete: del,
+  API_BASE_URL
+};

package/src/commands/login.js

@@ -0,0 +1,234 @@
+const open = require('open');
+const http = require('http');
+const { URL } = require('url');
+const chalk = require('chalk');
+const ora = require('ora');
+const { storeCredentials, hasValidCredentials } = require('../config/credentials');
+const { API_BASE_URL } = require('../api/client');
+
+// Local callback server port (chosen to be unlikely to conflict)
+const CALLBACK_PORT = 38274;
+const CALLBACK_URL = `http://localhost:${CALLBACK_PORT}/callback`;
+
+/**
+ * Login command - authenticates user via OAuth flow
+ */
+async function login() {
+  // Check if already logged in
+  if (await hasValidCredentials()) {
+    console.log(chalk.yellow('You are already logged in.'));
+    console.log('Run `vibe logout` to sign out first.');
+    return;
+  }
+
+  const spinner = ora('Opening browser for authentication...').start();
+
+  // Track server for cleanup
+  let server = null;
+
+  // Cleanup function to ensure server is closed
+  const cleanup = () => {
+    if (server) {
+      try {
+        server.close();
+        server = null;
+      } catch (e) {
+        // Ignore close errors
+      }
+    }
+  };
+
+  // Handle process termination signals
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(1);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(1);
+  });
+
+  // Create a promise that will resolve when auth completes or reject on error/timeout
+  const authPromise = new Promise((resolve, reject) => {
+    // Create local server to receive OAuth callback
+    server = http.createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url, `http://localhost:${CALLBACK_PORT}`);
+
+        if (url.pathname === '/callback') {
+          const accessToken = url.searchParams.get('access_token');
+          const refreshToken = url.searchParams.get('refresh_token');
+          const expiresIn = url.searchParams.get('expires_in');
+          const error = url.searchParams.get('error');
+
+          if (error) {
+            // Authentication failed
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(getErrorHtml(error));
+            server.close();
+            reject(new Error(error));
+            return;
+          }
+
+          if (accessToken) {
+            // Calculate expiry time
+            const expiresAt = expiresIn
+              ? new Date(Date.now() + parseInt(expiresIn) * 1000)
+              : new Date(Date.now() + 3600 * 1000); // Default 1 hour
+
+            // Store credentials securely
+            await storeCredentials({
+              accessToken,
+              refreshToken,
+              expiresAt: expiresAt.toISOString()
+            });
+
+            // Send success response to browser
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(getSuccessHtml());
+
+            server.close();
+            resolve();
+          } else {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(getErrorHtml('No access token received'));
+            server.close();
+            reject(new Error('No access token received'));
+          }
+        } else {
+          // Ignore other requests
+          res.writeHead(404);
+          res.end();
+        }
+      } catch (err) {
+        res.writeHead(500);
+        res.end();
+        server.close();
+        reject(err);
+      }
+    });
+
+    // Handle server errors
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`Port ${CALLBACK_PORT} is already in use. Please close any other vibe login attempts.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // Start listening and open browser
+    server.listen(CALLBACK_PORT, async () => {
+      try {
+        const authUrl = `${API_BASE_URL}/api/auth/cli?callback=${encodeURIComponent(CALLBACK_URL)}`;
+        await open(authUrl);
+        spinner.text = 'Waiting for authentication in browser...';
+      } catch (err) {
+        server.close();
+        reject(new Error(`Failed to open browser: ${err.message}`));
+      }
+    });
+
+    // Timeout after 5 minutes
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Authentication timed out after 5 minutes'));
+    }, 5 * 60 * 1000);
+  });
+
+  try {
+    await authPromise;
+    cleanup();
+    spinner.succeed('Successfully authenticated!');
+    console.log(chalk.green('\nYou are now logged in to Vibe Assurance.'));
+    console.log('\nNext steps:');
+    console.log('  1. Run `vibe setup-claude` to configure Claude Code');
+    console.log('  2. Restart Claude Code');
+    console.log('  3. Start using vibe_* tools in your conversations');
+  } catch (err) {
+    cleanup();
+    spinner.fail(`Authentication failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Generate success HTML page
+ * Matches the main app's branding with Tailwind CSS and emerald colors
+ */
+function getSuccessHtml() {
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Login Successful | Vibe Assurance</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script>tailwind.config={darkMode:'class',theme:{extend:{colors:{brand:{500:'#10b981',600:'#059669'}}}}}</script>
+  <script>(function(){var d=document.documentElement;var t=localStorage.getItem('theme');if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches))d.classList.add('dark')})();</script>
+</head>
+<body class="min-h-screen flex flex-col items-center justify-center p-4 bg-zinc-50 dark:bg-zinc-950 transition-colors">
+  <div class="absolute inset-0 pointer-events-none opacity-40 dark:opacity-10 bg-[radial-gradient(#cbd5e1_1px,transparent_1px)] [background-size:16px_16px]"></div>
+
+  <div class="mb-8 text-center relative z-10">
+    <div class="flex items-center justify-center gap-3 text-2xl font-bold text-zinc-900 dark:text-white tracking-tight">
+      <div class="w-10 h-10 bg-emerald-600 rounded-lg flex items-center justify-center text-white text-xl shadow-sm">V</div>
+      Vibe Assurance
+    </div>
+  </div>
+
+  <div class="max-w-md w-full bg-white dark:bg-zinc-900 p-8 rounded-xl shadow-xl border border-zinc-200 dark:border-zinc-800 text-center relative z-10">
+    <div class="w-16 h-16 bg-emerald-100 dark:bg-emerald-900/30 rounded-full flex items-center justify-center mx-auto mb-4">
+      <svg class="w-8 h-8 text-emerald-600 dark:text-emerald-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path>
+      </svg>
+    </div>
+    <h1 class="text-xl font-bold text-zinc-900 dark:text-white mb-2">Login Successful!</h1>
+    <p class="text-zinc-500 dark:text-zinc-400 text-sm">You can close this window and return to your terminal.</p>
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Generate error HTML page
+ * Matches the main app's branding with Tailwind CSS
+ */
+function getErrorHtml(error) {
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Login Failed | Vibe Assurance</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script>tailwind.config={darkMode:'class',theme:{extend:{colors:{brand:{500:'#10b981',600:'#059669'}}}}}</script>
+  <script>(function(){var d=document.documentElement;var t=localStorage.getItem('theme');if(t==='dark'||(!t&&matchMedia('(prefers-color-scheme:dark)').matches))d.classList.add('dark')})();</script>
+</head>
+<body class="min-h-screen flex flex-col items-center justify-center p-4 bg-zinc-50 dark:bg-zinc-950 transition-colors">
+  <div class="absolute inset-0 pointer-events-none opacity-40 dark:opacity-10 bg-[radial-gradient(#cbd5e1_1px,transparent_1px)] [background-size:16px_16px]"></div>
+
+  <div class="mb-8 text-center relative z-10">
+    <div class="flex items-center justify-center gap-3 text-2xl font-bold text-zinc-900 dark:text-white tracking-tight">
+      <div class="w-10 h-10 bg-emerald-600 rounded-lg flex items-center justify-center text-white text-xl shadow-sm">V</div>
+      Vibe Assurance
+    </div>
+  </div>
+
+  <div class="max-w-md w-full bg-white dark:bg-zinc-900 p-8 rounded-xl shadow-xl border border-zinc-200 dark:border-zinc-800 text-center relative z-10">
+    <div class="w-16 h-16 bg-red-100 dark:bg-red-900/30 rounded-full flex items-center justify-center mx-auto mb-4">
+      <svg class="w-8 h-8 text-red-600 dark:text-red-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
+      </svg>
+    </div>
+    <h1 class="text-xl font-bold text-zinc-900 dark:text-white mb-2">Login Failed</h1>
+    <p class="text-red-600 dark:text-red-400 text-sm mb-2">${error}</p>
+    <p class="text-zinc-500 dark:text-zinc-400 text-sm">Please close this window and try again.</p>
+  </div>
+</body>
+</html>`;
+}
+
+module.exports = login;

package/src/commands/logout.js

@@ -0,0 +1,22 @@
+const chalk = require('chalk');
+const { deleteCredentials, hasValidCredentials } = require('../config/credentials');
+
+/**
+ * Logout command - clears stored credentials
+ */
+async function logout() {
+  const wasLoggedIn = await hasValidCredentials();
+
+  // Delete credentials from all storage locations
+  await deleteCredentials();
+
+  if (wasLoggedIn) {
+    console.log(chalk.green('Successfully logged out.'));
+    console.log('\nYour local credentials have been cleared.');
+    console.log('Your data remains safe in your Vibe Assurance account.');
+  } else {
+    console.log(chalk.yellow('You were not logged in.'));
+  }
+}
+
+module.exports = logout;

package/src/commands/mcp-server.js

@@ -0,0 +1,29 @@
+const chalk = require('chalk');
+const { hasValidCredentials } = require('../config/credentials');
+const startServer = require('../mcp/server');
+
+/**
+ * MCP Server command
+ *
+ * Starts the MCP server that Claude Code connects to.
+ * Requires authentication (run `vibe login` first).
+ */
+async function mcpServerCommand() {
+  // Check if user is authenticated
+  if (!(await hasValidCredentials())) {
+    // Use stderr for messages (stdout is for MCP protocol)
+    console.error(chalk.red('Not authenticated.'));
+    console.error('Please run: vibe login');
+    process.exit(1);
+  }
+
+  try {
+    // Start the MCP server
+    await startServer();
+  } catch (error) {
+    console.error(chalk.red('Failed to start MCP server:'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = mcpServerCommand;

package/src/commands/setup-claude.js

@@ -0,0 +1,112 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const chalk = require('chalk');
+
+/**
+ * Possible locations for Claude Code MCP configuration
+ * Ordered by preference (first existing one will be used)
+ */
+const MCP_CONFIG_PATHS = [
+  // Standard location
+  path.join(os.homedir(), '.claude', 'mcp.json'),
+  // macOS Application Support
+  path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'mcp.json'),
+  // Windows AppData
+  path.join(os.homedir(), 'AppData', 'Roaming', 'Claude', 'mcp.json'),
+  // Linux config
+  path.join(os.homedir(), '.config', 'claude', 'mcp.json')
+];
+
+/**
+ * MCP server configuration for Vibe Assurance
+ */
+const VIBE_MCP_CONFIG = {
+  vibeassurance: {
+    command: 'vibe',
+    args: ['mcp-server']
+  }
+};
+
+/**
+ * Setup Claude command
+ *
+ * Configures Claude Code to use the Vibe Assurance MCP server
+ * by adding the vibeassurance entry to mcp.json
+ */
+async function setupClaude() {
+  console.log(chalk.blue('Configuring Claude Code to use Vibe Assurance MCP server...\n'));
+
+  // Find existing config file or determine default path
+  let configPath = null;
+  let existingConfig = {};
+
+  for (const p of MCP_CONFIG_PATHS) {
+    if (fs.existsSync(p)) {
+      configPath = p;
+      try {
+        const content = fs.readFileSync(p, 'utf8');
+        existingConfig = JSON.parse(content);
+        console.log(chalk.gray(`Found existing config at: ${p}`));
+      } catch (err) {
+        console.log(chalk.yellow(`Found config file but couldn't parse it, will overwrite: ${p}`));
+        existingConfig = {};
+      }
+      break;
+    }
+  }
+
+  // If no existing config found, use the default path
+  if (!configPath) {
+    configPath = MCP_CONFIG_PATHS[0];
+    console.log(chalk.gray(`Creating new config at: ${configPath}`));
+  }
+
+  // Check if vibeassurance is already configured
+  if (existingConfig.mcpServers?.vibeassurance) {
+    console.log(chalk.yellow('Vibe Assurance is already configured in Claude Code.'));
+    console.log('Updating configuration...');
+  }
+
+  // Merge configuration
+  const newConfig = {
+    ...existingConfig,
+    mcpServers: {
+      ...(existingConfig.mcpServers || {}),
+      ...VIBE_MCP_CONFIG
+    }
+  };
+
+  // Ensure directory exists
+  const configDir = path.dirname(configPath);
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+    console.log(chalk.gray(`Created directory: ${configDir}`));
+  }
+
+  // Write configuration
+  fs.writeFileSync(configPath, JSON.stringify(newConfig, null, 2));
+
+  // Success output
+  console.log();
+  console.log(chalk.green('Success!') + ' Claude Code has been configured.\n');
+
+  console.log('Configuration written to:');
+  console.log(chalk.gray(`  ${configPath}\n`));
+
+  console.log('The following MCP server was added:');
+  console.log(chalk.gray('  vibeassurance: vibe mcp-server\n'));
+
+  console.log(chalk.blue('Next steps:'));
+  console.log('  1. Restart Claude Code');
+  console.log('  2. The vibe_* tools will be available automatically');
+  console.log('  3. Try asking: "Get my governance context"\n');
+
+  console.log(chalk.gray('Available tools after restart:'));
+  console.log(chalk.gray('  - vibe_get_role     : Get AI analyst role prompts'));
+  console.log(chalk.gray('  - vibe_get_context  : Get CRs, risks, vulnerabilities'));
+  console.log(chalk.gray('  - vibe_store_artifact: Store created documents'));
+  console.log(chalk.gray('  - ...and more\n'));
+}
+
+module.exports = setupClaude;

package/src/config/credentials.js

@@ -0,0 +1,121 @@
+const keytar = require('keytar');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SERVICE_NAME = 'vibe-assurance';
+const ACCOUNT_NAME = 'auth-token';
+const FALLBACK_FILE = path.join(os.homedir(), '.vibe', 'credentials.json');
+
+/**
+ * Store authentication token
+ * Uses OS keychain (preferred) with file fallback
+ * @param {Object} credentials - { accessToken, refreshToken, expiresAt }
+ * @returns {Promise<{method: string}>} Storage method used
+ */
+async function storeCredentials(credentials) {
+  try {
+    await keytar.setPassword(SERVICE_NAME, ACCOUNT_NAME, JSON.stringify(credentials));
+    return { method: 'keychain' };
+  } catch (err) {
+    // Keychain unavailable (common on Linux without libsecret, or in containers)
+    console.warn('Keychain unavailable, using file storage');
+    const dir = path.dirname(FALLBACK_FILE);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(FALLBACK_FILE, JSON.stringify(credentials), { mode: 0o600 });
+    return { method: 'file' };
+  }
+}
+
+/**
+ * Retrieve stored credentials
+ * @returns {Promise<Object|null>} Credentials object or null if not found
+ */
+async function getCredentials() {
+  // Try keychain first
+  try {
+    const stored = await keytar.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+    if (stored) {
+      return JSON.parse(stored);
+    }
+  } catch (err) {
+    // Keychain unavailable, try file fallback
+  }
+
+  // Try file fallback
+  if (fs.existsSync(FALLBACK_FILE)) {
+    try {
+      const content = fs.readFileSync(FALLBACK_FILE, 'utf8');
+      return JSON.parse(content);
+    } catch (err) {
+      // File corrupted, return null
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Delete stored credentials from all storage locations
+ * @returns {Promise<void>}
+ */
+async function deleteCredentials() {
+  // Delete from keychain
+  try {
+    await keytar.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+  } catch (err) {
+    // Ignore keychain errors
+  }
+
+  // Delete file fallback
+  if (fs.existsSync(FALLBACK_FILE)) {
+    fs.unlinkSync(FALLBACK_FILE);
+  }
+
+  // Clean up empty .vibe directory
+  const vibeDir = path.dirname(FALLBACK_FILE);
+  if (fs.existsSync(vibeDir)) {
+    try {
+      const files = fs.readdirSync(vibeDir);
+      if (files.length === 0) {
+        fs.rmdirSync(vibeDir);
+      }
+    } catch (err) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Check if credentials exist and are valid (not expired)
+ * @returns {Promise<boolean>}
+ */
+async function hasValidCredentials() {
+  const creds = await getCredentials();
+  if (!creds || !creds.accessToken) {
+    return false;
+  }
+
+  // Check if token is expired (with 5 minute buffer)
+  if (creds.expiresAt) {
+    const expiresAt = new Date(creds.expiresAt);
+    const now = new Date();
+    const bufferMs = 5 * 60 * 1000; // 5 minutes
+
+    if (expiresAt.getTime() - bufferMs < now.getTime()) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+module.exports = {
+  storeCredentials,
+  getCredentials,
+  deleteCredentials,
+  hasValidCredentials
+};

package/src/mcp/server.js

@@ -0,0 +1,111 @@
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const tools = require('./tools');
+
+/**
+ * Start the MCP server
+ *
+ * The server communicates with Claude Code via stdio transport,
+ * exposing the vibe_* tools for governance operations.
+ */
+async function startServer() {
+  // Create MCP server instance using the low-level API
+  const server = new Server(
+    {
+      name: 'vibe-assurance',
+      version: '1.0.0'
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+
+  // Build tool definitions with enhanced descriptions
+  const toolDefinitions = tools.map(tool => {
+    let description = tool.description;
+
+    // Add parameter info to description for tools with parameters
+    if (tool.inputSchema?.properties && Object.keys(tool.inputSchema.properties).length > 0) {
+      const params = Object.entries(tool.inputSchema.properties)
+        .map(([name, schema]) => `  - ${name}: ${schema.description || schema.type}`)
+        .join('\n');
+      description += `\n\nParameters:\n${params}`;
+      if (tool.inputSchema.required?.length > 0) {
+        description += `\n\nRequired: ${tool.inputSchema.required.join(', ')}`;
+      }
+    }
+
+    return {
+      name: tool.name,
+      description,
+      inputSchema: tool.inputSchema
+    };
+  });
+
+  // Register handler for listing available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: toolDefinitions };
+  });
+
+  // Register handler for tool execution
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    // Find the tool by name
+    const tool = tools.find(t => t.name === name);
+    if (!tool) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: `Unknown tool: ${name}`,
+            availableTools: tools.map(t => t.name)
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    try {
+      // Execute the tool handler with the arguments
+      const result = await tool.handler(args || {});
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    } catch (error) {
+      // Extract meaningful error message
+      const message = error.response?.data?.error ||
+                      error.response?.data?.message ||
+                      error.message ||
+                      'Unknown error occurred';
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: message,
+            tool: name
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+  });
+
+  // Connect via stdio transport (used by Claude Code)
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Log to stderr (stdout is used for MCP communication)
+  console.error('[vibe-assurance] MCP server started');
+  console.error('[vibe-assurance] Available tools:', tools.map(t => t.name).join(', '));
+}
+
+module.exports = startServer;

package/src/mcp/tools.js

@@ -0,0 +1,271 @@
+const api = require('../api/client');
+
+/**
+ * MCP Tool definitions for Vibe Assurance
+ *
+ * These tools are exposed to Claude Code via the MCP protocol,
+ * allowing Claude to interact with the Vibe Assurance governance platform.
+ */
+const tools = [
+  // ============================================================================
+  // PULL TOOLS - Get data from Vibe Assurance
+  // ============================================================================
+
+  {
+    name: 'vibe_get_role',
+    description: 'Get an AI analyst role prompt from Vibe Assurance. Use this to get detailed instructions for roles like implementation-planner, security-auditor, risk-auditor, etc. The role prompt contains the full system prompt and instructions for acting as that role.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        role: {
+          type: 'string',
+          description: 'Role ID (e.g., "implementation-planner", "security-auditor", "risk-auditor", "commit-officer", "test-engineer")'
+        }
+      },
+      required: ['role']
+    },
+    handler: async ({ role }) => {
+      const response = await api.get(`/api/mcp/roles/${role}`);
+      return {
+        role: response.roleId,
+        name: response.name,
+        description: response.description,
+        prompt: response.systemPrompt,
+        referencedTemplates: response.referencedTemplates || [],
+        expectedOutputs: response.expectedOutputs || []
+      };
+    }
+  },
+
+  {
+    name: 'vibe_list_roles',
+    description: 'List all available AI analyst roles in Vibe Assurance. Returns role IDs, names, and descriptions for all governance roles you can use.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async () => {
+      return await api.get('/api/mcp/roles');
+    }
+  },
+
+  {
+    name: 'vibe_get_context',
+    description: 'Get your current governance context including existing CRs, open risks, vulnerabilities, and the next available CR ID. Use this before creating new CRs to ensure proper ID sequencing.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async () => {
+      return await api.get('/api/mcp/context');
+    }
+  },
+
+  {
+    name: 'vibe_get_template',
+    description: 'Get a document template from Vibe Assurance. Templates include placeholders and structure for governance documents like change requests, risk assessments, and security reports.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        template: {
+          type: 'string',
+          description: 'Template ID (e.g., "change-request", "risk-assessment", "security-report", "implementation-plan")'
+        }
+      },
+      required: ['template']
+    },
+    handler: async ({ template }) => {
+      return await api.get(`/api/mcp/templates/${template}`);
+    }
+  },
+
+  {
+    name: 'vibe_list_templates',
+    description: 'List all available document templates. Returns template IDs, names, descriptions, and categories.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async () => {
+      return await api.get('/api/mcp/templates');
+    }
+  },
+
+  // ============================================================================
+  // PUSH TOOLS - Store data to Vibe Assurance
+  // ============================================================================
+
+  {
+    name: 'vibe_store_artifact',
+    description: 'Store a created document (CR, report, risk, vulnerability, etc.) in Vibe Assurance. The artifact will be saved to your account and visible in the web portal.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['CR', 'RISK', 'VULNERABILITY', 'REPORT', 'POLICY'],
+          description: 'Type of artifact'
+        },
+        artifactId: {
+          type: 'string',
+          description: 'Unique ID for this artifact (e.g., "CR-2025-024", "VUL-059", "RISK-001")'
+        },
+        title: {
+          type: 'string',
+          description: 'Title of the artifact'
+        },
+        status: {
+          type: 'string',
+          enum: ['Draft', 'Active', 'Completed', 'Closed'],
+          description: 'Status of the artifact (default: Draft)'
+        },
+        content: {
+          type: 'string',
+          description: 'Main content in markdown format'
+        },
+        files: {
+          type: 'array',
+          description: 'Additional files for this artifact (e.g., implementation-plan.md, rollback-plan.md for CRs)',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Filename' },
+              content: { type: 'string', description: 'File content' }
+            },
+            required: ['name', 'content']
+          }
+        },
+        metadata: {
+          type: 'object',
+          description: 'Additional metadata (e.g., severity, priority, category)',
+          additionalProperties: true
+        }
+      },
+      required: ['type', 'artifactId', 'title', 'content']
+    },
+    handler: async (params) => {
+      return await api.post('/api/mcp/artifacts', params);
+    }
+  },
+
+  {
+    name: 'vibe_update_artifact',
+    description: 'Update an existing artifact. You can update the status, content, title, or metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: {
+          type: 'string',
+          description: 'The artifact ID to update (e.g., "CR-2025-024")'
+        },
+        status: {
+          type: 'string',
+          enum: ['Draft', 'Active', 'Completed', 'Closed'],
+          description: 'New status'
+        },
+        content: {
+          type: 'string',
+          description: 'Updated content'
+        },
+        title: {
+          type: 'string',
+          description: 'Updated title'
+        },
+        files: {
+          type: 'array',
+          description: 'Updated files array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              content: { type: 'string' }
+            }
+          }
+        },
+        metadata: {
+          type: 'object',
+          description: 'Updated metadata'
+        }
+      },
+      required: ['artifactId']
+    },
+    handler: async ({ artifactId, ...updates }) => {
+      return await api.put(`/api/mcp/artifacts/${artifactId}`, updates);
+    }
+  },
+
+  {
+    name: 'vibe_list_artifacts',
+    description: 'List your stored artifacts with optional filters. Use this to see what governance documents you have stored.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['CR', 'RISK', 'VULNERABILITY', 'REPORT', 'POLICY'],
+          description: 'Filter by artifact type'
+        },
+        status: {
+          type: 'string',
+          enum: ['Draft', 'Active', 'Completed', 'Closed'],
+          description: 'Filter by status'
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 50, max: 100)'
+        }
+      }
+    },
+    handler: async (params = {}) => {
+      const query = new URLSearchParams();
+      if (params.type) query.set('type', params.type);
+      if (params.status) query.set('status', params.status);
+      if (params.limit) query.set('limit', String(Math.min(params.limit, 100)));
+
+      const queryString = query.toString();
+      const path = queryString ? `/api/mcp/artifacts?${queryString}` : '/api/mcp/artifacts';
+      return await api.get(path);
+    }
+  },
+
+  {
+    name: 'vibe_get_artifact',
+    description: 'Get a specific artifact by ID. Returns the full content including any additional files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: {
+          type: 'string',
+          description: 'The artifact ID to retrieve (e.g., "CR-2025-024")'
+        }
+      },
+      required: ['artifactId']
+    },
+    handler: async ({ artifactId }) => {
+      return await api.get(`/api/mcp/artifacts/${artifactId}`);
+    }
+  },
+
+  {
+    name: 'vibe_delete_artifact',
+    description: 'Delete an artifact by ID. This is permanent and cannot be undone.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifactId: {
+          type: 'string',
+          description: 'The artifact ID to delete (e.g., "CR-2025-024")'
+        }
+      },
+      required: ['artifactId']
+    },
+    handler: async ({ artifactId }) => {
+      return await api.delete(`/api/mcp/artifacts/${artifactId}`);
+    }
+  }
+];
+
+module.exports = tools;