mcp-code-context 2.6.0 → 3.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/CHANGELOG.md +92 -260
  2. package/README.md +304 -298
  3. package/dist/src/core/engine.d.ts +21 -0
  4. package/dist/src/core/engine.js +68 -0
  5. package/dist/src/core/engine.js.map +1 -0
  6. package/dist/src/core/validator.d.ts +15 -0
  7. package/dist/src/core/validator.js +44 -0
  8. package/dist/src/core/validator.js.map +1 -0
  9. package/dist/src/index.d.ts +7 -11
  10. package/dist/src/index.js +182 -397
  11. package/dist/src/index.js.map +1 -1
  12. package/dist/src/operations/write.d.ts +51 -0
  13. package/dist/src/operations/write.js +169 -0
  14. package/dist/src/operations/write.js.map +1 -0
  15. package/dist/src/parsers/base.d.ts +28 -0
  16. package/dist/src/parsers/base.js +27 -0
  17. package/dist/src/parsers/base.js.map +1 -0
  18. package/dist/src/parsers/dartTreeSitter.d.ts +13 -0
  19. package/dist/src/parsers/dartTreeSitter.js +91 -0
  20. package/dist/src/parsers/dartTreeSitter.js.map +1 -0
  21. package/dist/src/parsers/php.d.ts +12 -0
  22. package/dist/src/parsers/php.js +86 -0
  23. package/dist/src/parsers/php.js.map +1 -0
  24. package/dist/src/parsers/python.d.ts +12 -0
  25. package/dist/src/parsers/python.js +86 -0
  26. package/dist/src/parsers/python.js.map +1 -0
  27. package/dist/src/parsers/registry.d.ts +15 -0
  28. package/dist/src/parsers/registry.js +70 -0
  29. package/dist/src/parsers/registry.js.map +1 -0
  30. package/dist/src/parsers/typescript.d.ts +13 -0
  31. package/dist/src/parsers/typescript.js +98 -0
  32. package/dist/src/parsers/typescript.js.map +1 -0
  33. package/llms.txt +246 -236
  34. package/mcp-code-context-3.0.2.tgz +0 -0
  35. package/package.json +59 -57
  36. package/tsconfig.tests.json +27 -0
  37. package/.io/RULES.md +0 -12
  38. package/CONTRIBUTING.md +0 -243
  39. package/TROUBLESHOOTING.md +0 -38
  40. package/dist/src/ast/dartCompressor.d.ts +0 -27
  41. package/dist/src/ast/dartCompressor.js +0 -859
  42. package/dist/src/ast/dartCompressor.js.map +0 -1
  43. package/dist/src/ast/phpCompressor.d.ts +0 -24
  44. package/dist/src/ast/phpCompressor.js +0 -634
  45. package/dist/src/ast/phpCompressor.js.map +0 -1
  46. package/dist/src/ast/semanticCompressor.d.ts +0 -22
  47. package/dist/src/ast/semanticCompressor.js +0 -677
  48. package/dist/src/ast/semanticCompressor.js.map +0 -1
  49. package/dist/src/ast/writers/dartWriter.d.ts +0 -37
  50. package/dist/src/ast/writers/dartWriter.js +0 -544
  51. package/dist/src/ast/writers/dartWriter.js.map +0 -1
  52. package/dist/src/ast/writers/phpWriter.d.ts +0 -37
  53. package/dist/src/ast/writers/phpWriter.js +0 -411
  54. package/dist/src/ast/writers/phpWriter.js.map +0 -1
  55. package/dist/src/ast/writers/pyWriter.d.ts +0 -37
  56. package/dist/src/ast/writers/pyWriter.js +0 -355
  57. package/dist/src/ast/writers/pyWriter.js.map +0 -1
  58. package/dist/src/ast/writers/safeRename.d.ts +0 -14
  59. package/dist/src/ast/writers/safeRename.js +0 -258
  60. package/dist/src/ast/writers/safeRename.js.map +0 -1
  61. package/dist/src/ast/writers/symbolWriter.d.ts +0 -64
  62. package/dist/src/ast/writers/symbolWriter.js +0 -174
  63. package/dist/src/ast/writers/symbolWriter.js.map +0 -1
  64. package/dist/src/ast/writers/tsWriter.d.ts +0 -38
  65. package/dist/src/ast/writers/tsWriter.js +0 -344
  66. package/dist/src/ast/writers/tsWriter.js.map +0 -1
  67. package/dist/src/cache/astCache.d.ts +0 -39
  68. package/dist/src/cache/astCache.js +0 -169
  69. package/dist/src/cache/astCache.js.map +0 -1
  70. package/dist/src/handlers/readHandlers.d.ts +0 -70
  71. package/dist/src/handlers/readHandlers.js +0 -455
  72. package/dist/src/handlers/readHandlers.js.map +0 -1
  73. package/dist/src/handlers/utilHandlers.d.ts +0 -31
  74. package/dist/src/handlers/utilHandlers.js +0 -69
  75. package/dist/src/handlers/utilHandlers.js.map +0 -1
  76. package/dist/src/handlers/writeHandlers.d.ts +0 -57
  77. package/dist/src/handlers/writeHandlers.js +0 -499
  78. package/dist/src/handlers/writeHandlers.js.map +0 -1
  79. package/dist/src/tools/readFileLines.d.ts +0 -26
  80. package/dist/src/tools/readFileLines.js +0 -77
  81. package/dist/src/tools/readFileLines.js.map +0 -1
  82. package/dist/src/tools/searchCodePattern.d.ts +0 -37
  83. package/dist/src/tools/searchCodePattern.js +0 -144
  84. package/dist/src/tools/searchCodePattern.js.map +0 -1
  85. package/dist/src/utils/arrayUtils.d.ts +0 -12
  86. package/dist/src/utils/arrayUtils.js +0 -27
  87. package/dist/src/utils/arrayUtils.js.map +0 -1
  88. package/dist/src/utils/backupManager.d.ts +0 -31
  89. package/dist/src/utils/backupManager.js +0 -124
  90. package/dist/src/utils/backupManager.js.map +0 -1
  91. package/dist/src/utils/confirmationCache.d.ts +0 -16
  92. package/dist/src/utils/confirmationCache.js +0 -40
  93. package/dist/src/utils/confirmationCache.js.map +0 -1
  94. package/dist/src/utils/constants.d.ts +0 -46
  95. package/dist/src/utils/constants.js +0 -112
  96. package/dist/src/utils/constants.js.map +0 -1
  97. package/dist/src/utils/dependencyChecker.d.ts +0 -1
  98. package/dist/src/utils/dependencyChecker.js +0 -55
  99. package/dist/src/utils/dependencyChecker.js.map +0 -1
  100. package/dist/src/utils/diffEngine.d.ts +0 -21
  101. package/dist/src/utils/diffEngine.js +0 -163
  102. package/dist/src/utils/diffEngine.js.map +0 -1
  103. package/dist/src/utils/fuzzyMatch.d.ts +0 -8
  104. package/dist/src/utils/fuzzyMatch.js +0 -70
  105. package/dist/src/utils/fuzzyMatch.js.map +0 -1
  106. package/dist/src/utils/ignoreManager.d.ts +0 -29
  107. package/dist/src/utils/ignoreManager.js +0 -144
  108. package/dist/src/utils/ignoreManager.js.map +0 -1
  109. package/dist/src/utils/normalization.d.ts +0 -49
  110. package/dist/src/utils/normalization.js +0 -173
  111. package/dist/src/utils/normalization.js.map +0 -1
  112. package/dist/src/utils/projectRoot.d.ts +0 -17
  113. package/dist/src/utils/projectRoot.js +0 -42
  114. package/dist/src/utils/projectRoot.js.map +0 -1
  115. package/dist/src/utils/secureValidation.d.ts +0 -15
  116. package/dist/src/utils/secureValidation.js +0 -41
  117. package/dist/src/utils/secureValidation.js.map +0 -1
  118. package/dist/src/utils/syntaxValidator.d.ts +0 -15
  119. package/dist/src/utils/syntaxValidator.js +0 -218
  120. package/dist/src/utils/syntaxValidator.js.map +0 -1
  121. package/dist/src/utils/transactionManager.d.ts +0 -46
  122. package/dist/src/utils/transactionManager.js +0 -123
  123. package/dist/src/utils/transactionManager.js.map +0 -1
  124. package/dist/src/utils/validation.d.ts +0 -87
  125. package/dist/src/utils/validation.js +0 -231
  126. package/dist/src/utils/validation.js.map +0 -1
  127. package/docs/ARCHITECTURE.md +0 -300
  128. package/docs/architecture/ADR-001-modular-handlers.md +0 -119
package/llms.txt CHANGED
@@ -1,236 +1,246 @@
1
- # mcp-code-context v2.6.0
2
-
3
- > A Model Context Protocol (MCP) server that compresses any code repository into LLM-ready semantic context and provides surgical code editing tools.
4
-
5
- ## What's New in v2.6.0
6
-
7
- 🚀 **Async I/O Migration**: Non-blocking architecture
8
- - ✅ Eliminated all synchronous file operations
9
- - ✅ Event loop never blocks on large repositories
10
- - ✅ 3x faster on repos with 1000+ files
11
- - ✅ Scalability: 4.0 → 9.0 (+5.0)
12
- - ✅ Fuzzy match with distance threshold (reduces noise)
13
-
14
- ## What's New in v2.5.1
15
-
16
- 🔒 **Critical Reliability Fixes**:
17
- - ✅ Race condition prevention with cache versioning
18
- - ✅ Post-write syntax validation (zero broken files)
19
- - ✅ Circuit breaker for batch operations
20
- - ✅ Data integrity: 95% → 100%
21
-
22
- ## What This Tool Does
23
-
24
- This MCP server solves two problems:
25
- 1. **Token bloat on reads**: When an LLM needs to understand a large codebase, sending raw source files wastes most of the context window. This server extracts only structural signatures.
26
- 2. **Imprecise writes**: When an LLM needs to edit code, rewriting entire files is error-prone and expensive. This server enables symbol-level surgical edits.
27
-
28
- ## Available Tools
29
-
30
- ### Read Tools
31
-
32
- #### 1. `get_semantic_repo_map`
33
- **Purpose:** Generate a compressed architectural map of an entire repository.
34
-
35
- **Input:**
36
- - `directoryPath` (required): Absolute path to the repository root.
37
- - `format` (optional): `"xml"` (default) or `"markdown"`.
38
-
39
- **What it does:**
40
- - Walks the directory tree respecting `.gitignore` and `.repomixignore` rules.
41
- - Always excludes `node_modules`, `dist`, `build`, `vendor`, `.git`.
42
- - For TypeScript/JavaScript: Uses AST parsing (ts-morph) to extract only function signatures, class structures, interfaces, types, and enums.
43
- - For PHP: Uses AST parsing (php-parser) to extract namespaces, classes, interfaces, traits, enums, methods, properties, and docblocks.
44
- - For Dart: Uses brace-counting + regex engine to extract classes, mixins, extensions, enums, methods, and fields.
45
- - For Python: Uses regex-based extraction to capture class/function signatures and docstrings.
46
- - For other files: Returns content as-is if small, or a truncated preview if large.
47
-
48
- **Best used when:** You need to understand the architecture of a project before diving into specific files.
49
-
50
- #### 2. `read_file_surgical`
51
- **Purpose:** Read a full file or extract only a specific named symbol.
52
-
53
- **Input:**
54
- - `filePath` (required): Absolute path to the source file.
55
- - `symbolName` (optional): Name of a function, class, interface, method, or type to extract.
56
-
57
- **What it does:**
58
- - With `symbolName`: Parses the AST and returns only the full source code block for that symbol. Saves tokens when you only need one function from a large file.
59
- - If missing: Returns structured JSON with `available_symbols` and `suggestions` (e.g., suggesting a `className` scope).
60
-
61
- **Best used when:** You identified a symbol from the repo map and need to see its full implementation.
62
-
63
- #### 3. `analyze_impact`
64
- **Purpose:** Find all files that depend on a given file.
65
-
66
- **Input:**
67
- - `filePath` (required): Absolute path to the file being modified.
68
- - `rootDir` (optional): Repository root. Auto-detected if omitted.
69
-
70
- **What it does:**
71
- - Scans all source files for `import`, `require()`, Python `from/import`, PHP `use`/`require_once`/`include`, and Dart `import` statements.
72
- - Resolves relative paths to determine if they point to the target file.
73
- - Returns a structured report listing every dependent file and the specific import statement.
74
-
75
- **Best used when:** You're about to modify a file and need to understand the blast radius.
76
-
77
- #### 4. `read_file_lines`
78
- **Purpose:** Read specific line ranges from a file without loading the entire content.
79
-
80
- **Input:**
81
- - `filePath` (required): Absolute path to the source file.
82
- - `startLine` (optional): Starting line number (1-indexed).
83
- - `endLine` (optional): Ending line number (1-indexed).
84
- - `aroundPattern` (optional): Search pattern to find and return surrounding lines.
85
- - `contextLines` (optional): Number of lines before/after pattern (default: 5).
86
-
87
- **What it does:**
88
- - **Mode 1 (Exact Range)**: When `startLine` and `endLine` are provided, returns only those lines.
89
- - **Mode 2 (Pattern Search)**: When `aroundPattern` is provided, finds the first occurrence and returns surrounding lines with context.
90
- - Validates line ranges and provides clear error messages.
91
- - 90% token savings compared to reading full files for small fragments.
92
-
93
- **Best used when:**
94
- - Debugging specific code blocks when you know the line numbers
95
- - Viewing context around error messages or logs
96
- - Extracting small fragments without AST parsing overhead
97
-
98
- **Example use cases:**
99
- - "Show me lines 120-135 of coordinator.dart"
100
- - "Show me the code around 'HeroBannerWidget' in hero_banner_widget.dart"
101
-
102
- #### 5. `search_code_pattern`
103
- **Purpose:** Search for code patterns across multiple files in a repository.
104
-
105
- **Input:**
106
- - `rootDir` (required): Absolute path to the repository root.
107
- - `pattern` (required): Regular expression pattern to search for.
108
- - `fileExtensions` (optional): Array of extensions to search (e.g., `[".ts", ".dart"]`). Defaults to common code extensions.
109
- - `excludeDirs` (optional): Directories to exclude (default: `["node_modules", "dist", "build"]`).
110
- - `showContext` (optional): Include surrounding lines (default: true).
111
- - `contextLines` (optional): Number of context lines before/after (default: 3).
112
- - `maxResults` (optional): Maximum matches to return (default: 50).
113
-
114
- **What it does:**
115
- - Walks the repository respecting `.gitignore` rules.
116
- - Searches for regex patterns across all matching files.
117
- - Returns structured results with file paths, line numbers, and optional context.
118
- - Highlights the matching line with a `>` marker in context output.
119
- - 85% more efficient than manual grep + analysis workflows.
120
-
121
- **Best used when:**
122
- - Finding all usages of a function or variable
123
- - Locating specific log statements or debug markers
124
- - Discovering patterns across the codebase
125
- - Understanding how a feature is implemented across files
126
-
127
- **Example use cases:**
128
- - "Find all occurrences of 'widget.height' in the Flutter project"
129
- - "Search for '🎯 \[BUILDER\]' logs in .dart files"
130
- - "Find all files that call 'HeroBannerWidget'"
131
-
132
- #### 6. `rollback_file`
133
- **Purpose:** Restores a file to a previous state from the automated backup system.
134
- **Input:**
135
- - `filePath` (required): Absolute path.
136
- - `steps` (optional): Number of versions to go back (1-5, default: 1).
137
- **What it does:** Reverts the file to the state it was in before the last 1-5 modifications.
138
-
139
- ### Write Tools (v2.2.0 Mandatory Workflow)
140
-
141
- All write tools follow a **Two-Phase Workflow**:
142
- 1. **Phase 1 (Preview)**: Call without a token to get a unified `diff` and a `confirmationToken`.
143
- 2. **Phase 2 (Apply)**: Call with `confirmationToken` and `confirm: true` to apply the changes.
144
-
145
- **Important Notes (v2.2.0):**
146
- - ✅ **Windows CRLF Support**: Fully resolved. All operations work correctly on Windows files with CRLF line endings.
147
- - ✅ **Parameter Brace Handling**: Methods with braces in parameters (e.g., `{int? cart}`) are now handled correctly.
148
-
149
- #### 7. `write_file_surgical`
150
- **Purpose:** Replace the full source code of a named symbol in a file.
151
-
152
- **Input:**
153
- - `filePath` (required): Absolute path to the file to modify.
154
- - `symbolName` (required): Name of the symbol to replace.
155
- - `newContent` (required): Complete replacement code (signature + body).
156
- - `confirmationToken` (optional): Token from Phase 1.
157
- - `confirm` (optional): Set to `true` to apply.
158
- - `className` (optional): Scope the symbol to a specific class.
159
-
160
- **What it does:**
161
- - Locates the symbol via AST parsing (ts-morph, php-parser, brace-counting, or indentation detection).
162
- - Replaces only that symbol's code, preserving all other file contents.
163
- - Returns a unified diff showing exactly what changed.
164
- - Validates the result is syntactically valid before writing.
165
-
166
- **Best used when:** You need to modify a specific function or method without touching the rest of the file.
167
-
168
- #### 8. `insert_symbol`
169
- **Purpose:** Insert new code at a precise location relative to an existing symbol.
170
-
171
- **Input:**
172
- - `filePath` (required): Absolute path to the file.
173
- - `code` (required): The new code to insert.
174
- - `anchorSymbol` (optional): Symbol name to position relative to. If omitted, inserts at end of file.
175
- - `position` (optional): `"before"`, `"after"`, `"inside_start"`, `"inside_end"`. Defaults to `"after"`.
176
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
177
-
178
- **What it does:**
179
- - Finds the anchor symbol and inserts new code at the specified position.
180
- - Automatically matches the surrounding indentation style.
181
- - `inside_start` and `inside_end` insert as members inside a class or interface.
182
-
183
- **Best used when:** Adding new methods to a class or new functions to a module.
184
-
185
- #### 9. `rename_symbol`
186
- **Purpose:** Rename a symbol across an entire repository.
187
-
188
- **Input:**
189
- - `filePath` (required): File where the symbol is defined.
190
- - `oldName` (required): Current name.
191
- - `newName` (required): New name.
192
- - `rootDir` (optional): Repository root. Auto-detected if omitted.
193
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
194
-
195
- **What it does:**
196
- - Renames the symbol definition in the source file.
197
- - Finds all dependent files using import analysis.
198
- - Renames all references in dependent files using whole-word replacement.
199
- - Returns a multi-file diff showing all changes.
200
- - Rolls back all changes if any file write fails.
201
-
202
- **Best used when:** Refactoring a class, function, or method name that is used across multiple files.
203
-
204
- #### 10. `remove_symbol`
205
- **Purpose:** Safely remove a symbol from a file.
206
-
207
- **Input:**
208
- - `filePath` (required): Absolute path.
209
- - `symbolName` (required): Symbol to remove.
210
- - `force` (optional): If true, skip dependency check. Defaults to false.
211
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
212
-
213
- **What it does:**
214
- - Checks if other files reference the symbol (unless `force: true`).
215
- - If dependents exist, refuses to remove and reports which files use it.
216
- - If safe, removes the symbol's code and cleans up whitespace.
217
-
218
- **Best used when:** Cleaning up deprecated functions or unused code.
219
-
220
- ## Recommended Workflow
221
-
222
- 1. **Start with `get_semantic_repo_map`** to understand the project structure.
223
- 2. **Use `read_file_surgical`** with a symbol name. Use suggestions if the symbol is missing.
224
- 3. **Before modifying, run `analyze_impact`** to know the blast radius.
225
- 4. **Phase 1: Preview Edit** → Call write tools to get a `diff` and `confirmationToken`.
226
- 5. **Phase 2: Apply Edit** → Verify the diff, then call with the token and `confirm: true`.
227
- 6. **Recovery** → Use `rollback_file` if needed.
228
-
229
- ## Technical Details
230
-
231
- - **Transport:** stdio (JSON-RPC over stdin/stdout)
232
- - **Runtime:** Node.js >= 18
233
- - **AST Engines:** ts-morph (TypeScript/JS), php-parser (PHP), brace-counting/regex (Dart, Python)
234
- - **Ignore Engine:** `ignore` npm package (full .gitignore spec support)
235
- - **Supported languages:** TypeScript, JavaScript (all variants), PHP, Dart, Python
236
- - **Safety features:** Mandatory two-phase confirmation, rolling 5-version backups (`.mcp-backups/`), fuzzy symbol suggestions, dependency tracking, surgical restoration.
1
+ # mcp-code-context v3.0.6
2
+
3
+ > A Model Context Protocol (MCP) server with **Tree-sitter WASM parsers** for 100% AST accuracy. Zero native dependencies.
4
+
5
+ ## What's New in v3.0.6
6
+
7
+ 🔧 **npx Compatibility Fix**:
8
+ - ✅ Fixed npx execution on Windows
9
+ - ✅ Reverted to v2 build structure (dist/src/index.js)
10
+ - ✅ Works with Claude Desktop using npx -y
11
+
12
+ ## What's New in v3.0.6
13
+
14
+ 🔧 **NPM Package Optimization**:
15
+ - ✅ Package size reduced: 658.6 kB → 105.5 kB (-84%)
16
+ - ✅ File count reduced: 131 files → 36 files (-73%)
17
+ - ✅ Clean dist/ structure (no nested dist/src/)
18
+ - ✅ Excluded legacy v2 code from npm distribution
19
+
20
+ ## What's New in v3.0.6
21
+
22
+ 🚀 **Complete WASM Migration**: 100% portable architecture
23
+ - ✅ Migrated to web-tree-sitter@0.25.1 (WASM)
24
+ - ✅ Zero native dependencies (no Visual Studio, node-gyp, Python)
25
+ - ✅ Works on Windows/Mac/Linux without compilation
26
+ - ✅ Dart with full Tree-sitter AST (no regex fallback)
27
+ - ✅ TypeScript/JavaScript/Python/PHP all use WASM parsers
28
+ - ✅ ABI v15 support (latest language grammars)
29
+
30
+ ## What This Tool Does
31
+
32
+ This MCP server solves two problems:
33
+ 1. **Token bloat on reads**: When an LLM needs to understand a large codebase, sending raw source files wastes most of the context window. This server extracts only structural signatures.
34
+ 2. **Imprecise writes**: When an LLM needs to edit code, rewriting entire files is error-prone and expensive. This server enables symbol-level surgical edits.
35
+
36
+ ## Available Tools
37
+
38
+ ### Read Tools
39
+
40
+ #### 1. `get_semantic_repo_map`
41
+ **Purpose:** Generate a compressed architectural map of an entire repository.
42
+
43
+ **Input:**
44
+ - `directoryPath` (required): Absolute path to the repository root.
45
+ - `format` (optional): `"xml"` (default) or `"markdown"`.
46
+
47
+ **What it does:**
48
+ - Walks the directory tree respecting `.gitignore` and `.repomixignore` rules.
49
+ - Always excludes `node_modules`, `dist`, `build`, `vendor`, `.git`.
50
+ - For TypeScript/JavaScript: Uses Tree-sitter WASM to extract function signatures, class structures, interfaces, types, and enums.
51
+ - For PHP: Uses Tree-sitter WASM to extract namespaces, classes, interfaces, traits, enums, methods, properties.
52
+ - For Dart: Uses Tree-sitter WASM to extract classes, mixins, extensions, enums, methods, and fields.
53
+ - For Python: Uses Tree-sitter WASM to capture class/function signatures and docstrings.
54
+ - For other files: Returns content as-is if small, or a truncated preview if large.
55
+
56
+ **Best used when:** You need to understand the architecture of a project before diving into specific files.
57
+
58
+ #### 2. `read_file_surgical`
59
+ **Purpose:** Read a full file or extract only a specific named symbol.
60
+
61
+ **Input:**
62
+ - `filePath` (required): Absolute path to the source file.
63
+ - `symbolName` (optional): Name of a function, class, interface, method, or type to extract.
64
+
65
+ **What it does:**
66
+ - With `symbolName`: Parses the AST and returns only the full source code block for that symbol. Saves tokens when you only need one function from a large file.
67
+ - If missing: Returns structured JSON with `available_symbols` and `suggestions` (e.g., suggesting a `className` scope).
68
+
69
+ **Best used when:** You identified a symbol from the repo map and need to see its full implementation.
70
+
71
+ #### 3. `analyze_impact`
72
+ **Purpose:** Find all files that depend on a given file.
73
+
74
+ **Input:**
75
+ - `filePath` (required): Absolute path to the file being modified.
76
+ - `rootDir` (optional): Repository root. Auto-detected if omitted.
77
+
78
+ **What it does:**
79
+ - Scans all source files for `import`, `require()`, Python `from/import`, PHP `use`/`require_once`/`include`, and Dart `import` statements.
80
+ - Resolves relative paths to determine if they point to the target file.
81
+ - Returns a structured report listing every dependent file and the specific import statement.
82
+
83
+ **Best used when:** You're about to modify a file and need to understand the blast radius.
84
+
85
+ #### 4. `read_file_lines`
86
+ **Purpose:** Read specific line ranges from a file without loading the entire content.
87
+
88
+ **Input:**
89
+ - `filePath` (required): Absolute path to the source file.
90
+ - `startLine` (optional): Starting line number (1-indexed).
91
+ - `endLine` (optional): Ending line number (1-indexed).
92
+ - `aroundPattern` (optional): Search pattern to find and return surrounding lines.
93
+ - `contextLines` (optional): Number of lines before/after pattern (default: 5).
94
+
95
+ **What it does:**
96
+ - **Mode 1 (Exact Range)**: When `startLine` and `endLine` are provided, returns only those lines.
97
+ - **Mode 2 (Pattern Search)**: When `aroundPattern` is provided, finds the first occurrence and returns surrounding lines with context.
98
+ - Validates line ranges and provides clear error messages.
99
+ - 90% token savings compared to reading full files for small fragments.
100
+
101
+ **Best used when:**
102
+ - Debugging specific code blocks when you know the line numbers
103
+ - Viewing context around error messages or logs
104
+ - Extracting small fragments without AST parsing overhead
105
+
106
+ **Example use cases:**
107
+ - "Show me lines 120-135 of coordinator.dart"
108
+ - "Show me the code around 'HeroBannerWidget' in hero_banner_widget.dart"
109
+
110
+ #### 5. `search_code_pattern`
111
+ **Purpose:** Search for code patterns across multiple files in a repository.
112
+
113
+ **Input:**
114
+ - `rootDir` (required): Absolute path to the repository root.
115
+ - `pattern` (required): Regular expression pattern to search for.
116
+ - `fileExtensions` (optional): Array of extensions to search (e.g., `[".ts", ".dart"]`). Defaults to common code extensions.
117
+ - `excludeDirs` (optional): Directories to exclude (default: `["node_modules", "dist", "build"]`).
118
+ - `showContext` (optional): Include surrounding lines (default: true).
119
+ - `contextLines` (optional): Number of context lines before/after (default: 3).
120
+ - `maxResults` (optional): Maximum matches to return (default: 50).
121
+
122
+ **What it does:**
123
+ - Walks the repository respecting `.gitignore` rules.
124
+ - Searches for regex patterns across all matching files.
125
+ - Returns structured results with file paths, line numbers, and optional context.
126
+ - Highlights the matching line with a `>` marker in context output.
127
+ - 85% more efficient than manual grep + analysis workflows.
128
+
129
+ **Best used when:**
130
+ - Finding all usages of a function or variable
131
+ - Locating specific log statements or debug markers
132
+ - Discovering patterns across the codebase
133
+ - Understanding how a feature is implemented across files
134
+
135
+ **Example use cases:**
136
+ - "Find all occurrences of 'widget.height' in the Flutter project"
137
+ - "Search for '🎯 \[BUILDER\]' logs in .dart files"
138
+ - "Find all files that call 'HeroBannerWidget'"
139
+
140
+ #### 6. `rollback_file`
141
+ **Purpose:** Restores a file to a previous state from the automated backup system.
142
+ **Input:**
143
+ - `filePath` (required): Absolute path.
144
+ - `steps` (optional): Number of versions to go back (1-5, default: 1).
145
+ **What it does:** Reverts the file to the state it was in before the last 1-5 modifications.
146
+
147
+ ### Write Tools (v2.2.0 Mandatory Workflow)
148
+
149
+ All write tools follow a **Two-Phase Workflow**:
150
+ 1. **Phase 1 (Preview)**: Call without a token to get a unified `diff` and a `confirmationToken`.
151
+ 2. **Phase 2 (Apply)**: Call with `confirmationToken` and `confirm: true` to apply the changes.
152
+
153
+ **Important Notes (v2.2.0):**
154
+ - ✅ **Windows CRLF Support**: Fully resolved. All operations work correctly on Windows files with CRLF line endings.
155
+ - ✅ **Parameter Brace Handling**: Methods with braces in parameters (e.g., `{int? cart}`) are now handled correctly.
156
+
157
+ #### 7. `write_file_surgical`
158
+ **Purpose:** Replace the full source code of a named symbol in a file.
159
+
160
+ **Input:**
161
+ - `filePath` (required): Absolute path to the file to modify.
162
+ - `symbolName` (required): Name of the symbol to replace.
163
+ - `newContent` (required): Complete replacement code (signature + body).
164
+ - `confirmationToken` (optional): Token from Phase 1.
165
+ - `confirm` (optional): Set to `true` to apply.
166
+ - `className` (optional): Scope the symbol to a specific class.
167
+
168
+ **What it does:**
169
+ - Locates the symbol via Tree-sitter WASM parsing.
170
+ - Replaces only that symbol's code, preserving all other file contents.
171
+ - Returns a unified diff showing exactly what changed.
172
+ - Validates the result is syntactically valid before writing.
173
+
174
+ **Best used when:** You need to modify a specific function or method without touching the rest of the file.
175
+
176
+ #### 8. `insert_symbol`
177
+ **Purpose:** Insert new code at a precise location relative to an existing symbol.
178
+
179
+ **Input:**
180
+ - `filePath` (required): Absolute path to the file.
181
+ - `code` (required): The new code to insert.
182
+ - `anchorSymbol` (optional): Symbol name to position relative to. If omitted, inserts at end of file.
183
+ - `position` (optional): `"before"`, `"after"`, `"inside_start"`, `"inside_end"`. Defaults to `"after"`.
184
+ - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
185
+
186
+ **What it does:**
187
+ - Finds the anchor symbol and inserts new code at the specified position.
188
+ - Automatically matches the surrounding indentation style.
189
+ - `inside_start` and `inside_end` insert as members inside a class or interface.
190
+
191
+ **Best used when:** Adding new methods to a class or new functions to a module.
192
+
193
+ #### 9. `rename_symbol`
194
+ **Purpose:** Rename a symbol across an entire repository.
195
+
196
+ **Input:**
197
+ - `filePath` (required): File where the symbol is defined.
198
+ - `oldName` (required): Current name.
199
+ - `newName` (required): New name.
200
+ - `rootDir` (optional): Repository root. Auto-detected if omitted.
201
+ - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
202
+
203
+ **What it does:**
204
+ - Renames the symbol definition in the source file.
205
+ - Finds all dependent files using import analysis.
206
+ - Renames all references in dependent files using whole-word replacement.
207
+ - Returns a multi-file diff showing all changes.
208
+ - Rolls back all changes if any file write fails.
209
+
210
+ **Best used when:** Refactoring a class, function, or method name that is used across multiple files.
211
+
212
+ #### 10. `remove_symbol`
213
+ **Purpose:** Safely remove a symbol from a file.
214
+
215
+ **Input:**
216
+ - `filePath` (required): Absolute path.
217
+ - `symbolName` (required): Symbol to remove.
218
+ - `force` (optional): If true, skip dependency check. Defaults to false.
219
+ - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
220
+
221
+ **What it does:**
222
+ - Checks if other files reference the symbol (unless `force: true`).
223
+ - If dependents exist, refuses to remove and reports which files use it.
224
+ - If safe, removes the symbol's code and cleans up whitespace.
225
+
226
+ **Best used when:** Cleaning up deprecated functions or unused code.
227
+
228
+ ## Recommended Workflow
229
+
230
+ 1. **Start with `get_semantic_repo_map`** to understand the project structure.
231
+ 2. **Use `read_file_surgical`** with a symbol name. Use suggestions if the symbol is missing.
232
+ 3. **Before modifying, run `analyze_impact`** to know the blast radius.
233
+ 4. **Phase 1: Preview Edit** → Call write tools to get a `diff` and `confirmationToken`.
234
+ 5. **Phase 2: Apply Edit** → Verify the diff, then call with the token and `confirm: true`.
235
+ 6. **Recovery** → Use `rollback_file` if needed.
236
+
237
+ ## Technical Details
238
+
239
+ - **Transport:** stdio (JSON-RPC over stdin/stdout)
240
+ - **Runtime:** Node.js >= 18
241
+ - **AST Engines:** web-tree-sitter@0.25.1 (WASM) for all languages
242
+ - **Language Grammars:** tree-sitter-wasms@0.1.13 (ABI v15)
243
+ - **Ignore Engine:** `ignore` npm package (full .gitignore spec support)
244
+ - **Supported languages:** TypeScript, JavaScript (all variants), PHP, Dart, Python
245
+ - **Safety features:** Mandatory two-phase confirmation, rolling 5-version backups (`.mcp-backups/`), fuzzy symbol suggestions, dependency tracking, surgical restoration.
246
+ - **Portability:** 100% WASM - no native dependencies, works on all platforms
Binary file
package/package.json CHANGED
@@ -1,57 +1,59 @@
1
- {
2
- "name": "mcp-code-context",
3
- "version": "2.6.0",
4
- "description": "Powerful MCP server for LLM-ready semantic code context and surgical AST-aware editing. Supports TypeScript, JavaScript, PHP, Dart, and Python.",
5
- "type": "module",
6
- "main": "dist/src/index.js",
7
- "bin": {
8
- "mcp-code-context": "dist/src/index.js"
9
- },
10
- "scripts": {
11
- "build": "tsc",
12
- "start": "node dist/src/index.js",
13
- "dev": "tsc && node dist/src/index.js",
14
- "test": "npm run build && node dist/tests/test-dart.js && node dist/tests/test-php.js && node dist/tests/writers/test-write-smoke.js && node dist/tests/test-new-tools.js && node dist/tests/test-backup-system.js && node dist/tests/test-rename-limitations.js",
15
- "clean": "rimraf dist",
16
- "rebuild": "npm run clean && npm run build"
17
- },
18
- "keywords": [
19
- "mcp",
20
- "model-context-protocol",
21
- "semantic-compression",
22
- "llm",
23
- "code-analysis",
24
- "ast",
25
- "repository-map",
26
- "claude",
27
- "cursor",
28
- "windsurf",
29
- "copilot",
30
- "amazon-q",
31
- "code-context",
32
- "typescript",
33
- "php",
34
- "dart",
35
- "python"
36
- ],
37
- "author": "",
38
- "license": "MIT",
39
- "repository": {
40
- "type": "git",
41
- "url": "git+https://github.com/achatainga/mcp-code-context.git"
42
- },
43
- "dependencies": {
44
- "@modelcontextprotocol/sdk": "^1.12.0",
45
- "ignore": "^6.0.2",
46
- "php-parser": "^3.5.1",
47
- "ts-morph": "^24.0.0",
48
- "typescript": "^5.7.0"
49
- },
50
- "devDependencies": {
51
- "@types/node": "^22.10.0",
52
- "rimraf": "^6.0.1"
53
- },
54
- "engines": {
55
- "node": ">=18.0.0"
56
- }
57
- }
1
+ {
2
+ "name": "mcp-code-context",
3
+ "version": "3.0.6",
4
+ "description": "Powerful MCP server with Tree-sitter WASM parsers for 100% AST accuracy. Zero native dependencies. Supports TypeScript, JavaScript, PHP, Dart, and Python.",
5
+ "type": "module",
6
+ "main": "dist/src/index.js",
7
+ "bin": {
8
+ "mcp-code-context": "dist/src/index.js"
9
+ },
10
+ "scripts": {
11
+ "build": "tsc",
12
+ "build:tests": "tsc -p tsconfig.tests.json",
13
+ "start": "node dist/index.js",
14
+ "dev": "npm run build && node dist/index.js",
15
+ "test": "npm run build && npm run build:tests && node dist-tests/tests/test-wasm-parsers.js",
16
+ "clean": "rimraf dist dist-tests",
17
+ "rebuild": "npm run clean && npm run build",
18
+ "prepublishOnly": "npm run rebuild"
19
+ },
20
+ "keywords": [
21
+ "mcp",
22
+ "model-context-protocol",
23
+ "semantic-compression",
24
+ "llm",
25
+ "code-analysis",
26
+ "ast",
27
+ "repository-map",
28
+ "claude",
29
+ "cursor",
30
+ "windsurf",
31
+ "copilot",
32
+ "amazon-q",
33
+ "code-context",
34
+ "typescript",
35
+ "php",
36
+ "dart",
37
+ "python"
38
+ ],
39
+ "author": "",
40
+ "license": "MIT",
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/achatainga/mcp-code-context.git"
44
+ },
45
+ "dependencies": {
46
+ "@modelcontextprotocol/sdk": "^1.12.0",
47
+ "ignore": "^6.0.2",
48
+ "tree-sitter-wasms": "^0.1.13",
49
+ "web-tree-sitter": "^0.25.1"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^22.10.0",
53
+ "rimraf": "^6.0.1",
54
+ "typescript": "^5.7.0"
55
+ },
56
+ "engines": {
57
+ "node": ">=18.0.0"
58
+ }
59
+ }