mcp-code-context 2.5.1 → 3.0.4

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 (129) hide show
  1. package/CHANGELOG.md +92 -236
  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 -234
  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/PLAN_v2.5.0.md +0 -407
  40. package/TROUBLESHOOTING.md +0 -38
  41. package/dist/src/ast/dartCompressor.d.ts +0 -27
  42. package/dist/src/ast/dartCompressor.js +0 -859
  43. package/dist/src/ast/dartCompressor.js.map +0 -1
  44. package/dist/src/ast/phpCompressor.d.ts +0 -24
  45. package/dist/src/ast/phpCompressor.js +0 -634
  46. package/dist/src/ast/phpCompressor.js.map +0 -1
  47. package/dist/src/ast/semanticCompressor.d.ts +0 -22
  48. package/dist/src/ast/semanticCompressor.js +0 -677
  49. package/dist/src/ast/semanticCompressor.js.map +0 -1
  50. package/dist/src/ast/writers/dartWriter.d.ts +0 -37
  51. package/dist/src/ast/writers/dartWriter.js +0 -544
  52. package/dist/src/ast/writers/dartWriter.js.map +0 -1
  53. package/dist/src/ast/writers/phpWriter.d.ts +0 -37
  54. package/dist/src/ast/writers/phpWriter.js +0 -411
  55. package/dist/src/ast/writers/phpWriter.js.map +0 -1
  56. package/dist/src/ast/writers/pyWriter.d.ts +0 -37
  57. package/dist/src/ast/writers/pyWriter.js +0 -355
  58. package/dist/src/ast/writers/pyWriter.js.map +0 -1
  59. package/dist/src/ast/writers/safeRename.d.ts +0 -14
  60. package/dist/src/ast/writers/safeRename.js +0 -258
  61. package/dist/src/ast/writers/safeRename.js.map +0 -1
  62. package/dist/src/ast/writers/symbolWriter.d.ts +0 -64
  63. package/dist/src/ast/writers/symbolWriter.js +0 -174
  64. package/dist/src/ast/writers/symbolWriter.js.map +0 -1
  65. package/dist/src/ast/writers/tsWriter.d.ts +0 -38
  66. package/dist/src/ast/writers/tsWriter.js +0 -344
  67. package/dist/src/ast/writers/tsWriter.js.map +0 -1
  68. package/dist/src/cache/astCache.d.ts +0 -39
  69. package/dist/src/cache/astCache.js +0 -169
  70. package/dist/src/cache/astCache.js.map +0 -1
  71. package/dist/src/handlers/readHandlers.d.ts +0 -70
  72. package/dist/src/handlers/readHandlers.js +0 -455
  73. package/dist/src/handlers/readHandlers.js.map +0 -1
  74. package/dist/src/handlers/utilHandlers.d.ts +0 -31
  75. package/dist/src/handlers/utilHandlers.js +0 -69
  76. package/dist/src/handlers/utilHandlers.js.map +0 -1
  77. package/dist/src/handlers/writeHandlers.d.ts +0 -57
  78. package/dist/src/handlers/writeHandlers.js +0 -499
  79. package/dist/src/handlers/writeHandlers.js.map +0 -1
  80. package/dist/src/tools/readFileLines.d.ts +0 -26
  81. package/dist/src/tools/readFileLines.js +0 -77
  82. package/dist/src/tools/readFileLines.js.map +0 -1
  83. package/dist/src/tools/searchCodePattern.d.ts +0 -37
  84. package/dist/src/tools/searchCodePattern.js +0 -144
  85. package/dist/src/tools/searchCodePattern.js.map +0 -1
  86. package/dist/src/utils/arrayUtils.d.ts +0 -12
  87. package/dist/src/utils/arrayUtils.js +0 -27
  88. package/dist/src/utils/arrayUtils.js.map +0 -1
  89. package/dist/src/utils/backupManager.d.ts +0 -31
  90. package/dist/src/utils/backupManager.js +0 -124
  91. package/dist/src/utils/backupManager.js.map +0 -1
  92. package/dist/src/utils/confirmationCache.d.ts +0 -16
  93. package/dist/src/utils/confirmationCache.js +0 -40
  94. package/dist/src/utils/confirmationCache.js.map +0 -1
  95. package/dist/src/utils/constants.d.ts +0 -46
  96. package/dist/src/utils/constants.js +0 -112
  97. package/dist/src/utils/constants.js.map +0 -1
  98. package/dist/src/utils/dependencyChecker.d.ts +0 -1
  99. package/dist/src/utils/dependencyChecker.js +0 -55
  100. package/dist/src/utils/dependencyChecker.js.map +0 -1
  101. package/dist/src/utils/diffEngine.d.ts +0 -21
  102. package/dist/src/utils/diffEngine.js +0 -163
  103. package/dist/src/utils/diffEngine.js.map +0 -1
  104. package/dist/src/utils/fuzzyMatch.d.ts +0 -8
  105. package/dist/src/utils/fuzzyMatch.js +0 -69
  106. package/dist/src/utils/fuzzyMatch.js.map +0 -1
  107. package/dist/src/utils/ignoreManager.d.ts +0 -30
  108. package/dist/src/utils/ignoreManager.js +0 -186
  109. package/dist/src/utils/ignoreManager.js.map +0 -1
  110. package/dist/src/utils/normalization.d.ts +0 -49
  111. package/dist/src/utils/normalization.js +0 -173
  112. package/dist/src/utils/normalization.js.map +0 -1
  113. package/dist/src/utils/projectRoot.d.ts +0 -17
  114. package/dist/src/utils/projectRoot.js +0 -42
  115. package/dist/src/utils/projectRoot.js.map +0 -1
  116. package/dist/src/utils/secureValidation.d.ts +0 -15
  117. package/dist/src/utils/secureValidation.js +0 -41
  118. package/dist/src/utils/secureValidation.js.map +0 -1
  119. package/dist/src/utils/syntaxValidator.d.ts +0 -15
  120. package/dist/src/utils/syntaxValidator.js +0 -218
  121. package/dist/src/utils/syntaxValidator.js.map +0 -1
  122. package/dist/src/utils/transactionManager.d.ts +0 -46
  123. package/dist/src/utils/transactionManager.js +0 -123
  124. package/dist/src/utils/transactionManager.js.map +0 -1
  125. package/dist/src/utils/validation.d.ts +0 -87
  126. package/dist/src/utils/validation.js +0 -231
  127. package/dist/src/utils/validation.js.map +0 -1
  128. package/docs/ARCHITECTURE.md +0 -300
  129. package/docs/architecture/ADR-001-modular-handlers.md +0 -119
package/llms.txt CHANGED
@@ -1,234 +1,246 @@
1
- # mcp-code-context v2.5.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.4.1
6
-
7
- 🐛 **Bug Fix**: analyze_impact now works correctly
8
- - ✅ Fixed TypeScript ESM import resolution
9
- - ✅ Correctly detects dependencies in TypeScript projects
10
-
11
- ## What's New in v2.4.0
12
-
13
- 🚀 **Performance Revolution**: Fully async I/O architecture
14
- - ✅ All blocking file operations eliminated
15
- - ✅ 3x faster on repositories with 1000+ files
16
- - ✅ Non-blocking event loop (was blocking in v2.3.x)
17
- - ✅ +300% throughput on large codebases
18
- - ✅ Scalability score: 4.0 → 9.0
19
-
20
- ## What This Tool Does
21
-
22
- This MCP server solves two problems:
23
- 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.
24
- 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.
25
-
26
- ## Available Tools
27
-
28
- ### Read Tools
29
-
30
- #### 1. `get_semantic_repo_map`
31
- **Purpose:** Generate a compressed architectural map of an entire repository.
32
-
33
- **Input:**
34
- - `directoryPath` (required): Absolute path to the repository root.
35
- - `format` (optional): `"xml"` (default) or `"markdown"`.
36
-
37
- **What it does:**
38
- - Walks the directory tree respecting `.gitignore` and `.repomixignore` rules.
39
- - Always excludes `node_modules`, `dist`, `build`, `vendor`, `.git`.
40
- - For TypeScript/JavaScript: Uses AST parsing (ts-morph) to extract only function signatures, class structures, interfaces, types, and enums.
41
- - For PHP: Uses AST parsing (php-parser) to extract namespaces, classes, interfaces, traits, enums, methods, properties, and docblocks.
42
- - For Dart: Uses brace-counting + regex engine to extract classes, mixins, extensions, enums, methods, and fields.
43
- - For Python: Uses regex-based extraction to capture class/function signatures and docstrings.
44
- - For other files: Returns content as-is if small, or a truncated preview if large.
45
-
46
- **Best used when:** You need to understand the architecture of a project before diving into specific files.
47
-
48
- #### 2. `read_file_surgical`
49
- **Purpose:** Read a full file or extract only a specific named symbol.
50
-
51
- **Input:**
52
- - `filePath` (required): Absolute path to the source file.
53
- - `symbolName` (optional): Name of a function, class, interface, method, or type to extract.
54
-
55
- **What it does:**
56
- - 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.
57
- - If missing: Returns structured JSON with `available_symbols` and `suggestions` (e.g., suggesting a `className` scope).
58
-
59
- **Best used when:** You identified a symbol from the repo map and need to see its full implementation.
60
-
61
- #### 3. `analyze_impact`
62
- **Purpose:** Find all files that depend on a given file.
63
-
64
- **Input:**
65
- - `filePath` (required): Absolute path to the file being modified.
66
- - `rootDir` (optional): Repository root. Auto-detected if omitted.
67
-
68
- **What it does:**
69
- - Scans all source files for `import`, `require()`, Python `from/import`, PHP `use`/`require_once`/`include`, and Dart `import` statements.
70
- - Resolves relative paths to determine if they point to the target file.
71
- - Returns a structured report listing every dependent file and the specific import statement.
72
-
73
- **Best used when:** You're about to modify a file and need to understand the blast radius.
74
-
75
- #### 4. `read_file_lines`
76
- **Purpose:** Read specific line ranges from a file without loading the entire content.
77
-
78
- **Input:**
79
- - `filePath` (required): Absolute path to the source file.
80
- - `startLine` (optional): Starting line number (1-indexed).
81
- - `endLine` (optional): Ending line number (1-indexed).
82
- - `aroundPattern` (optional): Search pattern to find and return surrounding lines.
83
- - `contextLines` (optional): Number of lines before/after pattern (default: 5).
84
-
85
- **What it does:**
86
- - **Mode 1 (Exact Range)**: When `startLine` and `endLine` are provided, returns only those lines.
87
- - **Mode 2 (Pattern Search)**: When `aroundPattern` is provided, finds the first occurrence and returns surrounding lines with context.
88
- - Validates line ranges and provides clear error messages.
89
- - 90% token savings compared to reading full files for small fragments.
90
-
91
- **Best used when:**
92
- - Debugging specific code blocks when you know the line numbers
93
- - Viewing context around error messages or logs
94
- - Extracting small fragments without AST parsing overhead
95
-
96
- **Example use cases:**
97
- - "Show me lines 120-135 of coordinator.dart"
98
- - "Show me the code around 'HeroBannerWidget' in hero_banner_widget.dart"
99
-
100
- #### 5. `search_code_pattern`
101
- **Purpose:** Search for code patterns across multiple files in a repository.
102
-
103
- **Input:**
104
- - `rootDir` (required): Absolute path to the repository root.
105
- - `pattern` (required): Regular expression pattern to search for.
106
- - `fileExtensions` (optional): Array of extensions to search (e.g., `[".ts", ".dart"]`). Defaults to common code extensions.
107
- - `excludeDirs` (optional): Directories to exclude (default: `["node_modules", "dist", "build"]`).
108
- - `showContext` (optional): Include surrounding lines (default: true).
109
- - `contextLines` (optional): Number of context lines before/after (default: 3).
110
- - `maxResults` (optional): Maximum matches to return (default: 50).
111
-
112
- **What it does:**
113
- - Walks the repository respecting `.gitignore` rules.
114
- - Searches for regex patterns across all matching files.
115
- - Returns structured results with file paths, line numbers, and optional context.
116
- - Highlights the matching line with a `>` marker in context output.
117
- - 85% more efficient than manual grep + analysis workflows.
118
-
119
- **Best used when:**
120
- - Finding all usages of a function or variable
121
- - Locating specific log statements or debug markers
122
- - Discovering patterns across the codebase
123
- - Understanding how a feature is implemented across files
124
-
125
- **Example use cases:**
126
- - "Find all occurrences of 'widget.height' in the Flutter project"
127
- - "Search for '🎯 \[BUILDER\]' logs in .dart files"
128
- - "Find all files that call 'HeroBannerWidget'"
129
-
130
- #### 6. `rollback_file`
131
- **Purpose:** Restores a file to a previous state from the automated backup system.
132
- **Input:**
133
- - `filePath` (required): Absolute path.
134
- - `steps` (optional): Number of versions to go back (1-5, default: 1).
135
- **What it does:** Reverts the file to the state it was in before the last 1-5 modifications.
136
-
137
- ### Write Tools (v2.2.0 Mandatory Workflow)
138
-
139
- All write tools follow a **Two-Phase Workflow**:
140
- 1. **Phase 1 (Preview)**: Call without a token to get a unified `diff` and a `confirmationToken`.
141
- 2. **Phase 2 (Apply)**: Call with `confirmationToken` and `confirm: true` to apply the changes.
142
-
143
- **Important Notes (v2.2.0):**
144
- - ✅ **Windows CRLF Support**: Fully resolved. All operations work correctly on Windows files with CRLF line endings.
145
- - ✅ **Parameter Brace Handling**: Methods with braces in parameters (e.g., `{int? cart}`) are now handled correctly.
146
-
147
- #### 7. `write_file_surgical`
148
- **Purpose:** Replace the full source code of a named symbol in a file.
149
-
150
- **Input:**
151
- - `filePath` (required): Absolute path to the file to modify.
152
- - `symbolName` (required): Name of the symbol to replace.
153
- - `newContent` (required): Complete replacement code (signature + body).
154
- - `confirmationToken` (optional): Token from Phase 1.
155
- - `confirm` (optional): Set to `true` to apply.
156
- - `className` (optional): Scope the symbol to a specific class.
157
-
158
- **What it does:**
159
- - Locates the symbol via AST parsing (ts-morph, php-parser, brace-counting, or indentation detection).
160
- - Replaces only that symbol's code, preserving all other file contents.
161
- - Returns a unified diff showing exactly what changed.
162
- - Validates the result is syntactically valid before writing.
163
-
164
- **Best used when:** You need to modify a specific function or method without touching the rest of the file.
165
-
166
- #### 8. `insert_symbol`
167
- **Purpose:** Insert new code at a precise location relative to an existing symbol.
168
-
169
- **Input:**
170
- - `filePath` (required): Absolute path to the file.
171
- - `code` (required): The new code to insert.
172
- - `anchorSymbol` (optional): Symbol name to position relative to. If omitted, inserts at end of file.
173
- - `position` (optional): `"before"`, `"after"`, `"inside_start"`, `"inside_end"`. Defaults to `"after"`.
174
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
175
-
176
- **What it does:**
177
- - Finds the anchor symbol and inserts new code at the specified position.
178
- - Automatically matches the surrounding indentation style.
179
- - `inside_start` and `inside_end` insert as members inside a class or interface.
180
-
181
- **Best used when:** Adding new methods to a class or new functions to a module.
182
-
183
- #### 9. `rename_symbol`
184
- **Purpose:** Rename a symbol across an entire repository.
185
-
186
- **Input:**
187
- - `filePath` (required): File where the symbol is defined.
188
- - `oldName` (required): Current name.
189
- - `newName` (required): New name.
190
- - `rootDir` (optional): Repository root. Auto-detected if omitted.
191
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
192
-
193
- **What it does:**
194
- - Renames the symbol definition in the source file.
195
- - Finds all dependent files using import analysis.
196
- - Renames all references in dependent files using whole-word replacement.
197
- - Returns a multi-file diff showing all changes.
198
- - Rolls back all changes if any file write fails.
199
-
200
- **Best used when:** Refactoring a class, function, or method name that is used across multiple files.
201
-
202
- #### 10. `remove_symbol`
203
- **Purpose:** Safely remove a symbol from a file.
204
-
205
- **Input:**
206
- - `filePath` (required): Absolute path.
207
- - `symbolName` (required): Symbol to remove.
208
- - `force` (optional): If true, skip dependency check. Defaults to false.
209
- - `confirmationToken`, `confirm` (optional): Standard Phase 2 parameters.
210
-
211
- **What it does:**
212
- - Checks if other files reference the symbol (unless `force: true`).
213
- - If dependents exist, refuses to remove and reports which files use it.
214
- - If safe, removes the symbol's code and cleans up whitespace.
215
-
216
- **Best used when:** Cleaning up deprecated functions or unused code.
217
-
218
- ## Recommended Workflow
219
-
220
- 1. **Start with `get_semantic_repo_map`** to understand the project structure.
221
- 2. **Use `read_file_surgical`** with a symbol name. Use suggestions if the symbol is missing.
222
- 3. **Before modifying, run `analyze_impact`** to know the blast radius.
223
- 4. **Phase 1: Preview Edit** → Call write tools to get a `diff` and `confirmationToken`.
224
- 5. **Phase 2: Apply Edit** → Verify the diff, then call with the token and `confirm: true`.
225
- 6. **Recovery** → Use `rollback_file` if needed.
226
-
227
- ## Technical Details
228
-
229
- - **Transport:** stdio (JSON-RPC over stdin/stdout)
230
- - **Runtime:** Node.js >= 18
231
- - **AST Engines:** ts-morph (TypeScript/JS), php-parser (PHP), brace-counting/regex (Dart, Python)
232
- - **Ignore Engine:** `ignore` npm package (full .gitignore spec support)
233
- - **Supported languages:** TypeScript, JavaScript (all variants), PHP, Dart, Python
234
- - **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.4
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.4
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.4
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.4
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.5.1",
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.4",
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
+ }