@skillsmith/mcp-server 0.4.12 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to `@skillsmith/mcp-server` are documented here.
 
+## [Unreleased]
+
+## v0.5.0
+
+This release ships the consumer namespace-audit feature end-to-end (SMI-4587 → SMI-4590, Waves 1–4). Three new MCP tools, an install-time pre-flight gate, an apply-with-confirmation edit-suggester, a session-start audit hook (Team/Enterprise), and an Enterprise scheduled-scan path.
+
+### New MCP tools (Team+ tier)
+
+- **Feature**: `skill_inventory_audit` — audits the local `~/.claude/` inventory across skills/commands/agents/CLAUDE.md for namespace collisions; returns rename + edit suggestions. Three pass-modes (`preventative` / `power_user` / `governance`) controlled by `~/.skillsmith/config.json` `audit_mode` or `SKILLSMITH_AUDIT_MODE` env. ULID-based audit-history at `~/.skillsmith/audits/<auditId>/`. Privacy-gated for Free/Individual (returns typed error). (SMI-4587 / SMI-4590 PR #940)
+- **Feature**: `apply_namespace_rename` — applies a rename suggestion from an audit result with three modes (`apply` / `custom` / `skip`); persists overrides via the namespace-overrides ledger. (SMI-4588 / SMI-4590 PR #940)
+- **Feature**: `apply_recommended_edit` — applies a recommended prose edit (e.g. `add_domain_qualifier`); gated behind `APPLY_TEMPLATE_REGISTRY` allow-list with `apply_with_confirmation` UX from the edit-suggester pipeline. (SMI-4589 / SMI-4590 PR #940)
+
+### Install-time + session-time gates
+
+- **Feature**: SMI-4588 install pre-flight + mode gate — `runNamespaceGate` runs before `install_skill` to surface name conflicts ahead of disk write; mode-aware behaviour (block in `preventative`, warn in `power_user`, audit-only in `governance`, skip in `off`). (PR #881)
+- **Feature**: SMI-4590 Wave 4 PR 6/6 — tier-gated session-start audit hook (`scripts/session-start-audit.sh` → `scripts/lib/session-start-audit-helper.ts`). Debounced 24h via `~/.skillsmith/last-audit.json`. Free/Individual emit zero output (audit is a paid feature); Team gets a one-line collapsed summary on stderr; Enterprise gets a path-only pointer on stderr. Bounded 5-second wall clock; fail-soft (helper always exits 0). Disable via `SKILLSMITH_SESSION_AUDIT_DISABLE=1`. Logs at `~/.skillsmith/logs/session-audit-<date>.log`. (#956)
+- **Feature**: SMI-4590 Wave 4 — Enterprise scheduled-scan via `runScheduledScan`. Idempotent within `SKILLSMITH_SCHEDULED_AUDIT_CACHE_MIN` (default 5 min); emits deep + un-filtered findings.
+
+### Detection passes + plumbing
+
+- **Feature**: SMI-4587 Wave 1 — local-inventory scanner across 4 sources (skills/commands/agents/CLAUDE.md), ULID-based audit-history writer at `~/.skillsmith/audits/<auditId>/`, and exact-name collision detector. Adds `ulid@3.0.1` dependency. PR #2 adds the generic-token pass via the existing `detectGenericTriggerWords` helper (results surface as `genericFlags`, severity `warning`). PR #3 adds the semantic-overlap pass via existing `OverlapDetector` (gated by `audit_mode`), adds `bootstrapUnmanagedSkills` plumbing. Latency invariant: in `preventative` mode no `EmbeddingService` is touched (zero ONNX model load on the cheap critical path). PR #4 ships the audit-report writer (atomic markdown render with conditional CLAUDE.md scan caveat per D-ANTI-1), aggregate-only server telemetry (`namespace_audit_complete` event with collision counts and resolution counters; never auditId/path/identifier per decision #7), the `index.ts` barrel re-export at `@skillsmith/mcp-server/audit`, and refactors `LocalIndexer.indexSkillDir` to delegate to the new `indexLocalSkill` core helper.
+- **Feature**: SMI-4588 Wave 2 — namespace overrides ledger + shared audit types (PR #877); rename engine + suggestion chain + 3 apply paths (PR #880); install pre-flight + mode gate (PR #881); integration tests + audit-report rename section + backup-gc (PR #884).
+- **Feature**: SMI-4589 Wave 3 — edit-suggester (`apply_with_confirmation` for `add_domain_qualifier`). (PR #886)
+- **Feature**: SMI-4590 Wave 4 PR 1/6 — `sklx audit advisories` tool routing + audit-tool-dispatch extraction. (#899)
+- **Feature**: SMI-4590 Wave 4 PR 2/6 — `FrameworkAdapter` interface + `claudeCodeAdapter` + package wiring. Allows the audit pipeline to address agent frameworks beyond Claude Code in future. (#913)
+
+### Other
+
+- **Bump**: `@skillsmith/core` dep range to `^0.6.0` to pick up the new audit subpath exports (`@skillsmith/core/config/audit-mode`, `@skillsmith/core/skills/index-local`) and multi-client install paths (`@skillsmith/core/install`).
+- **Bump**: minor version (0.4.13 → 0.5.0) signals new MCP tool surface — three new tools added to the Team+ tier.
+- **Feature**: SMI-4124 `skill_pack_audit` trigger-quality + namespace collision checks (PR #505).
+
+## v0.4.13
+
+- **Fix**: map curated trust tier through MCP surface (SMI-4520) (#822)
+- **Fix**: batch close 4 GitHub security alerts (SMI-4499/4501/4502/4504) (#805)
+- **Fix**: rotate KEY_HMAC_SECRET to env var (SMI-4503, CodeQL #81) (#807)
+
 ## v0.4.12
 
 - **Fix**: team-workspace uses service-role client post-license-resolution (SMI-4312) (#650)
@@ -15,10 +53,6 @@ All notable changes to `@skillsmith/mcp-server` are documented here.
 - **Fix**: restore category/security/repo in skill detail view (SMI-4240) (#583)
 - **Other**: SMI-4190: release cadence docs — ADR-114 + CHANGELOG backfill + CONTRIBUTING (#552)
 
-## [Unreleased]
-
-- **Feature**: SMI-4124 `skill_pack_audit` trigger-quality + namespace collision checks (PR #505).
-
 ## v0.4.9
 
 - **Feature**: SMI-4183 emit `webhook:subscription_tier_changed` audit events from subscription edge function (#538).

package/README.md

@@ -24,6 +24,8 @@ Restart your MCP client to use the latest version.
 
 To disable update checks, set `SKILLSMITH_AUTO_UPDATE_CHECK=false` in your environment.
 
+**Local-first by design.** Skillsmith caches the registry in a local SQLite database at `~/.skillsmith/skills.db`, shared across the MCP server, the CLI, and the VS Code extension. Search is FTS5 (SQLite's built-in keyword search) by default; semantic search is opt-in (`SKILLSMITH_USE_HNSW=true`) and runs over local ONNX embeddings (an open ML model format that runs on CPU — no API call). [Inside the Local Skill Database](https://skillsmith.app/blog/inside-the-local-skill-database) walks through the schema, the FTS5 / HNSW search paths, and how `sync` keeps the cache fresh.
+
 ## Installation
 
 ```bash
@@ -32,58 +34,132 @@ npm install @skillsmith/mcp-server
 
 ## Quick Start
 
-Copy this MCP configuration snippet:
+Skillsmith works with any MCP-compatible AI agent. Pick the snippet for your client.
+SMI-4580: snippets are sourced from `@skillsmith/cli/templates/mcp-server.template.snippets.ts`
+so this README and the website docs cannot drift.
+
+<details>
+<summary><strong>Claude Code</strong> — <code>~/.claude/settings.json</code></summary>
 
+```json
+{
+  "mcpServers": {
+    "@skillsmith/mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@skillsmith/mcp-server"],
+      "env": {
+        "SKILLSMITH_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
 ```
-Add this MCP server to my settings.json:
 
+Restart Claude Code after editing settings.json.
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong> — <code>~/.cursor/mcp.json</code></summary>
+
+```json
 {
   "mcpServers": {
-    "skillsmith": {
+    "@skillsmith/mcp-server": {
       "command": "npx",
-      "args": ["-y", "@skillsmith/mcp-server"]
+      "args": ["-y", "@skillsmith/mcp-server"],
+      "env": {
+        "SKILLSMITH_API_KEY": "sk_live_..."
+      }
     }
   }
 }
 ```
 
-## Platform Configuration
+Cursor 2.4+ required. Reload the window after saving.
 
-Skillsmith works with any MCP-compatible AI agent platform. Add the following to your platform's MCP config file:
+</details>
 
-**Claude Code** (`~/.claude/settings.json`):
+<details>
+<summary><strong>GitHub Copilot (VS Code)</strong> — <code>.vscode/mcp.json</code> (workspace)</summary>
 
 ```json
 {
   "mcpServers": {
-    "skillsmith": {
+    "@skillsmith/mcp-server": {
       "command": "npx",
       "args": ["-y", "@skillsmith/mcp-server"],
       "env": {
-        "SKILLSMITH_API_KEY": "sk_live_your_key_here"
+        "SKILLSMITH_API_KEY": "sk_live_..."
       }
     }
   }
 }
 ```
 
-**OpenClaw / Cursor / Codex / Antigravity / GitHub Copilot / other MCP clients** (`openclaw.json` or equivalent):
+VS Code 1.108+ required. Workspace-scoped (commit to repo if team-shared, or use user `settings.json` instead).
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
 
 ```json
 {
   "mcpServers": {
-    "skillsmith": {
+    "@skillsmith/mcp-server": {
       "command": "npx",
       "args": ["-y", "@skillsmith/mcp-server"],
       "env": {
-        "SKILLSMITH_API_KEY": "sk_live_your_key_here"
+        "SKILLSMITH_API_KEY": "${env:SKILLSMITH_API_KEY}"
       }
     }
   }
 }
 ```
 
-Get your API key at https://skillsmith.app/account (free Community tier available).
+Supports `${env:VAR}` interpolation; export `SKILLSMITH_API_KEY` in your shell instead of inlining the secret.
+
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong> — <code>~/.codex/config.toml</code> (TOML, not JSON)</summary>
+
+```toml
+[mcp_servers.@skillsmith/mcp-server]
+command = "npx"
+args = ["-y", "@skillsmith/mcp-server"]
+
+[mcp_servers.@skillsmith/mcp-server.env]
+SKILLSMITH_API_KEY = "sk_live_..."
+```
+
+Codex reads `~/.agents/skills`. When installing via Skillsmith CLI, pass `--client agents`.
+
+</details>
+
+<details>
+<summary><strong>Cross-agent (open standard)</strong> — <code>~/.agents/mcp.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "@skillsmith/mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@skillsmith/mcp-server"],
+      "env": {
+        "SKILLSMITH_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+Read by any agent honouring the cross-agent skill convention.
+
+</details>
+
+Get your API key at <https://skillsmith.app/account> (free Community tier available).
 
 After adding to your MCP client settings and restarting, try asking:
 
@@ -352,6 +428,50 @@ Index local skills from `~/.claude/skills/` directory.
 | `SKILLSMITH_TELEMETRY_ENABLED` | Enable anonymous telemetry | `false` |
 | `SKILLSMITH_USE_WASM` | Force WASM SQLite driver (sql.js) | `false` |
 | `POSTHOG_API_KEY` | PostHog API key (required if telemetry enabled) | - |
+| `SKILLSMITH_API_KEY_HMAC_SECRET` | HMAC secret for hashing Custom Integration API keys before DB storage. Required if you invoke `webhook_configure` or `api_key_manage`. See setup below. | - |
+
+### Custom Integration Setup (Team+ admins)
+
+The `webhook_configure` and `api_key_manage` tools hash secrets server-side via HMAC-SHA-256 before persisting to the shared `api_keys` table. The HMAC key lives in `SKILLSMITH_API_KEY_HMAC_SECRET` rather than as a hardcoded constant — defense-in-depth so a leaked DB cannot be reverse-cracked offline.
+
+**Distribution model**: identical to `SUPABASE_SERVICE_ROLE_KEY`. The same secret value must be set on every MCP host that creates or verifies Custom Integration API keys, otherwise hashes computed on host A won't match hashes verified on host B.
+
+If the variable is missing or shorter than 32 characters when these tools are invoked, the call fails fast with:
+
+```
+SKILLSMITH_API_KEY_HMAC_SECRET must be set to a 32+ character random secret
+before integration tools can be used. Generate one via: openssl rand -base64 48
+```
+
+**First-time provisioning** (Skillsmith admin, once per organization):
+
+```bash
+openssl rand -base64 48
+```
+
+Distribute that value through the same secure channel used for `SUPABASE_SERVICE_ROLE_KEY` (e.g., 1Password vault, encrypted onboarding email). Each Team-tier admin sets it on their own MCP host alongside their other secrets:
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "mcpServers": {
+    "skillsmith": {
+      "command": "npx",
+      "args": ["-y", "@skillsmith/mcp-server"],
+      "env": {
+        "SKILLSMITH_API_KEY": "sk_live_your_personal_key",
+        "SKILLSMITH_LICENSE_KEY": "sklic_your_team_license",
+        "SUPABASE_SERVICE_ROLE_KEY": "eyJ...your_service_role_jwt",
+        "SKILLSMITH_API_KEY_HMAC_SECRET": "<the shared 32+ char secret>"
+      }
+    }
+  }
+}
+```
+
+**Rotation**: replace the secret on every host in lockstep. Existing rows in the `api_keys` table become unverifiable after rotation, so coordinate with affected admins or invalidate keys explicitly. As of 2026-04-26 the table has zero rows, so the first rotation post-launch is free.
+
+If you only use Community/Individual tools (search, install, recommend, etc.), this variable is not needed.
 
 ### WASM Fallback (v0.3.18+)