mcp-code-context 2.1.3

package/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,135 @@
+# Smart Code Analysis & Editing Tools
+**Available tools for efficient code analysis, context management, and surgical code modification.**
+
+## Read Tools
+
+### 1. `get_semantic_repo_map` — Architectural Map
+**When to use**: At the start of a session, before a major refactor, or when you need to understand a new codebase or directory structure.
+**NEVER use**: For reading specific implementations — this tool extracts ONLY structural signatures (classes, functions), not the code bodies.
+```ts
+get_semantic_repo_map(directoryPath: "/path/to/project/src", format: "markdown")
+```
+
+### 2. `read_file_surgical` — Surgical Reading
+**When to use**: When you need a specific method, class, or symbol. ALWAYS prefer this over reading the entire file (like `fsRead`) if the symbol name is known.
+**NEVER use**: For reading complete files if you only need a single function or symbol.
+```ts
+read_file_surgical(filePath: "/path/to/file.ts", symbolName: "ClassName")
+read_file_surgical(filePath: "/path/to/file.dart", symbolName: "WidgetName")
+// Omitting symbolName will read the entire file
+read_file_surgical(filePath: "/path/to/file.php")
+```
+- If the symbol is not found, the tool returns a **structured JSON error** with `available_symbols` and `suggestions` (e.g., if a `className` scope is missing but the symbol exists in a class).
+- **Pro-tip**: Use the suggestions to fix your next tool call (e.g., adding the correct `className`).
+
+### 3. `analyze_impact` — Blast Radius Detection
+**When to use**: ALWAYS before modifying a file that might be imported or depended upon by other parts of the system.
+**NEVER use**: Ignore or skip this step when refactoring shared services, utilities, or core components.
+**Features**: Detects imports across ecosystems (e.g., `use Namespace\Class` in PHP, `import` in JS/TS/Dart/Python).
+```ts
+analyze_impact(filePath: "/path/to/project/src/services/MyService.ts")
+analyze_impact(filePath: "/path/to/project/src/Services/GeoIPService.php")
+analyze_impact(filePath: "/path/to/detodo24_mobile/lib/services/tracking_service.dart")
+```
+
+---
+
+## Write Tools
+
+### Mandatory Two-Phase Write Workflow (v2.1.1+)
+
+All write tools (`write_file_surgical`, `insert_symbol`, `rename_symbol`, `remove_symbol`) now enforce a safety-first confirmation flow.
+
+**Phase 1: Dry-Run / Preview**
+Call the tool with your proposed changes. You will receive:
+1. A unified `diff` of the proposed changes.
+2. A `confirmationToken`.
+
+**Phase 2: Confirmation**
+To apply the changes, call the SAME tool again with:
+1. `confirmationToken`: The token from Phase 1.
+2. `confirm: true`.
+
+---
+
+### 4. `write_file_surgical` — Surgical Symbol Replacement
+**When to use**: Replace a specific function, method, class, or interface.
+**Phase 1 (Preview)**:
+```ts
+write_file_surgical(filePath: "/path/to/file.ts", symbolName: "processOrder", newContent: "...")
+```
+**Phase 2 (Apply)**:
+```ts
+write_file_surgical(filePath: "/path/to/file.ts", symbolName: "processOrder", confirmationToken: "TOKEN_FROM_P1", confirm: true)
+```
+
+### 5. `insert_symbol` — Precise Code Insertion
+**When to use**: Adding new members relative to an existing anchor symbol.
+**Phase 1 (Preview)**:
+```ts
+insert_symbol(filePath: "/path/to/file.dart", code: "void clear() { ... }", anchorSymbol: "getUser", position: "after")
+```
+**Phase 2 (Apply)**:
+```ts
+insert_symbol(filePath: "/path/to/file.dart", code: "void clear() { ... }", confirmationToken: "TOKEN_FROM_P1", confirm: true)
+```
+
+### 6. `rename_symbol` — Repository-Wide Rename
+**When to use**: Atomic identifier renaming across the entire project.
+**Phase 1 (Preview)**:
+```ts
+rename_symbol(filePath: "/path/to/UserService.ts", oldName: "UserService", newName: "AccountService")
+```
+**Phase 2 (Apply)**:
+```ts
+rename_symbol(filePath: "/path/to/UserService.ts", oldName: "UserService", newName: "AccountService", confirmationToken: "TOKEN_FROM_P1", confirm: true)
+```
+
+### 7. `remove_symbol` — Safe Symbol Deletion
+**When to use**: Removing code with dependency checking.
+**Phase 1 (Preview)**:
+```ts
+remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper")
+```
+**Phase 2 (Apply)**:
+```ts
+remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper", confirmationToken: "TOKEN_FROM_P1", confirm: true)
+```
+- **Safety**: Safe removal check happens in Phase 1. If dependents exist, use `force: true` in your next Phase 1 call to override.
+
+### 8. `rollback_file` — Surgical Restoration
+**When to use**: If an applied change introduces an unexpected error or side effect.
+**Safety**: The server automatically keeps the last 5 versions in `.mcp-backups/`.
+```ts
+rollback_file(filePath: "/path/to/file.ts", steps: 1)
+```
+
+### 7. `remove_symbol` — Safe Symbol Deletion
+**When to use**: When removing a function, method, or class from a file.
+**Safety**: By default, checks for dependents and **refuses** to remove if other files reference it.
+```ts
+// Safe removal (checks dependents first)
+remove_symbol(filePath: "/path/to/file.ts", symbolName: "deprecatedHelper")
+// Force removal (skip dependency check)
+remove_symbol(filePath: "/path/to/file.php", symbolName: "oldMethod", force: true)
+```
+
+---
+
+## Mandatory Workflow
+1. **New Session / Unknown Context** → Use `get_semantic_repo_map` on the relevant directory to understand the structure.
+2. **Read Code** → Use `read_file_surgical` with a `symbolName` whenever possible.
+3. **Handle Missing Symbols** → If you get a JSON error, use the `suggestions` to refine your `symbolName` or `className`.
+4. **Before Modifying** → Use `analyze_impact` if the file is a shared module or component.
+5. **Modify Code (Phase 1)** → Use write tools to generate a `diff` and `confirmationToken`.
+6. **Verify Diff** → Read the diff carefully. If incorrect, correct your prompt and start Phase 1 again.
+7. **Apply (Phase 2)** → Call the same write tool with the token and `confirm: true`.
+8. **Verify Result** → Ensure nothing broke. Use `rollback_file` if needed.
+
+## Supported Languages (Read + Write)
+| Language | Read | Write | Engine |
+|----------|------|-------|--------|
+| TypeScript / JavaScript | ✅ | ✅ | AST (ts-morph) |
+| PHP | ✅ | ✅ | AST (php-parser) |
+| Dart | ✅ | ✅ | Brace-counting + regex |
+| Python | ✅ | ✅ | Indentation-based |

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.3] - 2025-04-17
+
+### Fixed
+- **Windows CRLF Line Ending Support**: Completely resolved false brace imbalance errors on Windows files with CRLF line endings. All Dart writer functions (`replaceDartSymbol`, `insertDartCode`, `renameDartSymbol`, `removeDartSymbol`) now normalize `\r\n` to `\n` before processing, ensuring consistent behavior across all platforms.
+- **Method Parameter Brace Handling**: Fixed critical bug where braces in method parameters (e.g., `{int? cart}`) were incorrectly counted as method body braces, causing false "unbalanced braces" errors. The `findMatchingBraceStateAware` function now correctly identifies the method body opening brace by tracking the closing parenthesis of the method signature.
+- **Helper Function Normalization**: Added CRLF normalization to `hasBraceBalance()` and `reindentCode()` helper functions for defensive consistency.
+
+### Added
+- **CRLF Test Suite**: New comprehensive test suite (`tests/writers/test-crlf-handling.ts`) covering all write operations with Windows line endings, mixed line endings, and edge cases.
+- **Parameter Brace Test Cases**: Added test cases for methods with braces in parameters to prevent regression.
+
+## [2.1.2] - 2026-04-17
+
+### Fixed
+- **State-Aware Brace Balancing**: Upgraded Dart parsing engine to correctly ignore braces inside string literals (single, double, and triple quotes) and comments. This eliminates "False Imbalance" errors during surgical writes.
+- **Improved Block Boundary Detection**: Block extraction now respects nested literals, fixing issues where \`insert_symbol\` would incorrectly place code inside a method body when using \`position: "after"\`.
+- **Cross-File Rename Propagation**: Refactored repository-wide renaming to update references in dependent files even if they don't contain a symbol definition, ensuring comprehensive refactoring.
+- **Dependency Guard Precision**: Refined the safe-removal dependency check to use whole-word regex, reducing false positives caused by sub-string matches in unrelated files.
+
+### Added
+- **Troubleshooting Guide**: New \`TROUBLESHOOTING.md\` documenting known architectural behaviors and recommended workarounds for complex editing scenarios.
+
+## [2.1.1] - 2026-04-17
+
+### Added
+- **Mandatory Preview-then-Confirm Workflow**: All surgical writing tools now implement a safety-first two-phase flow (Phase 1: Dry-Run Preview with \`confirmationToken\`, Phase 2: Atomic Apply).
+- **Rolling Multi-Step Backups**: Automatic rolling window of the last 5 versions for every modified file, stored in a hidden \`.mcp-backups/\` directory.
+- **Rollback Tool**: New \`rollback_file\` MCP tool enabling surgical restoration to any of the 5 previous versions.
+- **Fuzzy Symbol Matching**: Structured JSON error reporting for missing symbols, providing \`available_symbols\` and context-aware \`suggestions\` (e.g., suggesting a missing \`className\` scope or similar top-level symbols).
+- **Private Symbol Support**: Full surgical read/write support for \`_\` and \`__\` prefixed symbols in Dart and Python (fixing previous regex word-boundary limitations).
+- **Repository-Wide Rename Refinement**: Updated \`rename_symbol\` to automatically discover and propose renames across the entire dependency graph with multi-file diff previews.
+
+### Internal
+- Refactored write handlers to perform unconditional backups before modification.
+- Optimized Dart block extraction to correctly track nested parentheses within method signatures.
+- Stabilized TypeScript build process and resolved all existing type inconsistencies.
+
+
+## [2.1.0] - 2026-04-17
+
+### Added
+- **Class Scope Disambiguation**: Added a \`className\` parameter to all read and write tools (\`read_file_surgical\`, \`write_file_surgical\`, \`insert_symbol\`, \`remove_symbol\`).
+- Fixed collisions across duplicate method names (e.g., \`build\` methods in Flutter or identical controllers in PHP/Python) by enforcing boundaries based on the requested class wrapper.
+- Automatic smart detection block-bounding across 4 languages:
+  - TypeScript: Native TS-Morph class-level resolution mapping.
+  - PHP: Custom AST container mapping inside \`php-parser\`.
+  - Dart: Dynamic AST brace-bound indexing block extraction.
+  - Python: Dynamic regex scaling block extractor enforcing indentation thresholds.
+- **Enhanced Testing Options**: Increased overall smoke & unit testing assertion matrix (from 52 assertions to 59).
+
+## [2.0.0] - 2026-04-15
+
+### Added
+- **Surgical Writing Tools**: Four new tools for precise, AST-aware code modification:
+  - `write_file_surgical`: Replace symbol implementation while preserving file structure.
+  - `insert_symbol`: Insert new code relative to existing symbols (before, after, inside).
+  - `rename_symbol`: Repository-wide renaming with import/usage updates.
+  - `remove_symbol`: Safe deletion of symbols with automatic dependency checking.
+- **Language-Specific Writers**: Custom AST adapters for TypeScript, JavaScript, PHP, Dart, and Python.
+- **Dry-Run Engine**: Native unified diff generator for previewing changes without modifying the filesystem.
+- **Backup System**: Opt-in `.bak` file management with automatic atomic rollback on multi-file operation failures.
+- **Enhanced Agent Instructions**: Updated `AGENT_INSTRUCTIONS.md` and `llms.txt` for better AI integration.
+
+### Changed
+- Refactored project structure to separate read-only analysis from surgical editing logic.
+- Updated `README.md` with comprehensive v2.0 documentation and tool usage examples.
+- Standardized error reporting across all MCP tools.
+- Modernized `package.json` scripts and metadata.
+
+## [1.0.0] - 2026-04-14
+
+### Added
+- **Initial Release**: Basic MCP server for semantic code compression.
+- **Semantic Repository Map**: Generate structural maps of entire codebases.
+- **Surgical Reading**: Extract specific symbols to save context tokens.
+- **Impact Analysis**: Identify files that depend on or import a specific file.
+- **Multi-Language Support**: Initial support for TS, JS, PHP, Dart, and Python.

package/DEPLOYMENT_INSTRUCTIONS.md

@@ -0,0 +1,110 @@
+# Deployment Instructions for v2.1.3
+
+## ✅ Completed Steps
+1. ✅ Code fixes implemented and tested
+2. ✅ Version bumped to 2.1.3 in package.json
+3. ✅ CHANGELOG.md updated
+4. ✅ TROUBLESHOOTING.md updated
+5. ✅ llms.txt updated
+6. ✅ Test suite created and passing (11/11 tests)
+7. ✅ Git commit created with semantic message
+8. ✅ Git tag v2.1.3 created with release notes
+9. ✅ Pushed to GitHub (main branch + tag)
+
+## 🚀 Next Steps (Manual)
+
+### 1. Publish to npm
+You need to be logged in to npm. Run:
+
+```bash
+cd C:\code\antigravity-mcp-context
+
+# Login to npm (if not already)
+npm login
+
+# Publish the package
+npm publish
+
+# Verify publication
+npm view mcp-code-context@2.1.3
+```
+
+### 2. Create GitHub Release
+Go to: https://github.com/achatainga/mcp-code-context/releases/new
+
+- **Tag**: Select `v2.1.3` (already pushed)
+- **Title**: `v2.1.3 - Windows CRLF & Parameter Brace Fixes`
+- **Description**: Copy content from `RELEASE_NOTES_v2.1.3.md`
+- **Attach files**: None needed (npm package is the artifact)
+- Click **Publish release**
+
+### 3. Verify Installation
+Test that users can install the new version:
+
+```bash
+# Global install
+npm install -g mcp-code-context@2.1.3
+
+# Verify version
+npx mcp-code-context --version  # Should show 2.1.3
+
+# Test with MCP client (Claude Desktop, Amazon Q, etc.)
+# Update config to use @2.1.3 and restart client
+```
+
+### 4. Announce (Optional)
+Consider announcing on:
+- GitHub Discussions
+- Twitter/X
+- Reddit (r/LocalLLaMA, r/ClaudeAI)
+- Discord communities
+
+## 📋 Verification Checklist
+
+Before announcing:
+- [ ] npm package published successfully
+- [ ] GitHub release created
+- [ ] Can install via `npm install -g mcp-code-context@2.1.3`
+- [ ] Version shows correctly in `package.json`
+- [ ] Tag visible on GitHub releases page
+- [ ] CHANGELOG.md shows v2.1.3 entry
+- [ ] Tests passing on CI (if configured)
+
+## 🐛 Rollback Plan (If Needed)
+
+If critical issues are discovered:
+
+```bash
+# Unpublish from npm (within 72 hours)
+npm unpublish mcp-code-context@2.1.3
+
+# Delete GitHub release
+# Go to releases page and delete v2.1.3
+
+# Delete git tag
+git tag -d v2.1.3
+git push origin :refs/tags/v2.1.3
+
+# Revert commit
+git revert f0bfcfe
+git push origin main
+```
+
+## 📊 Monitoring
+
+After release, monitor:
+- npm download stats: https://npm-stat.com/charts.html?package=mcp-code-context
+- GitHub issues for bug reports
+- GitHub stars/forks for adoption
+
+## 🎉 Success Criteria
+- No critical bugs reported within 48 hours
+- Windows users confirm CRLF issues resolved
+- Download count increases
+- Positive feedback from users
+
+---
+
+**Current Status**: Ready for npm publish and GitHub release creation
+**Blocked By**: npm authentication required
+**Next Action**: Run `npm login` then `npm publish`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# mcp-code-context
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-passing-success.svg)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)]()
+[![Version](https://img.shields.io/badge/version-2.1.1-blue.svg)]()
+
+> MCP server that compresses any codebase into LLM-ready semantic context **and provides surgical code editing tools**. AST-based read & write for TypeScript, JavaScript, PHP, Dart & Python.
+
+## 🚀 Quick Start (Claude Desktop)
+
+1. **Install**: `npm install -g mcp-code-context`
+2. **Configure**: Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "code-context": {
+      "command": "npx",
+      "args": ["-y", "mcp-code-context"]
+    }
+  }
+}
+```
+3. **Enjoy**: Use symbols like `@code-context` to map repos or edit code surgically.
+
+Works with **Claude Desktop**, **Cursor**, **Windsurf**, **GitHub Copilot**, **Amazon Q**, and any [Model Context Protocol](https://modelcontextprotocol.io/) compatible client.
+
+## The Problem
+
+LLMs working with code face two bottlenecks:
+1. **Reading**: Sending raw source files wastes the context window on function bodies and boilerplate. A 500-line file might contain only 30 lines of *structural* information the LLM needs.
+2. **Writing**: Rewriting entire files to change one function is error-prone, token-expensive, and risks corrupting unrelated code.
+
+## The Solution
+
+`mcp-code-context` provides **7 tools** — 3 for reading and 4 for writing — that operate at the **symbol level** (functions, classes, methods). Furthermore, tools support a `className` scope which correctly isolates identical symbol names in the same file (e.g. Flutter `build()` methods) to avoid reading or changing the wrong logic. Read tools extract structural skeletons. Write tools splice changes into the exact AST location.
+
+| File | Original | Compressed | Reduction |
+|------|----------|------------|-----------|
+| PHP class (426 lines) | 426 | 60 | **85.9%** |
+| Dart repository (230 lines) | 230 | 30 | **87.0%** |
+| PHP config (68 lines) | 68 | 15 | **77.9%** |
+
+## Reliability & Testing
+
+Built to be robust and precise. Both read and write engines are tested against real-world, complex codebases (including nested generic types in Dart, complex interfaces in PHP, and multi-file rename operations) with a **100% test pass rate** across all languages and operations.
+
+## Features
+
+### Read
+- 🌳 **AST-based compression** — Real parsers for TypeScript/JavaScript ([ts-morph](https://ts-morph.com/)) and PHP ([php-parser](https://github.com/nickygerritsen/php-parser)). Brace-counting engine for Dart. Regex-based extraction for Python.
+- 🔬 **Surgical symbol extraction** — Extract a single function, class, or method from a file by name. Use `className` to scope disambiguation (e.g., getting multiple `build()` methods in Dart).
+- 💥 **Impact analysis** — Discover all files that depend on a given file before refactoring. Supports ES imports, CommonJS `require()`, Python imports, PHP `use`/`require_once`/`include`, and Dart imports.
+- 📁 **Smart file walking** — Respects `.gitignore` and `.repomixignore` rules. Automatically excludes `node_modules`, `dist`, `vendor`, `.git`, etc.
+- 📄 **Multi-format output** — XML (optimized for LLM consumption) or Markdown (human-readable).
+
+### Write
+- ✏️ **Surgical symbol replacement** — Replace a function, method, or class body without touching the rest of the file. Narrow down the target using the `className` parameter.
+- ➕ **Precise code insertion** — Insert new code before/after a symbol, or inside a class at the start/end.
+- 🔄 **Repository-wide rename** — Rename a symbol in its definition AND all files that import it, atomically.
+- 🗑️ **Safe symbol removal** — Delete code with automatic dependency checking to prevent breakage.
+- 🔍 **Mandatory dry-run flow** — Write tools return a preview diff and a `confirmationToken` by default. Changes are only applied after explicit confirmation.
+- 💾 **Robust rolling backups** — Automatically keeps the last 5 versions of modified files in a hidden `.mcp-backups/` directory.
+- ⏪ **Surgical rollback** — Revert files to any of the 5 previous states using the new `rollback_file` tool.
+- 🤖 **Fuzzy symbol matching** — When a symbol is not found, the server provides structured suggestions based on Levenshtein distance.
+- 🔐 **Private symbol support** — Full support for `_` and `__` prefixed symbols in Dart and Python.
+
+## Supported Languages
+
+| Language | Read (Compress + Extract) | Write (Replace + Insert + Rename + Remove) | Import Analysis |
+|----------|---------------------------|---------------------------------------------|------------------|
+| TypeScript / JavaScript | ✅ AST (ts-morph) | ✅ AST (ts-morph) | ✅ |
+| PHP | ✅ AST (php-parser) | ✅ AST + line-splice | ✅ |
+| Dart | ✅ Brace-counting + regex | ✅ Brace-counting + regex | ✅ |
+| Python | ✅ Regex-based | ✅ Indentation-aware | ✅ |
+| Others (JSON, YAML, CSS, etc.) | Passthrough / truncation | — | — |
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/YOUR_USERNAME/mcp-code-context.git
+cd mcp-code-context
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-code-context": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-code-context/dist/index.js"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-code-context": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-code-context/dist/index.js"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to your Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mcp-code-context": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-code-context/dist/index.js"]
+    }
+  }
+}
+```
+
+### Amazon Q / Other MCP Clients
+
+Any MCP-compatible client can use this server. The transport is **stdio** (JSON-RPC over stdin/stdout). Point your client to `node dist/index.js`.
+
+## Tools
+
+### Read Tools
+
+#### 1. `get_semantic_repo_map`
+Generate a compressed architectural overview of an entire repository.
+- `directoryPath` (required) — Path to the repo root
+- `format` (optional) — `"xml"` (default) or `"markdown"`
+
+#### 2. `read_file_surgical`
+Read a file, or extract only a specific named symbol. Returns structured suggestions if the symbol is missing.
+- `filePath` (required) — Path to the source file
+- `symbolName` (optional) — Name of a function, class, method, or type
+- `className` (optional) — Scope the symbol to a specific class (to avoid duplicates)
+
+#### 3. `analyze_impact`
+Find all files that depend on a given file.
+- `filePath` (required) — Path to the file being modified
+- `rootDir` (optional) — Repository root (auto-detected)
+
+#### 4. `rollback_file`
+Surgically restore a file to a previous state from the automated backup system.
+- `filePath` (required) — Path to the file to restore
+- `steps` (optional) — Number of versions to go back (1-5, default: 1)
+
+### Write Tools (Phase 1: Preview)
+
+All write tools follow a **Two-Phase Workflow**:
+1. **Call without token**: Returns a unified `diff` and a `confirmationToken`.
+2. **Call with token**: Set `confirm: true` and provide the token to apply the changes.
+
+#### 5. `write_file_surgical`
+Replace the full source code of a named symbol in a file.
+- `filePath` (required) — Path to the file
+- `symbolName` (required) — Symbol to replace
+- `newContent` (required) — Replacement code (signature + body)
+- `confirmationToken` (optional) — Token from Phase 1 to apply changes
+- `confirm` (optional) — Set to `true` to apply
+- `className` (optional) — Scope the symbol to a specific class
+
+#### 5. `insert_symbol`
+Insert new code at a precise location relative to an existing symbol.
+- `filePath` (required) — Path to the file
+- `code` (required) — Code to insert
+- `anchorSymbol` (optional) — Symbol to position relative to
+- `position` (optional) — `"before"`, `"after"`, `"inside_start"`, `"inside_end"`
+- `className` (optional) — Scope the anchor to a specific class
+- `confirmationToken`, `confirm` (optional)
+
+#### 6. `rename_symbol`
+Rename a symbol across the entire repository (definition + all usages).
+- `filePath` (required) — File where the symbol is defined
+- `oldName` (required) — Current name
+- `newName` (required) — New name
+- `rootDir` (optional) — Repository root
+- `confirmationToken`, `confirm` (optional)
+
+#### 7. `remove_symbol`
+Safely remove a symbol from a file with dependency checking.
+- `filePath` (required) — Path to the file
+- `symbolName` (required) — Symbol to remove
+- `className` (optional) — Scope the symbol to a specific class
+- `force` (optional) — Skip dependency check
+- `confirmationToken`, `confirm` (optional)
+
+## Recommended Workflow
+
+1. **Understand** → `get_semantic_repo_map` to see the architecture
+2. **Read** → `read_file_surgical` with symbol name for specific implementations
+3. **Assess** → `analyze_impact` before modifying shared files
+4. **Edit (Preview)** → Call write tools to generate a `diff` and `confirmationToken`
+5. **Confim** → Call the same write tool with the token and `confirm: true` to apply
+6. **Recovery** → Use `rollback_file` if something goes wrong after confirmation
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run read tests (compression + extraction)
+npm run build && node dist/tests/test-dart.js && node dist/tests/test-php.js
+
+# Run write tests (replace, insert, rename, remove)
+npm run build && node dist/tests/writers/test-write-smoke.js
+
+# Run all tests
+npm run build && node dist/tests/test-dart.js && node dist/tests/test-php.js && node dist/tests/writers/test-write-smoke.js
+
+# Development (build + start)
+npm run dev
+```
+
+## Technical Details
+
+- **Transport:** stdio (JSON-RPC over stdin/stdout)
+- **Runtime:** Node.js >= 18
+- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/)
+- **AST Engines:** ts-morph (TypeScript/JS), php-parser (PHP), brace-counting (Dart), regex (Python)
+- **Ignore Engine:** `ignore` npm package (full .gitignore spec support)
+- **Safety Features:** Mandatory two-phase confirmation, rolling 5-version backups, fuzzy matching, dependency checking, surgical restoration.
+
+## License
+
+[MIT](LICENSE)

package/RELEASE_NOTES_v2.1.3.md

@@ -0,0 +1,78 @@
+# Release v2.1.3 - Windows CRLF & Parameter Brace Fixes
+
+## 🎯 Overview
+This release completely resolves false brace imbalance errors on Windows systems and fixes a critical bug with Dart method parameters containing braces.
+
+## ✨ What's Fixed
+
+### Windows CRLF Support (Complete Resolution)
+- ✅ All Dart writer functions now normalize `\r\n` to `\n` before processing
+- ✅ No more false "unbalanced braces" errors on Windows files
+- ✅ Consistent behavior across Windows, macOS, and Linux
+- ✅ Helper functions (`hasBraceBalance`, `reindentCode`) also normalize line endings
+
+### Method Parameter Brace Handling
+- ✅ Fixed critical bug where braces in method parameters (e.g., `{int? cart}`) were incorrectly counted as method body braces
+- ✅ `findMatchingBraceStateAware` now tracks closing parenthesis to identify method body start
+- ✅ Correctly handles Dart named parameters, optional parameters, and destructuring syntax
+
+## 🧪 Testing
+- **11 new test cases** covering:
+  - CRLF line endings
+  - Mixed CRLF/LF line endings
+  - Methods with braces in parameters
+  - All write operations (replace, insert, rename, remove)
+- **100% test pass rate** on Windows 11
+
+## 📝 Changes
+
+### Modified Files
+- `src/ast/writers/dartWriter.ts` - Core CRLF normalization and parameter brace detection
+- `package.json` - Version bump to 2.1.3
+- `CHANGELOG.md` - Detailed release notes
+- `TROUBLESHOOTING.md` - Marked CRLF issue as resolved
+- `llms.txt` - Updated for LLM consumption
+
+### New Files
+- `tests/writers/test-crlf-handling.ts` - Comprehensive CRLF test suite
+
+## 🔄 Migration Guide
+No breaking changes. Simply update:
+
+```bash
+npm install -g mcp-code-context@2.1.3
+```
+
+Or in your MCP client config:
+```json
+{
+  "mcpServers": {
+    "code-context": {
+      "command": "npx",
+      "args": ["-y", "mcp-code-context@2.1.3"]
+    }
+  }
+}
+```
+
+## 🐛 Bug Reports Resolved
+- Windows CRLF false positive errors
+- Parameter brace detection in Dart methods
+- Mixed line ending handling
+
+## 📊 Impact
+- **Platforms affected**: Windows (primary), all platforms benefit from improved robustness
+- **Languages affected**: Dart (primary fix), all languages benefit from CRLF normalization
+- **Backward compatible**: Yes, no breaking changes
+
+## 🙏 Credits
+Special thanks to the Amazon Q Developer user who reported the Windows CRLF bug with detailed reproduction steps.
+
+## 📚 Documentation
+- [CHANGELOG.md](./CHANGELOG.md) - Full version history
+- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Known issues and solutions
+- [README.md](./README.md) - Complete usage guide
+
+---
+
+**Full Changelog**: https://github.com/achatainga/mcp-code-context/compare/v2.1.2...v2.1.3