Vs MCP Server

vs mcp服务器

由Claude Code（MCP）控制Visual Studio 2022的服务器。 通过COM/DTE自动化，MCP工具提供文件打开、构建、调试器控制、断点管理等功能。

仅限Windows。 COM/DTE只在Windows上运行。

______________________________________________________________________

快速入门

1.安装软件包

pip install vs-mcp-server

2.注册MCP服务器-Claude Code CLI

# uvx 방식 (권장, 가상환경 자동 관리)
claude mcp add --scope project vs -- uvx vs-mcp-server

# 또는 pip install 후 — 직접 실행 방식
claude mcp add --scope project vs -- vs-mcp-server

注册方法（全局、桌面、环境变量等）包括： 安装和注册MCP服务器 请参见部分。

3.运行Visual Studio 2022

如果VS已经在运行，则跳过它。如果没有运行 vs_launch 可以用工具自动执行。

4.从Claude Code连接VS

vs_connect(session_id="s1", solution_path="C:/MyProject/MyProject.sln")

5.开始使用工具

vs_file_open(session_id="s1", path="C:/MyProject/src/main.cpp")
vs_debug_evaluate(session_id="s1", expression="myVar.Value")

______________________________________________________________________

体系结构

Claude Code (MCP Client)
        │  stdio
        ▼
  server.py  ── 22개 도구 등록, 라우팅
        │
  session_manager.py  ── 세션 ↔ VS 인스턴스 바인딩
        │
  com_bridge.STAThread  ── VS 인스턴스 1개당 STA 전용 스레드
        │  immediate / long_running 채널
        ▼
  EnvDTE COM (devenv.exe)  ── out-of-process COM 서버
        │  ROT (Running Object Table)
        ▼
  Visual Studio 2022

核心设计原则：

• STA专用主题：EnvDTE COM仅在单线程公寓（STA）中运行稳定。每个VS实例 STAThread 分配一个。
• 双通道: immediate（编辑操作等快速命令）/ long_running（构建等耗时的命令）可以断开通道，在构建过程中立即处理通道。
• ROT导航: Running Object Table从 VisualStudio.DTE.17.0 搜索监视器并将其连接到正在运行的VS实例。
• 崩溃日志记录: vs_debug_evaluate 结果，COM错误，超时 logs/vs_mcp_crash.jsonl自动记录。

______________________________________________________________________

前提条件

# Python 버전 확인
python --version

______________________________________________________________________

安装和注册MCP服务器

在Claude Code CLI中注册

Claude Code CLI .mcp.json 通过文件管理MCP服务器。

方法1-uvx方法（推荐）

无需另行安装，uvx自动创建并运行虚拟环境。

# 프로젝트별 등록
claude mcp add --scope project vs -- uvx vs-mcp-server

# 전역 등록
claude mcp add --scope user vs -- uvx vs-mcp-server

或 .mcp.json 直接创建：

{
  "mcpServers": {
    "vs": {
      "command": "uvx",
      "args": ["vs-mcp-server"]
    }
  }
}

方法2-pip install后直接运行

# 설치 (git clone 불필요)
pip install vs-mcp-server
# 또는 GitHub에서 직접 설치
pip install git+https://github.com/panninghour/vs-mcp-server

# 등록
claude mcp add --scope project vs -- vs-mcp-server

或 ~/.claude.json(%USERPROFILE%\.claude.json）中创建：

{
  "mcpServers": {
    "vs": {
      "command": "vs-mcp-server"
    }
  }
}

方法3-面向开发人员（本地可编辑安装）

修改源时使用：

git clone https://github.com/panninghour/vs-mcp-server
cd vs-mcp-server
pip install -e .
claude mcp add --scope project vs -- vs-mcp-server

注册确认

# 등록된 MCP 서버 목록 확인
claude mcp list

要查看Claude Code会话中的服务器状态和工具列表，请：

/mcp

vs 服务器显示为已连接。 vs_connect, vs_debug_evaluate 等22个工具需要激活。

______________________________________________________________________

注册到Claude Desktop

claude_desktop_config.json打开 mcpServers添加到。

文件位置（Windows）：

%APPDATA%\Claude\claude_desktop_config.json

设置示例（uvx方式）：

{
  "mcpServers": {
    "vs": {
      "command": "uvx",
      "args": ["vs-mcp-server"],
      "env": {
        "VS_DEVENV_PATH": "C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE/devenv.exe"
      }
    }
  }
}

Claude Desktop重启后反映。

______________________________________________________________________

设置环境变量

VS安装路径示例：

# Community (기본값)
C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\devenv.exe

# Professional
C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\devenv.exe

# Enterprise
C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\devenv.exe

要永久设置环境变量，请：

[System.Environment]::SetEnvironmentVariable(
    "VS_DEVENV_PATH",
    "C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\devenv.exe",
    "User"
)

或 .mcp.json的 env 按服务器将数据块设置为：

"env": {
  "VS_DEVENV_PATH": "C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE/devenv.exe"
}

______________________________________________________________________

工具列表

管理实例

编辑-Claude→用户

编辑-用户→Claude

构建

调试

队列管理

DTE通用

______________________________________________________________________

使用示例

# 1. VS 인스턴스 목록 확인
vs_list_instances()
# → [{"pid": 12345, "solution": "C:/MyProject/MyProject.sln"}]

# 2. 세션 연결
vs_connect(session_id="s1", solution_path="C:/MyProject/MyProject.sln")

# 3. 파일 열기 + 특정 라인으로 이동
vs_file_open(session_id="s1", path="C:/MyProject/src/main.cpp")
vs_file_goto(session_id="s1", path="C:/MyProject/src/main.cpp", line=42)

# 4. 유저가 선택한 코드 읽기
vs_file_selection(session_id="s1")
# → {"text": "int x = foo();", "start_line": 42, "end_line": 42}

# 5. 빌드
vs_build_solution(session_id="s1", configuration="Debug")
# → {"success": true, "failed_projects": 0}

# 6. 브레이크포인트 추가 후 디버깅 시작
vs_debug_breakpoint(session_id="s1", action="add", file="C:/MyProject/src/main.cpp", line=42)
vs_debug_start(session_id="s1", wait_for_break=False)

# 7. Break 모드 진입 후 변수 검사
vs_debug_locals(session_id="s1")
vs_debug_evaluate(session_id="s1", expression="myObj.Value")
vs_debug_callstack(session_id="s1")

# 8. 스텝 실행
vs_debug_step(session_id="s1", step_type="over")

# 9. 디버깅 종료
vs_debug_stop(session_id="s1")

# 10. DTE 명령 직접 실행
vs_command(session_id="s1", command="Edit.FormatDocument")
vs_command(session_id="s1", command="File.SaveAll")

______________________________________________________________________

测试

单元测试（基于mock）

python -m pytest tests/ -v --ignore=tests/test_integration_vs.py

集成测试（实际需要VS2022）

VS2022运行时：

python -m pytest tests/test_integration_vs.py -v -s

如果VS未运行，则自动运行后等待ROT注册。

集成测试项目（18个IT组，28个pytest函数）：

组ID验证内容 |------|----|----------| ROT检测IT-001VS实例检测，PID验证， get_vs_pid() 准确性，过滤舞台项目| DTE属性IT-002| MainWindow, Solution, Version 访问COM属性| |打开文件IT-003| vs_file_open 后 ActiveDocument 确认更改| |文件列表/活动| IT-004| vs_file_list_open, vs_file_active 往返| |构建状态| IT-005 vs_build_status 验证返回值| |断点| IT-006| add / list / remove 积垢| 检查调试器模式IT-0007Design模式， vs_debug_stop | | STAthread队列| IT-008 |查看实际队列机制和历史记录| |光标移动| IT-009| vs_file_goto 后 vs_file_active 往返| |亮点| IT-010 vs_file_highlight 选择范围| |选择文本| IT-011| vs_file_selection 返回值| | 调试会话 |IT-012|新VS实例 DebugTarget.sln 加载、Debug构建、设置BP后确认进入Break模式| | 调试会话 |IT-013|Break模式下 vs_debug_locals → x=42, y=50, msg 检查变量| | 调试会话 |IT-014| vs_debug_evaluate("x + y") == "92", msg呃 "hello from debugger" 包括| | 调试会话 |IT-015| vs_debug_callstack → depth >= 1, .净值8 CurrentStackFrame 回退动作| | 调试会话 |IT-016| vs_debug_step("over") 后 mode == "break", line > BP_LINE, ActiveDocument 回退动作| | 调试会话 |IT-017| vs_debug_stop() → status == "stopped", mode == "design" | DTE通用IT-018 vs_command("Edit.LineEnd") 运行后 status == "executed"，错误命令时传播COM异常| | 错误列表 |IT-019| ErrorTarget.sln 构建后 vs_error_list →CS0103错误，确认解析CS1030警报|

______________________________________________________________________

设置

可调整为环境变量。面向开发人员的安装（pip install -e .）的情况 vs_mcp_server/config.py也可以在中直接修改。

______________________________________________________________________

已知限制

• 仅Windows：COM/DTE仅在Windows上工作。
• VS2022专用: VisualStudio.DTE.17.0 只支持Moniker。
• Python 3.11+：较低版本不保证操作。
• STAThread交叉公寓: STAThread 在内部使用DTE时，需要直接从ROT重新获得DTE。将主线程的DTE指针传递给STAthread RPC_E_WRONG_THREAD 发生。
• 仅Break模式功能: vs_debug_step, vs_debug_locals, vs_debug_evaluate, vs_debug_callstack只有在调试器处于Break模式时才工作。
• .NET 8管理代码限制: CurrentThread.StackFrames COM枚举有时会返回空集合。 vs_debug_callstack银 CurrentStackFrame 回退处理， vs_debug_step银 ActiveDocument.Selection 用回退处理。
• DTE2不可访问（Python）：下面 DTE2限制 参考。

______________________________________________________________________

DTE2限制（Python）

问题

Pythonpywin32是EnvDTE80.DTE2专用属性（ToolWindows 等）无法接近。 VisualStudio.DTE.17.0 通过ProgID从ROT获取的COM对象的默认IDispatch是EnvDTE。\_DTE（v7.0）。 ToolWindows仅存在于DTE2IDispatch vtable的DispId300中。

在Late-binding验证中 InvokeMember("ToolWindows")啊 DISP_E_UNKNOWNNAME (0x80020006)返回，在IDispatch本身中 ToolWindows确认没有。只有C# (DTE2)dte 铸造时通过COM QueryInterface直接获得DTE2vtable。

尝试的方法

1. python win32com.client.Dispatch：无论是否有gen_py缓存，都无法访问DTE2属性
2. python win32com.client.dynamic.Dispatch：late-bound强制→ DISP_E_UNKNOWNNAME （IDispatch中没有）
3. python _oleobj_.GetIDsOfNames("ToolWindows")：相同 DISP_E_UNKNOWNNAME
4. C#桥（subprocess）：DTE2广播成功， ToolWindows.ErrorList 可访问。但是 ErrorList.ErrorItems在外部COM进程中始终返回空集合-需要绕过Build Output解析

当前解决方案

vs_error_list可从DTE1访问 输出窗口解析的Build pane文本并返回错误/警告：

# DTE1으로 접근 가능 (ToolWindows 불필요)
ow = dte.Windows.Item("{34E76E81-EE4A-11D0-AE2E-00A0C90FFFC3}").Object
pane = ow.OutputWindowPanes.Item("Build")
text = pane.TextDocument.StartPoint.CreateEditPoint().GetText(pane.TextDocument.EndPoint)
# → MSBuild 출력 형식 정규식 파싱

这种方式不使用C#桥接或额外的运行时，而是使用纯Python。

______________________________________________________________________

直接访问DTE（Advanced）

无需MCP服务器即可直接从外部Python脚本访问DTE COM对象。VS实例在Windows运行对象表（ROT）中 VisualStudio.DTE.17.0 注册为monicker。

单VS实例

import pythoncom
import win32com.client

pythoncom.CoInitialize()
dte = win32com.client.GetActiveObject("VisualStudio.DTE.17.0")

# 예시: 솔루션 경로 출력
print(dte.Solution.FullName)

注意: GetActiveObject不保证在VS实例运行多个时返回哪个实例。仅在单实例环境中使用。

多个VS实例-使用PID选择特定实例

vs_list_instances 用工具确认PID后，直接从ROT获取该PID的实例。

import pythoncom
import win32com.client
from vs_mcp_server.utils.rot import find_vs_instances, get_vs_pid

pythoncom.CoInitialize()

target_pid = 12345  # vs_list_instances 또는 vs_connect 응답의 instance_pid

entries = find_vs_instances()
dte = next(
    e["dte"] for e in entries
    if get_vs_pid(e["dte"]) == target_pid
)

# 이후 dte 객체를 자유롭게 사용
print(dte.Solution.FullName)

参考: find_vs_instances()在ROT巡回所有 VisualStudio.DTE.17.0 返回项目。 get_vs_pid(dte)是DTE的 MainWindow.HWnd从中提取PID。