Metadata-Version: 2.4
Name: 1xn-vmcp
Version: 0.1.5
Summary: v(irtual)MCP - Extend, Compose, Customize MCP servers
Project-URL: Homepage, https://1xn.ai
Project-URL: Documentation, https://1xn.ai/docs
Project-URL: Repository, https://github.com/codesque16/1xn-vmcp
Project-URL: Issues, https://github.com/codesque16/1xn-vmcp/issues
Author-email: vMCP Team <team@vmcp.dev>
License: MIT
Keywords: agents,ai,mcp,model-context-protocol,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.10
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: alembic<2.0.0,>=1.12.0
Requires-Dist: asyncpg<1.0.0,>=0.29.0
Requires-Dist: fastapi<1.0.0,>=0.104.0
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: jinja2<4.0.0,>=3.1.2
Requires-Dist: mcp>=1.20.0
Requires-Dist: opentelemetry-api<2.0.0,>=1.21.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.21.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.21.0
Requires-Dist: opentelemetry-instrumentation-asyncio>=0.42b0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.42b0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.42b0
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.42b0
Requires-Dist: opentelemetry-instrumentation>=0.42b0
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.21.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.9
Requires-Dist: pydantic-settings<3.0.0,>=2.1.0
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: python-jose[cryptography]<4.0.0,>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pytz>=2023.3
Requires-Dist: rich<14.0.0,>=13.7.0
Requires-Dist: sqlalchemy<3.0.0,>=2.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: typer<1.0.0,>=0.9.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.24.0
Requires-Dist: websockets<13.0,>=12.0
Provides-Extra: dev
Requires-Dist: black>=23.12.0; extra == 'dev'
Requires-Dist: mypy>=1.7.1; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: ruff>=0.1.7; extra == 'dev'
Description-Content-Type: text/markdown

# vMCP - Virtual Model Context Protocol
A containerization platform for MCPs that lets you compose, customize, and deploy AI agent capabilities at scale.

#### What is vMCP?
vMCP (Virtual Model Context Protocol) transforms how you work with MCP servers by introducing containerization for AI capabilities. Instead of managing scattered MCP servers individually, vMCP lets you:

🎯 Curate with Precision: Connect to multiple MCP servers but cherry-pick only the tools, resources, and prompts you actually need
🔨 Extend with Custom Logic: Create your own tools using Python functions or REST APIs, and add custom resources and prompts
📦 Package as Containers: Bundle your curated capabilities into self-contained "virtual MCPs" (vMCPs) that can be versioned, shared, and deployed anywhere
🔌 Connect Once, Use Everywhere: Point any AI client (Claude, OpenAI, custom agents) to a single vMCP endpoint that aggregates everything

Think of vMCP as Docker for AI capabilities - where each container is a carefully crafted collection of tools, data sources, and prompts tailored for specific use cases.

## Why vMCP?
The Problem
Modern AI applications need access to multiple MCP servers (filesystem, GitHub, Slack, databases, etc.). Managing these connections individually leads to:

🔁 Redundant configurations across projects
🎚️ No granular control over which capabilities to expose
🚫 Difficulty standardizing agent behavior across teams
📊 No visibility into usage patterns

## The Solution
vMCP provides a unified aggregation layer where you can:
Multiple MCP Servers → Curate → Customize → Container → Deploy
(Filesystem, GitHub, Slack)  (Select tools)  (Add custom)  (vMCP)  (AI Clients)
Example: Create a "DevOps Assistant" vMCP that combines:

GitHub's create_issue and list_prs tools (but not delete_repo)
Filesystem's read_file (but not write_file for safety)
Your custom deploy_to_staging tool built with Python
Slack's notification capabilities
Custom prompts for incident response workflows

Deploy this single vMCP endpoint, and any AI agent can instantly access this curated, secure capability set.


## Key Features

✅ Selective Tool Exposure: Connect to any MCP server and choose exactly which tools, resources, and prompts to include
🔨 Custom Capabilities: Build your own tools using Python functions or REST API integrations
📦 Virtual Containers: Package everything into reusable, shareable vMCP containers
🔌 Universal Compatibility: Works with stdio, HTTP, and SSE MCP transports
🔐 Authentication Support: Handle OAuth 2.0, Bearer tokens, and Basic auth for MCP servers
📊 Usage Analytics: Track tool calls, resource reads, and prompt usage patterns
🐳 Deploy Anywhere: Run locally, in Docker, or on any cloud platform
🔍 OpenTelemetry Tracing: Built-in observability for debugging and monitoring

## 🚀 Quickstart

### Prerequisites

vMCP requires [Python 3.10 to 3.13](https://www.python.org/downloads/) and [uv](https://docs.astral.sh/uv/).

### Installation

To install vMCP, run:

```bash
uv pip install 1xn-vmcp
```

Or use uvx to run directly:

```bash
uvx 1xn-vmcp run
```

### Running vMCP

To run vMCP locally:

```bash
vmcp run
```

This will start the vMCP server on `http://localhost:8000`.

## 📖 What is vMCP?

vMCP (Virtual Model Context Protocol) is an open-source platform that allows you to:

- **Aggregate Multiple MCP Servers**: Connect to multiple MCP servers (stdio, HTTP, SSE) and manage them from a single interface
- **Create Virtual MCPs**: Combine tools, resources, and prompts from multiple servers into unified virtual endpoints. create custom tools using python function or using rest apis. 
- **Manage Connections**: Handle MCP server authentication (OAuth, Bearer tokens, Basic auth)
- **Track Usage**: Monitor tool calls, resource reads, and prompt usage with built-in analytics
- **Deploy Anywhere**: Run locally, in Docker, or deploy to cloud platforms

### Key Features

- ✅ **No Authentication Required**: Single local user mode for simplicity
- 🔌 **MCP Protocol Support**: Full support for stdio, HTTP, and SSE transports
- 🔐 **MCP Server Authentication**: OAuth 2.0 support for MCP servers that require it
- 📊 **Usage Statistics**: Track and analyze vMCP usage patterns
- 🐳 **Docker Ready**: Official Docker images for easy deployment
- 🔍 **OpenTelemetry Tracing**: Built-in distributed tracing support
- 📝 **Standard Logging**: Clean logging with DEBUG, INFO, WARNING, ERROR levels

## 🏗️ Architecture

### Components

1. **MCP Servers**: Individual MCP servers you connect to (e.g., filesystem, GitHub, Slack)
2. **VMCPs**: Virtual MCPs that aggregate multiple MCP servers
3. **Storage**: PostgreSQL database for configuration and stats
4. **Web UI**: React-based interface for managing VMCPs and connections

### How it Works

```
┌─────────────┐
│  AI Client  │ (Claude, OpenAI, etc.)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    vMCP     │ (Virtual MCP Endpoint)
└──────┬──────┘
       │
       ├─────► MCP Server 1 (Filesystem)
       ├─────► MCP Server 2 (GitHub)
       └─────► MCP Server 3 (Slack)
```

## 🛠️ Development

### Project Structure

```
1xn_oss/
├── backend/               # Python backend
│   ├── src/
│   │   ├── main.py        # Application entry point
│   │   └── vmcp/          # Main package
│   │       ├── cli/       # CLI commands
│   │       ├── config.py  # Configuration
│   │       ├── data/      # Data files
│   │       ├── mcps/      # MCP server management
│   │       ├── proxy_server/ # FastAPI backend
│   │       ├── scripts/   # Utility scripts
│   │       ├── storage/   # Database models
│   │       ├── utilities/ # Logging & tracing
│   │       └── vmcps/     # Virtual MCP management
│   ├── public/            # Static files (built frontend/docs)
│   └── pyproject.toml     # Python dependencies
├── frontend/              # React frontend (Vite)
├── docs/                  # Documentation (Docusaurus)
├── docker/                # Docker configuration
└── instructions/          # Project documentation
```

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/vmcp/vmcp.git
cd vmcp

# Install dependencies
uv sync


# Start development server
cd src
python3 main.py --reload
```

### Environment Variables

Create a `.env` file in the project root:

```env
# Database
DATABASE_URL=postgresql://vmcp:vmcp@localhost:5432/vmcp

# Server
HOST=0.0.0.0
PORT=8000
BASE_URL=http://localhost:8000

# Logging
LOG_LEVEL=INFO

# Tracing (optional)
ENABLE_TRACING=false
OTLP_ENDPOINT=http://localhost:4317
```

## 📊 Usage Examples

### Creating a vMCP

```python
import httpx

# Create a new vMCP
response = httpx.post("http://localhost:8000/vmcps/create", json={
    "name": "my-vmcp",
    "description": "My virtual MCP",
    "mcp_server_ids": [
        "filesystem-server",
        "github-server"
    ]
})

vmcp_id = response.json()["vmcp_id"]
print(f"Created vMCP: {vmcp_id}")
```

### Calling Tools via vMCP

```python
# Call a tool through the vMCP
response = httpx.post(
    f"http://localhost:8000/vmcp/{vmcp_id}/tools/call",
    json={
        "tool_name": "read_file",
        "arguments": {"path": "/tmp/test.txt"}
    }
)

result = response.json()
print(result)
```

## 🐳 Docker Deployment

### Quick Start with Docker

The easiest way to run vMCP is using our pre-built Docker image:

```bash
# Run vMCP directly from Docker Hub
docker run -p 8000:8000 onexn/vmcp:latest
```

Open your browser to `http://localhost:8000` - that's it!

### Using Docker Compose (Recommended)

For a full setup with PostgreSQL database:

```bash
# Clone the repository
git clone https://github.com/codesque16/1xn_oss.git
cd 1xn_oss

# Start with Docker Compose
make docker-run
# or
docker-compose -f docker/docker-compose.yml up -d
```

### Building Your Own Image

```bash
# Build from source
git clone https://github.com/codesque16/1xn_oss.git
cd 1xn_oss
make docker-build

# Run your custom build
docker run -p 8000:8000 your-image-name:latest
```

### Available Tags

- `onexn/vmcp:latest` - Latest stable release
- `onexn/vmcp:v0.1.3` - Specific version
- View all tags at: https://hub.docker.com/r/onexn/vmcp

## 📚 Documentation

Full documentation is available at [docs.vmcp.dev](https://docs.vmcp.dev) (coming soon).

### Key Concepts

- **MCP Servers**: Individual servers implementing the Model Context Protocol
- **vMCPs**: Virtual endpoints that aggregate multiple MCP servers
- **Tools**: Functions exposed by MCP servers
- **Resources**: Data sources accessible through MCP servers
- **Prompts**: Templated prompts provided by MCP servers

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=vmcp --cov-report=html

# Run specific test file
pytest tests/test_mcps/test_client.py
```

## 📄 License

vMCP is open-source software licensed under the [MIT License](LICENSE).

## 🙏 Acknowledgments

## 📞 Support

- 🐛 [Report Issues](https://github.com/codesque16/1xn_oss/issues)
- 💬 [Discussions](https://github.com/codesque16/1xn_oss/discussions)
- 📧 Email: support@1xn.ai

---

Made with ❤️ by the 1xn Team
