# VS Code MCP Server

A comprehensive Model Context Protocol (MCP) server designed to provide AI assistants with powerful VS Code integration capabilities, offering 29 specialized tools for file operations, command execution, project analysis, and development workflow automation.

## 🚀 Features

- **📁 File Operations**: Complete file and directory management (8 tools)
- **⚡ Advanced File Editing**: Precise line-level editing with validation (6 tools)
- **🖥️ Command Execution**: System command execution and process management (8 tools)
- **📊 Project Analysis**: Codebase insights and dependency discovery (3 tools)
- **🔍 VS Code Integration**: Symbol search, definitions, and diagnostics (4 tools)

## 📦 Installation

### Prerequisites

- Node.js 18.0.0 or higher
- Claude Desktop (or any MCP-compatible client)

### Setup

1. **Clone the repository:**
   ```bash
   git clone <your-repo-url>
   cd vs-code-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the server:**
   ```bash
   npm run build
   ```

### Configuration

Add the server to your MCP client configuration. For Claude Desktop, edit the config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vs-code-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/vs-code-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}
```

> **Note:** Replace `/path/to/your/vs-code-mcp-server` with the actual path to your cloned repository.

## 🛠️ Available Tools

### 📁 File Operations (8 tools)

| Tool | Description |
|------|-------------|
| `list_files_code` | List files and directories with optional recursive listing |
| `read_file_code` | Read file contents with encoding and line range options |
| `create_file_code` | Create new files with overwrite protection |
| `delete_file_code` | Delete files and directories with recursive options |
| `copy_file_code` | Copy files and directories to new locations |
| `move_file_code` | Move or rename files and directories |
| `create_directory_code` | Create directories with recursive parent creation |
| `search_files_code` | Search for text patterns across files with regex support |

### ⚡ Advanced File Operations (6 tools)

| Tool | Description |
|------|-------------|
| `replace_lines_code` | Replace specific lines with content validation |
| `insert_lines_code` | Insert content at specific line positions |
| `delete_lines_code` | Delete specific line ranges from files |
| `append_to_file_code` | Append content to file end |
| `prepend_to_file_code` | Prepend content to file beginning |
| `find_and_replace_code` | Advanced find/replace with regex support |

### 🖥️ Command Execution (8 tools)

| Tool | Description |
|------|-------------|
| `execute_shell_command_code` | Execute shell commands with timeout control |
| `execute_streaming_command_code` | Execute commands with real-time output streaming |
| `kill_process_code` | Kill processes by PID or name |
| `list_processes_code` | List running processes with filtering |
| `kill_all_processes_code` | Kill multiple processes matching patterns |
| `check_command_code` | Check command availability on system |
| `get_system_info_code` | Get comprehensive system information |
| `run_script_code` | Execute script files with appropriate interpreters |

### 📊 Project Analysis (3 tools)

| Tool | Description |
|------|-------------|
| `analyze_project` | Analyze project structure and provide insights |
| `get_project_stats` | Get detailed codebase statistics |
| `find_dependencies` | Discover and analyze project dependencies |

### 🔍 VS Code Integration (4 tools)

| Tool | Description |
|------|-------------|
| `search_symbols_code` | Search for symbols across workspace with fuzzy matching |
| `get_symbol_definition_code` | Get symbol definitions with type information |
| `get_document_symbols_code` | Get hierarchical symbol outline for files |
| `get_diagnostics_code` | Analyze code for errors and warnings |

## 🔧 Development

### Scripts

- `npm run build` - Build the TypeScript source
- `npm run start` - Start the MCP server
- `npm run dev` - Build and start in development mode
- `npm run watch` - Watch for changes and rebuild automatically
- `npm run test` - Run the test suite

### Project Structure

```
src/
├── index.ts              # Main server implementation
├── tools/                # Tool definitions and handlers
│   ├── file-tools.ts     # Basic file operations
│   ├── advanced-file-tools.ts # Advanced file editing
│   ├── command-tools.ts  # Command execution
│   ├── project-tools.ts  # Project analysis
│   └── vscode-integration-tools.ts # VS Code features
├── types/                # TypeScript type definitions
├── utils/                # Utility functions
│   ├── file-utils.ts     # File operation utilities
│   ├── command-utils.ts  # Command execution utilities
│   ├── file-watcher.ts   # File watching capabilities
│   └── logger.ts         # Logging utilities
```

## 🔒 Security

This MCP server is designed for defensive development tasks only. It includes:

- Input validation and sanitization
- Safe file operation boundaries
- Process execution controls
- Error handling and logging

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🐛 Issues & Support

If you encounter any issues or have questions:

1. Check the [Issues](../../issues) section
2. Create a new issue with detailed information
3. Include error logs and configuration details

## 🙏 Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Designed for integration with [Claude Desktop](https://claude.ai/)
- Supports VS Code development workflows