vMCP (Jaimecernuda)

vMCP-虚拟模型上下文协议

受DXT（桌面扩展）规范启发的模型上下文协议（MCP）服务器的统一网关

vMCP提供了一个类似虚拟文件系统的抽象层，通过一个接口聚合多个MCP服务器，实现了对科学计算、数据分析等各种工具和功能的无缝访问。

🔗 什么是vMCP？

vMCP（虚拟模型上下文协议）是一种 网关和代理系统 即：

• 统一多个MCP服务器：通过单一界面访问14多种科学计算工具
• DXT风格建筑：使用类似于VS Code或Chrome扩展程序的扩展程序打包
• 扩展管理：安装、启用、禁用和管理MCP服务器，如浏览器扩展
• Persona支持：控制哪些工具可供不同用户/环境使用
• stdio运输：与Claude Desktop和其他MCP客户端兼容

将vMCP视为具有统一网关接口的“MCP服务器的包管理器”。

🚀 快速开始

先决条件

• Python 3.10+
• 紫外线 包管理器

安装

# Clone and install
git clone https://github.com/JaimeCernuda/vmcp.git
cd vmcp
uv sync --all-extras

# Initialize configuration
uv run vmcp config init

# List available extensions
uv run vmcp extension list

基本用法

# Install and enable an extension
uv run vmcp extension install arxiv-mcp
uv run vmcp extension enable arxiv-mcp

# Start the vMCP gateway
uv run vmcp start

# Now Claude Desktop can connect to vMCP as a single MCP server
# and access all enabled extensions through the unified interface

📦 可用扩展

vMCP附带了14个预打包的科学计算扩展：

🏗️ 系统架构

graph TB
    A[Claude Desktop] --> B[vMCP Gateway]
    B --> C[Extension Manager]
    B --> D[Registry System]
    B --> E[Routing Engine]
    
    C --> F[Extension Repository]
    F --> G[arxiv-mcp.vext]
    F --> H[pandas-mcp.vext]
    F --> I[plot-mcp.vext]
    F --> J[... 11 more]
    
    E --> K[Enabled Extensions]
    K --> L[ArXiv Tools]
    K --> M[Pandas Tools]
    K --> N[Plot Tools]

关键组件

• 网关服务器：stdio传输与MCP客户端兼容
• 扩展管理器：DXT启发的扩展生命周期管理
• 处置库系统：管理扩展包（.vext文件）
• 注册表：跟踪已安装和启用的扩展
• 路由引擎：将请求路由到适当的MCP服务器
• Persona系统：出入控制和工具限制（计划中）

📖 教程和命令

扩展管理

列表扩展

# List all available extensions
uv run vmcp extension list

# List only installed extensions
uv run vmcp extension list --installed

# List only enabled extensions  
uv run vmcp extension list --enabled

# JSON format for scripting
uv run vmcp extension list --format json

安装扩展

# Install from built-in repository
uv run vmcp extension install pandas-mcp

# Install from specific repository
uv run vmcp extension install pandas-mcp --repository builtin

启用/禁用扩展

# Enable an extension (makes it available to vMCP)
uv run vmcp extension enable pandas-mcp

# Enable with custom configuration
uv run vmcp extension enable pandas-mcp --config '{"debug": true}'

# Disable an extension
uv run vmcp extension disable pandas-mcp

扩展信息

# Detailed information about an extension
uv run vmcp extension info pandas-mcp

# Shows: description, tools, status, installation path, etc.

更新和卸载

# Update an extension
uv run vmcp extension update pandas-mcp

# Uninstall an extension
uv run vmcp extension uninstall pandas-mcp

# Force uninstall (even if enabled)
uv run vmcp extension uninstall pandas-mcp --force

网关操作

启动/停止网关

# Start vMCP gateway with default config
uv run vmcp start

# Start with custom config
uv run vmcp start --config my-config.toml

# Stop the gateway
uv run vmcp stop

# Check gateway status
uv run vmcp status

系统信息

# List all registered servers
uv run vmcp list

# Show detailed system information
uv run vmcp info

# Health monitoring
uv run vmcp health check

# System metrics
uv run vmcp metrics show

配置管理

# Create default configuration
uv run vmcp config init

# Create config at specific location
uv run vmcp config init --output /path/to/config.toml

# Validate configuration file
uv run vmcp config validate config.toml

库管理

# Search for extensions
uv run vmcp repo search pandas

# Repository statistics
uv run vmcp repo stats

# Discover available extensions
uv run vmcp repo discover

壳牌完井

# Generate bash completion
uv run vmcp completion bash

# Generate zsh completion  
uv run vmcp completion zsh

# Add to your shell profile
uv run vmcp completion bash >> ~/.bashrc

⚙️ 配置

基本配置(vmcp_config.toml)

version = "0.1.0"

[gateway]
registry_path = "~/.vmcp/registry"
log_level = "INFO"
cache_enabled = true
cache_ttl = 300
max_connections = 1000
request_timeout = 30

[routing]
default_strategy = "hybrid"
load_balancer = "round_robin"

[transports.stdio]
enabled = true

[transports.http]
enabled = false
port = 3000
host = "127.0.0.1"

[transports.websocket]
enabled = false
port = 3001
host = "127.0.0.1"

Claude桌面集成

要将Claude Desktop连接到vMCP，请将以下内容添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "vmcp": {
      "command": "uv",
      "args": ["run", "vmcp", "start"],
      "cwd": "/path/to/vmcp"
    }
  }
}

✅ vMCP可以做什么

• ✅ 扩展管理：安装、启用、禁用MCP服务器，如浏览器扩展
• ✅ 统一网关：单个stdio接口可访问多个MCP服务器
• ✅ DXT风格建筑：专业的扩展包装和管理
• ✅ 丰富的CLI：漂亮的彩色命令行界面，带有标签完成
• ✅ 处置库系统：具有14个科学工具的集中扩展存储库
• ✅ 配置管理：灵活的基于TOML的配置
• ✅ 健康监测：监控扩展运行状况和性能
• ✅ FastMCP兼容性：适用于标准MCP和FastMCP服务器

❌ vMCP还不能做什么

• ❌ Persona系统：基于用户的访问控制（计划中）
• ❌ 动态加载：扩展的运行时加载/卸载（计划）
• ❌ HTTP/WebSocket传输：目前仅支持stdio传输
• ❌ 扩展开发工具：没有创建新扩展的脚手架
• ❌ 远程存储库：仅支持本地内置存储库
• ❌ 扩展依赖关系：扩展之间没有依赖解析
• ❌ 热重新加载：扩展需要重新启动网关才能重新加载

🛠️ 发展

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/vmcp

# Run specific test categories
uv run pytest -m unit
uv run pytest -m integration

代码质量

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy src/vmcp

GitHub操作

该项目包括全面的CI/CD：

• ✅ 多Python版本测试（3.10、3.11、3.12）
• ✅ 代码格式化和linting
• ✅ 类型检查
• ✅ 安全审计
• ✅ 包装建筑

🔧 技术细节

扩展包格式

vMCP使用 .vext （vMCP扩展）文件，类似于DXT的 .dxt 格式：

extension.vext
├── manifest.json          # DXT-style manifest
├── src/
│   ├── server.py          # MCP server entry point
│   └── capabilities/      # Tool implementations
├── tests/                 # Extension tests
└── README.md             # Extension documentation

清单结构

{
  "$schema": "https://vmcp.dev/schemas/manifest.json",
  "vmcp_version": "0.1.0",
  "name": "pandas-mcp",
  "display_name": "Pandas MCP Server",
  "version": "0.1.0",
  "description": "Data analysis with pandas",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "tools": [
    {
      "name": "data_profiling",
      "description": "Profile datasets and generate statistics"
    }
  ],
  "server": {
    "type": "python",
    "mcp": {
      "command": "uv",
      "args": ["run", "--directory", "{EXTENSION_DIR}", "python", "src/server.py"]
    }
  }
}

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试(uv run pytest)
5. 提交您的更改(git commit -m 'Add amazing feature')
6. 推到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• Anthropic 用于模型上下文协议规范
• DXT项目 可拓建筑的启示
• iowarp mcps 用于科学计算MCP服务器
• 紫外线 用于快速Python包管理
• 富有的 用于美观的终端输出

📞 支持

• 🐛 问题：
• 📖 文档： 维基工程
• 💬 讨论：

______________________________________________________________________

由以下材料制成❤️ 对于MCP社区