@softspark/ai-toolkit 1.2.0 → 1.3.0

package/app/hooks/mcp-health.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# mcp-health.sh — Check MCP server health at session start.
+#
+# Fires on: SessionStart
+# Non-blocking: always exits 0 (warnings only).
+
+# Common install hints for known MCP servers
+get_install_hint() {
+    case "$1" in
+        npx)   echo "npm install -g npx" ;;
+        uvx)   echo "pip install uv" ;;
+        node)  echo "https://nodejs.org/" ;;
+        python3|python) echo "https://python.org/" ;;
+        docker) echo "https://docs.docker.com/get-docker/" ;;
+        *)     echo "check the MCP server documentation" ;;
+    esac
+}
+
+# Check both global and local MCP config files
+CONFIG_FILES=()
+[ -f "$HOME/.claude/settings.json" ] && CONFIG_FILES+=("$HOME/.claude/settings.json")
+[ -f ".mcp.json" ] && CONFIG_FILES+=(".mcp.json")
+
+if [ ${#CONFIG_FILES[@]} -eq 0 ]; then
+    exit 0
+fi
+
+# Verify jq is available
+if ! command -v jq >/dev/null 2>&1; then
+    exit 0
+fi
+
+for CONFIG in "${CONFIG_FILES[@]}"; do
+    # Extract server names and their commands from mcpServers config
+    SERVERS=$(jq -r '
+        (.mcpServers // .mcp_servers // {})
+        | to_entries[]
+        | select(.value.command != null)
+        | "\(.key)\t\(.value.command)"
+    ' "$CONFIG" 2>/dev/null)
+
+    [ -z "$SERVERS" ] && continue
+
+    while IFS=$'\t' read -r SERVER_NAME CMD; do
+        [ -z "$CMD" ] && continue
+        if ! command -v "$CMD" >/dev/null 2>&1; then
+            HINT=$(get_install_hint "$CMD")
+            echo "MCP health: ${SERVER_NAME} command not found (${CMD}). Install with: ${HINT}"
+        fi
+    done <<< "$SERVERS"
+done
+
+exit 0

package/app/hooks/pre-compact-save.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# pre-compact-save.sh — Save conversation context summary before compaction.
+#
+# Fires on: PreCompact
+# Saves session metadata to timestamped file for audit trail.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+SAVE_DIR="$HOME/.ai-toolkit/compactions"
+mkdir -p "$SAVE_DIR"
+
+TIMESTAMP=$(date -u +"%Y-%m-%d_%H-%M-%S")
+SESSION="${CLAUDE_SESSION_ID:-$$}"
+SAVE_FILE="$SAVE_DIR/${TIMESTAMP}_${SESSION}.txt"
+
+# Gather context
+SESSION="${CLAUDE_SESSION_ID:-unknown}"
+WORKDIR="$(pwd)"
+BRANCH=""
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+fi
+
+cat > "$SAVE_FILE" << EOF
+# Pre-Compaction Context
+Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+Session: ${SESSION}
+Working Directory: ${WORKDIR}
+Git Branch: ${BRANCH:-N/A}
+EOF
+
+exit 0

package/app/hooks/session-context.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# session-context.sh — Capture session context at start for later reference.
+#
+# Fires on: SessionStart
+# Saves environment snapshot to JSON for cross-hook and cross-session use.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+SESSION="${CLAUDE_SESSION_ID:-$$}"
+SESSIONS_DIR="$HOME/.ai-toolkit/sessions"
+mkdir -p "$SESSIONS_DIR"
+
+CONTEXT_FILE="$SESSIONS_DIR/${SESSION}.json"
+
+# Gather context
+WORKDIR="$(pwd)"
+GIT_BRANCH=""
+GIT_STATUS=""
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+    GIT_STATUS=$(git status --short 2>/dev/null | head -20)
+fi
+
+NODE_VERSION=""
+if command -v node >/dev/null 2>&1; then
+    NODE_VERSION=$(node --version 2>/dev/null)
+fi
+
+PYTHON_VERSION=""
+if command -v python3 >/dev/null 2>&1; then
+    PYTHON_VERSION=$(python3 --version 2>/dev/null | awk '{print $2}')
+fi
+
+CURRENT_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Write JSON using python3 for proper escaping
+python3 - "$CONTEXT_FILE" "$WORKDIR" "$GIT_BRANCH" "$GIT_STATUS" "$CURRENT_DATE" "$NODE_VERSION" "$PYTHON_VERSION" <<'PY'
+import json
+import sys
+import os
+
+context_file = sys.argv[1]
+data = {
+    "pwd": sys.argv[2],
+    "git_branch": sys.argv[3],
+    "git_status": sys.argv[4],
+    "date": sys.argv[5],
+    "node_version": sys.argv[6],
+    "python_version": sys.argv[7],
+}
+
+tmp = context_file + ".tmp"
+with open(tmp, "w") as f:
+    json.dump(data, f, indent=2)
+os.replace(tmp, context_file)
+PY
+
+exit 0

package/app/hooks.json

@@ -10,6 +10,26 @@
                         "command": "\"$HOME/.ai-toolkit/hooks/session-start.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "startup|compact",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/mcp-health.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "startup|compact",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/session-context.sh\""
+                    }
+                ]
             }
         ],
         "Notification": [
@@ -44,6 +64,26 @@
                         "command": "\"$HOME/.ai-toolkit/hooks/guard-path.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Edit|Write|MultiEdit",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/guard-config.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/commit-quality.sh\""
+                    }
+                ]
             }
         ],
         "UserPromptSubmit": [
@@ -78,6 +118,16 @@
                         "command": "\"$HOME/.ai-toolkit/hooks/post-tool-use.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash|Edit|Write|MultiEdit",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/governance-capture.sh\""
+                    }
+                ]
             }
         ],
         "Stop": [
@@ -160,6 +210,16 @@
                         "command": "\"$HOME/.ai-toolkit/hooks/pre-compact.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/pre-compact-save.sh\""
+                    }
+                ]
             }
         ],
         "SessionEnd": [

package/app/mcp-templates/README.md

@@ -0,0 +1,105 @@
+# MCP Server Templates
+
+Ready-to-use MCP (Model Context Protocol) server configurations for Claude Code and other AI assistants.
+
+## What are these?
+
+Each JSON file contains a preconfigured MCP server definition that can be merged into your `.mcp.json` (project-level) or `~/.claude/settings.json` (global). Templates use `${ENV_VAR}` placeholders for secrets -- set the corresponding environment variables before use.
+
+## Quick start
+
+### Via CLI (recommended)
+
+```bash
+# List all available templates
+ai-toolkit mcp list
+
+# Show details for a template
+ai-toolkit mcp show github
+
+# Add one or more servers to your project
+ai-toolkit mcp add github fetch context7
+
+# Add to a specific directory
+ai-toolkit mcp add postgres --target /path/to/project
+
+# Remove a server
+ai-toolkit mcp remove github
+```
+
+### Manual copy
+
+1. Open the template file (e.g., `github.json`)
+2. Copy the `mcpServers` block
+3. Merge it into your `.mcp.json` or `~/.claude/settings.json`
+
+Example -- adding GitHub to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Available templates
+
+| Template | Description |
+|----------|-------------|
+| `github` | GitHub API for issues, PRs, and repos |
+| `filesystem` | Local file access |
+| `memory` | Persistent memory via knowledge graph |
+| `sequential-thinking` | Step-by-step reasoning |
+| `postgres` | PostgreSQL database access |
+| `sqlite` | SQLite database access |
+| `brave-search` | Web search via Brave API |
+| `puppeteer` | Browser automation |
+| `slack` | Slack workspace integration |
+| `google-drive` | Google Drive file management |
+| `google-maps` | Google Maps geocoding and directions |
+| `sentry` | Sentry error tracking |
+| `git` | Git repository operations |
+| `fetch` | HTTP fetch for web pages and APIs |
+| `context7` | Up-to-date library documentation |
+| `supabase` | Supabase project management |
+| `linear` | Linear issue tracker |
+| `notion` | Notion workspace integration |
+| `redis` | Redis cache and data management |
+| `docker` | Docker container management |
+| `cloudflare` | Cloudflare Workers, KV, D1, R2 |
+| `vercel` | Vercel deployments and settings |
+| `datadog` | Datadog monitoring and metrics |
+| `grafana` | Grafana dashboards and alerting |
+| `custom-template` | Empty template for custom servers |
+
+## Contributing a new template
+
+1. Create `app/mcp-templates/<name>.json` following this structure:
+
+```json
+{
+  "name": "<name>",
+  "description": "Short description of what this server does",
+  "mcpServers": {
+    "<name>": {
+      "command": "npx",
+      "args": ["-y", "<npm-package-name>"],
+      "env": {
+        "API_KEY": "${ENV_VAR_NAME}"
+      }
+    }
+  }
+}
+```
+
+2. Use `${ENV_VAR}` syntax for any secrets or tokens
+3. Keep the `name` field matching the filename (without `.json`)
+4. Update this README table
+5. Run `python3 scripts/validate.py` to verify

package/app/mcp-templates/brave-search.json

@@ -0,0 +1,13 @@
+{
+  "name": "brave-search",
+  "description": "Web and local search powered by Brave Search API",
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/cloudflare.json

@@ -0,0 +1,14 @@
+{
+  "name": "cloudflare",
+  "description": "Cloudflare Workers, KV, D1, R2, and DNS management",
+  "mcpServers": {
+    "cloudflare": {
+      "command": "npx",
+      "args": ["-y", "@cloudflare/mcp-server-cloudflare"],
+      "env": {
+        "CLOUDFLARE_API_TOKEN": "${CLOUDFLARE_API_TOKEN}",
+        "CLOUDFLARE_ACCOUNT_ID": "${CLOUDFLARE_ACCOUNT_ID}"
+      }
+    }
+  }
+}

package/app/mcp-templates/context7.json

@@ -0,0 +1,10 @@
+{
+  "name": "context7",
+  "description": "Up-to-date library documentation lookup via Context7",
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}

package/app/mcp-templates/custom-template.json

@@ -0,0 +1,13 @@
+{
+  "name": "custom-template",
+  "description": "Empty template — copy and customize for your own MCP server",
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "your-mcp-server-package"],
+      "env": {
+        "API_KEY": "${YOUR_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/datadog.json

@@ -0,0 +1,15 @@
+{
+  "name": "datadog",
+  "description": "Datadog monitoring for metrics, logs, traces, and dashboard queries",
+  "mcpServers": {
+    "datadog": {
+      "command": "npx",
+      "args": ["-y", "datadog-mcp-server"],
+      "env": {
+        "DD_API_KEY": "${DD_API_KEY}",
+        "DD_APP_KEY": "${DD_APP_KEY}",
+        "DD_SITE": "${DD_SITE:-datadoghq.com}"
+      }
+    }
+  }
+}

package/app/mcp-templates/docker.json

@@ -0,0 +1,10 @@
+{
+  "name": "docker",
+  "description": "Docker container and image management, logs, and compose operations",
+  "mcpServers": {
+    "docker": {
+      "command": "npx",
+      "args": ["-y", "docker-mcp-server"]
+    }
+  }
+}

package/app/mcp-templates/fetch.json

@@ -0,0 +1,10 @@
+{
+  "name": "fetch",
+  "description": "HTTP fetch for retrieving web pages and API responses as markdown or raw content",
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    }
+  }
+}

package/app/mcp-templates/filesystem.json

@@ -0,0 +1,10 @@
+{
+  "name": "filesystem",
+  "description": "Local filesystem access for reading, writing, and searching files",
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${FILESYSTEM_ROOT:-./}"]
+    }
+  }
+}

package/app/mcp-templates/git.json

@@ -0,0 +1,10 @@
+{
+  "name": "git",
+  "description": "Git operations for repository inspection, diffs, logs, and branches",
+  "mcpServers": {
+    "git": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-git"]
+    }
+  }
+}

package/app/mcp-templates/github.json

@@ -0,0 +1,13 @@
+{
+  "name": "github",
+  "description": "GitHub API integration for issues, PRs, repos, and code search",
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}

package/app/mcp-templates/google-drive.json

@@ -0,0 +1,15 @@
+{
+  "name": "google-drive",
+  "description": "Google Drive integration for file search, reading, and management",
+  "mcpServers": {
+    "google-drive": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-google-drive"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
+        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
+        "GOOGLE_REDIRECT_URI": "${GOOGLE_REDIRECT_URI}"
+      }
+    }
+  }
+}

package/app/mcp-templates/google-maps.json

@@ -0,0 +1,13 @@
+{
+  "name": "google-maps",
+  "description": "Google Maps API for geocoding, directions, and place search",
+  "mcpServers": {
+    "google-maps": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-google-maps"],
+      "env": {
+        "GOOGLE_MAPS_API_KEY": "${GOOGLE_MAPS_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/grafana.json

@@ -0,0 +1,14 @@
+{
+  "name": "grafana",
+  "description": "Grafana dashboard queries, alerting, and data source management",
+  "mcpServers": {
+    "grafana": {
+      "command": "npx",
+      "args": ["-y", "grafana-mcp-server"],
+      "env": {
+        "GRAFANA_URL": "${GRAFANA_URL}",
+        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/linear.json

@@ -0,0 +1,13 @@
+{
+  "name": "linear",
+  "description": "Linear issue tracker for issues, projects, and team workflows",
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "linear-mcp-server"],
+      "env": {
+        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/memory.json

@@ -0,0 +1,10 @@
+{
+  "name": "memory",
+  "description": "Persistent memory store using a local knowledge graph",
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    }
+  }
+}

package/app/mcp-templates/notion.json

@@ -0,0 +1,13 @@
+{
+  "name": "notion",
+  "description": "Notion workspace integration for pages, databases, and content management",
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "notion-mcp-server"],
+      "env": {
+        "NOTION_API_KEY": "${NOTION_API_KEY}"
+      }
+    }
+  }
+}

package/app/mcp-templates/postgres.json

@@ -0,0 +1,10 @@
+{
+  "name": "postgres",
+  "description": "PostgreSQL database access for queries, schema inspection, and analysis",
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "${POSTGRES_CONNECTION_STRING}"]
+    }
+  }
+}

package/app/mcp-templates/puppeteer.json

@@ -0,0 +1,10 @@
+{
+  "name": "puppeteer",
+  "description": "Browser automation for screenshots, navigation, and web scraping",
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+    }
+  }
+}

package/app/mcp-templates/redis.json

@@ -0,0 +1,13 @@
+{
+  "name": "redis",
+  "description": "Redis key-value store for cache inspection, data management, and monitoring",
+  "mcpServers": {
+    "redis": {
+      "command": "npx",
+      "args": ["-y", "redis-mcp-server"],
+      "env": {
+        "REDIS_URL": "${REDIS_URL:-redis://localhost:6379}"
+      }
+    }
+  }
+}

package/app/mcp-templates/sentry.json

@@ -0,0 +1,14 @@
+{
+  "name": "sentry",
+  "description": "Sentry error tracking for issue search, event details, and alerting",
+  "mcpServers": {
+    "sentry": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sentry"],
+      "env": {
+        "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
+        "SENTRY_ORG": "${SENTRY_ORG}"
+      }
+    }
+  }
+}

package/app/mcp-templates/sequential-thinking.json

@@ -0,0 +1,10 @@
+{
+  "name": "sequential-thinking",
+  "description": "Step-by-step reasoning and problem decomposition server",
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

package/app/mcp-templates/slack.json

@@ -0,0 +1,14 @@
+{
+  "name": "slack",
+  "description": "Slack workspace integration for channels, messages, and users",
+  "mcpServers": {
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "env": {
+        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
+        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
+      }
+    }
+  }
+}

package/app/mcp-templates/sqlite.json

@@ -0,0 +1,10 @@
+{
+  "name": "sqlite",
+  "description": "SQLite database access for queries and schema management",
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "${SQLITE_DB_PATH}"]
+    }
+  }
+}

package/app/mcp-templates/supabase.json

@@ -0,0 +1,14 @@
+{
+  "name": "supabase",
+  "description": "Supabase project management, database queries, and edge functions",
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "supabase-mcp-server"],
+      "env": {
+        "SUPABASE_URL": "${SUPABASE_URL}",
+        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
+      }
+    }
+  }
+}