knowz-mcp 0.4.0

package/skills/knowz/references/mcp-setup.md

@@ -0,0 +1,183 @@
+# MCP Server Configuration Reference
+
+## Enterprise Configuration
+
+Before using any endpoints below, check for an `enterprise.json` file in the plugin root directory (the directory containing `.claude-plugin/plugin.json`). If present, use its `mcp_endpoint` value instead of the production/development endpoints listed here. If absent, use the defaults below.
+
+## Server Details
+
+| Property | Value |
+|----------|-------|
+| **Protocol** | HTTP transport with JSON-RPC |
+| **Production endpoint** | `https://mcp.knowz.io/mcp` |
+| **Development endpoint** | `https://mcp.dev.knowz.io/mcp` |
+| **Authentication** | Bearer token or OAuth dynamic discovery |
+| **Project context** | `X-Project-Path` header |
+
+## Authentication Methods
+
+### API Key
+
+```bash
+claude mcp add --transport http \
+  --scope <local|project|user> \
+  knowz \
+  <endpoint-url> \
+  --header "Authorization: Bearer <api-key>" \
+  --header "X-Project-Path: $(pwd)"
+```
+
+### OAuth (recommended)
+
+No API key required — authentication happens via browser on first use.
+
+```bash
+claude mcp add --transport http \
+  --scope <local|project|user> \
+  knowz \
+  <endpoint-url> \
+  --header "X-Project-Path: $(pwd)"
+```
+
+On first tool call after restart, the server returns `401 + WWW-Authenticate` and Claude Code opens a browser for login.
+
+### Gemini CLI Configuration
+
+**OAuth:**
+```json
+{ "mcpServers": { "knowz": { "httpUrl": "<endpoint>", "authProviderType": "dynamic_discovery" } } }
+```
+Write to `.gemini/settings.json`. After writing, instruct: `Run /mcp auth knowz in Gemini CLI to complete authentication.`
+
+**API Key:**
+```json
+{
+  "mcpServers": {
+    "knowz": {
+      "httpUrl": "<endpoint>",
+      "headers": {
+        "Authorization": "Bearer <api-key>",
+        "X-Project-Path": "<project_path>"
+      }
+    }
+  }
+}
+```
+
+## Scope Options
+
+| Scope | Storage | Visibility | Best For |
+|-------|---------|------------|----------|
+| **local** (default) | Claude Code internal | Only you, this project | Personal development |
+| **project** | `.mcp.json` (git) | Team via git | Shared team key |
+| **user** | Claude Code user config | Only you, all projects | Personal, multi-project |
+
+### Security Warning for Project Scope
+
+If `--scope project` is selected:
+```
+Security Note: Project Scope Selected
+
+With project scope, your API key will be stored in .mcp.json
+which is typically committed to git.
+
+This is appropriate for:
+  - Team/shared API keys
+  - CI/CD automation keys
+
+For personal keys, consider using --scope local (default)
+```
+
+## Smart Config Discovery
+
+Before prompting for an API key, check known config sources in order:
+
+1. **Environment variable**: `KNOWZ_API_KEY`
+   - If set: use as API key, display "Using API key from KNOWZ_API_KEY (ending ...{last4})"
+
+2. **Cross-platform config files** (check for API key or OAuth):
+   - `.gemini/settings.json` → `mcpServers.knowz.authProviderType` (OAuth) or `mcpServers.knowz.headers.Authorization` (API key)
+   - `~/.gemini/settings.json` → same
+   - `.vscode/mcp.json` → `servers.knowz.headers`
+
+3. **KnowzCode vault config** (if present):
+   - `knowzcode/knowzcode_vaults.md` — if vaults have non-empty IDs, note for interop
+
+If a key is discovered, offer to reuse:
+```
+Found existing API key (ending ...{last4}) in {source}. Use this key? [Yes/No]
+```
+
+If OAuth config found in another platform:
+```
+Found existing OAuth configuration in {source}.
+Would you like to configure Claude Code with OAuth as well? [OAuth (recommended)] [API Key] [Skip]
+```
+
+## CLI Commands Reference
+
+```bash
+# Add MCP server
+claude mcp add --transport http --scope <scope> knowz <endpoint> --header "..."
+
+# Check existing config
+CLAUDECODE= claude mcp get knowz
+
+# Remove existing config
+CLAUDECODE= claude mcp remove knowz
+
+# List all MCP servers
+claude mcp list
+```
+
+## Error Handling
+
+### OAuth Authentication Required
+```
+OAuth authentication needed.
+
+This is expected if:
+  - First-time setup — you haven't completed browser login yet
+  - Token expired — your OAuth session needs renewal
+
+Important: MCP servers only connect at session startup. A restart is
+required before Claude Code can use a newly configured or re-authenticated
+MCP server — this is a platform limitation, not a bug.
+
+To authenticate:
+  Claude Code: Restart Claude Code — browser will open on first tool call
+  Gemini CLI: Run /mcp auth knowz to re-authenticate via browser
+
+If the problem persists:
+  - Re-configure: /knowz setup --oauth
+  - Or switch to API key (no browser login or token refresh needed): /knowz setup <api-key>
+```
+
+### API Key Invalid
+```
+Authentication failed. The API key appears to be invalid or expired.
+
+Get a new key at: https://knowz.io/api-keys
+Or switch to OAuth (no key needed): /knowz setup --oauth
+```
+
+### Already Configured
+```
+Knowz MCP server is already configured.
+Current scope: <scope>
+
+Do you want to reconfigure? [Yes/No]
+```
+If yes, run `CLAUDECODE= claude mcp remove knowz` first.
+
+### Claude CLI Not Available
+```
+Cannot configure MCP server — the 'claude' CLI command is not available.
+Please restart Claude Code or report this issue.
+```
+
+### Network/Connection Error
+```
+Cannot reach Knowz MCP server at {endpoint}.
+Check your internet connection and try again.
+```

package/skills/knowz/references/registration.md

@@ -0,0 +1,159 @@
+# Registration API Reference
+
+## Enterprise Configuration
+
+Before using any endpoints or brand names below, check for an `enterprise.json` file in the plugin root directory (the directory containing `.claude-plugin/plugin.json`). If present, use its values: `api_endpoint` replaces `https://api.knowz.io/api/v1` (registration becomes `{api_endpoint}/auth/register`), `mcp_endpoint` replaces `https://mcp.knowz.io/mcp`, and `brand` replaces "Knowz" in user-facing messages. When enterprise config is present, ignore the `--dev` flag. If absent, use the defaults below.
+
+## Endpoints
+
+| Environment | API Endpoint | MCP Endpoint |
+|:------------|:-------------|:-------------|
+| **Production** (default) | `https://api.knowz.io/api/v1/auth/register` | `https://mcp.knowz.io/mcp` |
+| **Development** (`--dev`) | `https://api.dev.knowz.io/api/v1/auth/register` | `https://mcp.dev.knowz.io/mcp` |
+
+## Request Format
+
+```bash
+curl -X POST https://api.knowz.io/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "{name}",
+    "email": "{email}",
+    "password": "{password}"
+  }'
+```
+
+## Response Structure
+
+```json
+{
+  "api_key": "kz_live_abc123...",
+  "vault_id": "vault_xyz789...",
+  "vault_name": "KnowzCode"
+}
+```
+
+Field name variants: `apiKey`/`api_key`/`token`, `vault_id`/`vaultId`, `vault_name`/`vaultName`.
+
+## Input Validation
+
+| Field | Rules |
+|-------|-------|
+| **Name** | Non-empty, 2-100 characters, letters/spaces/hyphens/apostrophes |
+| **Email** | Must contain `@` and domain, no leading/trailing whitespace |
+| **Password** | Minimum 8 characters |
+
+## Error Codes
+
+### Email Already Registered (HTTP 409)
+
+```
+The email {email} is already associated with an account.
+
+Options:
+1. Use a different email — run /knowz register again
+2. Retrieve existing API key — visit https://knowz.io/api-keys
+3. Reset password — https://knowz.io/forgot-password
+
+If this is your account, you can configure your existing key:
+  /knowz setup <your-existing-api-key>
+```
+
+### Invalid Input (HTTP 400)
+
+```
+Registration failed — validation errors:
+{error_message_from_response}
+
+Please correct the issue and try again.
+```
+
+Return to the step corresponding to the invalid field.
+
+### Rate Limited (HTTP 429)
+
+```
+Too many requests. Registration is temporarily rate limited.
+Please wait a few minutes and try again.
+
+If you continue to see this error, contact support:
+  https://knowz.io/support
+```
+
+### Network Error
+
+```
+Cannot reach registration server.
+
+Troubleshooting:
+1. Check your internet connection
+2. Verify firewall/proxy settings allow HTTPS to api.knowz.io
+3. Try again in a few moments
+
+Status page: https://status.knowz.io
+Support: https://knowz.io/support
+```
+
+### Server Error (HTTP 500+)
+
+```
+Server encountered an error. This is not your fault.
+
+Please:
+1. Try again in a few minutes
+2. Check status: https://status.knowz.io
+3. Contact support if persists: https://knowz.io/support
+```
+
+### MCP Configuration Failed (registration succeeded)
+
+```
+Account created, but MCP configuration failed.
+
+Your account:
+  Email: {email}
+  API Key: {masked_key}
+  Vault: {vault_name} ({vault_id prefix...})
+
+Configure manually:
+  /knowz setup {masked_key}
+
+Or visit https://knowz.io/api-keys to retrieve your key later.
+```
+
+### API Response Missing Vault ID
+
+```
+Account created, but no vault was auto-provisioned.
+
+This may indicate:
+  - Account provisioning is still in progress
+  - Server-side configuration needed
+
+You can:
+  1. Wait a few minutes and run /knowz status to check
+  2. Contact support: https://knowz.io/support
+  3. Run /knowz setup later to configure vaults
+```
+
+## Security Considerations
+
+- **HTTPS only** — all API calls use HTTPS
+- **Password not stored** — sent once, never saved locally
+- **Password not logged** — never display password in output
+- **Minimal data** — only collect what's needed for registration
+- **Mask displayed keys** — show only first 6 + last 4 chars (e.g., `kz_liv...wxyz`)
+- **Never log full keys** — exclude from diagnostic output
+- **Warn about project scope** — API key will be in git-committed `.mcp.json`
+- **Recommend local scope** — default to most secure option
+
+## What Registration Provides
+
+- **API Key** — unique key for MCP server authentication
+- **Knowz Vault** — auto-created vault for learnings, conventions, and patterns
+- **Vector Search** — AI-powered semantic search across vaults
+- **AI Q&A** — question answering with research mode
+- **Knowledge Capture** — save insights with automatic formatting
+
+Free tier: 1,000 API calls/month, single user, basic vector search.
+Upgrades: https://knowz.io/pricing

package/skills/knowz-auto/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: knowz-auto
+description: "Auto-detect when the user is asking knowledge questions or sharing insights that match Knowz vault rules. Triggers when user asks about past decisions, conventions, patterns, or shares learnings worth capturing — e.g. 'why did we...', 'what's our convention for...', 'we decided to...', 'I learned that...'"
+user-invocable: false
+allowed-tools: Read, Glob, Grep
+---
+
+# Knowz Auto — Frictionless Vault Awareness
+
+You are the **Knowz Auto** trigger skill. You make vault interaction truly frictionless by automatically consulting vaults or offering to save knowledge — without the user needing to explicitly use `/knowz`.
+
+## When This Skill Activates
+
+This skill activates automatically when Claude detects the user's message matches this skill's description:
+
+- Questions about past decisions: "why did we...", "what's our convention for...", "how did we build..."
+- Questions about patterns/standards: "what's the pattern for...", "do we have a standard for..."
+- Sharing insights/decisions: "we decided to...", "I learned that...", "the workaround is..."
+- Knowledge lookups: "check if we've done this before", "any prior art for..."
+
+## Prerequisites (ALL must be true)
+
+1. `knowz-vaults.md` exists in the project root
+2. MCP tools (`mcp__knowz__*`) are available
+3. This is NOT during an explicit `/knowz` command execution
+4. The user's message is NOT a clear code-related instruction (e.g., "fix this bug", "add a test")
+
+**If any prerequisite fails → do nothing.** Do not interfere with normal conversation.
+
+## Execution
+
+### Step 1: Read Vault Configuration
+
+Read `knowz-vaults.md` from the project root. Parse:
+- Each vault's **name** and **ID**
+- Each vault's **when to query** rules
+- Each vault's **when to save** rules
+- The **default vault** from `## Defaults`
+
+### Step 2: Classify the User's Message
+
+Determine if the user's message is a **query** or a **save candidate**:
+
+**Query signals** — the user is asking about something that might be in a vault:
+- Questions with "why", "how", "what", "when", "where" about past work
+- References to decisions, conventions, patterns, standards
+- "Do we have...", "Have we ever...", "What's our approach to..."
+- "Check if...", "Any prior art...", "Has anyone..."
+
+**Save signals** — the user is sharing knowledge worth capturing:
+- "We decided to...", "The approach is...", "I found that..."
+- "The workaround is...", "The trick is...", "Important: ..."
+- "Going forward, we should...", "The convention is..."
+- Sharing a lesson learned, a decision rationale, or a useful pattern
+
+### Step 3: Match Against Vault Rules
+
+Compare the classified message against each vault's routing rules:
+
+- **For queries:** Match against "when to query" rules
+- **For saves:** Match against "when to save" rules
+
+If no vault rules match the message, **do nothing** — this isn't vault-relevant content.
+
+### Step 4: Take Action
+
+**For query matches — search silently, include findings in response:**
+
+1. Call `mcp__knowz__search_knowledge` with:
+   - `query`: extract the core question from the user's message
+   - `vaultId`: the matched vault ID
+   - `limit`: 5
+2. If results are found, weave them into your response naturally:
+   ```
+   Based on your vault knowledge, {relevant finding}...
+   ```
+   or
+   ```
+   Your {Vault Name} vault has context on this:
+     - {relevant item title}: {key insight}
+   ```
+3. If no results found, proceed normally — don't mention the failed search
+
+**For save matches — offer to capture, never auto-save:**
+
+1. Identify the insight worth capturing
+2. Determine which vault it should go to based on "when to save" rules
+3. Offer to save — always ask first:
+   ```
+   This looks like it could be worth saving to {Vault Name}. Want me to capture it?
+   ```
+4. If the user agrees, use the `/knowz` skill's save flow:
+   - Format the content using the vault's content template
+   - Dedup check
+   - Create the knowledge item
+   - Report success
+5. **If MCP write fails** (e.g., server unreachable, auth expired), queue to pending captures:
+   - Append a capture block to `knowz-pending.md` in the project root (create file if needed)
+   - Use the format from `knowz-pending.example.md`:
+     ```
+     ---
+
+     ### {ISO timestamp} -- {Category}: {Title}
+     - **Category**: {category}
+     - **Target Vault**: {vault name}
+     - **Source**: knowz-auto
+     - **Content**:
+     {formatted content}
+
+     ---
+     ```
+   - Report: `"Queued to knowz-pending.md — run /knowz flush when MCP is available."`
+6. If the user declines, continue normally
+
+## Key Constraints
+
+- **Lightweight only.** Read vault file, check rules, do a quick search or offer to save. Nothing more.
+- **Never auto-save.** Always ask before capturing knowledge.
+- **Never block.** If vault lookup fails or returns nothing, continue with the normal response.
+- **Don't announce yourself.** Don't say "I'm checking your vaults..." — just include findings naturally or offer to save.
+- **Don't trigger during `/knowz`.** If the user is already using the explicit skill, stay out of the way.
+- **Don't trigger on code instructions.** "Fix this bug", "add a test", "refactor this" are not vault-relevant.