README.md

metadata

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.

... 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 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:

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

For private Spaces, add your HF token:

{
  "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

---

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:

[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 — security-first Python architecture

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

---

Foundation

• PyFundaments — Security-first Python boilerplate
• PyFundaments Function Overview
• PROJECT_STRUCTURE.md
• SECURITY.md

---

History

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
• Ethical Security Operations License v1.1 (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 😄