codesift-mcp 0.1.0 → 0.2.0

package/dist/utils/walk.js

@@ -0,0 +1,87 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+/**
+ * Directories to skip during filesystem walks.
+ * Shared by index-tools, search-tools, and (via toIgnorePatterns) watcher.
+ */
+export const IGNORE_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "coverage",
+    ".codesift", ".next", "__pycache__", ".pytest_cache",
+    ".venv", "venv", ".tox", ".mypy_cache", ".turbo",
+    "generated", "audit-results", ".backup", "jscpd-report",
+    "helpscout_export", ".output",
+]);
+/**
+ * Convert IGNORE_DIRS to chokidar-compatible glob patterns.
+ * e.g., "node_modules" -> "**\/node_modules/**"
+ */
+export function toIgnorePatterns() {
+    return [...IGNORE_DIRS].map((dir) => `**/${dir}/**`);
+}
+const DEFAULT_MAX_FILE_SIZE = 1_000_000; // 1MB
+/**
+ * Walk a directory tree collecting files.
+ * Skips directories listed in IGNORE_DIRS and hidden directories (dot-prefixed).
+ */
+export async function walkDirectory(rootPath, options) {
+    const files = [];
+    const maxFileSize = options?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const maxFiles = options?.maxFiles ?? Infinity;
+    const fileFilter = options?.fileFilter;
+    const includePaths = options?.includePaths;
+    const useRelative = options?.relative ?? false;
+    let limitReached = false;
+    async function walk(dirPath) {
+        if (limitReached)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dirPath, { withFileTypes: true });
+        }
+        catch {
+            return; // permission denied, etc.
+        }
+        for (const entry of entries) {
+            if (limitReached)
+                return;
+            const fullPath = join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const ext = extname(entry.name);
+                // Apply caller's file filter (e.g. language check, binary exclusion)
+                if (fileFilter && !fileFilter(ext, entry.name))
+                    continue;
+                // Filter by include paths if specified
+                if (includePaths && includePaths.length > 0) {
+                    const relPath = relative(rootPath, fullPath);
+                    const matches = includePaths.some((p) => relPath.startsWith(p));
+                    if (!matches)
+                        continue;
+                }
+                // Skip files that are too large
+                try {
+                    const fileStat = await stat(fullPath);
+                    if (fileStat.size > maxFileSize)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                files.push(useRelative ? relative(rootPath, fullPath) : fullPath);
+                if (files.length >= maxFiles) {
+                    console.warn(`[codesift] walkDirectory: reached ${maxFiles} file limit, returning partial results`);
+                    limitReached = true;
+                    return;
+                }
+            }
+        }
+    }
+    await walk(rootPath);
+    return files;
+}
+//# sourceMappingURL=walk.js.map

package/dist/utils/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../src/utils/walk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "codesift-mcp",
-  "version": "0.1.0",
-  "description": "MCP server for code intelligence — 21 tools for symbol search, call graph analysis, and semantic code retrieval",
-  "license": "MIT",
+  "version": "0.2.0",
+  "description": "MCP server for code intelligence — 39 tools for symbol search, call graph, semantic search, route tracing, community detection, LSP bridge, and HTML reporting",
+  "license": "BSL-1.1",
   "author": "Greg Laskowski",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "main": "./dist/server.js",
   "files": [
     "dist",
+    "rules",
     "src/parser/languages",
     "README.md",
     "LICENSE"
@@ -29,16 +30,21 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@sanity-labs/secret-scan": "^1.1.0",
     "chokidar": "^4.0.0",
     "ignore": "^6.0.0",
-    "web-tree-sitter": "^0.24.0"
+    "picomatch": "^4.0.3",
+    "web-tree-sitter": "^0.24.0",
+    "zod": "^4.3.6"
   },
   "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0",
     "openai": "^4.0.0",
     "voyageai": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.2",
     "@vitest/coverage-v8": "^3.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0",

package/rules/codesift.md

@@ -0,0 +1,187 @@
+<!-- codesift-rules v0.1.0 hash:PLACEHOLDER -->
+
+# CodeSift MCP — Agent Rules
+
+## Setup
+
+Run once per session:
+
+1. `list_repos()` — get the repo identifier (e.g. `local/codesift-mcp`). **Never call again** — cache the result.
+2. If the repo is missing: `index_folder(path=<root>)` once to index it.
+3. Use `"local/<folder-name>"` as the `repo` parameter for all tool calls.
+
+## Tool Discovery
+
+**63 MCP tools total** (13 core visible + 50 deferred/hidden).
+
+Only ~13 core tools appear in ListTools. Hidden tools are discovered on demand:
+
+- `discover_tools(query="dead code")` — keyword search across all 63 tools
+- `describe_tools(names=["find_dead_code"])` — get full parameter schema
+- `describe_tools(names=["find_dead_code"], reveal=true)` — also reveal in ListTools
+
+Core tools always visible: `search_text`, `search_symbols`, `get_file_outline`, `get_file_tree`, `get_symbol`, `get_symbols`, `find_references`, `find_and_show`, `codebase_retrieval`, `semantic_search`, `list_repos`, `index_file`, `discover_tools`, `describe_tools`.
+
+## Tool Mapping
+
+Use this table to pick the right tool for each task:
+
+| Task | Tool |
+|------|------|
+| text pattern search | `search_text(file_pattern=)` |
+| find function/class/type | `search_symbols(include_source=true)` |
+| file structure/outline | `get_file_outline` |
+| find files | `get_file_tree(compact=true)` |
+| read 1 symbol | `get_symbol` |
+| read 2+ symbols | `get_symbols` (batch) |
+| find usages | `find_references` |
+| symbol + refs in 1 call | `find_and_show(include_refs=true)` |
+| call chain | `trace_call_chain` |
+| blast radius | `impact_analysis(since="HEAD~3")` |
+| concept question | `semantic_search` or `codebase_retrieval(queries=[{type:"semantic",...}])` |
+| multi-search 3+ | `codebase_retrieval(queries=[...])` |
+| symbol in context | `get_context_bundle` |
+| dead code | `find_dead_code` |
+| complexity | `analyze_complexity` |
+| copy-paste | `find_clones` |
+| anti-patterns | `search_patterns` |
+| git churn | `analyze_hotspots` |
+| cross-repo | `cross_repo_search` |
+| circular deps | `find_circular_deps` or `get_knowledge_map(focus=)` |
+| mermaid diagram | `trace_call_chain(output_format="mermaid")` |
+| affected tests | `impact_analysis` → `.affected_tests` |
+| explore new repo | `suggest_queries` |
+| re-index 1 file | `index_file(path=)` |
+| route trace | `trace_route` |
+| code modules | `detect_communities(focus=)` |
+| go to definition | `go_to_definition` |
+| return type | `get_type_info` |
+| cross-file rename | `rename_symbol` |
+| scan secrets | `scan_secrets` |
+| search past sessions | `search_conversations` |
+| symbol ↔ conversation | `find_conversations_for_symbol` |
+| index conversations | `index_conversations` |
+| structural diff | `diff_outline(since=)` |
+| what changed | `changed_symbols(since=)` |
+
+## When to Use (Situational Triggers)
+
+| Situation | Tool |
+|-----------|------|
+| refactor/clean up | `analyze_complexity(top_n=10)` |
+| dead code/unused | `find_dead_code` |
+| unused imports | `find_unused_imports` |
+| DRY/duplication | `find_clones(min_similarity=0.7)` |
+| architecture/deps | `detect_communities(focus="src")` |
+| module boundaries | `check_boundaries` |
+| symbol roles (hub/leaf/bridge) | `classify_roles` |
+| structural code patterns | `ast_query` |
+| diagram/visualize | `trace_call_chain(output_format="mermaid")` |
+| hotspots/tech debt | `analyze_hotspots(since_days=90)` |
+| unfamiliar symbol | `get_context_bundle` |
+| new repo | `suggest_queries` |
+| trace endpoint | `trace_route` |
+| dense context (5+ symbols) | `assemble_context(level="L1")` |
+| overview only | `assemble_context(level="L3")` |
+| review git diff | `review_diff` |
+| code review / PR | `changed_symbols(since="HEAD~N")` + `diff_outline` |
+| quick symbol + refs | `find_and_show(include_refs=true)` |
+| error seen before | `search_conversations` |
+| before refactoring complex fn | `find_conversations_for_symbol` |
+| "we discussed this" | `search_conversations` |
+| secrets/leaked keys | `scan_secrets` |
+| security audit | `scan_secrets(min_confidence="high")` |
+| code audit | `search_patterns("empty-catch")` |
+| past decisions | `find_conversations_for_symbol` |
+
+## Key Parameters
+
+### search_symbols
+- `detail_level="compact"` — locations only (~15 tok/result vs ~150 default)
+- `token_budget=N` — cap output instead of guessing `top_k`
+- `file_pattern=` — always pass when scope is known (e.g. `"*.ts"`, `"src/tools/"`)
+- `kind=` — filter by type: `function`, `class`, `type`, `interface`
+- `include_source=true` — include source code in results
+
+### search_text
+- `group_by_file=true` — ~80% output reduction on many matches
+- `auto_group=true` — auto-switch to grouped above 50 matches
+- `ranked=true` — classifies hits by containing function, deduplicates (max 2/function), ranks by centrality. Returns `containing_symbol` field. Takes precedence over `auto_group`.
+- `file_pattern=` — always pass when scope is known
+
+### assemble_context levels
+- `L0` — full source (use when editing)
+- `L1` — signatures only (3× more symbols fit, use when reading)
+- `L2` — file summaries
+- `L3` — directory overview (91% less tokens, use for orientation)
+
+### codebase_retrieval
+- Always pass `token_budget` to cap output
+- Batch 3+ searches: `queries=[{type:"semantic",...},{type:"text",...}]`
+
+### get_knowledge_map
+- **ALWAYS pass `focus=`** — without it returns 129K+ tokens
+
+## Hint Codes
+
+The server appends hint codes to responses to guide tool usage. Act on them immediately.
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `H1(n)` | n matches returned | Add `group_by_file=true` |
+| `H2(n,tool)` | n consecutive identical calls | Batch into one `tool` call |
+| `H3(n)` | `list_repos` called n times | Reuse cached value |
+| `H4` | `include_source` without `file_pattern` | Add `file_pattern` |
+| `H5(path)` | Duplicate `get_file_tree` | Use cached result |
+| `H6(n)` | n results without `detail_level` | Add `detail_level='compact'` |
+| `H7` | `get_symbol` after `search_symbols` | Use `get_context_bundle` |
+| `H8(n)` | n× `get_symbol` calls | Use `assemble_context(level='L1')` |
+| `H9` | Question-word text query | Use semantic search |
+
+## ALWAYS
+
+- Use `semantic_search` or `codebase_retrieval(type:"semantic")` for conceptual questions
+- Use `trace_route` FIRST for any API endpoint — NEVER multiple `search_text` + `trace_call_chain`
+- Use `detect_communities` BEFORE `get_knowledge_map` — NEVER `knowledge_map` without communities first
+- Use `index_file(path)` after editing — NEVER `index_folder` (9ms vs 3-8s)
+- Pass `include_source=true` on `search_symbols`
+- Use `get_symbols` (batch) for 2+ symbols — NEVER sequential `get_symbol`
+- Batch 3+ searches into `codebase_retrieval`
+- Use `search_conversations` when encountering error/bug that may have been solved before
+- Use `Read` tool when file path is already known — CodeSift excels at discovery
+
+## NEVER
+
+- Call `index_folder` if repo already in `list_repos` — file watcher auto-updates
+- Call `list_repos` more than once per session
+- Use manual Edit on multiple files for rename — use `rename_symbol`
+- Read entire file just to get a return type — use `get_type_info`
+- Index worktrees — use the main repo index
+- Call `get_knowledge_map` without `focus=` parameter
+
+## Response Cascade
+
+Large responses auto-shorten to stay within token limits:
+
+| Threshold | Format | Annotation |
+|-----------|--------|------------|
+| > 52,500 chars | compact format | `[compact]` prepended |
+| > 87,500 chars | counts only | `[counts]` prepended |
+| > 105,000 chars | hard truncate | `[truncated]` prepended |
+
+Cascade is **skipped** when `detail_level` or `token_budget` is explicitly set.
+
+## Hooks
+
+Setup auto-indexing and read-redirect hooks for Claude Code:
+
+```
+codesift setup claude --hooks
+```
+
+Installs two hooks in `.claude/settings.local.json`:
+
+- **PreToolUse** (`precheck-read`) — redirects `Read` on large code files to CodeSift tools
+- **PostToolUse** (`postindex-file`) — auto-runs `index_file` after `Edit` or `Write`
+
+This ensures the index stays current without manual `index_file` calls after every edit.

package/rules/codesift.mdc

@@ -0,0 +1,192 @@
+---
+description: CodeSift MCP tool usage rules
+globs: **/*
+alwaysApply: true
+---
+<!-- codesift-rules v0.1.0 hash:PLACEHOLDER -->
+
+# CodeSift MCP — Agent Rules
+
+## Setup
+
+Run once per session:
+
+1. `list_repos()` — get the repo identifier (e.g. `local/codesift-mcp`). **Never call again** — cache the result.
+2. If the repo is missing: `index_folder(path=<root>)` once to index it.
+3. Use `"local/<folder-name>"` as the `repo` parameter for all tool calls.
+
+## Tool Discovery
+
+**63 MCP tools total** (13 core visible + 50 deferred/hidden).
+
+Only ~13 core tools appear in ListTools. Hidden tools are discovered on demand:
+
+- `discover_tools(query="dead code")` — keyword search across all 63 tools
+- `describe_tools(names=["find_dead_code"])` — get full parameter schema
+- `describe_tools(names=["find_dead_code"], reveal=true)` — also reveal in ListTools
+
+Core tools always visible: `search_text`, `search_symbols`, `get_file_outline`, `get_file_tree`, `get_symbol`, `get_symbols`, `find_references`, `find_and_show`, `codebase_retrieval`, `semantic_search`, `list_repos`, `index_file`, `discover_tools`, `describe_tools`.
+
+## Tool Mapping
+
+Use this table to pick the right tool for each task:
+
+| Task | Tool |
+|------|------|
+| text pattern search | `search_text(file_pattern=)` |
+| find function/class/type | `search_symbols(include_source=true)` |
+| file structure/outline | `get_file_outline` |
+| find files | `get_file_tree(compact=true)` |
+| read 1 symbol | `get_symbol` |
+| read 2+ symbols | `get_symbols` (batch) |
+| find usages | `find_references` |
+| symbol + refs in 1 call | `find_and_show(include_refs=true)` |
+| call chain | `trace_call_chain` |
+| blast radius | `impact_analysis(since="HEAD~3")` |
+| concept question | `semantic_search` or `codebase_retrieval(queries=[{type:"semantic",...}])` |
+| multi-search 3+ | `codebase_retrieval(queries=[...])` |
+| symbol in context | `get_context_bundle` |
+| dead code | `find_dead_code` |
+| complexity | `analyze_complexity` |
+| copy-paste | `find_clones` |
+| anti-patterns | `search_patterns` |
+| git churn | `analyze_hotspots` |
+| cross-repo | `cross_repo_search` |
+| circular deps | `find_circular_deps` or `get_knowledge_map(focus=)` |
+| mermaid diagram | `trace_call_chain(output_format="mermaid")` |
+| affected tests | `impact_analysis` → `.affected_tests` |
+| explore new repo | `suggest_queries` |
+| re-index 1 file | `index_file(path=)` |
+| route trace | `trace_route` |
+| code modules | `detect_communities(focus=)` |
+| go to definition | `go_to_definition` |
+| return type | `get_type_info` |
+| cross-file rename | `rename_symbol` |
+| scan secrets | `scan_secrets` |
+| search past sessions | `search_conversations` |
+| symbol ↔ conversation | `find_conversations_for_symbol` |
+| index conversations | `index_conversations` |
+| structural diff | `diff_outline(since=)` |
+| what changed | `changed_symbols(since=)` |
+
+## When to Use (Situational Triggers)
+
+| Situation | Tool |
+|-----------|------|
+| refactor/clean up | `analyze_complexity(top_n=10)` |
+| dead code/unused | `find_dead_code` |
+| unused imports | `find_unused_imports` |
+| DRY/duplication | `find_clones(min_similarity=0.7)` |
+| architecture/deps | `detect_communities(focus="src")` |
+| module boundaries | `check_boundaries` |
+| symbol roles (hub/leaf/bridge) | `classify_roles` |
+| structural code patterns | `ast_query` |
+| diagram/visualize | `trace_call_chain(output_format="mermaid")` |
+| hotspots/tech debt | `analyze_hotspots(since_days=90)` |
+| unfamiliar symbol | `get_context_bundle` |
+| new repo | `suggest_queries` |
+| trace endpoint | `trace_route` |
+| dense context (5+ symbols) | `assemble_context(level="L1")` |
+| overview only | `assemble_context(level="L3")` |
+| review git diff | `review_diff` |
+| code review / PR | `changed_symbols(since="HEAD~N")` + `diff_outline` |
+| quick symbol + refs | `find_and_show(include_refs=true)` |
+| error seen before | `search_conversations` |
+| before refactoring complex fn | `find_conversations_for_symbol` |
+| "we discussed this" | `search_conversations` |
+| secrets/leaked keys | `scan_secrets` |
+| security audit | `scan_secrets(min_confidence="high")` |
+| code audit | `search_patterns("empty-catch")` |
+| past decisions | `find_conversations_for_symbol` |
+
+## Key Parameters
+
+### search_symbols
+- `detail_level="compact"` — locations only (~15 tok/result vs ~150 default)
+- `token_budget=N` — cap output instead of guessing `top_k`
+- `file_pattern=` — always pass when scope is known (e.g. `"*.ts"`, `"src/tools/"`)
+- `kind=` — filter by type: `function`, `class`, `type`, `interface`
+- `include_source=true` — include source code in results
+
+### search_text
+- `group_by_file=true` — ~80% output reduction on many matches
+- `auto_group=true` — auto-switch to grouped above 50 matches
+- `ranked=true` — classifies hits by containing function, deduplicates (max 2/function), ranks by centrality. Returns `containing_symbol` field. Takes precedence over `auto_group`.
+- `file_pattern=` — always pass when scope is known
+
+### assemble_context levels
+- `L0` — full source (use when editing)
+- `L1` — signatures only (3× more symbols fit, use when reading)
+- `L2` — file summaries
+- `L3` — directory overview (91% less tokens, use for orientation)
+
+### codebase_retrieval
+- Always pass `token_budget` to cap output
+- Batch 3+ searches: `queries=[{type:"semantic",...},{type:"text",...}]`
+
+### get_knowledge_map
+- **ALWAYS pass `focus=`** — without it returns 129K+ tokens
+
+## Hint Codes
+
+The server appends hint codes to responses to guide tool usage. Act on them immediately.
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `H1(n)` | n matches returned | Add `group_by_file=true` |
+| `H2(n,tool)` | n consecutive identical calls | Batch into one `tool` call |
+| `H3(n)` | `list_repos` called n times | Reuse cached value |
+| `H4` | `include_source` without `file_pattern` | Add `file_pattern` |
+| `H5(path)` | Duplicate `get_file_tree` | Use cached result |
+| `H6(n)` | n results without `detail_level` | Add `detail_level='compact'` |
+| `H7` | `get_symbol` after `search_symbols` | Use `get_context_bundle` |
+| `H8(n)` | n× `get_symbol` calls | Use `assemble_context(level='L1')` |
+| `H9` | Question-word text query | Use semantic search |
+
+## ALWAYS
+
+- Use `semantic_search` or `codebase_retrieval(type:"semantic")` for conceptual questions
+- Use `trace_route` FIRST for any API endpoint — NEVER multiple `search_text` + `trace_call_chain`
+- Use `detect_communities` BEFORE `get_knowledge_map` — NEVER `knowledge_map` without communities first
+- Use `index_file(path)` after editing — NEVER `index_folder` (9ms vs 3-8s)
+- Pass `include_source=true` on `search_symbols`
+- Use `get_symbols` (batch) for 2+ symbols — NEVER sequential `get_symbol`
+- Batch 3+ searches into `codebase_retrieval`
+- Use `search_conversations` when encountering error/bug that may have been solved before
+- Use `Read` tool when file path is already known — CodeSift excels at discovery
+
+## NEVER
+
+- Call `index_folder` if repo already in `list_repos` — file watcher auto-updates
+- Call `list_repos` more than once per session
+- Use manual Edit on multiple files for rename — use `rename_symbol`
+- Read entire file just to get a return type — use `get_type_info`
+- Index worktrees — use the main repo index
+- Call `get_knowledge_map` without `focus=` parameter
+
+## Response Cascade
+
+Large responses auto-shorten to stay within token limits:
+
+| Threshold | Format | Annotation |
+|-----------|--------|------------|
+| > 52,500 chars | compact format | `[compact]` prepended |
+| > 87,500 chars | counts only | `[counts]` prepended |
+| > 105,000 chars | hard truncate | `[truncated]` prepended |
+
+Cascade is **skipped** when `detail_level` or `token_budget` is explicitly set.
+
+## Hooks
+
+Setup auto-indexing and read-redirect hooks for Claude Code:
+
+```
+codesift setup claude --hooks
+```
+
+Installs two hooks in `.claude/settings.local.json`:
+
+- **PreToolUse** (`precheck-read`) — redirects `Read` on large code files to CodeSift tools
+- **PostToolUse** (`postindex-file`) — auto-runs `index_file` after `Edit` or `Write`
+
+This ensures the index stays current without manual `index_file` calls after every edit.