# Enhanced Directory Context MCP Server

**TL;DR**: A powerful MCP server that gives AI assistants full directory analysis and file editing capabilities.

## What It Does
- 📁 **Analyze directories** - Get project structure, find files, search content
- ✏️ **Edit files** - Create, update, delete, rename files and folders
- 🔍 **Smart search** - Find code/text across multiple files with regex support
- 🔄 **Git integration** - View commits, branches, and changes
- 🛡️ **Safe operations** - Auto-backups and transaction rollback

## Quick Setup
1. Install dependencies: `npm install`
2. Add to your Claude Desktop config:
```json
{
  "mcpServers": {
    "directory-context": {
      "command": "node",
      "args": ["path/to/server.js"]
    }
  }
}
```

## Main Tools
| Tool | What It Does |
|------|-------------|
| `set_working_directory` | Set the folder to work in |
| `get_directory_structure` | Show folder/file tree |
| `search_files` | Find text in files |
| `create_file` | Make new files |
| `update_file` | Edit existing files |
| `delete_file` | Remove files (with backup) |
| `batch_file_operations` | Do multiple operations at once |





# Enhanced Directory Context MCP Server

A comprehensive Model Context Protocol (MCP) server that provides advanced directory analysis and file management capabilities for AI assistants like Claude. This server combines directory context extraction with full file editing capabilities, making it a powerful tool for code analysis, project management, and file operations.

## Features

### 🔍 Directory Analysis
- **Complete Directory Structure**: Get detailed tree views of any directory with metadata
- **Intelligent Project Analysis**: Automatic project type detection and context summary
- **Smart File Search**: Regex and text-based search across multiple file types
- **Git Integration**: Extract repository context, commit history, and working directory status
- **File Statistics**: Comprehensive analysis of file types, sizes, and modification dates

### 📝 File Operations
- **Create Files**: Generate new files with specified content
- **Update Files**: Sophisticated search-and-replace operations with regex support
- **Append Content**: Add content to existing files with formatting options
- **Delete Files**: Remove files with optional backup creation
- **Rename/Move Files**: Relocate and rename files with collision detection
- **Directory Management**: Create directory structures recursively

### 🔄 Advanced Features
- **Batch Operations**: Execute multiple file operations in a single transaction
- **Automatic Backups**: Optional backup creation for destructive operations
- **Transaction Rollback**: Rollback capability for failed batch operations
- **Resource Exposure**: Automatic exposure of important project files as MCP resources
- **Error Handling**: Comprehensive error handling with detailed feedback

## Installation

### Prerequisites
- Node.js 18.0.0 or higher
- npm or yarn package manager

### Setup
1. Clone or download the MCP server files
2. Install dependencies:
```bash
npm install
```

3. Configure your MCP client (Claude Desktop, etc.) to use this server:

**Claude Desktop Configuration:**
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "directory-context": {
      "command": "node",
      "args": ["path/to/your/server.js"],
      "cwd": "your-default-working-directory"
    }
  }
}
```

**Alternative Configuration:**
Use the provided `mcp-json-config.json` as a template and update the paths accordingly.

## Usage

### Setting Up Your Working Directory
Before using any features, set your working directory:
```
set_working_directory(directory="/path/to/your/project")
```

### Directory Analysis Tools

#### Get Directory Structure
```
get_directory_structure(
  max_depth=10,           // Maximum traversal depth
  include_hidden=false,   // Include hidden files/directories
  file_types=[".js", ".py", ".md"]  // Filter by extensions
)
```

#### Analyze Project Context
```
analyze_project_context(
  include_code_analysis=true,    // Include complexity analysis
  focus_files=["specific_file.js"]  // Focus on specific files
)
```

#### Search Files
```
search_files(
  query="function myFunction",  // Search query
  file_types=[".js", ".ts"],   // File types to search
  is_regex=false,              // Use regex matching
  max_results=50               // Maximum results
)
```

#### Git Context
```
get_git_context(
  include_diff=true,     // Include working directory changes
  commit_count=10        // Number of recent commits
)
```

### File Management Tools

#### Create Files
```
create_file(
  path="src/new-component.js",
  content="const MyComponent = () => { ... }",
  encoding="utf8",
  overwrite=false
)
```

#### Update Files
```
update_file(
  path="src/config.js",
  updates=[
    {
      search: "oldValue: 'old'",
      replace: "newValue: 'new'",
      regex: false,
      all: true
    }
  ],
  backup=true
)
```

#### Append to Files
```
append_to_file(
  path="README.md",
  content="## New Section\nContent here...",
  newline_before=true
)
```

#### Delete Files
```
delete_file(
  path="old-file.js",
  backup=true  // Creates .deleted backup
)
```

#### Rename/Move Files
```
rename_file(
  old_path="old-name.js",
  new_path="new-name.js",
  overwrite=false
)
```

#### Create Directories
```
create_directory(
  path="src/components/new-feature",
  recursive=true
)
```

### Batch Operations
Execute multiple operations atomically:
```
batch_file_operations(
  operations=[
    {
      operation: "create",
      params: {
        path: "src/component.js",
        content: "export default () => {}"
      }
    },
    {
      operation: "update",
      params: {
        path: "src/index.js",
        updates: [...]
      }
    }
  ],
  rollback_on_error=true
)
```

## Project Type Detection

The server automatically detects project types based on configuration files:

- **Node.js/JavaScript**: `package.json`
- **Python**: `requirements.txt`
- **Rust**: `Cargo.toml`
- **Go**: `go.mod`
- **Java**: `pom.xml`, `build.gradle`
- **PHP**: `composer.json`
- **Ruby**: `Gemfile`
- **Docker**: `Dockerfile`, `docker-compose.yml`
- And more...

## File Priority Detection

The server identifies important files automatically:
- Configuration files (`package.json`, `config.js`, etc.)
- Entry points (`index.js`, `main.py`, `app.js`)
- Documentation (`README.md`, docs)
- Docker files
- Environment files (`.env`)

## Resource Exposure

Important files are automatically exposed as MCP resources, making them easily accessible to AI assistants without explicit file reading requests.

## Error Handling and Safety Features

- **Backup Creation**: Automatic backups for destructive operations
- **Collision Detection**: Prevents accidental overwrites
- **Transaction Rollback**: Batch operations can be fully rolled back on error
- **Path Validation**: Ensures operations stay within working directory bounds
- **Detailed Error Messages**: Comprehensive error reporting for debugging

## API Reference

### Core Tools

| Tool | Description | Required Parameters |
|------|-------------|-------------------|
| `set_working_directory` | Set the working directory | `directory` |
| `get_directory_structure` | Get directory tree | None |
| `get_file_contents` | Read multiple files | `files` |
| `search_files` | Search within files | `query` |
| `analyze_project_context` | Analyze project | None |
| `get_git_context` | Git repository info | None |

### File Operations

| Tool | Description | Required Parameters |
|------|-------------|-------------------|
| `create_file` | Create new file | `path`, `content` |
| `update_file` | Update existing file | `path`, `updates` |
| `append_to_file` | Append to file | `path`, `content` |
| `delete_file` | Delete file | `path` |
| `rename_file` | Rename/move file | `old_path`, `new_path` |
| `create_directory` | Create directory | `path` |
| `batch_file_operations` | Multiple operations | `operations` |

## Configuration Options

### Server Configuration
- **Working Directory**: Set via `set_working_directory` or during initialization
- **File Type Filters**: Configurable file extension filtering
- **Search Limits**: Configurable maximum search results
- **Backup Policies**: Optional backup creation for destructive operations

### MCP Client Configuration
Configure the server in your MCP client with appropriate command and arguments. The server communicates via stdio and requires no additional network configuration.

## Development and Contribution

### Project Structure
```
enhanced-directory-context-mcp/
├── server.js                 # Main MCP server implementation
├── package.json             # Node.js package configuration
├── mcp-json-config.json     # Example MCP client configuration
└── README.md               # This documentation
```

### Dependencies
- `@modelcontextprotocol/sdk`: Core MCP functionality
- Node.js built-in modules: `fs`, `path`, `child_process`

### Running in Development Mode
```bash
npm run dev
```

This starts the server with Node.js inspector enabled for debugging.

## License

MIT License - See package.json for details.

## Support and Issues

For issues, feature requests, or contributions, please refer to the repository's issue tracker.

---

**Note**: This MCP server provides powerful file system access. Ensure you trust the AI assistant and understand the operations being performed, especially destructive operations like file deletion or modification.