viberag 0.1.7 → 0.3.0

package/README.md

@@ -115,14 +115,10 @@ The wizard can auto-configure project-level configs and merge into global config
 
 ### Manual Setup Instructions
 
-The following sections describe manual MCP server setup configurations for various editors, and agent CLI commands if applicable.
-
-#### Project-Specific Configs
-
-These editors use per-project config files that VibeRAG can auto-create.
+The following sections describe manual MCP server setup configurations for various editors and agents.
 
 <details>
-<summary><strong>Claude Code</strong> — <code>.mcp.json</code></summary>
+<summary><strong>Claude Code</strong></summary>
 
 **CLI Command:**
 
@@ -130,7 +126,7 @@ These editors use per-project config files that VibeRAG can auto-create.
 claude mcp add viberag -- npx viberag-mcp
 ```
 
-**Manual Setup:**
+**Global Config:** `~/.claude.json`
 
 ```json
 {
@@ -143,16 +139,7 @@ claude mcp add viberag -- npx viberag-mcp
 }
 ```
 
-**Verify:** Run `/mcp` in Claude Code, look for "viberag: connected"
-
-[Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)
-
-</details>
-
-<details>
-<summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code></summary>
-
-**Manual Setup:**
+**Project Config:** `.mcp.json`
 
 ```json
 {
@@ -165,16 +152,16 @@ claude mcp add viberag -- npx viberag-mcp
 }
 ```
 
-**Verify:** Settings → Cursor Settings → MCP, verify "viberag" shows with toggle enabled
+**Verify:** Run `/mcp` in Claude Code, look for "viberag: connected"
 
-[Documentation](https://docs.cursor.com/context/model-context-protocol)
+[Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)
 
 </details>
 
 <details>
-<summary><strong>Roo Code</strong> — <code>.roo/mcp.json</code></summary>
+<summary><strong>Cursor</strong></summary>
 
-**Manual Setup:**
+**Global Config:** `~/.cursor/mcp.json`
 
 ```json
 {
@@ -187,20 +174,11 @@ claude mcp add viberag -- npx viberag-mcp
 }
 ```
 
-**Verify:** Click MCP icon in Roo Code pane header, verify "viberag" appears in server list
-
-[Documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
-
-</details>
-
-<details>
-<summary><strong>VS Code Copilot</strong> — <code>.vscode/mcp.json</code></summary>
-
-**Manual Setup:**
+**Project Config:** `.cursor/mcp.json`
 
 ```json
 {
-	"servers": {
+	"mcpServers": {
 		"viberag": {
 			"command": "npx",
 			"args": ["viberag-mcp"]
@@ -209,22 +187,14 @@ claude mcp add viberag -- npx viberag-mcp
 }
 ```
 
-> **Note:** VS Code uses `"servers"` instead of `"mcpServers"`
-
-**Verify:** Cmd/Ctrl+Shift+P → "MCP: List Servers", verify "viberag" appears
+**Verify:** Settings → Cursor Settings → MCP, verify "viberag" shows with toggle enabled
 
-[Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+[Documentation](https://docs.cursor.com/context/model-context-protocol)
 
 </details>
 
----
-
-### Global Configs
-
-These editors use global config files. VibeRAG can merge into existing configs.
-
 <details>
-<summary><strong>Gemini CLI</strong> — <code>~/.gemini/settings.json</code></summary>
+<summary><strong>Gemini CLI</strong></summary>
 
 **CLI Command:**
 
@@ -232,7 +202,20 @@ These editors use global config files. VibeRAG can merge into existing configs.
 gemini mcp add viberag -- npx viberag-mcp
 ```
 
-**Manual Setup:** Add to your existing settings.json:
+**Global Config:** `~/.gemini/settings.json`
+
+```json
+{
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
+}
+```
+
+**Project Config:** `.gemini/settings.json`
 
 ```json
 {
@@ -252,22 +235,41 @@ gemini mcp add viberag -- npx viberag-mcp
 </details>
 
 <details>
-<summary><strong>OpenAI Codex</strong> — <code>~/.codex/config.toml</code></summary>
+<summary><strong>JetBrains IDEs</strong></summary>
+
+**UI Setup:**
+
+1. Open Settings → Tools → AI Assistant → MCP
+2. Click "Add Server"
+3. Set name: `viberag`
+4. Set command: `npx`
+5. Set args: `viberag-mcp`
+
+**Verify:** Settings → Tools → AI Assistant → MCP, verify "viberag" shows green in Status column
+
+[Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html)
+
+</details>
+
+<details>
+<summary><strong>OpenAI Codex</strong></summary>
 
 **CLI Command:**
 
 ```bash
-codex mcp add viberag -- npx viberag-mcp
+codex mcp add viberag -- npx -y viberag-mcp
 ```
 
-**Manual Setup:** Add to your config.toml:
+**Global Config:** `~/.codex/config.toml`
 
 ```toml
 [mcp_servers.viberag]
 command = "npx"
-args = ["viberag-mcp"]
+args = ["-y", "viberag-mcp"]
 ```
 
+> **Note:** The `-y` flag is required for npx to auto-confirm package installation
+
 **Verify:** Run `/mcp` in Codex TUI, look for "viberag" in server list
 
 [Documentation](https://codex.openai.com/docs/tools/mcp-servers)
@@ -275,11 +277,22 @@ args = ["viberag-mcp"]
 </details>
 
 <details>
-<summary><strong>OpenCode</strong> — <code>~/.config/opencode/opencode.json</code></summary>
+<summary><strong>OpenCode</strong></summary>
+
+**Global Config:** `~/.config/opencode/opencode.json` (Linux/macOS) or `%APPDATA%/opencode/opencode.json` (Windows)
 
-**Config:** `~/.config/opencode/opencode.json` (Linux/macOS) or `%APPDATA%/opencode/opencode.json` (Windows)
+```json
+{
+	"mcp": {
+		"viberag": {
+			"type": "local",
+			"command": ["npx", "-y", "viberag-mcp"]
+		}
+	}
+}
+```
 
-**Manual Setup:** Add to your existing opencode.json:
+**Project Config:** `opencode.json`
 
 ```json
 {
@@ -301,9 +314,11 @@ args = ["viberag-mcp"]
 </details>
 
 <details>
-<summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+<summary><strong>Roo Code</strong></summary>
+
+**Global Config:** UI only — Click MCP icon in Roo Code pane header → Edit Global MCP
 
-**Manual Setup:** Merge into your existing mcp_config.json:
+**Project Config:** `.roo/mcp.json`
 
 ```json
 {
@@ -316,22 +331,35 @@ args = ["viberag-mcp"]
 }
 ```
 
-**Verify:** Click Plugins icon in Cascade panel, verify "viberag" shows in plugin list
+**Verify:** Click MCP icon in Roo Code pane header, verify "viberag" appears in server list
 
-[Documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
+[Documentation](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
 
 </details>
 
 <details>
-<summary><strong>Zed</strong> — <code>~/Library/Application Support/Zed/settings.json</code></summary>
+<summary><strong>VS Code Copilot</strong></summary>
 
-**Config:** `~/Library/Application Support/Zed/settings.json` (macOS) or `~/.config/zed/settings.json` (Linux)
+**Global Config:** Add to User `settings.json` under `mcp.servers`:
 
-**Manual Setup:** Merge into your existing settings.json:
+```json
+{
+	"mcp": {
+		"servers": {
+			"viberag": {
+				"command": "npx",
+				"args": ["viberag-mcp"]
+			}
+		}
+	}
+}
+```
+
+**Project Config:** `.vscode/mcp.json`
 
 ```json
 {
-	"context_servers": {
+	"servers": {
 		"viberag": {
 			"command": "npx",
 			"args": ["viberag-mcp"]
@@ -340,37 +368,83 @@ args = ["viberag-mcp"]
 }
 ```
 
-> **Note:** Zed uses `"context_servers"` instead of `"mcpServers"`
+> **Note:** VS Code uses `"servers"` instead of `"mcpServers"`
 
-**Verify:** Open Agent Panel settings, verify "viberag" shows green indicator
+> **Required:** Enable Agent Mode in VS Code settings:
+>
+> - Settings → search `chat.agent.enabled` → check the box, OR
+> - Add `"chat.agent.enabled": true` to your User `settings.json`
 
-[Documentation](https://zed.dev/docs/ai/mcp)
+**Verify:** Cmd/Ctrl+Shift+P → "MCP: List Servers", verify "viberag" appears
+
+[Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
 
 </details>
 
----
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+**Global Config:** `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+	"mcpServers": {
+		"viberag": {
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
+}
+```
+
+**Verify:** Click Plugins icon in Cascade panel, verify "viberag" shows in plugin list
 
-### UI-Based Setup
+[Documentation](https://docs.windsurf.com/windsurf/cascade/mcp)
+
+</details>
 
 <details>
-<summary><strong>JetBrains IDEs</strong> — Settings UI</summary>
+<summary><strong>Zed</strong></summary>
 
-**Manual Setup:**
+**Global Config:** `~/.config/zed/settings.json`
 
-1. Open Settings → Tools → AI Assistant → MCP
-2. Click "Add Server"
-3. Set name: `viberag`
-4. Set command: `npx`
-5. Set args: `viberag-mcp`
+```json
+{
+	"context_servers": {
+		"viberag": {
+			"source": "custom",
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
+}
+```
 
-**Verify:** Settings → Tools → AI Assistant → MCP, verify "viberag" shows green in Status column
+**Project Config:** `.zed/settings.json`
 
-[Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html)
+```json
+{
+	"context_servers": {
+		"viberag": {
+			"source": "custom",
+			"command": "npx",
+			"args": ["viberag-mcp"]
+		}
+	}
+}
+```
+
+> **Note:** Zed uses `"context_servers"` instead of `"mcpServers"` and requires `"source": "custom"` for non-extension servers
+
+**Verify:** Open Agent Panel settings, verify "viberag" shows green indicator
+
+[Documentation](https://zed.dev/docs/ai/mcp)
 
 </details>
 
+---
 
-### Exposed MCP Tools
+## Exposed MCP Tools
 
 | Tool                       | Description                                          |
 | -------------------------- | ---------------------------------------------------- |
@@ -472,7 +546,6 @@ Check the file watcher for auto-indexing.
 - Pending changes count
 - Last update timestamp
 
-
 ## CLI Commands
 
 VibeRAG includes a CLI for easy execution of initialization, indexing, setup, and other things you may want to manually control outside of agent use.
@@ -507,7 +580,7 @@ Choose your embedding provider during `/init`:
 | Provider | Model                  | Dims | Cost      | Get API Key                                             |
 | -------- | ---------------------- | ---- | --------- | ------------------------------------------------------- |
 | Gemini   | gemini-embedding-001   | 1536 | Free tier | [Google AI Studio](https://aistudio.google.com)         |
-| Mistral  | codestral-embed        | 1024 | $0.10/1M  | [Mistral Console](https://console.mistral.ai/api-keys/) |
+| Mistral  | codestral-embed        | 1536 | $0.10/1M  | [Mistral Console](https://console.mistral.ai/api-keys/) |
 | OpenAI   | text-embedding-3-small | 1536 | $0.02/1M  | [OpenAI Platform](https://platform.openai.com/api-keys) |
 
 - **Gemini** - Free tier available, great for getting started

package/dist/cli/commands/mcp-setup.d.ts

@@ -3,6 +3,9 @@
  *
  * Functions for generating, writing, and merging MCP configurations
  * for various AI coding tools.
+ *
+ * Note: Zed and VS Code use JSONC (JSON with Comments) for their config files.
+ * We strip comments before parsing to handle this.
  */
 import { type EditorConfig, type EditorId } from '../data/mcp-editors.js';
 /**
@@ -19,11 +22,21 @@ export interface McpSetupResult {
  * Generate the viberag MCP server configuration object.
  */
 export declare function generateViberagConfig(): object;
+/**
+ * Generate Zed-specific viberag MCP server configuration.
+ * Zed requires: source="custom" for non-extension MCP servers.
+ */
+export declare function generateZedViberagConfig(): object;
 /**
  * Generate OpenCode-specific viberag MCP server configuration.
  * OpenCode requires: type="local", command as array, no args key.
  */
 export declare function generateOpenCodeViberagConfig(): object;
+/**
+ * Generate Roo Code-specific viberag MCP server configuration.
+ * Roo Code supports alwaysAllow for auto-approving common operations.
+ */
+export declare function generateRooCodeViberagConfig(): object;
 /**
  * Generate complete MCP config for an editor.
  */
@@ -32,12 +45,33 @@ export declare function generateMcpConfig(editor: EditorConfig): object;
  * Generate TOML config for OpenAI Codex.
  */
 export declare function generateTomlConfig(): string;
+/**
+ * Read existing TOML config file.
+ * Returns the raw content string, or null if file doesn't exist or can't be read.
+ */
+export declare function readTomlConfig(configPath: string): Promise<string | null>;
+/**
+ * Check if viberag is already configured in a TOML config.
+ * Looks for [mcp_servers.viberag] section.
+ */
+export declare function hasViberagTomlConfig(content: string): boolean;
+/**
+ * Merge viberag config into existing TOML content.
+ * Appends the viberag section if not present.
+ */
+export declare function mergeTomlConfig(existing: string): string;
+/**
+ * Remove viberag from a TOML config.
+ * Returns the modified content, or null if nothing to remove.
+ */
+export declare function removeViberagFromTomlConfig(content: string): string | null;
 /**
  * Check if a config file exists.
  */
 export declare function configExists(configPath: string): Promise<boolean>;
 /**
  * Read existing config file as JSON.
+ * Handles JSONC (JSON with Comments) format used by Zed and VS Code.
  */
 export declare function readJsonConfig(configPath: string): Promise<object | null>;
 /**
@@ -51,23 +85,31 @@ export declare function hasViberagConfig(config: object, editor: EditorConfig):
 /**
  * Write MCP config to file, creating directories as needed.
  */
-export declare function writeMcpConfig(editor: EditorConfig, projectRoot: string): Promise<McpSetupResult>;
+export declare function writeMcpConfig(editor: EditorConfig, scope: 'global' | 'project', projectRoot: string): Promise<McpSetupResult>;
 /**
  * Generate manual setup instructions for an editor.
  */
-export declare function getManualInstructions(editor: EditorConfig, projectRoot: string): string;
+export declare function getManualInstructions(editor: EditorConfig, scope: 'global' | 'project', projectRoot: string): string;
 /**
  * Get a diff preview of the merge operation.
  */
-export declare function getMergeDiff(editor: EditorConfig, projectRoot: string): Promise<{
+export declare function getMergeDiff(editor: EditorConfig, scope: 'global' | 'project', projectRoot: string): Promise<{
     before: string;
     after: string;
     configPath: string;
 } | null>;
 /**
- * Check if viberag is already configured for an editor.
+ * Check if viberag is already configured for an editor at a specific scope.
  */
-export declare function isAlreadyConfigured(editor: EditorConfig, projectRoot: string): Promise<boolean>;
+export declare function isAlreadyConfigured(editor: EditorConfig, scope: 'global' | 'project', projectRoot: string): Promise<boolean>;
+/**
+ * Check if viberag is configured at any scope for an editor.
+ * Returns info about which scopes are configured.
+ */
+export declare function getConfiguredScopes(editor: EditorConfig, projectRoot: string): Promise<{
+    global: boolean;
+    project: boolean;
+}>;
 /**
  * Remove viberag from an existing config object.
  * Returns the modified config, or null if nothing to remove.
@@ -87,14 +129,21 @@ export interface McpRemovalResult {
  * Remove viberag from an editor's MCP config.
  * Always keeps the config file, even if it becomes empty (no other servers).
  */
-export declare function removeViberagConfig(editor: EditorConfig, projectRoot: string): Promise<McpRemovalResult>;
+export declare function removeViberagConfig(editor: EditorConfig, scope: 'global' | 'project', projectRoot: string): Promise<McpRemovalResult>;
+/**
+ * Info about a configured editor and its scope.
+ */
+export interface ConfiguredEditorInfo {
+    editor: EditorConfig;
+    scope: 'global' | 'project';
+}
 /**
  * Find all editors that have viberag configured.
- * Returns both project-scope and global-scope editors.
+ * Returns both project-scope and global-scope configurations.
  */
 export declare function findConfiguredEditors(projectRoot: string): Promise<{
-    projectScope: EditorConfig[];
-    globalScope: EditorConfig[];
+    projectScope: ConfiguredEditorInfo[];
+    globalScope: ConfiguredEditorInfo[];
 }>;
 /**
  * Add an entry to .gitignore if not already present.