README.md•12.2 kB
# VSCode Internal Command MCP Server
🚀 一个基于 [FastMCP](https://github.com/punkpeye/fastmcp) 框架的 VSCode 扩展，将 VSCode 转换为 MCP (Model Context Protocol) 服务器，支持外部客户端通过 HTTP Streaming 和 Server-Sent Events (SSE) 执行 VSCode 内部命令。
[English Documentation](./doc/README.en.md)
## ✨ 功能特性
- 🌐 **HTTP Streaming 支持**: 使用 `text/event-stream` 协议，支持实时通信
- 🔧 **VSCode 命令执行**: 远程执行任意 VSCode 内部命令
- 📊 **工作区信息查询**: 获取当前工作区状态和文件信息
- ⚡ **异步后台执行**: 支持异步命令执行，不阻塞用户界面
- ⏰ **可配置延时**: 支持设置命令执行延时
- 🛡️ **安全控制**: 可配置的命令白名单机制
- 📡 **实时状态监控**: 状态栏显示服务器运行状态
- 🔗 **标准 MCP 协议**: 完全兼容 Model Context Protocol 规范
- ⚡ **高性能**: 基于 FastMCP 框架，支持并发请求和会话管理
- 🩺 **健康检查**: 内置健康检查端点
## 📦 安装
### 1. 克隆项目
```bash
git clone https://github.com/bestk/vscode-internal-command-mcp-server
cd vscode-internal-command-mcp-server
```
### 2. 安装依赖
```bash
npm install
```
### 3. 编译项目
```bash
npm run compile
```
### 4. 在 VSCode 中安装
- 按 `F5` 启动扩展开发主机
- 或者打包为 `.vsix` 文件进行安装
## ⚙️ 配置
在 VSCode 设置中配置服务器参数：
```json
{
"vscode-internal-command-mcp-server.port": 8080,
"vscode-internal-command-mcp-server.host": "localhost",
"vscode-internal-command-mcp-server.autoStart": true,
"vscode-internal-command-mcp-server.asyncExecution": true,
"vscode-internal-command-mcp-server.executionDelay": 1000,
"vscode-internal-command-mcp-server.showAsyncNotifications": false,
"vscode-internal-command-mcp-server.allowedCommands": [
"editor.action.formatDocument",
"workbench.action.files.save",
"editor.action.clipboardCopyAction"
]
}
```
### 配置说明
| 配置项 | 类型 | 默认值 | 说明 |
| ------------------------ | -------- | ----------- | -------------------------------------------- |
| `port` | number | 8080 | MCP 服务器端口 |
| `host` | string | "localhost" | MCP 服务器主机地址 |
| `autoStart` | boolean | true | 扩展激活时自动启动服务器 |
| `asyncExecution` | boolean | true | 启用异步命令执行（立即返回，后台执行） |
| `executionDelay` | number | 0 | 命令执行延时（毫秒） |
| `showAsyncNotifications` | boolean | false | 显示异步命令执行完成通知 |
| `allowedCommands` | string[] | [] | 允许执行的命令列表（空数组表示允许所有命令） |
## 🚀 使用方法
### 启动服务器
1. **自动启动**: 扩展激活时自动启动（如果 `autoStart` 为 true）
2. **手动启动**:
- 命令面板: `VSCode Internal Command MCP Server: Start Server`
- 或点击状态栏中的 🚀 VSCode internal command MCP 按钮
### 服务器地址
- **MCP 端点**: `http://localhost:8080/mcp`
- **健康检查**: `http://localhost:8080/health`
### 状态监控
- 状态栏显示: 🚀 VSCode internal command MCP 🟢 (运行中) / 🚀 VSCode internal command MCP 🔴 (已停止)
- 命令面板: `VSCode Internal Command MCP Server: Show Status` 查看详细状态
## 🛠️ 可用工具 (MCP Tools)
### 1. execute_vscode_command
执行 VSCode 内部命令
**参数**:
```typescript
{
command: string; // VSCode 命令 ID
arguments?: string[]; // 命令参数（可选）
}
```
**异步执行响应示例**:
```json
{
"success": true,
"async": true,
"taskId": "bg_task_1_1756952250790",
"message": "命令 'composer.cancelComposerStep' 已提交到后台执行，将在 1000ms 后执行",
"command": "composer.cancelComposerStep",
"arguments": [],
"executionDelay": 1000,
"queueLength": 1,
"taskStats": {
"total": 1,
"pending": 1,
"running": 0,
"completed": 0,
"failed": 0,
"cancelled": 0
}
}
```
### 2. list_vscode_commands
列出所有可用的 VSCode 命令
**参数**: 无
**返回**: 命令列表（前20个，如果超过会显示省略提示）
### 3. get_workspace_info
获取当前工作区信息
**参数**: 无
**返回**:
```typescript
{
name: string; // 工作区名称
folders: Array<{
// 工作区文件夹
name: string;
uri: string;
}>;
activeEditor: string; // 当前活动编辑器文件路径
}
```
## 🔌 客户端连接
### 使用官方 MCP SDK
```typescript
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const transport = new StreamableHTTPClientTransport(new URL('http://localhost:8080/mcp'), {
requestInit: {
headers: {
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
},
},
});
const client = new Client({
name: 'vscode-mcp-client',
version: '1.0.0',
});
// 连接并使用
await client.connect(transport);
// 调用工具
const result = await client.callTool({
name: 'execute_vscode_command',
arguments: {
command: 'editor.action.formatDocument',
},
});
console.log('Command result:', result);
```
### 使用 Cursor
在 Cursor 中配置 MCP 服务器：
```json
{
"mcpServers": {
"vscode-internal-commands": {
"url": "http://localhost:8080/mcp",
"transport": "http"
}
}
}
```
### 使用 curl 测试
```bash
# 健康检查
curl http://localhost:8080/health
# 列出工具
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'
# 执行命令
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "execute_vscode_command",
"arguments": {
"command": "workbench.action.files.save"
}
}
}'
```
## 🏗️ 技术架构
### 核心组件
```
┌─────────────────────────┐
│ VSCode Extension │
├─────────────────────────┤
│ FastMcpServer │ ← 基于 FastMCP 框架
├─────────────────────────┤
│ ServerManager │ ← 服务器管理和状态
├─────────────────────────┤
│ CommandExecutor │ ← VSCode 命令执行器
├─────────────────────────┤
│ BackgroundTaskExecutor │ ← 后台任务执行器
├─────────────────────────┤
│ TaskProvider │ ← VS Code 任务提供者
└─────────────────────────┘
```
### 技术栈
- **框架**: [FastMCP](https://github.com/punkpeye/fastmcp) - TypeScript MCP 服务器框架
- **协议**: Model Context Protocol (MCP)
- **传输**: HTTP Streaming with Server-Sent Events (SSE)
- **验证**: Zod Schema 验证
- **平台**: VSCode Extension API
- **异步执行**: 基于 setInterval 的后台任务队列
### 网络协议
- **传输类型**: `httpStream`
- **内容类型**: `text/event-stream`
- **支持协议**: HTTP/1.1
- **CORS**: 默认启用
### 异步执行机制
- **任务队列**: 基于 Map 数据结构的内存队列
- **执行器**: 使用 setInterval 定期检查待执行任务
- **状态管理**: 支持 pending、running、completed、failed、cancelled 状态
- **延时执行**: 支持配置延时，任务在指定时间后执行
- **通知系统**: 可选的执行完成通知
## 🔧 开发
### 项目结构
```
vscode-internal-command-mcp-server/
├── src/
│ ├── extension.ts # 扩展入口点
│ ├── fastMcpServer.ts # FastMCP 服务器实现
│ ├── serverManager.ts # 服务器管理器
│ ├── commandExecutor.ts # VSCode 命令执行器
│ ├── backgroundTaskExecutor.ts # 后台任务执行器
│ └── taskProvider.ts # VS Code 任务提供者
├── out/ # 编译输出
├── package.json # 扩展配置和依赖
├── tsconfig.json # TypeScript 配置
└── README.md # 项目文档
```
### 开发命令
```bash
# 开发模式编译
npm run compile
# 监视模式编译
npm run watch
# 启动开发
code . # 打开 VSCode，按 F5 启动调试
```
### 调试
1. 在 VSCode 中打开项目
2. 按 `F5` 启动扩展开发主机
3. 在新窗口中测试扩展功能
4. 查看调试控制台输出
## 🧪 测试
### 使用内置测试工具
1. 启动服务器后，使用命令: `VSCode Internal Command MCP Server: Test MCP Tools`
2. 选择要测试的工具
3. 输入必要的参数
4. 查看执行结果
### 使用 FastMCP CLI
```bash
# 使用 FastMCP 开发工具测试
npx fastmcp dev src/fastMcpServer.ts
# 使用 MCP Inspector 检查
npx fastmcp inspect src/fastMcpServer.ts
```
## 🛡️ 安全考虑
### 命令白名单
为了安全起见，建议配置 `allowedCommands` 白名单：
```json
{
"vscode-internal-command-mcp-server.allowedCommands": [
"editor.action.formatDocument",
"workbench.action.files.save",
"workbench.action.files.saveAll",
"editor.action.clipboardCopyAction",
"editor.action.clipboardPasteAction"
]
}
```
### 网络安全
- 默认只监听 `localhost`，避免外部访问
- 支持 CORS，但建议在生产环境中配置适当的源限制
- 所有命令执行都在 VSCode 安全上下文中进行
### 异步执行安全
- 任务队列在内存中管理，扩展关闭时自动清理
- 支持任务取消和状态监控
- 执行失败时提供详细错误信息
## 📝 更新日志
### v0.0.2 (当前版本)
- ✅ 重构异步执行机制，使用后台任务队列
- ✅ 修复配置刷新问题，确保配置变更立即生效
- ✅ 优化任务状态管理和监控
- ✅ 改进错误处理和日志记录
- ✅ 简化代码结构，移除冗余组件
### v0.0.1
- ✅ 基于 FastMCP 框架实现 MCP 服务器
- ✅ 支持 HTTP Streaming 和 SSE
- ✅ 实现三个核心工具：命令执行、命令列表、工作区信息
- ✅ 状态栏集成和实时监控
- ✅ 健康检查端点
- ✅ Zod Schema 参数验证
- ✅ TypeScript 5.9+ 支持
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
### 开发指南
1. Fork 项目
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 提交更改: `git commit -m 'Add amazing feature'`
4. 推送分支: `git push origin feature/amazing-feature`
5. 创建 Pull Request
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE.md) 文件
## 🙏 致谢
- [FastMCP](https://github.com/punkpeye/fastmcp) - 优秀的 TypeScript MCP 框架
- [Model Context Protocol](https://modelcontextprotocol.io/) - 标准协议规范
- VSCode Extension API - 强大的扩展平台
## 📞 支持
如果您遇到问题或有疑问：
1. 查看 [Issues](https://github.com/bestk/vscode-internal-command-mcp-server/issues)
2. 创建新的 Issue
3. 查看 FastMCP 文档: https://github.com/punkpeye/fastmcp
---
**🚀 让 VSCode 成为您的 MCP 服务器，释放无限可能！**
