knowzcode 0.4.0 → 0.6.0

package/commands/connect-mcp.md

@@ -1,549 +1,574 @@
----
-description: Configure KnowzCode MCP server for vector-powered code search and context
----
-
-# KnowzCode MCP Server Connection
-
-You are the **KnowzCode MCP Connection Agent**. Your task is to configure the KnowzCode MCP (Model Context Protocol) server to enable vector-based code search and context retrieval.
-
-## Command Syntax
-
-```bash
-/kc:connect-mcp <api-key> [--endpoint <url>] [--scope <local|project|user>] [--dev] [--configure-vaults]
-```
-
-**Note:** If you don't have an API key yet, run `/kc:register` to create an account and get one automatically.
-Registration also auto-configures your vault - no manual setup needed!
-
-**Parameters:**
-- `<api-key>` - Required. Your KnowzCode API key (or omit for interactive prompt)
-- `--endpoint <url>` - Optional. Custom MCP endpoint (overrides environment default)
-- `--scope <scope>` - Optional. Configuration scope: local (default), project, or user
-- `--dev` - Optional. Use development environment instead of production
-- `--configure-vaults` - Optional. Force vault configuration prompts (even if already configured)
-
-**Environments:**
-| Environment | Endpoint | When to Use |
-|:------------|:---------|:------------|
-| **Production** (default) | `https://mcp.knowz.io/mcp` | Normal usage |
-| **Development** | `https://mcp.dev.knowz.io/mcp` | Testing new features |
-
-**Examples:**
-```bash
-# Basic usage (production - default)
-/kc:connect-mcp kz_live_abc123...
-
-# Interactive mode (production)
-/kc:connect-mcp
-
-# Development environment
-/kc:connect-mcp kz_test_abc123... --dev
-
-# Self-hosted endpoint
-/kc:connect-mcp kz_live_abc123... --endpoint https://your-domain.com/mcp
-
-# Project-wide configuration (production)
-/kc:connect-mcp kz_live_team456... --scope project
-
-# Development with project scope
-/kc:connect-mcp kz_test_team456... --dev --scope project
-```
-
-## What This Enables
-
-Once connected, you get access to these tools:
-
-- **`search_knowledge`** - Vector similarity search across vaults
-- **`ask_question`** - Q&A with optional research mode
-- **`create_knowledge`** - Save learnings to vault (used by finalization)
-- **`update_knowledge`** - Update existing knowledge items
-- **`find_entities`** - Find people, locations, or events in your knowledge
-
-### Default Vault Types
-
-KnowzCode ships with three default vault types:
-
-| Vault Type | Purpose | Query Examples |
-|------------|---------|----------------|
-| **Code** | Implementation patterns, workarounds, performance | "Find auth middleware", "JWT validation" |
-| **Ecosystem** | Conventions, decisions, integrations, business rules | "Error handling conventions", "Why Redis?" |
-| **Finalizations** | WorkGroup completion summaries, outcome records | "What happened in WG-feat-auth?" |
-
-Types are user-configurable labels — users can add custom types freely.
-
-## Your Task
-
-Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
-
-### Steps to Execute
-
-1. **Parse command arguments**
-   - Extract API key from first positional argument (if provided)
-   - Parse `--dev` flag to determine environment
-   - Parse `--endpoint <url>` flag (overrides environment default if provided)
-   - Default endpoint: `https://mcp.knowz.io/mcp` (production)
-   - With `--dev` flag: `https://mcp.dev.knowz.io/mcp` (development)
-   - Parse `--scope <scope>` flag (default: `local`)
-   - Parse `--configure-vaults` flag (forces vault prompts)
-   - Store parsed values for use in configuration
-
-2. **Check for existing configuration**
-   - Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
-   - If already configured, ask if user wants to reconfigure
-   - If yes, run `CLAUDECODE= claude mcp remove knowz` first
-
-3. **Prompt for API key (if not provided)**
-   - If no API key in arguments, prompt user interactively:
-     ```
-     Enter your KnowzCode API key
-     (Get one at https://knowz.io/api-keys)
-     ```
-   - Validate format (should start with `kz_live_` or `kz_test_`)
-   - Never display the full API key back to user
-
-4. **Confirm scope (if not provided)**
-   - If `--scope` not provided, ask user which scope to use:
-     - **local** (default): Only this project, private to you
-     - **project**: Shared with team via `.mcp.json` (committed to git)
-     - **user**: Available across all your projects
-
-   Present as options to user if not specified in command.
-
-5. **Validate endpoint URL (if custom)**
-   - If custom endpoint provided via `--endpoint`, validate it's a valid URL
-   - Ensure it starts with `https://` (or `http://` for local dev)
-   - Show which endpoint will be used
-
-6. **Configure Vault IDs (Conditional with Discovery)**
-
-   First, check if vaults are already configured in `knowzcode/knowzcode_vaults.md`:
-   - Read the file and check for connected vaults section
-
-   **If vaults already configured AND `--configure-vaults` NOT set:**
-   - Skip vault prompts entirely
-   - Display:
-     ```
-     Vaults already configured (from previous setup or /kc:register):
-       {List vaults from knowzcode_vaults.md}
-
-     To reconfigure vaults, run: /kc:connect-mcp --configure-vaults
-     ```
-
-   **If vaults NOT configured OR `--configure-vaults` IS set:**
-
-   **Step 6a: Fetch available vaults using list_vaults()**
-
-   Call the `list_vaults` MCP tool to discover available vaults:
-   ```
-   list_vaults(includeStats: true)
-   ```
-
-   If successful, display available vaults:
-   ```
-   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   ◆ VAULT DISCOVERY
-   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-   Fetching your available vaults...
-
-   Available Vaults:
-   ┌────┬──────────────────────┬──────────────────┬───────────┐
-   │ #  │ Name                 │ Type             │ Documents │
-   ├────┼──────────────────────┼──────────────────┼───────────┤
-   │ 1  │ KnowzCode            │ ecosystem        │ 42        │
-   │ 2  │ my-project-code      │ code             │ 1,234     │
-   │ 3  │ team-wiki            │ ecosystem        │ 89        │
-   └────┴──────────────────────┴──────────────────┴───────────┘
-   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   ```
-
-   If `list_vaults` fails or returns empty:
-   - Fall back to manual vault ID entry (legacy behavior)
-   - Prompt:
-     ```
-     Could not fetch vaults automatically.
-
-     Enter vault IDs manually:
-
-     Ecosystem Vault ID (required for /kc:learn):
-       • Get from: https://knowz.io/vaults
-
-     Code Vault ID (optional):
-       • Leave blank to use grep/glob for code search
-     ```
-
-   **Step 6b: Interactive vault selection**
-
-   For each discovered vault, ask if user wants to connect it:
-
-   ```
-   Would you like to connect "KnowzCode" (research)?
-   ```
-   Use AskUserQuestion with options: [Yes] [No]
-
-   **If "Yes":**
-   - Prompt for description:
-     ```
-     Describe what this vault contains (for intelligent routing):
-
-     Tips for good descriptions:
-     • Be specific about content type
-     • Include example queries that should route here
-     • Mention key topics covered
-
-     Examples:
-     • "Team learnings, conventions, architectural decisions. Use for 'why did we choose X?' questions."
-     • "Source code for the main API. Use for 'where is X defined?' questions."
-     ```
-
-   - Collect description via AskUserQuestion (free text input)
-
-   **Step 6c: Loop for additional vaults**
-
-   After each vault selection:
-   ```
-   Would you like to connect another vault?
-   ```
-   Options: [Yes] [No]
-
-   - If "Yes" and more vaults available: Continue selection loop
-   - If "No" or no more vaults: Exit loop
-
-   **Step 6d: Write vault configuration**
-
-   Write selected vaults to `knowzcode/knowzcode_vaults.md`:
-
-   ```markdown
-   # KnowzCode Vault Configuration
-
-   Multi-vault routing configuration for intelligent vault selection.
-
-   ---
-
-   ## Connected Vaults
-
-   ### {vault_id_1}
-   - **Name**: {vault_name}
-   - **ID**: {vault_id}
-   - **Type**: {code | ecosystem | finalizations}
-   - **Description**: {user_provided_description}
-
-   ### {vault_id_2}
-   - **Name**: {vault_name}
-   - **ID**: {vault_id}
-   - **Type**: {code | ecosystem | finalizations}
-   - **Description**: {user_provided_description}
-
-   ---
-
-   ## Vault Routing Rules
-
-   - **Code questions** (implementations, files, structure) → {first code vault ID}
-   - **Convention questions** (patterns, decisions, best practices) → {first ecosystem vault ID}
-   - **Completion records** → {first finalizations vault ID}
-   - **Learning capture** → {default ecosystem vault ID}
-   ```
-
-   **Also update `knowzcode/mcp_config.md`** to reflect primary vault (for backwards compatibility):
-   - Set Ecosystem Vault ID to first ecosystem vault selected
-   - Set Code Vault ID to first code vault selected (or "not configured")
-
-   **Step 6d.5: Detect uncreated default vaults**
-
-   After writing vault configuration, check `knowzcode/knowzcode_vaults.md` for entries with empty **ID** fields:
-
-   1. Parse all vault entries in the Connected Vaults section
-   2. Find entries where the **ID** field is empty (null GUID — indicates "not yet created on server")
-   3. If uncreated entries found:
-      ```
-      Found {N} default vault(s) not yet created: {names}. Create them now?
-      ```
-      Use AskUserQuestion with options: [Yes, create them] [No, skip for now]
-   4. If user confirms: for each uncreated entry, call MCP tool to create the vault on the server. Update the entry's **ID** field with the server-returned vault ID. Update the H3 heading from `(not created)` to the vault ID.
-   5. If user declines: proceed normally — vaults can be created later via `/kc:register` or `/kc:connect-mcp --configure-vaults`
-
-   **Step 6e: Show vault configuration summary**
-
-   ```
-   Vault configuration saved to knowzcode/knowzcode_vaults.md
-
-   Connected Vaults:
-     • KnowzCode (ecosystem) - "Team learnings and conventions"
-     • my-code (code) - "Source code for API project"
-
-   Routing:
-     • Code questions → my-code
-     • Convention questions → KnowzCode
-     • Completion records → Finalizations
-     • Learning capture → KnowzCode
-
-   You can edit knowzcode/knowzcode_vaults.md to update descriptions or routing rules.
-   ```
-
-   **Step 6f: Update CLAUDE.md with vault targeting guidance**
-
-   Ensure agents always know to pass `vaultId` by adding a reference section to the project's CLAUDE.md:
-
-   1. Read the project's `CLAUDE.md`
-   2. Search for an existing `### Vault Targeting` or `### Knowz MCP` section
-   3. **If found:** Replace the existing section with the updated content below
-   4. **If NOT found:** Append the section after the `# KnowzCode Integration` block (or at the end if not found)
-   5. Insert a vault targeting reference section that points to the central config:
-
-   ```markdown
-   ### Vault Targeting (MCP Writes)
-   **Always pass `vaultId`** when calling `create_knowledge` or `update_knowledge`.
-   Omitting it saves to the tenant default vault — NOT the project vault.
-
-   Vault IDs and routing rules: `knowzcode/knowzcode_vaults.md`
-   If vault IDs are already in context from a previous read, do not re-read the file.
-   For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
-   ```
-
-   6. Confirm: `"Updated CLAUDE.md with vault targeting guidance (vault IDs managed in knowzcode/knowzcode_vaults.md)."`
-
-   **Idempotent:** Replaces existing `### Vault Targeting` section rather than duplicating.
-
-7. **Add MCP server using CLI**
-   ```bash
-   claude mcp add --transport http \
-     --scope <chosen-scope> \
-     knowz \
-     <endpoint-url> \
-     --header "Authorization: Bearer <api-key>" \
-     --header "X-Project-Path: $(pwd)"
-   ```
-
-8. **Verify configuration**
-   - Run: `CLAUDECODE= claude mcp get knowz`
-   - Confirm server appears in the list
-   - Check for any error messages
-
-9. **Update mcp_config.md**
-   - Update `knowzcode/mcp_config.md` with connection details:
-     - Set `Connected: Yes`
-     - Set `Endpoint: <endpoint-url>`
-     - Set `Last Verified: <timestamp>`
-     - Set Ecosystem Vault ID and name (if provided or already set)
-     - Set Code Vault ID and name (if provided)
-     - Set `Auto-configured: No` (to distinguish from /kc:register setup)
-
-10. **Test connection (optional)**
-    - If verification succeeds, optionally test with a simple tool call
-    - This validates the API key is valid
-
-11. **Report success**
-    ```
-    ✅ KnowzCode MCP server configured!
-
-    Scope: <chosen-scope>
-    Endpoint: <endpoint-url>
-
-    Vaults Configured:
-      • Code Vault: <vault-name or "Not configured">
-      • Ecosystem Vault: <vault-name or "Not configured">
-      • Finalizations Vault: <vault-name or "Not configured">
-
-    🔄 Please restart Claude Code to activate these features:
-       • search_knowledge - Vector search across vaults
-       • ask_question - AI Q&A with research mode
-       • create_knowledge - Save learnings (via finalization)
-       • update_knowledge - Update existing items
-       • find_entities - Find people/locations/events
-
-    After restart, these tools will be available to all KnowzCode agents.
-
-    Check connection status: /kc:status
-    ```
-
-## Configuration Details
-
-### Scope Comparison
-
-**Local (default)**:
-- ✅ Private to you
-- ✅ Project-specific
-- ❌ Not shared with team
-- **Use when:** Personal API key, working solo
-
-**Project**:
-- ✅ Shared with team
-- ✅ Committed to git via `.mcp.json`
-- ⚠️ API key visible to team
-- **Use when:** Team API key, collaborative project
-
-**User**:
-- ✅ Available everywhere
-- ✅ Set once, works across projects
-- ❌ Not project-specific
-- **Use when:** Single API key for all your work
-
-### Security Considerations
-
-- **Never log API keys** in command output
-- **Mask displayed keys**: Show only first/last 4 chars (e.g., `kz_live_abc...xyz`)
-- **Warn about project scope**: API key will be in git-committed `.mcp.json`
-- **Suggest environment variables**: For team setups, recommend storing in CI/CD secrets
-
-### MCP Server Details
-
-The KnowzCode MCP server (default: `https://mcp.knowz.io/mcp`):
-- **Protocol:** HTTP transport with JSON-RPC
-- **Authentication:** Bearer token in `Authorization` header
-- **Project Context:** `X-Project-Path` header identifies project
-- **Rate Limiting:** Standard API rate limits apply
-- **Caching:** Responses cached for performance
-
-### Environment Endpoints
-
-**Available Environments:**
-
-| Environment | Endpoint | Flag | Use Case |
-|:------------|:---------|:-----|:---------|
-| **Production** (default) | `https://mcp.knowz.io/mcp` | (none) | Normal usage |
-| **Development** | `https://mcp.dev.knowz.io/mcp` | `--dev` | Testing new features |
-
-**Switching Environments:**
-```bash
-# Production (default)
-/kc:connect-mcp kz_live_abc123...
-
-# Development
-/kc:connect-mcp kz_test_abc123... --dev
-
-# Local development server
-/kc:connect-mcp kz_test_local... --endpoint http://localhost:3000/mcp
-
-# Self-hosted enterprise
-/kc:connect-mcp kz_live_abc123... --endpoint https://knowzcode.mycompany.com/mcp
-```
-
-## Error Handling
-
-### API Key Invalid
-```
-❌ Authentication failed
-The API key appears to be invalid or expired.
-
-Get a new key at: https://knowz.io/api-keys
-Then run: /kc:connect-mcp <new-key>
-```
-
-### Already Configured
-```
-⚠️ KnowzCode MCP server is already configured
-Current scope: <scope>
-
-Do you want to reconfigure?
-```
-
-### Claude CLI Not Available
-```
-❌ Cannot configure MCP server
-The 'claude' CLI command is not available.
-
-This is unusual - Claude Code should provide this command.
-Please restart Claude Code or report this issue.
-```
-
-### Network/Connection Error
-```
-❌ Cannot reach KnowzCode API
-Failed to connect to {endpoint}
-
-Check your internet connection and try again.
-If using --dev environment, verify the dev server is running.
-```
-
-## Advanced Usage
-
-### Switching Scopes
-To change from local to project scope:
-```bash
-# Remove existing (or the command will prompt to reconfigure)
-CLAUDECODE= claude mcp remove knowz
-
-# Re-add with new scope
-/kc:connect-mcp <api-key> --scope project
-```
-
-### Switching Endpoints
-To switch between environments or self-hosted:
-```bash
-# Switch to development
-/kc:connect-mcp <api-key> --dev
-
-# Switch back to production (default)
-/kc:connect-mcp <api-key>
-
-# Switch to self-hosted
-/kc:connect-mcp <api-key> --endpoint https://knowzcode.mycompany.com/mcp
-```
-
-## Integration with KnowzCode Agents
-
-Once configured, agents automatically detect and use MCP tools with dual vault support:
-
-**analyst**:
-- Uses `search_knowledge` with **code vault** to find related code
-- Uses `search_knowledge` with **ecosystem vault** to find past decisions
-- Uses `ask_question` with **ecosystem vault** for architectural context
-
-**architect**:
-- Uses `search_knowledge` with **code vault** for implementation examples
-- Uses `ask_question` with **ecosystem vault** for conventions
-
-**builder**:
-- Uses `search_knowledge` with **code vault** for similar patterns
-- Uses `search_knowledge` with **ecosystem vault** for best practices
-
-**reviewer**:
-- Uses `search_knowledge` with **ecosystem vault** for standards
-- Uses `search_knowledge` with **code vault** for precedent checks
-
-**closer**:
-- Uses `search_knowledge` with **ecosystem vault** to check for duplicate learnings
-- Uses `create_knowledge` to save new learnings to **ecosystem vault**
-
-**All agents**:
-- Automatically leverage MCP tools when available
-- Gracefully degrade if MCP server unavailable
-
-## Next Steps
-
-After configuration:
-1. **Restart Claude Code** (required to activate MCP server)
-2. **Verify connection**: `/kc:status`
-3. **Start building**: `/kc:work "your feature"`
-4. **Watch agents use MCP tools** automatically during workflow
-
-## Tool Control & Filtering
-
-Tools are controlled **server-side** at the MCP endpoint:
-
-**Server controls which tools to expose based on:**
-- API key tier (free/pro/enterprise)
-- Project type (monorepo, microservices, etc.)
-- Feature flags per user
-- Runtime conditions
-
-**Agents automatically discover and use available tools** - no client-side filtering needed.
-
-See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete server implementation guide.
-
-## Related Commands
-
-- `/kc:register` - Register for KnowzCode and configure MCP automatically
-- `/kc:status` - Check MCP connection status and available tools
-- `/kc:init` - Initialize KnowzCode in project
-- `/kc:work` - Start feature development (uses MCP tools)
-
-## Implementation Notes
-
-**For Server Developers:**
-- See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete specification
-- Required methods: `initialize`, `tools/list`, `tools/call`
-- Authentication via `Authorization: Bearer` header
-- Project context via `X-Project-Path` header
-
-Execute this configuration now.
+---
+description: Configure KnowzCode MCP server for vector-powered code search and context
+---
+
+# KnowzCode MCP Server Connection
+
+You are the **KnowzCode MCP Connection Agent**. Your task is to configure the KnowzCode MCP (Model Context Protocol) server to enable vector-based code search and context retrieval.
+
+## Command Syntax
+
+```bash
+/kc:connect-mcp <api-key> [--endpoint <url>] [--scope <local|project|user>] [--dev] [--configure-vaults]
+```
+
+**Note:** If you don't have an API key yet, run `/kc:register` to create an account and get one automatically.
+Registration also auto-configures your vault - no manual setup needed!
+
+**Parameters:**
+- `<api-key>` - Required. Your KnowzCode API key (or omit for interactive prompt)
+- `--endpoint <url>` - Optional. Custom MCP endpoint (overrides environment default)
+- `--scope <scope>` - Optional. Configuration scope: local (default), project, or user
+- `--dev` - Optional. Use development environment instead of production
+- `--configure-vaults` - Optional. Force vault configuration prompts (even if already configured)
+
+**Environments:**
+| Environment | Endpoint | When to Use |
+|:------------|:---------|:------------|
+| **Production** (default) | `https://mcp.knowz.io/mcp` | Normal usage |
+| **Development** | `https://mcp.dev.knowz.io/mcp` | Testing new features |
+
+**Examples:**
+```bash
+# Basic usage (production - default)
+/kc:connect-mcp kz_live_abc123...
+
+# Interactive mode (production)
+/kc:connect-mcp
+
+# Development environment
+/kc:connect-mcp kz_test_abc123... --dev
+
+# Self-hosted endpoint
+/kc:connect-mcp kz_live_abc123... --endpoint https://your-domain.com/mcp
+
+# Project-wide configuration (production)
+/kc:connect-mcp kz_live_team456... --scope project
+
+# Development with project scope
+/kc:connect-mcp kz_test_team456... --dev --scope project
+```
+
+## What This Enables
+
+Once connected, you get access to these tools:
+
+- **`search_knowledge`** - Vector similarity search across vaults
+- **`ask_question`** - Q&A with optional research mode
+- **`create_knowledge`** - Save learnings to vault (used by finalization)
+- **`update_knowledge`** - Update existing knowledge items
+- **`find_entities`** - Find people, locations, or events in your knowledge
+
+### Default Vault Types
+
+KnowzCode ships with three default vault types:
+
+| Vault Type | Purpose | Query Examples |
+|------------|---------|----------------|
+| **Code** | Implementation patterns, workarounds, performance | "Find auth middleware", "JWT validation" |
+| **Ecosystem** | Conventions, decisions, integrations, business rules | "Error handling conventions", "Why Redis?" |
+| **Finalizations** | WorkGroup completion summaries, outcome records | "What happened in WG-feat-auth?" |
+
+Types are user-configurable labels — users can add custom types freely.
+
+## Your Task
+
+Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
+
+### Steps to Execute
+
+1. **Parse command arguments**
+   - Extract API key from first positional argument (if provided)
+   - Parse `--dev` flag to determine environment
+   - Parse `--endpoint <url>` flag (overrides environment default if provided)
+   - Default endpoint: `https://mcp.knowz.io/mcp` (production)
+   - With `--dev` flag: `https://mcp.dev.knowz.io/mcp` (development)
+   - Parse `--scope <scope>` flag (default: `local`)
+   - Parse `--configure-vaults` flag (forces vault prompts)
+   - Store parsed values for use in configuration
+
+1.5. **Smart Config Discovery (if no API key in arguments)**
+
+   Before prompting for an API key, check known config sources:
+
+   a. **Environment variable**: Check `KNOWZ_API_KEY`
+      - If set: use as the API key, display "Using API key from KNOWZ_API_KEY (ending ...{last4})"
+
+   b. **Project config**: Read `knowzcode/mcp_config.md`
+      - If `Connected: Yes` and endpoint set: pre-populate endpoint for Step 5
+      - If `API Key (last 4)` set: note for confirmation prompt
+
+   c. **Vault config**: Read `knowzcode/knowzcode_vaults.md`
+      - If vaults have non-empty IDs: note for Step 6 (skip vault prompts unless `--configure-vaults`)
+
+   d. **Cross-platform config files** (check for API key in other platforms):
+      - `.gemini/settings.json` → `mcpServers.knowz.headers.Authorization`
+      - `~/.gemini/settings.json` → same
+      - `.vscode/mcp.json` → `servers.knowz.headers`
+      - If found: extract Bearer token, offer to reuse:
+        "Found existing API key (ending ...{last4}) in {source}. Use this key? [Yes/No]"
+
+   If a key was discovered, skip Step 3 (interactive API key prompt).
+   If vaults were discovered, skip vault prompts in Step 6.
+
+2. **Check for existing configuration**
+   - Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
+   - If already configured, ask if user wants to reconfigure
+   - If yes, run `CLAUDECODE= claude mcp remove knowz` first
+
+3. **Prompt for API key (if not provided)**
+   - If no API key in arguments, prompt user interactively:
+     ```
+     Enter your KnowzCode API key
+     (Get one at https://knowz.io/api-keys)
+     ```
+   - Validate format (should start with `kz_live_` or `kz_test_`)
+   - Never display the full API key back to user
+
+4. **Confirm scope (if not provided)**
+   - If `--scope` not provided, ask user which scope to use:
+     - **local** (default): Only this project, private to you
+     - **project**: Shared with team via `.mcp.json` (committed to git)
+     - **user**: Available across all your projects
+
+   Present as options to user if not specified in command.
+
+5. **Validate endpoint URL (if custom)**
+   - If custom endpoint provided via `--endpoint`, validate it's a valid URL
+   - Ensure it starts with `https://` (or `http://` for local dev)
+   - Show which endpoint will be used
+
+6. **Configure Vault IDs (Conditional with Discovery)**
+
+   First, check if vaults are already configured in `knowzcode/knowzcode_vaults.md`:
+   - Read the file and check for connected vaults section
+
+   **If vaults already configured AND `--configure-vaults` NOT set:**
+   - Skip vault prompts entirely
+   - Display:
+     ```
+     Vaults already configured (from previous setup or /kc:register):
+       {List vaults from knowzcode_vaults.md}
+
+     To reconfigure vaults, run: /kc:connect-mcp --configure-vaults
+     ```
+
+   **If vaults NOT configured OR `--configure-vaults` IS set:**
+
+   **Step 6a: Fetch available vaults using list_vaults()**
+
+   Call the `list_vaults` MCP tool to discover available vaults:
+   ```
+   list_vaults(includeStats: true)
+   ```
+
+   If successful, display available vaults:
+   ```
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ◆ VAULT DISCOVERY
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Fetching your available vaults...
+
+   Available Vaults:
+   ┌────┬──────────────────────┬──────────────────┬───────────┐
+   │ #  │ Name                 │ Type             │ Documents │
+   ├────┼──────────────────────┼──────────────────┼───────────┤
+   │ 1  │ KnowzCode            │ ecosystem        │ 42        │
+   │ 2  │ my-project-code      │ code             │ 1,234     │
+   │ 3  │ team-wiki            │ ecosystem        │ 89        │
+   └────┴──────────────────────┴──────────────────┴───────────┘
+   ◆━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+   If `list_vaults` fails or returns empty:
+   - Fall back to manual vault ID entry (legacy behavior)
+   - Prompt:
+     ```
+     Could not fetch vaults automatically.
+
+     Enter vault IDs manually:
+
+     Ecosystem Vault ID (required for /kc:learn):
+       • Get from: https://knowz.io/vaults
+
+     Code Vault ID (optional):
+       • Leave blank to use grep/glob for code search
+     ```
+
+   **Step 6b: Interactive vault selection**
+
+   For each discovered vault, ask if user wants to connect it:
+
+   ```
+   Would you like to connect "KnowzCode" (research)?
+   ```
+   Use AskUserQuestion with options: [Yes] [No]
+
+   **If "Yes":**
+   - Prompt for description:
+     ```
+     Describe what this vault contains (for intelligent routing):
+
+     Tips for good descriptions:
+     • Be specific about content type
+     • Include example queries that should route here
+     • Mention key topics covered
+
+     Examples:
+     • "Team learnings, conventions, architectural decisions. Use for 'why did we choose X?' questions."
+     • "Source code for the main API. Use for 'where is X defined?' questions."
+     ```
+
+   - Collect description via AskUserQuestion (free text input)
+
+   **Step 6c: Loop for additional vaults**
+
+   After each vault selection:
+   ```
+   Would you like to connect another vault?
+   ```
+   Options: [Yes] [No]
+
+   - If "Yes" and more vaults available: Continue selection loop
+   - If "No" or no more vaults: Exit loop
+
+   **Step 6d: Write vault configuration**
+
+   Write selected vaults to `knowzcode/knowzcode_vaults.md`:
+
+   ```markdown
+   # KnowzCode Vault Configuration
+
+   Multi-vault routing configuration for intelligent vault selection.
+
+   ---
+
+   ## Connected Vaults
+
+   ### {vault_id_1}
+   - **Name**: {vault_name}
+   - **ID**: {vault_id}
+   - **Type**: {code | ecosystem | finalizations}
+   - **Description**: {user_provided_description}
+
+   ### {vault_id_2}
+   - **Name**: {vault_name}
+   - **ID**: {vault_id}
+   - **Type**: {code | ecosystem | finalizations}
+   - **Description**: {user_provided_description}
+
+   ---
+
+   ## Vault Routing Rules
+
+   - **Code questions** (implementations, files, structure) → {first code vault ID}
+   - **Convention questions** (patterns, decisions, best practices) → {first ecosystem vault ID}
+   - **Completion records** → {first finalizations vault ID}
+   - **Learning capture** → {default ecosystem vault ID}
+   ```
+
+   **Also update `knowzcode/mcp_config.md`** to reflect primary vault (for backwards compatibility):
+   - Set Ecosystem Vault ID to first ecosystem vault selected
+   - Set Code Vault ID to first code vault selected (or "not configured")
+
+   **Step 6d.5: Detect uncreated default vaults**
+
+   After writing vault configuration, check `knowzcode/knowzcode_vaults.md` for entries with empty **ID** fields:
+
+   1. Parse all vault entries in the Connected Vaults section
+   2. Find entries where the **ID** field is empty (null GUID — indicates "not yet created on server")
+   3. If uncreated entries found:
+      ```
+      Found {N} default vault(s) not yet created: {names}. Create them now?
+      ```
+      Use AskUserQuestion with options: [Yes, create them] [No, skip for now]
+   4. If user confirms: for each uncreated entry, call MCP tool to create the vault on the server. Update the entry's **ID** field with the server-returned vault ID. Update the H3 heading from `(not created)` to the vault ID.
+   5. If user declines: proceed normally — vaults can be created later via `/kc:register` or `/kc:connect-mcp --configure-vaults`
+
+   **Step 6e: Show vault configuration summary**
+
+   ```
+   Vault configuration saved to knowzcode/knowzcode_vaults.md
+
+   Connected Vaults:
+     • KnowzCode (ecosystem) - "Team learnings and conventions"
+     • my-code (code) - "Source code for API project"
+
+   Routing:
+     • Code questions → my-code
+     • Convention questions → KnowzCode
+     • Completion records → Finalizations
+     • Learning capture → KnowzCode
+
+   You can edit knowzcode/knowzcode_vaults.md to update descriptions or routing rules.
+   ```
+
+   **Step 6f: Update CLAUDE.md with vault targeting guidance**
+
+   Ensure agents always know to pass `vaultId` by adding a reference section to the project's CLAUDE.md:
+
+   1. Read the project's `CLAUDE.md`
+   2. Search for an existing `### Vault Targeting` or `### Knowz MCP` section
+   3. **If found:** Replace the existing section with the updated content below
+   4. **If NOT found:** Append the section after the `# KnowzCode Integration` block (or at the end if not found)
+   5. Insert a vault targeting reference section that points to the central config:
+
+   ```markdown
+   ### Vault Targeting (MCP Writes)
+   **Always pass `vaultId`** when calling `create_knowledge` or `update_knowledge`.
+   Omitting it saves to the tenant default vault — NOT the project vault.
+
+   Vault IDs and routing rules: `knowzcode/knowzcode_vaults.md`
+   If vault IDs are already in context from a previous read, do not re-read the file.
+   For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+   ```
+
+   6. Confirm: `"Updated CLAUDE.md with vault targeting guidance (vault IDs managed in knowzcode/knowzcode_vaults.md)."`
+
+   **Idempotent:** Replaces existing `### Vault Targeting` section rather than duplicating.
+
+7. **Add MCP server using CLI**
+   ```bash
+   claude mcp add --transport http \
+     --scope <chosen-scope> \
+     knowz \
+     <endpoint-url> \
+     --header "Authorization: Bearer <api-key>" \
+     --header "X-Project-Path: $(pwd)"
+   ```
+
+8. **Verify configuration**
+   - Run: `CLAUDECODE= claude mcp get knowz`
+   - Confirm server appears in the list
+   - Check for any error messages
+
+9. **Update mcp_config.md**
+   - Update `knowzcode/mcp_config.md` with connection details:
+     - Set `Connected: Yes`
+     - Set `Endpoint: <endpoint-url>`
+     - Set `Last Verified: <timestamp>`
+     - Set `API Key (last 4): <last 4 characters of the API key>`
+     - Set Ecosystem Vault ID and name (if provided or already set)
+     - Set Code Vault ID and name (if provided)
+     - Set `Auto-configured: No` (to distinguish from /kc:register setup)
+
+10. **Test connection (optional)**
+    - If verification succeeds, optionally test with a simple tool call
+    - This validates the API key is valid
+
+11. **Report success**
+    ```
+    ✅ KnowzCode MCP server configured!
+
+    Scope: <chosen-scope>
+    Endpoint: <endpoint-url>
+
+    Vaults Configured:
+      • Code Vault: <vault-name or "Not configured">
+      • Ecosystem Vault: <vault-name or "Not configured">
+      • Finalizations Vault: <vault-name or "Not configured">
+
+    🔄 Please restart Claude Code to activate these features:
+       • search_knowledge - Vector search across vaults
+       • ask_question - AI Q&A with research mode
+       • create_knowledge - Save learnings (via finalization)
+       • update_knowledge - Update existing items
+       • find_entities - Find people/locations/events
+
+    After restart, these tools will be available to all KnowzCode agents.
+
+    Check connection status: /kc:status
+    ```
+
+## Configuration Details
+
+### Scope Comparison
+
+**Local (default)**:
+- ✅ Private to you
+- ✅ Project-specific
+- ❌ Not shared with team
+- **Use when:** Personal API key, working solo
+
+**Project**:
+- ✅ Shared with team
+- ✅ Committed to git via `.mcp.json`
+- ⚠️ API key visible to team
+- **Use when:** Team API key, collaborative project
+
+**User**:
+- ✅ Available everywhere
+- ✅ Set once, works across projects
+- ❌ Not project-specific
+- **Use when:** Single API key for all your work
+
+### Security Considerations
+
+- **Never log API keys** in command output
+- **Mask displayed keys**: Show only first/last 4 chars (e.g., `kz_live_abc...xyz`)
+- **Warn about project scope**: API key will be in git-committed `.mcp.json`
+- **Suggest environment variables**: For team setups, recommend storing in CI/CD secrets
+
+### MCP Server Details
+
+The KnowzCode MCP server (default: `https://mcp.knowz.io/mcp`):
+- **Protocol:** HTTP transport with JSON-RPC
+- **Authentication:** Bearer token in `Authorization` header
+- **Project Context:** `X-Project-Path` header identifies project
+- **Rate Limiting:** Standard API rate limits apply
+- **Caching:** Responses cached for performance
+
+### Environment Endpoints
+
+**Available Environments:**
+
+| Environment | Endpoint | Flag | Use Case |
+|:------------|:---------|:-----|:---------|
+| **Production** (default) | `https://mcp.knowz.io/mcp` | (none) | Normal usage |
+| **Development** | `https://mcp.dev.knowz.io/mcp` | `--dev` | Testing new features |
+
+**Switching Environments:**
+```bash
+# Production (default)
+/kc:connect-mcp kz_live_abc123...
+
+# Development
+/kc:connect-mcp kz_test_abc123... --dev
+
+# Local development server
+/kc:connect-mcp kz_test_local... --endpoint http://localhost:3000/mcp
+
+# Self-hosted enterprise
+/kc:connect-mcp kz_live_abc123... --endpoint https://knowzcode.mycompany.com/mcp
+```
+
+## Error Handling
+
+### API Key Invalid
+```
+❌ Authentication failed
+The API key appears to be invalid or expired.
+
+Get a new key at: https://knowz.io/api-keys
+Then run: /kc:connect-mcp <new-key>
+```
+
+### Already Configured
+```
+⚠️ KnowzCode MCP server is already configured
+Current scope: <scope>
+
+Do you want to reconfigure?
+```
+
+### Claude CLI Not Available
+```
+❌ Cannot configure MCP server
+The 'claude' CLI command is not available.
+
+This is unusual - Claude Code should provide this command.
+Please restart Claude Code or report this issue.
+```
+
+### Network/Connection Error
+```
+❌ Cannot reach KnowzCode API
+Failed to connect to {endpoint}
+
+Check your internet connection and try again.
+If using --dev environment, verify the dev server is running.
+```
+
+## Advanced Usage
+
+### Switching Scopes
+To change from local to project scope:
+```bash
+# Remove existing (or the command will prompt to reconfigure)
+CLAUDECODE= claude mcp remove knowz
+
+# Re-add with new scope
+/kc:connect-mcp <api-key> --scope project
+```
+
+### Switching Endpoints
+To switch between environments or self-hosted:
+```bash
+# Switch to development
+/kc:connect-mcp <api-key> --dev
+
+# Switch back to production (default)
+/kc:connect-mcp <api-key>
+
+# Switch to self-hosted
+/kc:connect-mcp <api-key> --endpoint https://knowzcode.mycompany.com/mcp
+```
+
+## Integration with KnowzCode Agents
+
+Once configured, agents automatically detect and use MCP tools with dual vault support:
+
+**analyst**:
+- Uses `search_knowledge` with **code vault** to find related code
+- Uses `search_knowledge` with **ecosystem vault** to find past decisions
+- Uses `ask_question` with **ecosystem vault** for architectural context
+
+**architect**:
+- Uses `search_knowledge` with **code vault** for implementation examples
+- Uses `ask_question` with **ecosystem vault** for conventions
+
+**builder**:
+- Uses `search_knowledge` with **code vault** for similar patterns
+- Uses `search_knowledge` with **ecosystem vault** for best practices
+
+**reviewer**:
+- Uses `search_knowledge` with **ecosystem vault** for standards
+- Uses `search_knowledge` with **code vault** for precedent checks
+
+**closer**:
+- Uses `search_knowledge` with **ecosystem vault** to check for duplicate learnings
+- Uses `create_knowledge` to save new learnings to **ecosystem vault**
+
+**All agents**:
+- Automatically leverage MCP tools when available
+- Gracefully degrade if MCP server unavailable
+
+## Next Steps
+
+After configuration:
+1. **Restart Claude Code** (required to activate MCP server)
+2. **Verify connection**: `/kc:status`
+3. **Start building**: `/kc:work "your feature"`
+4. **Watch agents use MCP tools** automatically during workflow
+
+## Tool Control & Filtering
+
+Tools are controlled **server-side** at the MCP endpoint:
+
+**Server controls which tools to expose based on:**
+- API key tier (free/pro/enterprise)
+- Project type (monorepo, microservices, etc.)
+- Feature flags per user
+- Runtime conditions
+
+**Agents automatically discover and use available tools** - no client-side filtering needed.
+
+See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete server implementation guide.
+
+## Related Commands
+
+- `/kc:register` - Register for KnowzCode and configure MCP automatically
+- `/kc:status` - Check MCP connection status and available tools
+- `/kc:init` - Initialize KnowzCode in project
+- `/kc:work` - Start feature development (uses MCP tools)
+
+## Implementation Notes
+
+**For Server Developers:**
+- See `docs/MCP_SERVER_IMPLEMENTATION.md` for complete specification
+- Required methods: `initialize`, `tools/list`, `tools/call`
+- Authentication via `Authorization: Bearer` header
+- Project context via `X-Project-Path` header
+
+Execute this configuration now.