trace-mcp 1.4.1 → 1.5.4

package/hooks/trace-mcp-guard.cmd

@@ -1,9 +1,12 @@
 @echo off
-REM trace-mcp-guard v0.2.0
+REM trace-mcp-guard v0.4.0
 REM trace-mcp PreToolUse guard (Windows)
 REM Blocks Read/Grep/Glob/Bash on source code files - redirects to trace-mcp tools.
 REM Allows: non-code files, Read before Edit, safe Bash commands (git, npm, build, test).
 REM
+REM Consultation markers: trace-mcp server writes markers when tools access files.
+REM If a marker exists, Read is allowed immediately.
+REM
 REM Install: add to ~\.claude\settings.json or .claude\settings.local.json
 REM See README.md for setup instructions.
 
@@ -47,6 +50,14 @@ REM Block code file reads - redirect to trace-mcp
 echo "%FILE_PATH%" | findstr /i /r "\.ts$ \.tsx$ \.js$ \.jsx$ \.mjs$ \.cjs$ \.py$ \.pyi$ \.go$ \.rs$ \.java$ \.kt$ \.kts$ \.rb$ \.php$ \.cs$ \.cpp$ \.c$ \.h$ \.hpp$ \.swift$ \.scala$ \.vue$ \.svelte$ \.astro$" >nul 2>&1
 if not %errorlevel%==0 goto :allow
 
+REM Check consultation markers (trace-mcp server writes these when get_outline/get_symbol called)
+for /f "usebackq delims=" %%h in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%CD%'))).Replace('-','').Substring(0,12).ToLower()"`) do set "PROJ_HASH=%%h"
+set "REL_FOR_HASH=%FILE_PATH%"
+set "REL_FOR_HASH=!REL_FOR_HASH:%CD%\=!"
+set "REL_FOR_HASH=!REL_FOR_HASH:\=/!"
+for /f "usebackq delims=" %%h in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('!REL_FOR_HASH!'))).Replace('-','').ToLower()"`) do set "FILE_HASH=%%h"
+if exist "%TEMP%\trace-mcp-consulted-!PROJ_HASH!\!FILE_HASH!" goto :allow
+
 REM Allow on second attempt (agent needs full content for Edit)
 set "SESSION_ID=default"
 for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "try { (Get-Content '%TMPINPUT%' -Raw | ConvertFrom-Json).session_id } catch { 'default' }"`) do set "SESSION_ID=%%i"
@@ -54,7 +65,7 @@ set "DENY_DIR=%TEMP%\trace-mcp-guard-%SESSION_ID%"
 if not exist "%DENY_DIR%" mkdir "%DENY_DIR%" 2>nul
 
 REM Create a hash of the file path for the marker
-for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.MD5]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%FILE_PATH%'))).Replace('-','')"`) do set "MARKER_HASH=%%i"
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%FILE_PATH%'))).Replace('-','').ToLower()"`) do set "MARKER_HASH=%%i"
 set "DENY_MARKER=%DENY_DIR%\%MARKER_HASH%"
 
 if exist "%DENY_MARKER%" (
@@ -137,6 +148,13 @@ REM Allow safe commands
 echo "%COMMAND%" | findstr /i /r /c:"^git " /c:"^npm " /c:"^npx " /c:"^pnpm " /c:"^yarn " /c:"^bun " /c:"^node " /c:"^deno " /c:"^cargo " /c:"^go " /c:"^make " /c:"^mvn " /c:"^gradle " /c:"^docker " /c:"^kubectl " /c:"^helm " /c:"^terraform " /c:"^pip " /c:"^poetry " /c:"^uv " /c:"^pytest " /c:"^vitest " /c:"^jest " /c:"^phpunit " /c:"^composer " /c:"^artisan " /c:"^rails " /c:"^bundle " /c:"^mix " /c:"^dotnet " /c:"^cmake " >nul 2>&1
 if %errorlevel%==0 goto :allow
 
+REM Block bash commands targeting .env files - prevent secret leakage
+echo "%COMMAND%" | findstr /i /r "\.env" >nul 2>&1
+if %errorlevel%==0 (
+    call :deny "Use get_env_vars for .env files - it masks sensitive values (passwords, API keys, tokens)." "trace-mcp alternatives: get_env_vars to list keys + types without exposing secrets. Never access .env files via shell."
+    goto :cleanup
+)
+
 REM Block code exploration via bash
 set "HAS_EXPLORE=0"
 echo "%COMMAND%" | findstr /i /r "grep rg find cat head tail less more awk sed" >nul 2>&1

package/hooks/trace-mcp-guard.sh

@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
-# trace-mcp-guard v0.2.0
+# trace-mcp-guard v0.4.0
 # trace-mcp PreToolUse guard
 # Blocks Read/Grep/Glob/Bash on source code files → redirects to trace-mcp tools.
 # Allows: non-code files, Read before Edit, safe Bash commands (git, npm, build, test).
 #
+# Consultation markers: trace-mcp server writes markers when tools access files
+# (get_outline, get_symbol, etc.). If a marker exists for a file, Read is allowed
+# immediately — the agent already consulted trace-mcp for this file.
+#
 # Install: add to ~/.claude/settings.json or .claude/settings.local.json
 # See README.md for setup instructions.
 
@@ -24,6 +28,11 @@ ENV_FILE_RE='\.env(\.[a-zA-Z0-9._-]+)?$'
 # Safe bash command prefixes — never block
 SAFE_BASH_RE='^(git |npm |npx |pnpm |yarn |bun |node |deno |cargo |go |make |mvn |gradle |docker |kubectl |helm |terraform |pip |poetry |uv |pytest |vitest |jest |phpunit |composer |artisan |rails |bundle |mix |dotnet |cmake |ninja |meson )'
 
+# Cross-platform sha256 hash (Linux: sha256sum, macOS: shasum)
+file_sha256() {
+  echo -n "$1" | sha256sum 2>/dev/null | cut -d' ' -f1 || echo -n "$1" | shasum -a 256 2>/dev/null | cut -d' ' -f1
+}
+
 deny() {
   local reason="$1"
   local context="$2"
@@ -45,6 +54,19 @@ SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"')
 DENY_DIR="/tmp/trace-mcp-guard-${SESSION_ID}"
 mkdir -p "$DENY_DIR" 2>/dev/null
 
+# Consultation markers: trace-mcp server writes these when get_outline/get_symbol/etc. are called.
+# If a file was already consulted via trace-mcp, allow Read immediately (agent needs full content for Edit).
+# Dir format: $TMPDIR/trace-mcp-consulted-{sha256(projectRoot)[:12]}/{sha256(relPath)}
+PROJECT_ROOT="$(pwd)"
+if command -v sha256sum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | sha256sum | cut -c1-12)
+elif command -v shasum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)
+else
+  PROJECT_HASH=""
+fi
+CONSULTED_DIR="${TMPDIR:-/tmp}/trace-mcp-consulted-${PROJECT_HASH}"
+
 # --- Read ---
 if [[ "$TOOL_NAME" == "Read" ]]; then
   FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
@@ -70,8 +92,18 @@ if [[ "$TOOL_NAME" == "Read" ]]; then
 
   # Block code file reads → redirect to trace-mcp
   if echo "$FILE_PATH" | grep -qiE "$CODE_EXT_RE"; then
+    # Compute relative path for consultation marker check (server writes markers keyed by relative path)
+    REL_PATH_FOR_HASH=$(echo "$FILE_PATH" | sed "s|^${PROJECT_ROOT}/||")
+    CONSULTED_HASH=$(file_sha256 "$REL_PATH_FOR_HASH")
+
+    # Check if file was already consulted via trace-mcp (get_outline, get_symbol, etc.)
+    if [[ -n "$PROJECT_HASH" && -f "$CONSULTED_DIR/$CONSULTED_HASH" ]]; then
+      # File was consulted via trace-mcp → allow Read (agent needs full content for Edit)
+      exit 0
+    fi
+
     # Allow on second attempt — agent needs full content for Edit
-    DENY_MARKER="$DENY_DIR/$(echo "$FILE_PATH" | md5sum | cut -d' ' -f1)"
+    DENY_MARKER="$DENY_DIR/$(file_sha256 "$FILE_PATH")"
     if [[ -f "$DENY_MARKER" ]]; then
       rm -f "$DENY_MARKER"
       exit 0
@@ -153,6 +185,13 @@ if [[ "$TOOL_NAME" == "Bash" ]]; then
     exit 0
   fi
 
+  # Block bash commands targeting .env files — prevent secret leakage
+  if echo "$COMMAND" | grep -qiE "$ENV_FILE_RE"; then
+    deny \
+      "Use get_env_vars for .env files — it masks sensitive values (passwords, API keys, tokens)." \
+      "trace-mcp alternatives:\\n- get_env_vars {} — list all env vars across all .env files\\n- get_env_vars { \\\"pattern\\\": \\\"DB_\\\" } — filter by key prefix\\nNever access .env files via shell — secrets will leak into AI model context."
+  fi
+
   # Block code exploration via bash (grep, find, cat, head, tail on code files)
   if echo "$COMMAND" | grep -qE '(^|\|)\s*(grep|rg|find|cat|head|tail|less|more|awk|sed)\s' && echo "$COMMAND" | grep -qiE "$CODE_EXT_RE"; then
     deny \

package/hooks/trace-mcp-precompact.cmd

@@ -0,0 +1,33 @@
+@echo off
+REM trace-mcp-precompact v0.1.0
+REM trace-mcp PreCompact hook (Windows)
+REM Injects session snapshot into compacted context to prevent "compaction amnesia".
+REM Reads the live snapshot file written by the running trace-mcp MCP server and
+REM returns it via the systemMessage field in Claude Code's hook output schema.
+REM
+REM Install: add to ~\.claude\settings.json or .claude\settings.local.json under PreCompact
+REM See README.md for setup instructions.
+
+setlocal enabledelayedexpansion
+
+REM Determine project root from working directory
+set "PROJECT_ROOT=%CD%"
+
+REM Compute project hash using PowerShell (sha256, first 12 hex chars)
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "[System.BitConverter]::ToString([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes('%PROJECT_ROOT%'))).Replace('-','').Substring(0,12).ToLower()"`) do set "PROJECT_HASH=%%i"
+
+if "%PROJECT_HASH%"=="" goto :done
+
+set "SNAPSHOT_FILE=%USERPROFILE%\.trace-mcp\sessions\%PROJECT_HASH%-snapshot.json"
+
+if not exist "%SNAPSHOT_FILE%" goto :done
+
+REM Read markdown from snapshot file and output as systemMessage
+for /f "usebackq delims=" %%i in (`powershell -NoProfile -Command "$j = Get-Content '%SNAPSHOT_FILE%' -Raw | ConvertFrom-Json; if ($j.markdown) { $j.markdown }"`) do set "MARKDOWN=%%i"
+
+if "%MARKDOWN%"=="" goto :done
+
+powershell -NoProfile -Command "$m = (Get-Content '%SNAPSHOT_FILE%' -Raw | ConvertFrom-Json).markdown; @{systemMessage=$m} | ConvertTo-Json -Compress"
+
+:done
+exit /b 0

package/hooks/trace-mcp-precompact.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# trace-mcp-precompact v0.1.0
+# trace-mcp PreCompact hook
+# Injects session snapshot into compacted context to prevent "compaction amnesia".
+# Reads the live snapshot file written by the running trace-mcp MCP server and
+# returns it via the systemMessage field in Claude Code's hook output schema.
+#
+# Install: add to ~/.claude/settings.json or .claude/settings.local.json under PreCompact
+# See README.md for setup instructions.
+
+set -euo pipefail
+
+# Determine project root from working directory
+PROJECT_ROOT="$(pwd)"
+
+# Compute project hash (same algorithm as trace-mcp: sha256, first 12 hex chars)
+if command -v sha256sum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | sha256sum | cut -c1-12)
+elif command -v shasum >/dev/null 2>&1; then
+  PROJECT_HASH=$(echo -n "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)
+else
+  # Fallback: no hash available, exit silently
+  exit 0
+fi
+
+SNAPSHOT_FILE="$HOME/.trace-mcp/sessions/${PROJECT_HASH}-snapshot.json"
+
+# If no snapshot file exists, exit silently (no session data yet)
+if [[ ! -f "$SNAPSHOT_FILE" ]]; then
+  exit 0
+fi
+
+# Check file freshness — skip if older than 10 minutes (stale session)
+if command -v stat >/dev/null 2>&1; then
+  if [[ "$(uname)" == "Darwin" ]]; then
+    FILE_MTIME=$(stat -f %m "$SNAPSHOT_FILE" 2>/dev/null || echo 0)
+  else
+    FILE_MTIME=$(stat -c %Y "$SNAPSHOT_FILE" 2>/dev/null || echo 0)
+  fi
+  NOW=$(date +%s)
+  AGE=$(( NOW - FILE_MTIME ))
+  if [[ $AGE -gt 600 ]]; then
+    exit 0
+  fi
+fi
+
+# Read the markdown snapshot from the JSON file
+MARKDOWN=$(jq -r '.markdown // empty' "$SNAPSHOT_FILE" 2>/dev/null)
+
+if [[ -z "$MARKDOWN" ]]; then
+  exit 0
+fi
+
+# Output systemMessage for Claude Code to inject into compacted context
+jq -n --arg msg "$MARKDOWN" '{ "systemMessage": $msg }'
+
+exit 0

package/hooks/trace-mcp-worktree.cmd

@@ -0,0 +1,33 @@
+@echo off
+REM trace-mcp-worktree v0.1.0
+REM trace-mcp WorktreeCreate / WorktreeRemove hook
+REM On WorktreeCreate: registers and indexes the new worktree.
+REM On WorktreeRemove: deregisters the worktree project.
+
+setlocal enabledelayedexpansion
+
+set "INPUT="
+for /f "delims=" %%i in ('more') do set "INPUT=!INPUT!%%i"
+
+REM Extract event type
+for /f "delims=" %%e in ('echo !INPUT! ^| jq -r ".hook_event_name // .event // empty" 2^>nul') do set "EVENT=%%e"
+if not defined CLAUDE_HOOK_EVENT set "CLAUDE_HOOK_EVENT=%EVENT%"
+if defined CLAUDE_HOOK_EVENT set "EVENT=%CLAUDE_HOOK_EVENT%"
+
+REM Extract worktree path
+for /f "delims=" %%p in ('echo !INPUT! ^| jq -r ".tool_input.path // .worktree_path // .path // .cwd // empty" 2^>nul') do set "WPATH=%%p"
+
+if "%WPATH%"=="" exit /b 0
+
+if "%EVENT%"=="WorktreeCreate" (
+  start /b trace-mcp add "%WPATH%" --force --json >nul 2>&1
+) else if "%EVENT%"=="WorktreeRemove" (
+  REM Clean up worktree DB file if it exists
+  for /f "delims=" %%h in ('echo %WPATH%^| certutil -hashfile - SHA256 2^>nul ^| findstr /v "hash"') do set "PHASH=%%h"
+  if defined PHASH (
+    set "PHASH=!PHASH:~0,12!"
+    del /q "%USERPROFILE%\.trace-mcp\db\!PHASH!.db" "%USERPROFILE%\.trace-mcp\db\!PHASH!.db-shm" "%USERPROFILE%\.trace-mcp\db\!PHASH!.db-wal" 2>nul
+  )
+)
+
+exit /b 0

package/hooks/trace-mcp-worktree.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# trace-mcp-worktree v0.1.0
+# trace-mcp WorktreeCreate / WorktreeRemove hook
+# On WorktreeCreate: registers and indexes the new worktree so trace-mcp tools work immediately.
+# On WorktreeRemove: deregisters the worktree project from the registry.
+#
+# Install: add to ~/.claude/settings.json or .claude/settings.local.json
+# See README.md for setup instructions.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Claude Code passes the event type via CLAUDE_HOOK_EVENT or hook_event_name
+EVENT="${CLAUDE_HOOK_EVENT:-}"
+if [[ -z "$EVENT" ]]; then
+  EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // .event // empty' 2>/dev/null)
+fi
+
+# Extract worktree path from hook input
+WORKTREE_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // .worktree_path // .path // empty' 2>/dev/null)
+
+if [[ -z "$WORKTREE_PATH" ]]; then
+  # Fallback: use working directory from input
+  WORKTREE_PATH=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+fi
+
+if [[ -z "$WORKTREE_PATH" ]]; then
+  exit 0
+fi
+
+# Resolve to absolute path
+WORKTREE_PATH=$(cd "$WORKTREE_PATH" 2>/dev/null && pwd || echo "$WORKTREE_PATH")
+
+case "$EVENT" in
+  WorktreeCreate|worktree_create|create)
+    # Register and index the new worktree in the background
+    # --force: re-register even if parent repo is already known (worktree is a different root)
+    nohup trace-mcp add "$WORKTREE_PATH" --force --json >/dev/null 2>&1 &
+    ;;
+  WorktreeRemove|worktree_remove|remove)
+    # Clean up the worktree DB file if it exists.
+    # The global registry entry becomes stale but is harmless — next `trace-mcp add` overwrites it.
+    PROJECT_HASH=""
+    if command -v sha256sum >/dev/null 2>&1; then
+      PROJECT_HASH=$(echo -n "$WORKTREE_PATH" | sha256sum | cut -c1-12)
+    elif command -v shasum >/dev/null 2>&1; then
+      PROJECT_HASH=$(echo -n "$WORKTREE_PATH" | shasum -a 256 | cut -c1-12)
+    fi
+    if [[ -n "$PROJECT_HASH" ]]; then
+      DB_FILE="$HOME/.trace-mcp/db/${PROJECT_HASH}.db"
+      rm -f "$DB_FILE" "$DB_FILE-shm" "$DB_FILE-wal" 2>/dev/null
+    fi
+    ;;
+esac
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-mcp",
-  "version": "1.4.1",
+  "version": "1.5.4",
   "description": "Framework-aware code intelligence MCP server — 48+ frameworks, 68 languages",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,7 @@
     "prepublishOnly": "npm run build"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=18.0.0"
   },
   "license": "ELv2",
   "author": "Nikolai Vysotskyi",