VMCP

CI codecov Python 3.10+ License: MIT Code style: ruff uv

A unified gateway for Model Context Protocol (MCP) servers, inspired by the DXT (Desktop Extensions) specification

vMCP provides a Virtual File System-like abstraction layer that aggregates multiple MCP servers through a single interface, enabling seamless access to diverse tools and capabilities from scientific computing, data analysis, and more.

🔗 What is vMCP?

vMCP (Virtual Model Context Protocol) is a gateway and proxy system that:

• Unifies Multiple MCP Servers: Access 14+ scientific computing tools through a single interface
• DXT-Inspired Architecture: Uses extension packaging similar to VS Code or Chrome extensions
• Extension Management: Install, enable, disable, and manage MCP servers like browser extensions
• Persona Support: Control which tools are available to different users/contexts
• stdio Transport: Compatible with Claude Desktop and other MCP clients

Think of vMCP as a "package manager for MCP servers" with a unified gateway interface.

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv package manager

Installation

# 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

Basic Usage

# 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

📦 Available Extensions

vMCP comes with 14 pre-packaged scientific computing extensions:

Extension	Category	Description
adios-mcp	Scientific Computing	ADIOS2 dataset access for simulation data
arxiv-mcp	Research	Academic paper search and download
chronolog-mcp	Data Management	Time-series data logging and retrieval
compression-mcp	Data Processing	High-performance data compression
darshan-mcp	Performance	I/O profiling for HPC applications
hdf5-mcp	Data Management	HDF5 file operations and analysis
jarvis-mcp	Materials Science	Materials database access and analysis
node-hardware-mcp	System Monitoring	Hardware monitoring and system info
pandas-mcp	Data Analysis	Data manipulation with pandas
parallel-sort-mcp	Data Processing	High-performance parallel sorting
plot-mcp	Visualization	Data visualization and plotting
slurm-mcp	Job Scheduling	SLURM cluster job management
lmod-mcp	Environment	Environment module management
parquet-mcp	Data Management	Columnar data processing

🏗️ System Architecture

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]

Key Components

• Gateway Server: stdio transport compatible with MCP clients
• Extension Manager: DXT-inspired extension lifecycle management
• Repository System: Manages extension packages (.vext files)
• Registry: Tracks installed and enabled extensions
• Routing Engine: Routes requests to appropriate MCP servers
• Persona System: Access control and tool restrictions (planned)

📖 Tutorial & Commands

Extension Management

List Extensions

# 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 Extensions

# 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/Disable Extensions

# 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

Extension Information

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

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

Update & Uninstall

# 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

Gateway Operations

Start/Stop Gateway

# 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

System Information

# 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

Configuration Management

# 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

Repository Management

# Search for extensions
uv run vmcp repo search pandas

# Repository statistics
uv run vmcp repo stats

# Discover available extensions
uv run vmcp repo discover

Shell Completion

# 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

⚙️ Configuration

Basic Configuration (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 Desktop Integration

To connect Claude Desktop to vMCP, add this to your Claude Desktop MCP configuration:

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

✅ What vMCP Can Do

• ✅ Extension Management: Install, enable, disable MCP servers like browser extensions
• ✅ Unified Gateway: Single stdio interface to access multiple MCP servers
• ✅ DXT-Inspired Architecture: Professional extension packaging and management
• ✅ Rich CLI: Beautiful, colored command-line interface with tab completion
• ✅ Repository System: Centralized extension repository with 14 scientific tools
• ✅ Configuration Management: Flexible TOML-based configuration
• ✅ Health Monitoring: Monitor extension health and performance
• ✅ FastMCP Compatibility: Works with both standard MCP and FastMCP servers

❌ What vMCP Cannot Do Yet

• ❌ Persona System: User-based access control (planned)
• ❌ Dynamic Loading: Runtime loading/unloading of extensions (planned)
• ❌ HTTP/WebSocket Transports: Only stdio transport currently supported
• ❌ Extension Development Tools: No scaffolding for creating new extensions
• ❌ Remote Repositories: Only local built-in repository supported
• ❌ Extension Dependencies: No dependency resolution between extensions
• ❌ Hot Reload: Extensions require gateway restart to reload

🛠️ Development

Running Tests

# 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

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy src/vmcp

GitHub Actions

The project includes comprehensive CI/CD:

• ✅ Multi-Python version testing (3.10, 3.11, 3.12)
• ✅ Code formatting and linting
• ✅ Type checking
• ✅ Security auditing
• ✅ Package building

🔧 Technical Details

Extension Package Format

vMCP uses .vext (vMCP Extension) files, similar to DXT's .dxt format:

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

Manifest Structure

{
  "$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": "[email protected]"
  },
  "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"]
    }
  }
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (uv run pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for the Model Context Protocol specification
• DXT Project for extension architecture inspiration
• iowarp-mcps for the scientific computing MCP servers
• uv for fast Python package management
• Rich for beautiful terminal output

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: Project Wiki
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the MCP community