流浪MCP服务器（Go实现）

\[！小心\] 这是一项正在进行的工作，尚未准备好使用。

HashiCorp Vagrant的模型上下文协议（MCP）服务器实现，为AI代理提供了创建和管理具有同步文件系统和无缝命令执行功能的开发VM的能力。

注：此服务器必须直接在安装了Vagrant和虚拟化提供程序（例如VirtualBox、libvirt）的主机上运行。不支持在Docker中运行，因为服务器需要直接访问Vagrant CLI、虚拟化驱动程序和项目文件。

特性

开发VM管理： 创建、确保和销毁开发虚拟机
同步命令执行： 在VM内执行命令，并保证文件同步
文件系统同步： 配置同步方法、监视同步状态和解决冲突
开发环境设置： 安装语言运行时、工具和依赖项

工作示例提示

以下是您可以与AI助手一起使用的示例提示，以演示服务器的功能：

VM管理示例

“为此Node.js项目创建一个4GB RAM的开发VM，并同步当前目录”
“为这个Python项目设置一个名为'myapp-dev'的新开发环境，并自动进行文件同步”
“使用默认的Ubuntu盒子启动开发VM，并确保端口3000被转发到主机”

命令执行示例

“在开发VM中运行'npm install'，并确保所有文件在前后同步”
“在VM环境中执行测试套件并向我显示结果”
“在VM内后台运行开发服务器并转发端口3000”

环境设置示例

“在开发VM中安装Node.js版本18和npm”
“使用pip和virtualenv设置Python开发环境”
“在VM中安装Docker和Docker compose进行容器化开发”

文件同步示例

“将我的所有本地更改同步到开发VM”
“将dist/文件夹上传到VM并解压缩”
“检查同步状态，并通过保留主机版本来解决任何冲突”

系统要求

Vagrant CLI： Vagrant命令行界面必须在PATH中安装并可用
虚拟化提供商： 受支持的虚拟化提供商（例如VirtualBox、VMware、Hyper-V或libvirt）
执行1.18+： 从源头建造所需

您可以通过运行以下命令来验证Vagrant是否安装正确：

vagrant --version

安装

下载预构建二进制文件（推荐）

从以下网址下载适用于您平台的最新版本发布页面:

平台	架构	下载
Linux	x86_64	流浪者mcp服务器-linux-amd64
Linux	ARM64	流浪汉mcp服务器-linux-arm64
macOS	英特尔	流浪汉mcp服务器darwin-amd64
macOS	苹果硅	流浪汉mcp服务器darwin-arm64
Windows	x86_64	流浪汉mcp服务器-windows-amd64.exe

安装步骤：

# Download the appropriate binary for your platform
curl -L -o vagrant-mcp-server https://github.com/vagrant-mcp/server/releases/latest/download/vagrant-mcp-server-linux-amd64

# Make it executable (Linux/macOS)
chmod +x vagrant-mcp-server

# Move to your PATH (optional)
sudo mv vagrant-mcp-server /usr/local/bin/

# Verify installation
vagrant-mcp-server -version

验证完整性：

# Download checksums file
curl -L -O https://github.com/vagrant-mcp/server/releases/latest/download/checksums.txt

# Verify your binary
sha256sum -c checksums.txt --ignore-missing

从源代码构建

# Clone the repository
git clone https://github.com/vagrant-mcp/server.git vagrant-mcp-server
cd vagrant-mcp-server

# Build the server
make build

# Start the server (stdio mode by default)
./bin/vagrant-mcp-server

配置

可以使用环境变量配置服务器：

MCP_TRANSPORT -要使用的传输类型（stdio或sse，默认值：stdio）
MCP_PORT -用于SSE传输的端口（默认值：8080）
LOG_LEVEL -日志记录级别（调试、信息、警告、错误、默认值：信息）
VSCODE_MCP -从VS Code运行时设置为“true”
VM_BASE_DIR -VM文件的基本目录（默认：~/.vargant-mcp服务器/vms）

VS代码集成

Vagrant MCP Server可以与Visual Studio Code一起使用，允许AI助手直接从编辑器创建和管理开发VM。

先决条件

确保已按照安装部分中的说明构建了服务器
确保您的系统上安装了Vagrant CLI和虚拟化提供程序
安装Visual Studio代码

在VS代码中安装的步骤

配置VS代码设置

将以下内容添加到您的VS代码中 settings.json 或 mcp.json 文件（命令选项板>首选项：打开用户设置（JSON））：

   "mcp": {
     "inputs": [],
     "servers": {
       "vagrant-mcp-server": {
         "type": "stdio",
         "command": "/path/to/vagrant-mcp-server/bin/vagrant-mcp-server",
         "description": "Manage Vagrant development VMs",
         "env": {
           "VSCODE_MCP": "true"
         }
       }
     }
   }

替换 /path/to/vagrant-mcp-server 使用构建的服务器二进制文件的绝对路径。

重新启动VS代码

重新启动VS Code以应用新的MCP连接设置。

使用具有VS Code AI功能的MCP服务器

现在，VS Code中的AI助手将能够：

- 为您的项目创建开发虚拟机 - 在虚拟机内执行命令 - 在本地系统和虚拟机之间同步文件 - 安装开发工具和语言 - 管理VM生命周期（启动/停止/销毁）

AI助手使用示例

您可以向AI助手提出以下问题：

- “为此项目创建开发VM” - “在VM中运行测试” - “在开发VM中安装Node.js” - “在VM中执行应用程序并转发端口3000”

安全考虑

使用带有VS代码的Vagrant MCP服务器时：

权限：服务器以您的用户权限运行，可以：

- 在项目目录中创建、修改和删除文件 - 通过Vagrant在系统上执行命令 - 代表您管理虚拟机

访问控制:

- 仅在您信任具有上述权限的AI助手的系统上安装此MCP服务器 - 服务器本身不提供身份验证机制，它依赖于VS Code的安全模型 - 不要在公共网络上暴露SSE传输（如果使用SSE模式）

数据处理:

- 在主机和VM之间同步敏感数据时要小心 - 考虑对机密文件使用同步排除模式

资源管理:

- 监控创建的虚拟机的资源使用情况，以防止过度消耗 - 当不再需要虚拟机时，始终销毁它们

VS代码集成故障排除

如果您遇到VS Code集成问题：

检查服务器日志:

- 设置 LOG_LEVEL 环境变量 debug 在您的settings.json中：

“mcp”：{ “输入”：\[\]， “服务器”：{ “流浪mcp服务器”：{ “类型”：“stdio”， “command”：“/path/to/vagrant-mcp服务器/bin/vagrant-mcp-server”， “description”：“管理Vagrant开发虚拟机”， “env”：{ “LOGLEVEL”：“调试”， “VSCODE_MCP”：“true” } } } }

验证Vagrant安装:

- 跑 vagrant --version 在您的终端中确认Vagrant已正确安装 - 确保您的虚拟化提供商（VirtualBox等）正常工作

检查路径:

- 确保您的settings.json中指向服务器二进制文件的路径正确 - 验证与服务器一起使用的项目路径是否有效且可访问

常见问题:

- “未安装Vagrant”错误：将Vagrant添加到PATH或指定环境中的完整路径 - “创建VM失败”：检查您的虚拟化提供程序是否正在运行且配置正确 - 连接问题：重新启动VS Code并检查MCP服务器是否配置正确

用法

MCP工具

开发VM管理

create_dev_vm：创建和配置开发VM

- 参数： - name （string）：开发VM的名称 - project_path （string）：要同步的项目目录的路径 - cpu （数字，可选）：CPU核数（默认值：2） - memory （数字，可选）：内存量（MB）（默认值：2048） - box （字符串，可选）：要使用的模糊框（默认值：“ubuntu/focal64”） - sync_type （字符串，可选）：要使用的同步类型（默认值：“rsync”） - 示例提示： - 为当前项目目录创建一个名为“webapp-dev”的开发虚拟机 - “在/home/user/myapi中为项目设置一个名为‘api服务器’的虚拟机，内存为4GB” - “为机器学习项目创建一个8核8GB RAM的高性能虚拟机”

ensure_dev_vm：确保开发VM正在运行

- 参数： - name （string）：要确保的VM的名称 - 示例提示： - “确保'webapp-dev'虚拟机正在运行并准备就绪” - “如果开发VM尚未运行，请启动它” - “确保我的项目VM已启动并可用于开发”

destroy_dev_vm：销毁开发VM

- 参数： - name （string）：要销毁的VM的名称 - 示例提示： - “清理并销毁‘旧项目’开发VM” - “删除虚拟机以释放磁盘空间” - “永久删除虚拟机及其所有资源”

命令执行

exec_in_vm：使用预/后文件同步在VM内执行命令

- 参数： - vm_name （string）：虚拟机的名称 - command （string）：要执行的命令 - working_dir （字符串，可选）：工作目录 - env （对象，可选）：环境变量 - 示例提示： - “在开发VM中运行'npm test'，并同步前后文件” - “使用最新的代码更改在VM中执行构建脚本” - “在VM环境中运行数据库迁移命令”

exec_with_sync：在同步之前/之后显式执行命令

- 参数： - vm_name （string）：虚拟机的名称 - command （string）：要执行的命令 - sync_before （boolean）：执行前同步文件 - sync_after （boolean）：执行后同步文件 - working_dir （字符串，可选）：工作目录 - env （对象，可选）：环境变量 - 示例提示： - 先运行测试，不同步文件，但将结果同步回来 - “执行linter并仅将固定文件同步回主机” - “运行开发服务器，不进行任何文件同步”

run_background_task：将VM中的命令作为后台任务运行

- 参数： - vm_name （string）：虚拟机的名称 - command （string）：要执行的命令 - sync_before （boolean）：执行前同步文件 - working_dir （字符串，可选）：工作目录 - 示例提示： - “在VM中后台启动开发服务器” - “在VM后台运行文件监视器进程” - “在VM中启动数据库服务器并保持其运行”

sync_to_vm：从主机手动同步到VM

- 参数： - vm_name （string）：虚拟机的名称 - path （字符串，可选）：同步路径（默认：所有路径） - 示例提示： - “将我最新的代码更改同步到开发VM” - “将新的配置文件上载到VM” - “将我所有未提交的更改推送到VM环境”

sync_from_vm：从VM手动同步到主机

- 参数： - vm_name （string）：虚拟机的名称 - path （字符串，可选）：同步路径（默认：所有路径） - 示例提示： - “从VM下载生成的构建工件” - “将VM中的日志文件同步到我的本地计算机” - “将VM中所做的任何更改拉回到我的主机”

upload_to_vm：将文件从主机上载到VM

- 参数： - vm_name （string）：虚拟机的名称 - source （string）：主机上的源文件或目录路径 - destination （string）：VM上的目标路径 - compress （boolean，可选）：上传前是否压缩文件 - compression_type （字符串，可选）：要使用的压缩类型（tgz或zip） - 示例提示： - “将数据文件上传到VM中的/tmp/data” - “将backup.tar.gz文件复制到VM的主目录” - “将依赖项文件夹上载并提取到VM”

环境设置

setup_dev_environment：安装语言运行时和工具

- 参数： - vm_name （string）：虚拟机的名称 - runtimes （array）：要安装的语言运行时（例如“node”、“python”、“go”） - tools （阵列，可选）：要安装的其他工具 - 示例提示： - “在开发VM中安装Node.js和Python” - “使用所有必要的工具设置Go开发环境” - “安装Ruby和Rails进行web开发”

install_dev_tools：安装特定的开发工具

- 参数： - vm_name （string）：虚拟机的名称 - tools （array）：要安装的工具列表 - 示例提示： - “在VM中安装Docker和Docker compose” - 将git、vim和curl添加到开发环境中 - “安装最新版本的PostgreSQL和Redis”

configure_shell：配置shell环境

- 参数： - vm_name （string）：虚拟机的名称 - shell_type （string，可选）：Shell配置（bash、zsh等） - env_vars （数组，可选）：要设置的环境变量 - aliases （数组，可选）：要配置的Shell别名 - 示例提示： - “在VM中使用开发别名设置zsh” - “使用自定义环境变量配置bash” - “为常用开发命令添加有用的别名”

同步

configure_sync：配置同步方法和选项

- 参数： - vm_name （string）：虚拟机的名称 - sync_type （string）：同步类型（rsync、nfs、smb、virtualbox） - exclude_patterns （数组，可选）：要排除的模式 - guest_path （字符串，可选）：要同步的访客路径 - host_path （字符串，可选）：要同步的主机路径 - 示例提示： - “配置NFS同步以实现更快的文件操作” - “设置rsync，排除node_modules和.git文件夹” - “切换到SMB同步以获得更好的Windows主机兼容性”

sync_status：检查同步状态

- 参数： - vm_name （string）：虚拟机的名称 - 示例提示： - “检查主机和VM之间是否同步了所有文件” - “显示当前同步状态和任何挂起的更改” - “验证文件同步是否正常工作”

resolve_sync_conflicts：解决同步冲突

- 参数： - vm_name （string）：虚拟机的名称 - path （string）：冲突文件的路径 - resolution （string）：解析方法（“use_host”、“use_vm”、“merge”、“keep_both”） - 示例提示： - “通过保留主机版本来解决同步冲突” - “使用VM版本修复配置文件中的同步冲突” - “合并冲突的文件并保留两个版本”

search_code：在VM中语义搜索代码

- 参数： - vm_name （string）：虚拟机的名称 - query （string）：搜索查询 - search_type （字符串，可选）：搜索类型（“语义”、“精确”、“模糊”） - max_results （数字，可选）：返回的最大结果 - case_sensitive （布尔值，可选）：区分大小写的搜索 - 示例提示： - “查找处理用户身份验证的所有函数” - “在VM中搜索数据库连接代码” - “在所有项目文件中查找TODO注释”

get_vm_status：获取开发虚拟机的状态

- 参数： - name （string，可选）：要检查的特定VM的名称 - 示例提示： - “显示所有开发虚拟机的状态” - “检查'webapp-dev'虚拟机是否正在运行且健康” - “获取开发VM的资源使用统计信息”

隐私政策

数据收集： Vagrant MCP服务器不会收集、存储或向外部服务器传输任何个人数据或项目信息。所有操作都在您的开发机器上本地执行。

本地数据处理：

项目文件仅在主机和本地VM之间同步
命令在开发环境中本地执行
不收集遥测、分析或使用数据
未与外部服务建立网络连接（您配置的下载Vagrant盒子除外）

VM数据： 此服务器创建的虚拟机仅包含您明确提供的数据。虚拟机存储在您的计算机上，不会在任何地方共享或传输。

登录中： 服务器出于调试目的生成本地日志。这些日志保留在您的计算机上，不会向外传输。

安全

安全考虑

此MCP服务器提供了需要仔细考虑的强大功能：

权限和访问：

服务器以您的用户权限运行，可以创建、修改和删除项目目录中的文件
通过服务器执行的命令在VM中运行，但会通过文件同步影响您的主机系统
服务器可以代表您管理虚拟机，包括资源分配和网络配置

网络安全：

此服务器创建的VM可能会将端口转发到您的主机
确保防火墙规则适合您的开发需求
在没有适当安全措施的情况下，不要暴露公共网络上的转发端口

文件系统安全：

在主机和VM之间同步敏感数据时要小心
对机密文件使用同步排除模式(.env、私钥等）
定期检查同步配置，以防止意外的数据泄露

资源安全：

监控创建的虚拟机的资源使用情况，以防止资源耗尽
在不再需要释放资源时销毁虚拟机
为虚拟机设置适当的内存和CPU限制

发展

先决条件

上涨1.18或更高
Vagrant CLI -运行服务器和测试都需要

- 所有测试都使用真正的Vagrant CLI进行验证 - 如果未安装Vagrant，则将跳过需要Vagrant的测试 - CI中可能会跳过一些需要完整VM环境的测试

受支持的虚拟化提供商 -建议使用VirtualBox进行开发

常见任务

# Format code
go fmt ./...

# Lint code
make lint

# Run unit tests (requires Vagrant CLI installed)
make test

# Run integration tests (requires Vagrant CLI and a virtualization provider)
make test-integration

# Run VM start tests (actually starts VMs - very slow)
make test-vm-start

# See all test options
make help-test

# Security checks
make sec

# Build all release binaries
git tag v1.0.0  # or your version
git push --tags
make release

开发人员脚本

这 dev-scripts/ 目录包含用于开发和手动测试的可选实用程序：

test_script.sh：用于测试的shell脚本示例 exec_in_vm 工具。可以在VM中上传和执行，以验证命令执行和环境设置。
test_mcp.py：Python实用程序，用于向MCP服务器发送JSON-RPC请求以进行手动或临时测试。对于希望在正常客户端工作流之外与服务器交互的开发人员来说很有用。

这些脚本不是正常操作或生产使用所必需的，但可能对贡献者和高级用户有所帮助。

测试和验证

在生产中使用之前，我们建议使用MCP Inspector测试服务器：

# Install the MCP Inspector (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector /path/to/vagrant-mcp-server/bin/vagrant-mcp-server

开发人员脚本

这 dev-scripts/ 目录包含用于开发和手动测试的可选实用程序：

test_script.sh：用于测试的shell脚本示例 exec_in_vm 工具。可以在VM中上传和执行，以验证命令执行和环境设置。
test_mcp.py：Python实用程序，用于向MCP服务器发送JSON-RPC请求以进行手动或临时测试。对于希望在正常客户端工作流之外与服务器交互的开发人员来说很有用。

这些脚本不是正常操作或生产使用所必需的，但可能对贡献者和高级用户有所帮助。

兼容性测试

此服务器已通过以下方式进行了测试和验证：

克劳德·艾 -与web界面完全兼容
Claude桌面版 -完整的VS代码集成支持
MCP连接器 -符合标准MCP协议
流浪者2.3+ -所有支持的Vagrant版本
VirtualBox、VMware、Hyper-V、libvirt -主要虚拟化提供商

VM清理

在测试和开发过程中，虚拟机偶尔可能无法正确清理。我们提供了几种机制来处理这个问题：

自动清理

测试使用强大的清理过程自动清理VM，该过程：

尝试正常的VM停止和销毁操作
使用Vagrant全局命令进行强制摧毁
记录所有清理活动以进行调试

手动清理

如果您发现孤立的测试VM，可以手动清理它们：

# Check for any running VMs
vagrant global-status

# Destroy a specific VM by ID
vagrant destroy VM_ID --force

当前没有捆绑的清理脚本。使用上述Vagrant命令进行手动清理。

集成测试配置

长期运行的集成测试（实际创建虚拟机）被封闭在环境变量后面：

# Run unit tests only (default, no VMs created)
make test

# Run integration tests (creates real VMs)
make test-integration

这可以防止在正常开发过程中意外创建VM，同时允许在需要时进行完全集成测试。

发布过程

我们的自动化发布流程确保了质量和可靠性：

自动化测试 -在每次提交时运行全面的测试套件
安全扫描 -扫描代码以查找安全漏洞
集成测试 -测试真实的流浪环境
文件审查 -所有文件均经过准确性验证
MCP协议合规性 -根据官方MCP规范进行验证

创建发布： 当按下git标签时，会自动创建发布：

# Create and push a new version tag
git tag v1.0.0
git push origin v1.0.0

这将触发GitHub Actions工作流，该工作流：

验证版本标记格式
运行包括集成测试在内的完整测试套件
为所有支持的平台（Linux、macOS、Windows）构建二进制文件
为所有二进制文件生成SHA256校验和
创建包含所有资产的GitHub版本
包括详细的发行说明和更新日志

版本管理：

版本号自动从git标签中提取
源代码中没有硬编码版本
版本、提交和构建元数据的构建时注入
支持语义版本控制（例如v1.0.0、v1.0.0-beta.1）

联系和支持

项目维护人员： 流浪的MCP服务器团队\ 电子邮件： support@vagrant-mcp-server.dev\ 存储库： \ 问题：

响应时间：

安全漏洞：24小时内
Bug报告：72小时内
功能请求：1周内

维修承诺： 该项目通过定期更新、安全补丁和功能增强进行积极维护。我们承诺支持Vagrant和主要虚拟化提供商的最新稳定版本。

许可证

此项目根据Mozilla公共许可证2.0（MPL-2.0）获得许可。

此源代码表受Mozilla公共许可证2.0版条款的约束。如果MPL的副本没有与此文件一起分发，您可以在http://mozilla.org/MPL/2.0/.

Vagrant MCP Server

快速接入

详细介绍

流浪MCP服务器（Go实现）

特性

工作示例提示

VM管理示例

命令执行示例

环境设置示例

文件同步示例

系统要求

安装

下载预构建二进制文件（推荐）

从源代码构建

配置

VS代码集成

先决条件

在VS代码中安装的步骤

安全考虑

VS代码集成故障排除

用法

MCP工具

开发VM管理

命令执行

环境设置

同步

隐私政策

安全

安全考虑

发展

先决条件

常见任务

开发人员脚本

测试和验证

开发人员脚本

兼容性测试

VM清理

自动清理

手动清理

集成测试配置

发布过程

联系和支持

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP