Metadata-Version: 2.4
Name: 1xn-vmcp
Version: 0.1.6
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 <contact@1xn.ai>
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

An open-source tool for aggregating and managing multiple MCP servers with a unified interface.


vMCP (Virtual Model Context Protocol) is an open-source platform that allows you to connect to different mcp servers, modify them and add new tools, prompts . vMCP allows user to create customised mcp servers that can be used as drop in replactement in the agent building platforms. 

### Highlight Features

- ✅ **Flexible Proxy Server Creation**: Selectively combine different MCP servers into a unified proxy server.
- 🛠️ **Customizable Tools**: Override tool names/descriptions and prefill tool arguments.
- ✨ **Extensible Tooling**: Create new tools using Python snippets or REST APIs or plain text. 
- 🗣️ **Programmable Prompts**: Define prompts that can invoke other tools, enabling user-controlled tool chaining.
- 🔐 **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
- 📝 **Standard Logging**: Clean logging with DEBUG, INFO, WARNING, ERROR levels

<div align="center">
  <img src=".assets/img/vmcp-arch.png" alt="vMCP Architecture" width="780"/>
</div>

## 🚀 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:

#### Option 1: Using uvx (Recommended)
```bash
uvx --with 1xn-vmcp vmcp run
```
Or using uv

#### Option 2: Using pip
```bash
pip install 1xn-vmcp
vmcp run
```

#### Option 3: Using Docker
```bash
docker pull onexn/vmcp:latest
docker run -it onexn/vmcp:latest vmcp run
```
```

##docker deployement :


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

## 🛠️ Development

### Project Structure

```
vmcp/
├── src/vmcp/              # Main package
│   ├── backend/           # FastAPI backend
│   │   ├── mcps/          # MCP server management
│   │   ├── vmcps/         # Virtual MCP management
│   │   ├── storage/       # Database models
│   │   ├── proxy_server/  # Main app
│   │   └── utilities/     # Logging & tracing
│   └── cli/               # CLI commands
├── frontend/              # React frontend (Vite)
```

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/codesque16/1xn-vmcp
make build-frontend
make run
```

## 📊 Usage Examples

### Creating a vMCP

This guide walks you through the process of creating and managing virtual MCP servers with vMCP. Follow these steps to get started with aggregating multiple MCP servers into a unified interface.

#### Step 1: Access the vMCP Home Page

After starting vMCP with `vmcp run`, navigate to `http://localhost:8000` in your browser. The vMCP home page provides a centralized dashboard where you can manage your virtual MCP configurations

<div align="center">
  <img src=".assets/img/1_home_page.png" alt="vMCP Home Page Dashboard" width="650"/>
</div>

#### Step 2: Create a New vMCP

Click the **"+ Create Your First vMCP"** button to start building your virtual MCP. In the creation dialog, provide a name and description for your vMCP. A vMCP allows you to combine tools, resources, and prompts from multiple MCP servers into a single unified endpoint. You can add servers and configure tools later, so start with a descriptive name like "Coding_assistant" for a development-focused vMCP.

<div align="center">
  <img src=".assets/img/2_create_vmcp.png" alt="Create New vMCP Dialog" width="650"/>
</div>

#### Step 3: Extend Your vMCP with MCP Servers

After creating your vMCP, you'll see the "Add MCP Connector" button which displays a grid of well known remote mcp servers. You can browse and add the servers to Vmcp
<div align="center">
  <img src=".assets/img/3_extend_vmcp.png" alt="Extend vMCP with MCP Servers" width="650"/>
</div>

#### Step 4: Add a Custom Server

If you need to connect to a custom MCP server that's not in the community library, click **"Add Custom Server"** or use the custom server option. In the dialog, provide the server name, select the transport type (HTTP, SSE), enter the server URL, and optionally add environment variables and headers. This allows you to connect to any MCP-compatible server, including your own custom implementations.

<div align="center">
  <img src=".assets/img/4_add_custom_server.png" alt="Add Custom MCP Server Dialog" width="650"/>
</div>

#### Step 5: Filter and Edit Existing Tools

Once MCP servers are added to your vMCP, navigate to the **"Tools"** tab in the vMCP editor. Here you can view all available tools from your connected MCP servers. Use the search and filter options to find specific tools, enable or disable them, and override tool names and descriptions. You can also test individual tools or select/deselect all tools from a specific MCP server at once.

<div align="center">
  <img src=".assets/img/5_filter_edit_existing_tools.png" alt="Filter and Edit Tools in vMCP" width="650"/>
</div>

#### Step 6: Add Custom Tools and Prompts

In addition to tools from MCP servers, you can create custom tools and prompts directly in your vMCP. Navigate to the **"Prompts"** tab to create programmable prompts that can invoke other tools, enabling user-controlled tool chaining. You can define prompt parameters, descriptions, and use the `@` syntax to mention params, config, tools, and resources. Similarly, you can create custom tools using Python snippets or REST APIs.

<div align="center">
  <img src=".assets/img/6_add_custom_tools_prompts.png" alt="Add Custom Tools and Prompts" width="650"/>
</div>

#### Step 7: Use Your vMCP

Once your vMCP is configured and saved, you can use it with any MCP-compatible client. Copy the vMCP URL from the editor (e.g., `http://localhost:8000/private/Coding_asstistant/vmcp`) and connect to it using tools like MCP Inspector or directly from AI applications like Claude, Cursor, or Copilot. The vMCP will aggregate all your selected tools, resources, and prompts into a single unified endpoint.

<div align="center">
  <img src=".assets/img/7_use_vmcp.png" alt="Using vMCP with MCP Inspector" width="650"/>
</div>

## 🤝 Contributing

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

### Running Tests

```bash
# start test mcp server and rest api server.
make test-servers

# run test with pytest
make run-tests
```

## 📄 License

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

## 🙏 Acknowledgments


## 📞 Support

- 🐛 [Report Issues](https://github.com/codesque16/1xn-vmcp/issues)
- 📧 Email: contact@1xn.ai

---

Made with ❤️ by the 1xn Team