README.md

---
title: Universal MCP Hub
emoji: 👀
colorFrom: indigo
colorTo: red
sdk: docker
pinned: false
license: apache-2.0
short_description: 'Universal MCP Server(Sandboxed) built on PyFundaments '
---

# Universal MCP Hub (Sandboxed)
The only real (MCP) HUB you need!

> running on simpleCity and **paranoidMode** — built on [PyFundaments](PyFundaments.md).

... because too many (Hype) MCP servers exist with no sandboxing, hardcoded keys, and zero security thought. 


#### This one is different.

- **No key → no tool → no crash**
- `main.py` = Guardian (controls everything, nothing bypasses it)
- `app/app.py` receives only injected, validated services — never reads `os.environ` directly
- Every tool is registered dynamically — only if the API key exists

> *"I use AI as a tool, not as a replacement for thinking."* — Volkan Kücükbudak

---

## Quick Start

1. **Fork/Clone** this Repo (Space)
2. Add your API keys as **Space Secrets** (Settings → Variables and secrets)
3. Space starts automatically — only tools with valid keys are registered

That's it. No config files to edit, no code to touch.

[Demo for `cloning space`](https://huggingface.co/spaces/codey-lab/Universal-MCP-Hub-DEMO) on HF

---

## Available Tools

Tools are registered automatically based on which keys you configure. No key = tool doesn't exist. No crashes, no errors, no exposed secrets.

| Secret | Tool | Description |
| :--- | :--- | :--- |
| `ANTHROPIC_API_KEY` | `llm_complete` | Claude Haiku / Sonnet / Opus |
| `GEMINI_API_KEY` | `llm_complete` | Gemini Flash / Pro |
| `OPENROUTER_API_KEY` | `llm_complete` | 100+ models via OpenRouter |
| `HF_TOKEN` | `llm_complete` | HuggingFace Inference API |
| `BRAVE_API_KEY` | `web_search` | Web Search (independent index) |
| `TAVILY_API_KEY` | `web_search` | AI-optimized Search |
| `DATABASE_URL` | `db_query` | Read-only DB access (SELECT only) |
| *(always active)* | `list_active_tools` | Lists all currently active tools |
| *(always active)* | `health_check` | System health + uptime |

All LLM providers share a single `llm_complete` tool with automatic **fallback chain**: `anthropic → gemini → openrouter → huggingface`

---

## MCP Client Configuration (SSE)

Connect Claude Desktop or any MCP-compatible client:

```json
{
  "mcpServers": {
    "universal-mcp-hub": {
      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/sse"
    }
  }
}
```

For private Spaces, add your HF token:

```json
{
  "mcpServers": {
    "universal-mcp-hub": {
      "url": "https://YOUR_USERNAME-universal-mcp-hub.hf.space/sse",
      "headers": {
        "Authorization": "Bearer hf_..."
      }
    }
  }
}
```

---

## Desktop Client
#### Perfect for non-public spaces


- A standalone PySide6 desktop client is included: `hub.py`, with help of ClaudeAi, was to lazy 😄
- Features: Chat tab, Tools inspector, Settings (provider/model override, font size), Logs — all saved locally in `~/.mcp_desktop.json`. Token never leaves your machine except to your own Hub.
- more about the [Desktop Client](DESKTOP_CLIENT/README.md)

---

## Architecture
```
UMH
├── main.py # run main!
├── README.md
├── ESOL
├── LICENSE
├── PyFundaments.md
├── PyFundaments – Function Overview.md
├── SECURITY.md
├── requirements.txt
├── .gitignore
├── example.Dockerfile
├── example-mcp___.env
├── DESKTOP_CLIENT
│   └── hub.py        ← light MCP Desktop client
├── app/
│   ├── __init__.py
│   ├── app.py        ←  sandboxed Orchestrator
│   ├── mcp.py        ← MCP SSE server (FastMCP + Quart)
│   ├── tools.py      ← Tool registry (from .pyfun)
│   ├── provider.py   ← LLM + Search execution + fallback
│   ├── models.py     ← Model limits + costs
│   ├── db_sync.py    ← Internal SQLite state (IPC)
│   ├── config.py     ← .pyfun parser (single source of truth)
│   └── .pyfun        ←  single source of truth
├── fundaments/ # do not touch!
│   ├── __init__.py
│   ├── access_control.py
│   ├── config_handler.py
│   ├── encryption.py
│   ├── postgresql.py
│   ├── security.py
│   └── user_handler.py
└── docs/
    ├── access_control.py.md
    ├── encryption.py.md
    ├── postgresql.py.md
    ├── security.py.md
    └── user_handler.py.md



```

**The Guardian pattern:** `app/*` never touches `os.environ`, `.env`, or `fundaments/` directly. Everything is injected by `main.py` as a validated `fundaments` dict. The sandbox is structural — not optional.

---

## Configuration (.pyfun)

All app behavior is configured via `app/.pyfun` — a structured, human-readable config format:

```ini
[LLM_PROVIDER.anthropic]
active           = "true"
env_key          = "ANTHROPIC_API_KEY"
default_model    = "claude-haiku-4-5-20251001"
fallback_to      = "gemini"
[LLM_PROVIDER.anthropic_END]

[TOOL.llm_complete]
active           = "true"
provider_type    = "llm"
default_provider = "anthropic"
timeout_sec      = "60"
[TOOL.llm_complete_END]
```

Add a new tool/Provider/API_URL or something else just = edit `.pyfun` only. No code changes required.

---

## Security Design

- All API keys via e.g. HF Space Secrets — never hardcoded, never in `.pyfun`
- `list_active_tools` returns key **names** only, never values
- DB tools are `SELECT`-only, enforced at application level
- Direct execution of `app/*` is blocked by design
- `app/*` has zero access to `fundaments/` internals
- Built on [PyFundaments](PyFundaments.md) — security-first Python architecture

> PyFundaments is not perfect. But it's more secure than most of what runs in production today!

---

## Foundation

- [PyFundaments](PyFundaments.md) — Security-first Python boilerplate
- [PyFundaments Function Overview](Fundaments-–-Function---Overview.md)
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
- [SECURITY.md](SECURITY.md)

---

## History

[ShellMaster](https://github.com/VolkanSah/ChatGPT-ShellMaster) (2023, archived, MIT) was the precursor — a browser-accessible shell for ChatGPT with session memory via `/tmp/shellmaster_brain.log`, built before MCP was a word. Universal MCP Hub is its natural evolution.

---

## License

Dual-licensed:

- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
- [Ethical Security Operations License v1.1 (ESOL)](ESOL) — mandatory, non-severable

By using this software you agree to all ethical constraints defined in ESOL v1.1. Misuse may result in automatic license termination and legal liability.

---

*Architecture, security decisions, and PyFundaments by Volkan Kücükbudak. Built with Claude (Anthropic) as a typing assistant for docs & some bugs*

> crafted with passion by {Volkan Kücükbudak](https://github.com/volkansah/) - just want to feel how it works, mean i do not need it, have cli 😄