# VS Code MCP Server

[![GitHub](https://img.shields.io/badge/GitHub-vscode--mcp--server-blue)](https://github.com/chaworld/vscode-mcp-server)
[![Python](https://img.shields.io/badge/Python-3.12+-green)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-1.17.0-orange)](https://modelcontextprotocol.io/)

一個可攜式的 Model Context Protocol (MCP) 伺服器,讓 AI 助手能夠操作 VS Code - 支援檔案管理、擴充套件控制和工作區自動化。

[English](#english) | [繁體中文](#繁體中文)

---

## 繁體中文

### 🌟 特色

- **檔案操作**: 讀取、寫入、建立、刪除檔案和目錄
- **擴充套件管理**: 安裝、列出、啟用/停用 VS Code 擴充套件
- **可攜式設計**: 使用 uvx/pipx 全域執行,無需絕對路徑
- **多客戶端支援**: 
  - ✅ GitHub Copilot CLI
  - ✅ Claude Desktop
  - ✅ Google Gemini CLI
  - ✅ 任何支援 MCP 的客戶端

### 📦 安裝

#### 方法 1: 使用 uvx (推薦)
```bash
# 從專案目錄
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uvx --from . vscode-mcp-server
```

#### 方法 2: 全域安裝
```bash
# 使用 uv
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uv tool install --editable .

# 或使用 pipx
pipx install --editable .

# 之後可直接執行
vscode-mcp-server
```

#### 方法 3: 開發模式
```bash
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uv pip install -e .
python -m vscode_mcp_server
```

### 🔧 客戶端配置

#### GitHub Copilot CLI
```json
{
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

#### Claude Desktop
檔案位置: `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

```json
{
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

#### Google Gemini CLI
```json
{
  "name": "vscode-mcp",
  "version": "0.1.0",
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

### 🛠️ 可用工具

1. **read_file** - 讀取檔案內容
2. **write_file** - 寫入檔案內容
3. **create_directory** - 建立目錄
4. **list_directory** - 列出目錄內容
5. **install_extension** - 安裝 VS Code 擴充套件
6. **list_extensions** - 列出已安裝的擴充套件

### 📖 文件

- [可攜式設定指南](PORTABLE_SETUP.md) - 詳細的可攜式安裝說明
- [全域安裝指南](GLOBAL_INSTALL.md) - 5 種全域安裝方法比較
- [Claude Desktop 設定](CLAUDE_DESKTOP_SETUP.md) - Claude Desktop 完整設定
- [Copilot CLI 設定](COPILOT_CLI_SETUP.md) - GitHub Copilot CLI 設定
- [檔案結構說明](FILE_STRUCTURE.md) - 專案結構文件

### 🧪 測試

```bash
# 安裝開發依賴
uv pip install -e .

# 執行測試
pytest

# 執行測試並顯示詳細輸出
pytest -v
```

### 🤝 貢獻

歡迎提交 Issues 和 Pull Requests!

### 📄 授權

MIT License

---

## English

### 🌟 Features

- **File Operations**: Read, write, create, delete files and directories
- **Extension Management**: Install, list, enable/disable VS Code extensions
- **Portable Design**: Run globally with uvx/pipx, no absolute paths needed
- **Multi-Client Support**: 
  - ✅ GitHub Copilot CLI
  - ✅ Claude Desktop
  - ✅ Google Gemini CLI
  - ✅ Any MCP-compatible client

### 📦 Installation

#### Method 1: Using uvx (Recommended)
```bash
# From project directory
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uvx --from . vscode-mcp-server
```

#### Method 2: Global Installation
```bash
# Using uv
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uv tool install --editable .

# Or using pipx
pipx install --editable .

# Then run directly
vscode-mcp-server
```

#### Method 3: Development Mode
```bash
git clone https://github.com/chaworld/vscode-mcp-server.git
cd vscode-mcp-server
uv pip install -e .
python -m vscode_mcp_server
```

### 🔧 Client Configuration

#### GitHub Copilot CLI
```json
{
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

#### Claude Desktop
File location: `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

```json
{
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

#### Google Gemini CLI
```json
{
  "name": "vscode-mcp",
  "version": "0.1.0",
  "mcpServers": {
    "vscode_local": {
      "command": "uvx",
      "args": ["--from", "/path/to/vscode-mcp-server", "vscode-mcp-server"]
    }
  }
}
```

### 🛠️ Available Tools

1. **read_file** - Read file contents
2. **write_file** - Write file contents
3. **create_directory** - Create directories
4. **list_directory** - List directory contents
5. **install_extension** - Install VS Code extensions
6. **list_extensions** - List installed extensions

### 📖 Documentation

- [Portable Setup Guide](PORTABLE_SETUP.md) - Detailed portable installation guide
- [Global Install Guide](GLOBAL_INSTALL.md) - Comparison of 5 global installation methods
- [Claude Desktop Setup](CLAUDE_DESKTOP_SETUP.md) - Complete Claude Desktop configuration
- [Copilot CLI Setup](COPILOT_CLI_SETUP.md) - GitHub Copilot CLI configuration
- [File Structure](FILE_STRUCTURE.md) - Project structure documentation

### 🧪 Testing

```bash
# Install dev dependencies
uv pip install -e .

# Run tests
pytest

# Run tests with verbose output
pytest -v
```

### 🤝 Contributing

Issues and Pull Requests are welcome!

### 📄 License

MIT License

---

## 🔗 Links

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP](https://github.com/jlowin/fastmcp)
- [VS Code Extension API](https://code.visualstudio.com/api)