Upload 15 files

app/.pyfun

@@ -0,0 +1,334 @@
+# =============================================================================
+# .pyfun — PyFundaments App Configuration
+# Single source of truth for app/* modules (provider, models, tools, hub)
+# Part of: Universal MCP Hub on PyFundaments
+# =============================================================================
+# RULES:
+#   - All values in double quotes "value"
+#   - NO secrets here! Keys stay in .env → only ENV-VAR NAMES referenced here
+#   - Comment-out unused sections with #  → keep structure, parsers need it!
+#   - DO NOT DELETE headers or [X_END]   → parsers rely on these markers
+#   - Empty/unused values: ""            → never leave bare =
+# =============================================================================
+# TIERS:
+#   LAZY:       fill [HUB] + one [LLM_PROVIDER.*] only        → works
+#   NORMAL:     + [SEARCH_PROVIDER.*] + [MODELS.*]             → works better
+#   PRODUCTIVE: + [TOOLS] + [FALLBACK] + [HUB_LIMITS]          → full power
+# =============================================================================
+# DO NOT DELETE — file identifier used by all parsers
+[PYFUN_FILE = .pyfun]
+
+# =============================================================================
+# HUB — Core identity & transport config
+# =============================================================================
+[HUB]
+HUB_NAME            = "Universal MCP Hub"
+HUB_VERSION         = "1.0.0"
+HUB_DESCRIPTION     = "Universal MCP Hub built on PyFundaments"
+
+# Transport: stdio (local/Claude Desktop) | sse (HuggingFace/Remote)
+# Override via ENV: MCP_TRANSPORT
+HUB_TRANSPORT       = "sse"
+HUB_HOST            = "0.0.0.0"
+HUB_PORT            = "7860"
+
+# App mode: mcp | app
+# Override via ENV: APP_MODE
+HUB_MODE            = "mcp"
+
+# HuggingFace Space URL (used as HTTP-Referer for some APIs)
+HUB_SPACE_URL       = ""
+[HUB_END]
+
+# =============================================================================
+# HUB_LIMITS — Request & retry behavior
+# =============================================================================
+[HUB_LIMITS]
+MAX_PARALLEL_REQUESTS   = "5"
+RETRY_COUNT             = "3"
+RETRY_DELAY_SEC         = "2"
+REQUEST_TIMEOUT_SEC     = "60"
+SEARCH_TIMEOUT_SEC      = "30"
+[HUB_LIMITS_END]
+
+# =============================================================================
+# PROVIDERS — All external API providers
+# Secrets stay in .env! Only ENV-VAR NAMES are referenced here.
+# =============================================================================
+[PROVIDERS]
+
+# ── LLM Providers ─────────────────────────────────────────────────────────────
+[LLM_PROVIDERS]
+
+  [LLM_PROVIDER.anthropic]
+  active              = "true"
+  base_url            = "https://api.anthropic.com/v1"
+  env_key             = "ANTHROPIC_API_KEY"       # → .env: ANTHROPIC_API_KEY=sk-ant-...
+  api_version_header  = "2023-06-01"              # anthropic-version header
+  default_model       = "claude-haiku-4-5-20251001"
+  models              = "claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001"
+  fallback_to         = "openrouter"              # if this provider fails → try next
+  [LLM_PROVIDER.anthropic_END]
+
+  [LLM_PROVIDER.gemini]
+  active              = "true"
+  base_url            = "https://generativelanguage.googleapis.com/v1beta"
+  env_key             = "GEMINI_API_KEY"          # → .env: GEMINI_API_KEY=...
+  default_model       = "gemini-2.0-flash"
+  models              = "gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash"
+  fallback_to         = "openrouter"
+  [LLM_PROVIDER.gemini_END]
+
+  [LLM_PROVIDER.openrouter]
+  active              = "true"
+  base_url            = "https://openrouter.ai/api/v1"
+  env_key             = "OPENROUTER_API_KEY"      # → .env: OPENROUTER_API_KEY=sk-or-...
+  default_model       = "mistralai/mistral-7b-instruct"
+  models              = "openai/gpt-4o, meta-llama/llama-3-8b-instruct, mistralai/mistral-7b-instruct"
+  fallback_to         = ""                        # last in chain, no further fallback
+  [LLM_PROVIDER.openrouter_END]
+
+  [LLM_PROVIDER.huggingface]
+  active              = "true"
+  base_url            = "https://api-inference.huggingface.co/models"
+  env_key             = "HF_TOKEN"                # → .env: HF_TOKEN=hf_...
+  default_model       = "mistralai/Mistral-7B-Instruct-v0.3"
+  models              = "mistralai/Mistral-7B-Instruct-v0.3, meta-llama/Llama-3.3-70B-Instruct"
+  fallback_to         = ""
+  [LLM_PROVIDER.huggingface_END]
+
+  # ── Add more LLM providers below ──────────────────────────────────────────
+  # [LLM_PROVIDER.mistral]
+  # active            = "false"
+  # base_url          = "https://api.mistral.ai/v1"
+  # env_key           = "MISTRAL_API_KEY"
+  # default_model     = "mistral-large-latest"
+  # models            = "mistral-large-latest, mistral-small-latest"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.mistral_END]
+
+  # [LLM_PROVIDER.openai]
+  # active            = "false"
+  # base_url          = "https://api.openai.com/v1"
+  # env_key           = "OPENAI_API_KEY"
+  # default_model     = "gpt-4o"
+  # models            = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.openai_END]
+
+[LLM_PROVIDERS_END]
+
+# ── Search Providers ───────────────────────────────────────────────────────────
+[SEARCH_PROVIDERS]
+
+  [SEARCH_PROVIDER.brave]
+  active              = "true"
+  base_url            = "https://api.search.brave.com/res/v1/web/search"
+  env_key             = "BRAVE_API_KEY"           # → .env: BRAVE_API_KEY=BSA...
+  default_results     = "5"
+  max_results         = "20"
+  fallback_to         = "tavily"
+  [SEARCH_PROVIDER.brave_END]
+
+  [SEARCH_PROVIDER.tavily]
+  active              = "true"
+  base_url            = "https://api.tavily.com/search"
+  env_key             = "TAVILY_API_KEY"          # → .env: TAVILY_API_KEY=tvly-...
+  default_results     = "5"
+  max_results         = "10"
+  include_answer      = "true"                    # AI-synthesized answer
+  fallback_to         = ""
+  [SEARCH_PROVIDER.tavily_END]
+
+  # ── Add more search providers below ───────────────────────────────────────
+  # [SEARCH_PROVIDER.serper]
+  # active            = "false"
+  # base_url          = "https://google.serper.dev/search"
+  # env_key           = "SERPER_API_KEY"
+  # fallback_to       = ""
+  # [SEARCH_PROVIDER.serper_END]
+
+[SEARCH_PROVIDERS_END]
+
+# ── Web / Action Providers (Webhooks, Bots, Social) ───────────────────────────
+# [WEB_PROVIDERS]
+
+  # [WEB_PROVIDER.discord]
+  # active            = "false"
+  # base_url          = "https://discord.com/api/v10"
+  # env_key           = "BOT_TOKEN"
+  # [WEB_PROVIDER.discord_END]
+
+  # [WEB_PROVIDER.github]
+  # active            = "false"
+  # base_url          = "https://api.github.com"
+  # env_key           = "GITHUB_TOKEN"
+  # [WEB_PROVIDER.github_END]
+
+# [WEB_PROVIDERS_END]
+
+[PROVIDERS_END]
+
+# =============================================================================
+# MODELS — Token & rate limits per model
+# Parser builds: MODELS[provider][model_name] → limits dict
+# =============================================================================
+[MODELS]
+
+  [MODEL.claude-opus-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "32000"
+  requests_per_min    = "5"
+  requests_per_day    = "300"
+  cost_input_per_1k   = "0.015"                  # USD — update as pricing changes
+  cost_output_per_1k  = "0.075"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-opus-4-6_END]
+
+  [MODEL.claude-sonnet-4-6]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "16000"
+  requests_per_min    = "50"
+  requests_per_day    = "1000"
+  cost_input_per_1k   = "0.003"
+  cost_output_per_1k  = "0.015"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-sonnet-4-6_END]
+
+  [MODEL.claude-haiku-4-5-20251001]
+  provider            = "anthropic"
+  context_tokens      = "200000"
+  max_output_tokens   = "8000"
+  requests_per_min    = "50"
+  requests_per_day    = "2000"
+  cost_input_per_1k   = "0.00025"
+  cost_output_per_1k  = "0.00125"
+  capabilities        = "text, code, fast"
+  [MODEL.claude-haiku-4-5-20251001_END]
+
+  [MODEL.gemini-2.0-flash]
+  provider            = "gemini"
+  context_tokens      = "1000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "15"
+  requests_per_day    = "1500"
+  cost_input_per_1k   = "0.00010"
+  cost_output_per_1k  = "0.00040"
+  capabilities        = "text, code, vision, audio"
+  [MODEL.gemini-2.0-flash_END]
+
+  [MODEL.gemini-1.5-pro]
+  provider            = "gemini"
+  context_tokens      = "2000000"
+  max_output_tokens   = "8192"
+  requests_per_min    = "2"
+  requests_per_day    = "50"
+  cost_input_per_1k   = "0.00125"
+  cost_output_per_1k  = "0.00500"
+  capabilities        = "text, code, vision, audio, long-context"
+  [MODEL.gemini-1.5-pro_END]
+
+  [MODEL.mistral-7b-instruct]
+  provider            = "openrouter"
+  context_tokens      = "32000"
+  max_output_tokens   = "4096"
+  requests_per_min    = "60"
+  requests_per_day    = "10000"
+  cost_input_per_1k   = "0.00006"
+  cost_output_per_1k  = "0.00006"
+  capabilities        = "text, code, fast, cheap"
+  [MODEL.mistral-7b-instruct_END]
+
+[MODELS_END]
+
+# =============================================================================
+# TOOLS — Tool definitions + provider mapping
+# Tools are registered in mcp.py only if their provider ENV key exists!
+# =============================================================================
+[TOOLS]
+
+  [TOOL.llm_complete]
+  active              = "true"
+  description         = "Send prompt to any configured LLM provider"
+  provider_type       = "llm"
+  default_provider    = "anthropic"
+  timeout_sec         = "60"
+  [TOOL.llm_complete_END]
+
+  [TOOL.web_search]
+  active              = "true"
+  description         = "Search the web via configured search provider"
+  provider_type       = "search"
+  default_provider    = "brave"
+  timeout_sec         = "30"
+  [TOOL.web_search_END]
+
+  [TOOL.db_query]
+  active              = "true"
+  description         = "Execute SELECT queries on connected database (read-only)"
+  provider_type       = "db"
+  readonly            = "true"
+  timeout_sec         = "10"
+  [TOOL.db_query_END]
+
+  # ── Future tools ──────────────────────────────────────────────────────────
+  # [TOOL.image_gen]
+  # active            = "false"
+  # description       = "Generate images via configured provider"
+  # provider_type     = "image"
+  # default_provider  = ""
+  # timeout_sec       = "120"
+  # [TOOL.image_gen_END]
+
+  # [TOOL.code_exec]
+  # active            = "false"
+  # description       = "Execute sandboxed code snippets"
+  # provider_type     = "sandbox"
+  # timeout_sec       = "30"
+  # [TOOL.code_exec_END]
+
+[TOOLS_END]
+
+# =============================================================================
+# DB_SYNC — Internal SQLite config for app/* IPC
+# This is NOT the cloud DB — that lives in .env → DATABASE_URL
+# =============================================================================
+[DB_SYNC]
+SQLITE_PATH         = "app/.hub_state.db"       # internal state, never commit!
+SYNC_INTERVAL_SEC   = "30"                       # how often to flush to SQLite
+MAX_CACHE_ENTRIES   = "1000"
+[DB_SYNC_END]
+
+# =============================================================================
+# DEBUG — app/* debug behavior (fundaments debug stays in .env)
+# =============================================================================
+[DEBUG]
+DEBUG               = "ON"                       # ON | OFF
+DEBUG_LEVEL         = "FULL"                     # FULL | WARN | ERROR
+LOG_FILE            = "hub_debug.log"
+LOG_REQUESTS        = "true"                     # log every provider request
+LOG_RESPONSES       = "false"                    # careful: may log sensitive data!
+[DEBUG_END]
+
+# =============================================================================
+# PARSER_PROVIDER FREE ENDPOINTS — soon
+# =============================================================================
+[PARSER_PROVIDER]
+#[PARSER_PROVIDER.metaculus]
+#active    = "true"
+#base_url  = "https://www.metaculus.com/api2"
+#env_key   = ""          # public API, kein key!
+#category  = "research"
+#legal_de  = "true"      # ← Deutschland-Check direkt in config!
+#[PARSER_PROVIDER.metaculus_END]
+
+#[PARSER_PROVIDER.polymarket]
+#active    = "false"
+#base_url  = "https://gamma-api.polymarket.com"
+#env_key   = ""
+#legal_de  = "false"
+#[PARSER_PROVIDER.polymarket_END]
+[PARSER_PROVIDER_END]
+

app/README.md

@@ -0,0 +1,2 @@
+> Haha! Sandboxed MCP server! (No nelson image cause big "D")
+

app/__init__.py

@@ -0,0 +1 @@
+

app/app.py

@@ -0,0 +1,213 @@
+# =============================================================================
+# root/app/app.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file is the Orchestrator of the sandboxed app/* layer.
+#   It is ONLY started by main.py (the "Guardian").
+#   All fundament services are injected via the `fundaments` dictionary.
+#   Direct execution is blocked by design.
+#
+# SANDBOX RULES:
+#   - fundaments dict is ONLY unpacked inside start_application()
+#   - fundaments are NEVER stored globally or passed to other app/* modules
+#   - app/* modules read their own config from app/.pyfun
+#   - app/* internal state/IPC uses app/db_sync.py (SQLite) — NOT postgresql.py
+#   - Secrets stay in .env → Guardian reads them → never touched by app/*
+# =============================================================================
+from quart import Quart, request, jsonify  # async Flask — ASGI compatible
+import logging
+from hypercorn.asyncio import serve        # ASGI server — async native, replaces waitress
+from hypercorn.config import Config        # hypercorn config
+import threading                           # for future tools that need own threads
+import requests                            # sync HTTP for future tool workers
+import time
+from datetime import datetime
+import asyncio
+from typing import Dict, Any, Optional
+# =============================================================================
+# Import app/* modules — MINIMAL BUILD
+# Each module reads its own config from app/.pyfun independently.
+# NO fundaments passed into these modules!
+# =============================================================================
+from . import mcp                   # MCP transport layer (SSE via Quart route)
+from . import config as app_config  # app/.pyfun parser — used only in app/*
+from . import providers    # API provider registry — reads app/.pyfun
+from . import models       # Model config + token/rate limits — reads app/.pyfun
+from . import tools        # MCP tool definitions + provider mapping — reads app/.pyfun
+from . import db_sync      # Internal SQLite IPC — app/* state & communication
+#                          # db_sync ≠ postgresql.py! Cloud DB is Guardian-only.
+# Future modules (will uncomment when ready):
+# from . import discord_api  # Discord bot integration
+# from . import hf_hooks     # HuggingFace Space hooks
+# from . import git_hooks    # GitHub/GitLab webhook handler
+# from . import web_api      # Generic REST API handler
+# =============================================================================
+# Loggers — one per module for clean log filtering
+# =============================================================================
+logger        = logging.getLogger('application')
+logger_mcp    = logging.getLogger('mcp')
+logger_config = logging.getLogger('config')
+logger_tools     = logging.getLogger('tools')
+logger_providers = logging.getLogger('providers')
+logger_models    = logging.getLogger('models')
+logger_db_sync   = logging.getLogger('db_sync')
+# =============================================================================
+# Quart app instance
+# =============================================================================
+app = Quart(__name__)
+START_TIME = datetime.utcnow()
+# =============================================================================
+# Quart Routes
+# =============================================================================
+@app.route("/", methods=["GET"])
+async def health_check():
+    """
+    Health check endpoint.
+    Used by HuggingFace Spaces and monitoring systems to verify the app is running.
+    """
+    uptime = datetime.utcnow() - START_TIME
+    return jsonify({
+        "status": "running",
+        "service": "Universal MCP Hub",
+        "uptime_seconds": int(uptime.total_seconds()),
+    })
+
+
+@app.route("/api", methods=["POST"])
+async def api_endpoint():
+    """
+    Generic REST API endpoint for direct tool invocation.
+    Accepts JSON: { "tool": "tool_name", "params": { ... } }
+    Auth and validation handled by tools layer.
+    """
+    # TODO: implement tool dispatch via tools.invoke()
+    data = await request.get_json()
+    return jsonify({"status": "not_implemented", "received": data}), 501
+
+
+@app.route("/crypto", methods=["POST"])
+async def crypto_endpoint():
+    """
+    Encrypted API endpoint.
+    Encryption handled by app/* layer — no direct fundaments access here.
+    """
+    # TODO: implement via app/* encryption wrapper
+    data = await request.get_json()
+    return jsonify({"status": "not_implemented"}), 501
+
+
+@app.route("/mcp", methods=["GET", "POST"])
+async def mcp_endpoint():
+    """
+    MCP SSE Transport endpoint — routed through Quart/hypercorn.
+    All MCP traffic passes through here — enables interception, logging,
+    auth checks, rate limiting, payload transformation before reaching MCP.
+    """
+    return await mcp.handle_request(request)
+
+
+# Future routes (uncomment when ready):
+# @app.route("/discord", methods=["POST"])
+# async def discord_interactions():
+#     """Discord interactions endpoint — signature verification via discord_api module."""
+#     pass
+
+# @app.route("/webhook/hf", methods=["POST"])
+# async def hf_webhook():
+#     """HuggingFace Space event hooks."""
+#     pass
+
+# @app.route("/webhook/git", methods=["POST"])
+# async def git_webhook():
+#     """GitHub / GitLab webhook handler."""
+#     pass
+# =============================================================================
+# Main entry point — called exclusively by Guardian (main.py)
+# =============================================================================
+async def start_application(fundaments: Dict[str, Any]) -> None:
+    """
+    Main entry point for the sandboxed app layer.
+    Called exclusively by main.py after all fundament services are initialized.
+
+    Args:
+        fundaments: Dictionary of initialized services from Guardian (main.py).
+                    Services are unpacked here and NEVER stored globally or
+                    passed into other app/* modules.
+    """
+    logger.info("Application starting...")
+
+    # =========================================================================
+    # Unpack fundaments — ONLY here, NEVER elsewhere in app/*
+    # These are the 6 fundament services from fundaments/*
+    # =========================================================================
+    config_service          = fundaments["config"]          # fundaments/config_handler.py
+    db_service              = fundaments["db"]              # fundaments/postgresql.py — None if not configured
+    encryption_service      = fundaments["encryption"]      # fundaments/encryption.py — None if keys not set
+    access_control_service  = fundaments["access_control"]  # fundaments/access_control.py — None if no DB
+    user_handler_service    = fundaments["user_handler"]    # fundaments/user_handler.py — None if no DB
+    security_service        = fundaments["security"]        # fundaments/security.py — None if deps missing
+
+    # --- Log active fundament services ---
+    if encryption_service:
+        logger.info("Encryption service active.")
+
+    if user_handler_service and security_service:
+        logger.info("Auth services active (user_handler + security).")
+
+    if access_control_service and security_service:
+        logger.info("Access control active.")
+
+    if db_service and not user_handler_service:
+        logger.info("Database-only mode active (e.g. ML pipeline).")
+
+    if not db_service:
+        logger.info("Database-free mode active (e.g. Discord bot, API client).")
+
+    # =========================================================================
+    # Initialize app/* internal services — MINIMAL BUILD
+    # Uncomment each line when the module is ready!
+    # =========================================================================
+    # await db_sync.initialize()    # SQLite IPC store for app/* — unrelated to postgresql.py
+    # await providers.initialize()  # reads app/.pyfun [LLM_PROVIDERS] [SEARCH_PROVIDERS] # in mcp_init
+    # await models.initialize()     # reads app/.pyfun [MODELS] # in mcp_init
+    # await tools.initialize()      # reads app/.pyfun [TOOLS]
+
+    # --- Initialize MCP (registers tools, prepares SSE handler) ---
+    # db_sync only if cloud_DB used to! 
+    # await db_sync.initialize()
+    await mcp.initialize()
+
+    # --- Read PORT from app/.pyfun [HUB] ---
+    port = int(app_config.get_hub().get("HUB_PORT", "7860"))
+
+    # --- Configure hypercorn ---
+    config = Config()
+    config.bind = [f"0.0.0.0:{port}"]
+
+    logger.info(f"Starting hypercorn on port {port}...")
+    logger.info("All services running.")
+
+    # --- Run hypercorn — blocks until shutdown ---
+    await serve(app, config)
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == '__main__':
+    print("WARNING: Running app.py directly. Fundament modules might not be correctly initialized.")
+    print("Please run 'python main.py' instead for proper initialization.")
+
+    test_fundaments = {
+        "config":           None,
+        "db":               None,
+        "encryption":       None,
+        "access_control":   None,
+        "user_handler":     None,
+        "security":         None,
+    }
+
+    asyncio.run(start_application(test_fundaments))

app/config.py

@@ -0,0 +1,293 @@
+# =============================================================================
+# app/config.py
+# .pyfun parser for app/* modules
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# USAGE in any app/* module:
+#   from . import config
+#   cfg = config.get()
+#   providers = cfg["LLM_PROVIDERS"]
+# =============================================================================
+# USAGE
+# in providers.py
+# from . import config
+
+# active = config.get_active_llm_providers()
+# → { "anthropic": { "base_url": "...", "env_key": "ANTHROPIC_API_KEY", ... }, ... }
+# =============================================================================
+# in models.py  
+# from . import config
+
+# anthropic_models = config.get_models_for_provider("anthropic")
+# =============================================================================
+# in tools.py
+# from . import config
+
+# active_tools = config.get_active_tools()
+# =============================================================================
+import os
+import logging
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger('app.config')
+
+# Path to .pyfun — lives in app/ next to this file
+PYFUN_PATH = os.path.join(os.path.dirname(__file__), ".pyfun")
+
+# Internal cache — loaded once at first get()
+_cache: Optional[Dict[str, Any]] = None
+
+
+def _parse_value(value: str) -> str:
+    """Strip quotes and inline comments from a value."""
+    value = value.strip()
+    # Remove inline comment
+    if " #" in value:
+        value = value[:value.index(" #")].strip()
+    # Strip surrounding quotes
+    if value.startswith('"') and value.endswith('"'):
+        value = value[1:-1]
+    return value
+
+
+def _parse() -> Dict[str, Any]:
+    """
+    Parses the app/.pyfun file into a nested dictionary.
+
+    Structure:
+        [SECTION]
+            [SUBSECTION]
+                [BLOCK.name]
+                key = "value"
+                [BLOCK.name_END]
+            [SUBSECTION_END]
+        [SECTION_END]
+
+    Returns nested dict:
+        {
+            "HUB": { "HUB_NAME": "...", ... },
+            "LLM_PROVIDERS": {
+                "anthropic": { "active": "true", "base_url": "...", ... },
+                "gemini":    { ... },
+            },
+            "MODELS": {
+                "claude-opus-4-6": { "provider": "anthropic", ... },
+            },
+            ...
+        }
+    """
+    if not os.path.isfile(PYFUN_PATH):
+        logger.critical(f".pyfun not found at: {PYFUN_PATH}")
+        raise FileNotFoundError(f".pyfun not found at: {PYFUN_PATH}")
+
+    result: Dict[str, Any] = {}
+
+    # Parser state
+    section: Optional[str]      = None   # e.g. "HUB", "PROVIDERS"
+    subsection: Optional[str]   = None   # e.g. "LLM_PROVIDERS"
+    block_type: Optional[str]   = None   # e.g. "LLM_PROVIDER", "MODEL", "TOOL"
+    block_name: Optional[str]   = None   # e.g. "anthropic", "claude-opus-4-6"
+
+    with open(PYFUN_PATH, "r", encoding="utf-8") as f:
+        for raw_line in f:
+            line = raw_line.strip()
+
+            # Skip empty lines and full-line comments
+            if not line or line.startswith("#"):
+                continue
+
+            # Skip file identifier
+            if line.startswith("[PYFUN_FILE"):
+                continue
+
+            # --- Block END markers (most specific first) ---
+            if line.endswith("_END]") and "." in line:
+                # e.g. [LLM_PROVIDER.anthropic_END] or [MODEL.claude-opus-4-6_END]
+                block_type = None
+                block_name = None
+                continue
+
+            if line.endswith("_END]") and not "." in line:
+                # e.g. [LLM_PROVIDERS_END], [HUB_END], [MODELS_END]
+                inner = line[1:-1].replace("_END", "")
+                if subsection and inner == subsection:
+                    subsection = None
+                elif section and inner == section:
+                    section = None
+                continue
+
+            # --- Block START markers ---
+            if line.startswith("[") and line.endswith("]"):
+                inner = line[1:-1]
+
+                # Named block: [LLM_PROVIDER.anthropic] or [MODEL.claude-opus-4-6]
+                if "." in inner:
+                    parts = inner.split(".", 1)
+                    block_type = parts[0]   # e.g. LLM_PROVIDER, MODEL, TOOL
+                    block_name = parts[1]   # e.g. anthropic, claude-opus-4-6
+
+                    # Determine which top-level key to store under
+                    if block_type == "LLM_PROVIDER":
+                        result.setdefault("LLM_PROVIDERS", {})
+                        result["LLM_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "SEARCH_PROVIDER":
+                        result.setdefault("SEARCH_PROVIDERS", {})
+                        result["SEARCH_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "WEB_PROVIDER":
+                        result.setdefault("WEB_PROVIDERS", {})
+                        result["WEB_PROVIDERS"].setdefault(block_name, {})
+                    elif block_type == "MODEL":
+                        result.setdefault("MODELS", {})
+                        result["MODELS"].setdefault(block_name, {})
+                    elif block_type == "TOOL":
+                        result.setdefault("TOOLS", {})
+                        result["TOOLS"].setdefault(block_name, {})
+                    continue
+
+                # Subsection: [LLM_PROVIDERS], [SEARCH_PROVIDERS] etc.
+                if section and not subsection:
+                    subsection = inner
+                    result.setdefault(inner, {})
+                    continue
+
+                # Top-level section: [HUB], [PROVIDERS], [MODELS] etc.
+                section = inner
+                result.setdefault(inner, {})
+                continue
+
+            # --- Key = Value ---
+            if "=" in line:
+                key, _, val = line.partition("=")
+                key = key.strip()
+                val = _parse_value(val)
+
+                # Strip provider prefix from key (e.g. "anthropic.base_url" → "base_url")
+                if block_name and key.startswith(f"{block_name}."):
+                    key = key[len(block_name) + 1:]
+
+                # Store in correct location
+                if block_type and block_name:
+                    if block_type == "LLM_PROVIDER":
+                        result["LLM_PROVIDERS"][block_name][key] = val
+                    elif block_type == "SEARCH_PROVIDER":
+                        result["SEARCH_PROVIDERS"][block_name][key] = val
+                    elif block_type == "WEB_PROVIDER":
+                        result["WEB_PROVIDERS"][block_name][key] = val
+                    elif block_type == "MODEL":
+                        result["MODELS"][block_name][key] = val
+                    elif block_type == "TOOL":
+                        result["TOOLS"][block_name][key] = val
+                elif section:
+                    result[section][key] = val
+
+    logger.info(f".pyfun loaded. Sections: {list(result.keys())}")
+    return result
+
+
+def load() -> Dict[str, Any]:
+    """Force (re)load of .pyfun — clears cache."""
+    global _cache
+    _cache = _parse()
+    return _cache
+
+
+def get() -> Dict[str, Any]:
+    """
+    Returns parsed .pyfun config as nested dict.
+    Loads and caches on first call — subsequent calls return cache.
+    """
+    global _cache
+    if _cache is None:
+        _cache = _parse()
+    return _cache
+
+
+def get_section(section: str) -> Dict[str, Any]:
+    """
+    Returns a specific top-level section.
+    Returns empty dict if section not found.
+    """
+    return get().get(section, {})
+
+
+def get_llm_providers() -> Dict[str, Any]:
+    """Returns all LLM providers (active and inactive)."""
+    return get().get("LLM_PROVIDERS", {})
+
+
+def get_active_llm_providers() -> Dict[str, Any]:
+    """Returns only LLM providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_llm_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_search_providers() -> Dict[str, Any]:
+    """Returns all search providers."""
+    return get().get("SEARCH_PROVIDERS", {})
+
+
+def get_active_search_providers() -> Dict[str, Any]:
+    """Returns only search providers where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_search_providers().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_models() -> Dict[str, Any]:
+    """Returns all model definitions."""
+    return get().get("MODELS", {})
+
+
+def get_models_for_provider(provider_name: str) -> Dict[str, Any]:
+    """Returns all models for a specific provider."""
+    return {
+        name: cfg
+        for name, cfg in get_models().items()
+        if cfg.get("provider", "") == provider_name
+    }
+
+
+def get_tools() -> Dict[str, Any]:
+    """Returns all tool definitions."""
+    return get().get("TOOLS", {})
+
+
+def get_active_tools() -> Dict[str, Any]:
+    """Returns only tools where active = 'true'."""
+    return {
+        name: cfg
+        for name, cfg in get_tools().items()
+        if cfg.get("active", "false").lower() == "true"
+    }
+
+
+def get_hub() -> Dict[str, Any]:
+    """Returns [HUB] section."""
+    return get_section("HUB")
+
+
+def get_limits() -> Dict[str, Any]:
+    """Returns [HUB_LIMITS] section."""
+    return get_section("HUB_LIMITS")
+
+
+def get_db_sync() -> Dict[str, Any]:
+    """Returns [DB_SYNC] section."""
+    return get_section("DB_SYNC")
+
+
+def get_debug() -> Dict[str, Any]:
+    """Returns [DEBUG] section."""
+    return get_section("DEBUG")
+
+
+def is_debug() -> bool:
+    """Returns True if DEBUG = 'ON' in .pyfun."""
+    return get_debug().get("DEBUG", "OFF").upper() == "ON"

app/db_sync.py

@@ -0,0 +1,302 @@
+
+# =============================================================================
+# app/db_sync.py
+# Internal SQLite IPC — app/* state & communication
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   DB path comes from app/.pyfun [DB_SYNC] → SQLITE_PATH via app/config.py.
+#
+# CRITICAL RULES:
+#   - This is NOT postgresql.py — cloud DB is Guardian-only!
+#   - db_sync ONLY manages its own tables (hub_state, tool_cache)
+#   - NEVER touch Guardian tables (users, sessions) — those belong to user_handler.py
+#   - SQLite path is shared with user_handler.py via SQLITE_PATH
+#   - app/* modules call db_sync.write() / db_sync.read() — never aiosqlite directly
+#
+# TABLE OWNERSHIP:
+#   users, sessions  → Guardian (fundaments/user_handler.py) — DO NOT TOUCH!
+#   hub_state        → db_sync (app/* internal state)
+#   tool_cache       → db_sync (app/* tool response cache)
+# =============================================================================
+
+import aiosqlite
+import logging
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from . import config
+
+logger = logging.getLogger("db_sync")
+
+# =============================================================================
+# Internal State
+# =============================================================================
+_db_path: Optional[str] = None
+_initialized: bool = False
+
+
+# =============================================================================
+# Initialization — called by app/app.py (parameterless, sandboxed)
+# =============================================================================
+
+async def initialize() -> None:
+    """
+    Initializes db_sync — reads SQLITE_PATH from .pyfun [DB_SYNC].
+    Creates app/* tables if they don't exist.
+    Called once by app/app.py during startup sequence.
+    No fundaments passed in — fully sandboxed.
+
+    Shares the SQLite file with user_handler.py (Guardian) but only
+    manages its own tables. Guardian tables are never touched here.
+    """
+    global _db_path, _initialized
+
+    if _initialized:
+        return
+
+    db_cfg   = config.get_db_sync()
+    _db_path = db_cfg.get("SQLITE_PATH", "app/.hub_state.db")
+
+    await _init_tables()
+
+    _initialized = True
+    logger.info(f"db_sync initialized — path: {_db_path}")
+
+
+# =============================================================================
+# SECTION 1 — Table Setup (app/* tables only!)
+# =============================================================================
+
+async def _init_tables() -> None:
+    """
+    Creates app/* internal tables if they don't exist.
+    NEVER modifies Guardian tables (users, sessions).
+    """
+    async with aiosqlite.connect(_db_path) as db:
+
+        # hub_state — generic key/value store for app/* modules
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS hub_state (
+                key        TEXT PRIMARY KEY,
+                value      TEXT,
+                updated_at TEXT
+            )
+        """)
+
+        # tool_cache — cached tool responses to reduce API calls
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS tool_cache (
+                id         INTEGER PRIMARY KEY AUTOINCREMENT,
+                tool_name  TEXT NOT NULL,
+                prompt     TEXT NOT NULL,
+                response   TEXT NOT NULL,
+                provider   TEXT,
+                model      TEXT,
+                created_at TEXT
+            )
+        """)
+
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_tool_cache_tool
+            ON tool_cache(tool_name)
+        """)
+
+        await db.commit()
+
+    logger.info("db_sync tables ready.")
+
+
+# =============================================================================
+# SECTION 2 — Key/Value Store (hub_state table)
+# =============================================================================
+
+async def write(key: str, value: Any) -> None:
+    """
+    Write a value to hub_state key/value store.
+    Value is JSON-serialized — supports dicts, lists, strings, numbers.
+
+    Args:
+        key:   Unique key string (e.g. 'scheduler.last_run').
+        value: Any JSON-serializable value.
+    """
+    _check_init()
+    now = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("""
+            INSERT OR REPLACE INTO hub_state (key, value, updated_at)
+            VALUES (?, ?, ?)
+        """, (key, json.dumps(value), now))
+        await db.commit()
+
+
+async def read(key: str, default: Any = None) -> Any:
+    """
+    Read a value from hub_state key/value store.
+    Returns default if key does not exist.
+
+    Args:
+        key:     Key string to look up.
+        default: Default value if key not found. Default: None.
+
+    Returns:
+        Deserialized value, or default if not found.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute(
+            "SELECT value FROM hub_state WHERE key = ?", (key,)
+        )
+        row = await cursor.fetchone()
+
+    if row is None:
+        return default
+
+    try:
+        return json.loads(row[0])
+    except (json.JSONDecodeError, TypeError):
+        return row[0]
+
+
+async def delete(key: str) -> None:
+    """
+    Delete a key from hub_state.
+
+    Args:
+        key: Key string to delete.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("DELETE FROM hub_state WHERE key = ?", (key,))
+        await db.commit()
+
+
+# =============================================================================
+# SECTION 3 — Tool Cache (tool_cache table)
+# =============================================================================
+
+async def cache_write(
+    tool_name: str,
+    prompt: str,
+    response: str,
+    provider: str = None,
+    model: str = None,
+) -> None:
+    """
+    Cache a tool response to reduce redundant API calls.
+
+    Args:
+        tool_name: Tool name (e.g. 'llm_complete', 'web_search').
+        prompt:    The input prompt/query that was used.
+        response:  The response to cache.
+        provider:  Provider name used (optional).
+        model:     Model name used (optional).
+    """
+    _check_init()
+
+    db_cfg      = config.get_db_sync()
+    max_entries = int(db_cfg.get("MAX_CACHE_ENTRIES", "1000"))
+    now         = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("""
+            INSERT INTO tool_cache (tool_name, prompt, response, provider, model, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """, (tool_name, prompt, response, provider, model, now))
+
+        # Enforce MAX_CACHE_ENTRIES — delete oldest if exceeded
+        await db.execute("""
+            DELETE FROM tool_cache WHERE id NOT IN (
+                SELECT id FROM tool_cache ORDER BY created_at DESC LIMIT ?
+            )
+        """, (max_entries,))
+
+        await db.commit()
+
+
+async def cache_read(tool_name: str, prompt: str) -> Optional[str]:
+    """
+    Read a cached tool response.
+    Returns None if no cache entry exists.
+
+    Args:
+        tool_name: Tool name to look up.
+        prompt:    The exact prompt/query to match.
+
+    Returns:
+        Cached response string, or None if not found.
+    """
+    _check_init()
+
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute("""
+            SELECT response FROM tool_cache
+            WHERE tool_name = ? AND prompt = ?
+            ORDER BY created_at DESC LIMIT 1
+        """, (tool_name, prompt))
+        row = await cursor.fetchone()
+
+    return row[0] if row else None
+
+
+# =============================================================================
+# SECTION 4 — Read-Only Query (for mcp.py db_query tool)
+# =============================================================================
+
+async def query(sql: str) -> List[Dict]:
+    """
+    Execute a read-only SELECT query on the internal hub state database.
+    Only SELECT statements are permitted — write operations are blocked.
+    Called by mcp.py db_query tool when db_sync.py is active.
+
+    Args:
+        sql: SQL SELECT statement to execute.
+
+    Returns:
+        List of result rows as dicts.
+
+    Raises:
+        ValueError: If the query is not a SELECT statement.
+    """
+    _check_init()
+
+    if not sql.strip().upper().startswith("SELECT"):
+        raise ValueError("Only SELECT queries are permitted in db_query tool.")
+
+    async with aiosqlite.connect(_db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(sql)
+        rows   = await cursor.fetchall()
+        return [dict(r) for r in rows]
+
+
+# =============================================================================
+# SECTION 5 — Helpers
+# =============================================================================
+
+def _check_init() -> None:
+    """Raise RuntimeError if db_sync was not initialized."""
+    if not _initialized or not _db_path:
+        raise RuntimeError("db_sync not initialized — call initialize() first.")
+
+
+def is_ready() -> bool:
+    """Returns True if db_sync is initialized and ready."""
+    return _initialized and _db_path is not None
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/mcp.py

@@ -0,0 +1,289 @@
+# =============================================================================
+# root/app/mcp.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+#   MCP SSE transport runs through Quart/hypercorn via /mcp route.
+#   All MCP traffic can be intercepted, logged, and transformed in app.py
+#   before reaching this handler — this is by design.
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are registered via tools.py — NOT hardcoded here.
+#   No key = no provider = no tool = no crash.
+#   Server always starts, just with fewer tools.
+#   Adding a new tool = update .pyfun + providers.py only. Never touch mcp.py.
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search provider registry + fallback chain
+#   models.py    → model limits, costs, capabilities from .pyfun [MODELS]
+#   tools.py     → tool registry + execution — reads .pyfun [TOOLS]
+#   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
+#   mcp.py       → registers tools only, delegates all logic to tools.py
+# =============================================================================
+import logging
+from typing import Dict, Any
+from . import config as app_config
+from . import providers
+from . import models
+from . import tools
+
+logger = logging.getLogger('mcp')
+# =============================================================================
+# Global MCP instance — initialized once via initialize()
+# =============================================================================
+_mcp = None
+# =============================================================================
+# Initialization — called exclusively by app/app.py
+# =============================================================================
+async def initialize() -> None:
+    """
+    Initializes the MCP instance and registers all tools.
+    Called once by app/app.py during startup sequence.
+    No fundaments passed in — fully sandboxed.
+
+    Registration order:
+        1. LLM tools    → via tools.py + providers.py (key-gated)
+        2. Search tools → via tools.py + providers.py (key-gated)
+        3. System tools → always registered, no key required
+        4. DB tools     → uncomment when db_sync.py is ready
+    """
+    global _mcp
+
+    logger.info("MCP Hub initializing...")
+
+    hub_cfg = app_config.get_hub()
+
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        logger.critical("FastMCP not installed. Run: pip install mcp")
+        raise
+
+    _mcp = FastMCP(
+        name=hub_cfg.get("HUB_NAME", "Universal MCP Hub"),
+        instructions=(
+            f"{hub_cfg.get('HUB_DESCRIPTION', 'Universal MCP Hub on PyFundaments')} "
+            "Use list_active_tools to see what is currently available."
+        )
+    )
+
+    # --- Initialize registries ---
+    providers.initialize()
+    models.initialize()
+    tools.initialize()
+
+    # --- Register MCP tools ---
+    _register_llm_tools(_mcp)
+    _register_search_tools(_mcp)
+    _register_system_tools(_mcp)
+    # _register_db_tools(_mcp)  # uncomment when db_sync.py is ready
+
+    logger.info("MCP Hub initialized.")
+    
+# =============================================================================
+# Request Handler — Quart /mcp route entry point
+# =============================================================================
+
+async def handle_request(request) -> None:
+    """
+    Handles incoming MCP SSE requests routed through Quart /mcp endpoint.
+    Central interceptor point for all MCP traffic.
+    Add auth, logging, rate limiting, payload transformation here as needed.
+    """
+    if _mcp is None:
+        logger.error("MCP not initialized — call initialize() first.")
+        from quart import jsonify
+        return jsonify({"error": "MCP not initialized"}), 503
+
+    # --- Interceptor hooks (uncomment as needed) ---
+    # logger.debug(f"MCP request: {request.method} {request.path}")
+    # await _check_auth(request)
+    # await _rate_limit(request)
+    # await _log_payload(request)
+
+    return await _mcp.handle_sse(request)
+
+
+# =============================================================================
+# Tool Registration — delegates all logic to tools.py
+# =============================================================================
+
+def _register_llm_tools(mcp) -> None:
+    """
+    Register LLM completion tool.
+    All logic delegated to tools.py → providers.py.
+    Adding a new LLM provider = update .pyfun + providers.py. Never touch this.
+    """
+    if not providers.list_active_llm():
+        logger.info("No active LLM providers — llm_complete tool skipped.")
+        return
+
+    @mcp.tool()
+    async def llm_complete(
+        prompt: str,
+        provider: str = None,
+        model: str = None,
+        max_tokens: int = 1024,
+    ) -> str:
+        """
+        Send a prompt to any configured LLM provider.
+        Automatically follows the fallback chain defined in .pyfun if a provider fails.
+
+        Args:
+            prompt:     The input text to send to the model.
+            provider:   Provider name (e.g. 'anthropic', 'gemini', 'openrouter', 'huggingface').
+                        Defaults to default_provider from .pyfun [TOOL.llm_complete].
+            model:      Model name override. Defaults to provider's default_model in .pyfun.
+            max_tokens: Maximum tokens in the response. Default: 1024.
+
+        Returns:
+            Model response as plain text string.
+        """
+        return await tools.run(
+            tool_name="llm_complete",
+            prompt=prompt,
+            provider_name=provider,
+            model=model,
+            max_tokens=max_tokens,
+        )
+
+    logger.info(f"Tool registered: llm_complete (active providers: {providers.list_active_llm()})")
+
+
+def _register_search_tools(mcp) -> None:
+    """
+    Register web search tool.
+    All logic delegated to tools.py → providers.py.
+    Adding a new search provider = update .pyfun + providers.py. Never touch this.
+    """
+    if not providers.list_active_search():
+        logger.info("No active search providers — web_search tool skipped.")
+        return
+
+    @mcp.tool()
+    async def web_search(
+        query: str,
+        provider: str = None,
+        max_results: int = 5,
+    ) -> str:
+        """
+        Search the web via any configured search provider.
+        Automatically follows the fallback chain defined in .pyfun if a provider fails.
+
+        Args:
+            query:       Search query string.
+            provider:    Provider name (e.g. 'brave', 'tavily').
+                         Defaults to default_provider from .pyfun [TOOL.web_search].
+            max_results: Maximum number of results to return. Default: 5.
+
+        Returns:
+            Formatted search results as plain text string.
+        """
+        return await tools.run(
+            tool_name="web_search",
+            prompt=query,
+            provider_name=provider,
+            max_results=max_results,
+        )
+
+    logger.info(f"Tool registered: web_search (active providers: {providers.list_active_search()})")
+
+
+def _register_system_tools(mcp) -> None:
+    """
+    System tools — always registered, no ENV key required.
+    Exposes hub status and model info without touching secrets.
+    """
+
+    @mcp.tool()
+    def list_active_tools() -> Dict[str, Any]:
+        """
+        List all active providers and registered tools.
+        Shows ENV key names only — never exposes values or secrets.
+
+        Returns:
+            Dict with hub info, active LLM providers, active search providers,
+            available tools and model names.
+        """
+        hub = app_config.get_hub()
+        return {
+            "hub":                     hub.get("HUB_NAME", "Universal MCP Hub"),
+            "version":                 hub.get("HUB_VERSION", ""),
+            "active_llm_providers":    providers.list_active_llm(),
+            "active_search_providers": providers.list_active_search(),
+            "active_tools":            tools.list_all(),
+            "available_models":        models.list_all(),
+        }
+
+    logger.info("Tool registered: list_active_tools")
+
+    @mcp.tool()
+    def health_check() -> Dict[str, str]:
+        """
+        Health check endpoint for HuggingFace Spaces and monitoring systems.
+
+        Returns:
+            Dict with service status.
+        """
+        return {"status": "ok", "service": "Universal MCP Hub"}
+
+    logger.info("Tool registered: health_check")
+
+    @mcp.tool()
+    def get_model_info(model_name: str) -> Dict[str, Any]:
+        """
+        Get limits, costs, and capabilities for a specific model.
+
+        Args:
+            model_name: Model name as defined in .pyfun [MODELS] (e.g. 'claude-sonnet-4-6').
+
+        Returns:
+            Dict with context size, max output tokens, rate limits, costs, and capabilities.
+            Returns empty dict if model is not configured in .pyfun.
+        """
+        return models.get(model_name)
+
+    logger.info("Tool registered: get_model_info")
+
+
+# =============================================================================
+# DB Tools — uncomment when db_sync.py is ready
+# =============================================================================
+
+# def _register_db_tools(mcp) -> None:
+#     """
+#     Register internal SQLite query tool.
+#     Uses db_sync.py (app/* internal SQLite) — NOT postgresql.py (Guardian-only)!
+#     Only SELECT queries are permitted — read-only by design.
+#     """
+#     from . import db_sync
+#
+#     @mcp.tool()
+#     async def db_query(query: str) -> list:
+#         """
+#         Execute a read-only SELECT query on the internal hub state database.
+#         Only SELECT statements are allowed — write operations are blocked.
+#
+#         Args:
+#             query: SQL SELECT statement to execute.
+#
+#         Returns:
+#             List of result rows as dicts.
+#         """
+#         return await db_sync.query(query)
+#
+#     logger.info("Tool registered: db_query")
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == '__main__':
+    print("WARNING: Run via main.py → app.py, not directly.")

app/mcp_old.py

@@ -0,0 +1,379 @@
+# =============================================================================
+# app/mcp.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+#   MCP SSE transport runs through Quart/hypercorn via /mcp route.
+#   All MCP traffic can be intercepted, logged, and transformed in app.py
+#   before reaching the MCP handler — this is by design.
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are only registered if their required ENV key exists.
+#   No key = no tool = no crash. Server always starts, just with fewer tools.
+#   ENV key NAMES come from app/.pyfun — values are never touched here.
+# =============================================================================
+
+import asyncio
+import logging
+import os
+from typing import Dict, Any
+
+from . import config as app_config  # reads app/.pyfun — only config source for app/*
+# from . import polymarket
+
+logger = logging.getLogger('mcp')
+
+# Global MCP instance — initialized once via initialize()
+_mcp = None
+
+
+async def initialize() -> None:
+    """
+    Initializes the MCP instance and registers all tools.
+    Called once by app/app.py during startup.
+    No fundaments passed in — sandboxed.
+    """
+    global _mcp
+
+    logger.info("MCP Hub initializing...")
+
+    hub_cfg = app_config.get_hub()
+
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        logger.critical("FastMCP not installed. Run: pip install mcp")
+        raise
+
+    _mcp = FastMCP(
+        name=hub_cfg.get("HUB_NAME", "Universal MCP Hub"),
+        instructions=(
+            f"{hub_cfg.get('HUB_DESCRIPTION', 'Universal MCP Hub on PyFundaments')} "
+            "Use list_active_tools to see what is currently available."
+        )
+    )
+
+    # --- Register tools ---
+    _register_llm_tools(_mcp)
+    _register_search_tools(_mcp)
+    # _register_db_tools(_mcp)   # uncomment when db_sync is ready
+    _register_system_tools(_mcp)
+    _register_polymarket_tools(_mcp)
+
+    logger.info("MCP Hub initialized.")
+
+
+async def handle_request(request) -> None:
+    """
+    Handles incoming MCP SSE requests routed through Quart /mcp endpoint.
+    This is the interceptor point — add auth, logging, rate limiting here.
+    """
+    if _mcp is None:
+        logger.error("MCP not initialized — call initialize() first.")
+        from quart import jsonify
+        return jsonify({"error": "MCP not initialized"}), 503
+
+    # --- Interceptor hooks (add as needed) ---
+    # logger.debug(f"MCP request: {request.method} {request.path}")
+    # await _check_auth(request)
+    # await _rate_limit(request)
+    # await _log_payload(request)
+
+    # --- Forward to FastMCP SSE handler ---
+    return await _mcp.handle_sse(request)
+
+
+# =============================================================================
+# Tool registration helpers
+# =============================================================================
+
+def _register_llm_tools(mcp) -> None:
+    """Register LLM tools based on active providers in app/.pyfun + ENV key check."""
+    active = app_config.get_active_llm_providers()
+
+    for name, cfg in active.items():
+        env_key = cfg.get("env_key", "")
+        if not env_key or not os.getenv(env_key):
+            logger.info(f"LLM provider '{name}' skipped — ENV key '{env_key}' not set.")
+            continue
+
+        if name == "anthropic":
+            import httpx
+            _key       = os.getenv(env_key)
+            _api_ver   = cfg.get("api_version_header", "2023-06-01")
+            _base_url  = cfg.get("base_url", "https://api.anthropic.com/v1")
+            _def_model = cfg.get("default_model", "claude-haiku-4-5-20251001")
+
+            @mcp.tool()
+            async def anthropic_complete(
+                prompt: str,
+                model: str = _def_model,
+                max_tokens: int = 1024
+            ) -> str:
+                """Send a prompt to Anthropic Claude."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        f"{_base_url}/messages",
+                        headers={
+                            "x-api-key": _key,
+                            "anthropic-version": _api_ver,
+                            "content-type": "application/json"
+                        },
+                        json={
+                            "model": model,
+                            "max_tokens": max_tokens,
+                            "messages": [{"role": "user", "content": prompt}]
+                        },
+                        timeout=60.0
+                    )
+                    r.raise_for_status()
+                    return r.json()["content"][0]["text"]
+
+            logger.info(f"Tool registered: anthropic_complete (model: {_def_model})")
+
+        elif name == "gemini":
+            import httpx
+            _key       = os.getenv(env_key)
+            _base_url  = cfg.get("base_url", "https://generativelanguage.googleapis.com/v1beta")
+            _def_model = cfg.get("default_model", "gemini-2.0-flash")
+
+            @mcp.tool()
+            async def gemini_complete(
+                prompt: str,
+                model: str = _def_model,
+                max_tokens: int = 1024
+            ) -> str:
+                """Send a prompt to Google Gemini."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        f"{_base_url}/models/{model}:generateContent",
+                        params={"key": _key},
+                        json={
+                            "contents": [{"parts": [{"text": prompt}]}],
+                            "generationConfig": {"maxOutputTokens": max_tokens}
+                        },
+                        timeout=60.0
+                    )
+                    r.raise_for_status()
+                    return r.json()["candidates"][0]["content"]["parts"][0]["text"]
+
+            logger.info(f"Tool registered: gemini_complete (model: {_def_model})")
+
+        elif name == "openrouter":
+            import httpx
+            _key       = os.getenv(env_key)
+            _base_url  = cfg.get("base_url", "https://openrouter.ai/api/v1")
+            _def_model = cfg.get("default_model", "mistralai/mistral-7b-instruct")
+            _referer   = os.getenv("APP_URL", "https://huggingface.co")
+
+            @mcp.tool()
+            async def openrouter_complete(
+                prompt: str,
+                model: str = _def_model,
+                max_tokens: int = 1024
+            ) -> str:
+                """Send a prompt via OpenRouter (100+ models)."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        f"{_base_url}/chat/completions",
+                        headers={
+                            "Authorization": f"Bearer {_key}",
+                            "HTTP-Referer": _referer,
+                            "content-type": "application/json"
+                        },
+                        json={
+                            "model": model,
+                            "max_tokens": max_tokens,
+                            "messages": [{"role": "user", "content": prompt}]
+                        },
+                        timeout=60.0
+                    )
+                    r.raise_for_status()
+                    return r.json()["choices"][0]["message"]["content"]
+
+            logger.info(f"Tool registered: openrouter_complete (model: {_def_model})")
+
+        elif name == "huggingface":
+            import httpx
+            _key       = os.getenv(env_key)
+            _base_url  = cfg.get("base_url", "https://api-inference.huggingface.co/models")
+            _def_model = cfg.get("default_model", "mistralai/Mistral-7B-Instruct-v0.3")
+
+            @mcp.tool()
+            async def hf_inference(
+                prompt: str,
+                model: str = _def_model,
+                max_tokens: int = 512
+            ) -> str:
+                """Send a prompt to HuggingFace Inference API."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        f"{_base_url}/{model}/v1/chat/completions",
+                        headers={
+                            "Authorization": f"Bearer {_key}",
+                            "content-type": "application/json"
+                        },
+                        json={
+                            "model": model,
+                            "max_tokens": max_tokens,
+                            "messages": [{"role": "user", "content": prompt}]
+                        },
+                        timeout=120.0
+                    )
+                    r.raise_for_status()
+                    return r.json()["choices"][0]["message"]["content"]
+
+            logger.info(f"Tool registered: hf_inference (model: {_def_model})")
+
+        else:
+            logger.info(f"LLM provider '{name}' has no tool handler yet — skipped.")
+
+
+def _register_search_tools(mcp) -> None:
+    """Register search tools based on active providers in app/.pyfun + ENV key check."""
+    active = app_config.get_active_search_providers()
+
+    for name, cfg in active.items():
+        env_key = cfg.get("env_key", "")
+        if not env_key or not os.getenv(env_key):
+            logger.info(f"Search provider '{name}' skipped — ENV key '{env_key}' not set.")
+            continue
+
+        if name == "brave":
+            import httpx
+            _key         = os.getenv(env_key)
+            _base_url    = cfg.get("base_url", "https://api.search.brave.com/res/v1/web/search")
+            _def_results = int(cfg.get("default_results", "5"))
+            _max_results = int(cfg.get("max_results", "20"))
+
+            @mcp.tool()
+            async def brave_search(query: str, count: int = _def_results) -> str:
+                """Search the web via Brave Search API."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.get(
+                        _base_url,
+                        headers={
+                            "Accept": "application/json",
+                            "X-Subscription-Token": _key
+                        },
+                        params={"q": query, "count": min(count, _max_results)},
+                        timeout=30.0
+                    )
+                    r.raise_for_status()
+                    results = r.json().get("web", {}).get("results", [])
+                    if not results:
+                        return "No results found."
+                    return "\n\n".join([
+                        f"{i}. {res.get('title', '')}\n   {res.get('url', '')}\n   {res.get('description', '')}"
+                        for i, res in enumerate(results, 1)
+                    ])
+
+            logger.info("Tool registered: brave_search")
+
+        elif name == "tavily":
+            import httpx
+            _key         = os.getenv(env_key)
+            _base_url    = cfg.get("base_url", "https://api.tavily.com/search")
+            _def_results = int(cfg.get("default_results", "5"))
+            _incl_answer = cfg.get("include_answer", "true").lower() == "true"
+
+            @mcp.tool()
+            async def tavily_search(query: str, max_results: int = _def_results) -> str:
+                """AI-optimized web search via Tavily."""
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        _base_url,
+                        json={
+                            "api_key": _key,
+                            "query": query,
+                            "max_results": max_results,
+                            "include_answer": _incl_answer
+                        },
+                        timeout=30.0
+                    )
+                    r.raise_for_status()
+                    data = r.json()
+                    parts = []
+                    if data.get("answer"):
+                        parts.append(f"Summary: {data['answer']}")
+                    for res in data.get("results", []):
+                        parts.append(
+                            f"- {res['title']}\n  {res['url']}\n  {res.get('content', '')[:200]}..."
+                        )
+                    return "\n\n".join(parts)
+
+            logger.info("Tool registered: tavily_search")
+
+        else:
+            logger.info(f"Search provider '{name}' has no tool handler yet — skipped.")
+
+
+def _register_system_tools(mcp) -> None:
+    """System tools — always registered, no ENV key required."""
+
+    @mcp.tool()
+    def list_active_tools() -> Dict[str, Any]:
+        """Show active providers and configured integrations (key names only, never values)."""
+        llm    = app_config.get_active_llm_providers()
+        search = app_config.get_active_search_providers()
+        hub    = app_config.get_hub()
+        return {
+            "hub":                    hub.get("HUB_NAME", "Universal MCP Hub"),
+            "version":                hub.get("HUB_VERSION", ""),
+            "active_llm_providers":   [n for n, c in llm.items()    if os.getenv(c.get("env_key", ""))],
+            "active_search_providers":[n for n, c in search.items() if os.getenv(c.get("env_key", ""))],
+        }
+    logger.info("Tool registered: list_active_tools")
+
+    @mcp.tool()
+    def health_check() -> Dict[str, str]:
+        """Health check for monitoring and HuggingFace Spaces."""
+        return {"status": "ok", "service": "Universal MCP Hub"}
+    logger.info("Tool registered: health_check")
+
+
+
+# 3. Neue Funktion — analog zu _register_search_tools():
+def _register_polymarket_tools(mcp) -> None:
+    """Polymarket tools — no ENV key needed, Gamma API is public."""
+
+    @mcp.tool()
+    async def get_markets(category: str = None, limit: int = 20) -> list:
+        """Get active prediction markets, optional category filter."""
+        return await polymarket.get_markets(category=category, limit=limit)
+
+    @mcp.tool()
+    async def trending_markets(limit: int = 10) -> list:
+        """Get top trending markets by trading volume."""
+        return await polymarket.trending_markets(limit=limit)
+
+    @mcp.tool()
+    async def analyze_market(market_id: str) -> dict:
+        """LLM analysis of a single market. Fallback if no LLM key set."""
+        return await polymarket.analyze_market(market_id)
+
+    @mcp.tool()
+    async def summary_report(category: str = None) -> dict:
+        """Summary report for a category or all markets."""
+        return await polymarket.summary_report(category=category)
+
+    @mcp.tool()
+    async def polymarket_cache_info() -> dict:
+        """Cache status, available categories, LLM availability."""
+        return await polymarket.get_cache_info()
+
+    logger.info("Tools registered: polymarket (5 tools)")
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == '__main__':
+    print("WARNING: Run via main.py, not directly.")

app/models.py

@@ -0,0 +1,73 @@
+# =============================================================================
+# # app/models.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are registered via models.py and models.py .
+#   No key = no provider = no tool = no crash.
+#   Adding a new provider = update .pyfun + providers.py only. Never touch mcp.py!
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search provider registry + fallback chain
+#   models.py    → model limits, costs, capabilities from .pyfun [MODELS]
+#   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
+#   mcp.py       → registers tools only, delegates all logic to providers/*
+# =============================================================================
+# app/models.py
+from . import config
+import logging
+
+logger = logging.getLogger("models")
+
+_registry: dict = {}
+
+def initialize() -> None:
+    """Build model registry from .pyfun [MODELS]"""
+    global _registry
+    _registry = config.get_models()
+    logger.info(f"Models loaded: {list(_registry.keys())}")
+
+
+def get(model_name: str) -> dict:
+    """Get model config by name."""
+    return _registry.get(model_name, {})
+
+
+def get_limit(model_name: str, key: str, default=None):
+    """Get specific limit for a model."""
+    return _registry.get(model_name, {}).get(key, default)
+
+
+def for_provider(provider_name: str) -> dict:
+    """Get all models for a provider."""
+    return config.get_models_for_provider(provider_name)
+
+
+def max_tokens(model_name: str) -> int:
+    return int(get_limit(model_name, "max_output_tokens", "1024"))
+
+
+def context_size(model_name: str) -> int:
+    return int(get_limit(model_name, "context_tokens", "4096"))
+
+
+def cost_input(model_name: str) -> float:
+    return float(get_limit(model_name, "cost_input_per_1k", "0"))
+
+
+def cost_output(model_name: str) -> float:
+    return float(get_limit(model_name, "cost_output_per_1k", "0"))
+
+
+def list_all() -> list:
+    return list(_registry.keys())

app/provider.py

@@ -0,0 +1,210 @@
+# =============================================================================
+# # app/providers.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+#
+# TOOL REGISTRATION PRINCIPLE:
+#   Tools are registered via providers.py and models.py .
+#   No key = no provider = no tool = no crash.
+#   Adding a new provider = update .pyfun + providers.py only. Never touch mcp.py!
+#
+# DEPENDENCY CHAIN (app/* only, no fundaments!):
+#   config.py    → parses app/.pyfun — single source of truth
+#   providers.py → LLM + Search provider registry + fallback chain
+#   models.py    → model limits, costs, capabilities from .pyfun [MODELS]
+#   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
+#   mcp.py       → registers tools only, delegates all logic to providers/*
+# =============================================================================
+
+from . import config
+import os
+import httpx
+import logging
+
+logger = logging.getLogger("providers")
+
+# =============================================================================
+# Base Provider — gemeinsame Logic EINMAL
+# =============================================================================
+class BaseProvider:
+    def __init__(self, name: str, cfg: dict):
+        self.name      = name
+        self.key       = os.getenv(cfg.get("env_key", ""))
+        self.base_url  = cfg.get("base_url", "")
+        self.fallback  = cfg.get("fallback_to", "")
+        self.timeout   = int(config.get_limits().get("REQUEST_TIMEOUT_SEC", "60"))
+        self.model     = cfg.get("default_model", "")
+
+    async def complete(self, prompt: str, model: str, max_tokens: int) -> str:
+        raise NotImplementedError
+
+    async def _post(self, url: str, headers: dict, payload: dict) -> dict:
+        """EINMAL — alle Provider nutzen das!"""
+        async with httpx.AsyncClient() as client:
+            r = await client.post(
+                url,
+                headers=headers,
+                json=payload,
+                timeout=self.timeout
+            )
+            r.raise_for_status()
+            return r.json()
+
+# =============================================================================
+# Provider Implementierungen — nur parse logic verschieden
+# =============================================================================
+class AnthropicProvider(BaseProvider):
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        cfg = config.get_active_llm_providers().get("anthropic", {})
+        data = await self._post(
+            f"{self.base_url}/messages",
+            headers={
+                "x-api-key":           self.key,
+                "anthropic-version":   cfg.get("api_version_header", "2023-06-01"),
+                "content-type":        "application/json",
+            },
+            payload={
+                "model":      model or self.model,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            }
+        )
+        return data["content"][0]["text"]
+
+
+class GeminiProvider(BaseProvider):
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        m = model or self.model
+        async with httpx.AsyncClient() as client:
+            r = await client.post(
+                f"{self.base_url}/models/{m}:generateContent",
+                params={"key": self.key},
+                json={
+                    "contents":       [{"parts": [{"text": prompt}]}],
+                    "generationConfig":{"maxOutputTokens": max_tokens},
+                },
+                timeout=self.timeout
+            )
+            r.raise_for_status()
+            return r.json()["candidates"][0]["content"]["parts"][0]["text"]
+
+
+class OpenRouterProvider(BaseProvider):
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        data = await self._post(
+            f"{self.base_url}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "HTTP-Referer":  os.getenv("APP_URL", "https://huggingface.co"),
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":    model or self.model,
+                "max_tokens": max_tokens,
+                "messages": [{"role": "user", "content": prompt}],
+            }
+        )
+        return data["choices"][0]["message"]["content"]
+
+
+class HuggingFaceProvider(BaseProvider):
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 512) -> str:
+        m = model or self.model
+        data = await self._post(
+            f"{self.base_url}/{m}/v1/chat/completions",
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":      m,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            }
+        )
+        return data["choices"][0]["message"]["content"]
+
+
+# =============================================================================
+# Provider Registry — gebaut aus .pyfun
+# =============================================================================
+_PROVIDER_CLASSES = {
+    "anthropic":   AnthropicProvider,
+    "gemini":      GeminiProvider,
+    "openrouter":  OpenRouterProvider,
+    "huggingface": HuggingFaceProvider,
+}
+
+_registry: dict = {}
+
+def initialize() -> None:
+    """Build provider registry from .pyfun — called by app.py"""
+    global _registry
+    active = config.get_active_llm_providers()
+
+    for name, cfg in active.items():
+        env_key = cfg.get("env_key", "")
+        if not env_key or not os.getenv(env_key):
+            logger.info(f"Provider '{name}' skipped — ENV key not set.")
+            continue
+        cls = _PROVIDER_CLASSES.get(name)
+        if not cls:
+            logger.info(f"Provider '{name}' has no handler yet — skipped.")
+            continue
+        _registry[name] = cls(name, cfg)
+        logger.info(f"Provider registered: {name}")
+
+
+async def complete(
+    prompt: str,
+    provider_name: str = None,
+    model: str = None,
+    max_tokens: int = 1024
+) -> str:
+    """
+    Complete with fallback chain from .pyfun.
+    anthropic → fails → openrouter → fails → error
+    """
+    # default provider aus [TOOL.llm_complete] → default_provider
+    if not provider_name:
+        tools = config.get_active_tools()
+        provider_name = tools.get("llm_complete", {}).get("default_provider", "anthropic")
+
+    visited = set()
+    current = provider_name
+
+    while current and current not in visited:
+        visited.add(current)
+        provider = _registry.get(current)
+
+        if not provider:
+            logger.warning(f"Provider '{current}' not in registry — trying fallback.")
+        else:
+            try:
+                return await provider.complete(prompt, model, max_tokens)
+            except Exception as e:
+                logger.warning(f"Provider '{current}' failed: {e} — trying fallback.")
+
+        # Fallback aus .pyfun
+        cfg = config.get_active_llm_providers().get(current, {})
+        current = cfg.get("fallback_to", "")
+
+    raise RuntimeError("All providers failed — no fallback available.")
+
+
+def get(name: str) -> BaseProvider:
+    """Get a specific provider by name."""
+    return _registry.get(name)
+
+
+def list_active() -> list:
+    """List all active provider names."""
+    return list(_registry.keys())

app/tmp/__init__.py

@@ -0,0 +1 @@
+> DO NOT DELETE THIS FOLDER!

app/tools.py

@@ -0,0 +1,228 @@
+# =============================================================================
+# app/tools.py
+# Tool Registry — Modular Wrapper
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun via app/config.py.
+#
+# TOOL REGISTRY PRINCIPLE:
+#   Tools are defined in .pyfun [TOOLS] — never hardcoded here.
+#   Adding a new tool = update .pyfun only. Never touch this file.
+#   config.py parses [TOOLS] and delivers ready-to-use dicts.
+#
+# DEPENDENCY CHAIN:
+#   .pyfun → config.py → tools.py → mcp.py
+#   tools.py delegates execution to providers.py — never calls APIs directly.
+# =============================================================================
+
+import logging
+import os
+from typing import Any, Dict, Optional
+
+from . import config     # reads app/.pyfun — single source of truth
+from . import providers  # LLM + Search execution + fallback chain
+
+logger = logging.getLogger("tools")
+
+# =============================================================================
+# Internal Registry — built from .pyfun [TOOLS] at initialize()
+# =============================================================================
+_registry: Dict[str, Dict] = {}
+
+
+# =============================================================================
+# Initialization — called by app/app.py (parameterless, sandboxed)
+# =============================================================================
+
+def initialize() -> None:
+    """
+    Builds the tool registry from .pyfun [TOOLS].
+    Called once by app/app.py during startup sequence.
+    No fundaments passed in — fully sandboxed.
+
+    Loads all active tools and their config (description, provider_type,
+    default_provider, timeout_sec, system_prompt, etc.) into _registry.
+    Inactive tools (active = "false") are skipped silently.
+    """
+    global _registry
+    _registry = config.get_active_tools()
+    logger.info(f"Tools loaded: {list(_registry.keys())}")
+
+
+# =============================================================================
+# Public API — used by mcp.py tool handlers
+# =============================================================================
+
+async def run(
+    tool_name: str,
+    prompt: str,
+    provider_name: Optional[str] = None,
+    model: Optional[str] = None,
+    max_tokens: int = 1024,
+) -> str:
+    """
+    Execute a tool by name.
+    Reads tool config from registry, delegates to providers.py.
+    Applies system_prompt from .pyfun if defined.
+
+    Args:
+        tool_name:     Tool name as defined in .pyfun [TOOLS] (e.g. 'llm_complete').
+        prompt:        User input / query string.
+        provider_name: Override provider. Defaults to tool's default_provider in .pyfun.
+        model:         Override model. Defaults to provider's default_model in .pyfun.
+        max_tokens:    Max tokens for LLM response. Default: 1024.
+
+    Returns:
+        Tool response as plain text string.
+
+    Raises:
+        ValueError:   If tool_name is not found in registry.
+        RuntimeError: If all providers fail (propagated from providers.py).
+    """
+    tool_cfg = _registry.get(tool_name)
+    if not tool_cfg:
+        raise ValueError(f"Tool '{tool_name}' not found in registry or not active.")
+
+    provider_type    = tool_cfg.get("provider_type", "llm")
+    default_provider = provider_name or tool_cfg.get("default_provider", "")
+    system_prompt    = tool_cfg.get("system_prompt", "")
+
+    # Build full prompt — prepend system_prompt if defined in .pyfun
+    full_prompt = f"{system_prompt}\n\n{prompt}".strip() if system_prompt else prompt
+
+    # --- LLM tools ---
+    if provider_type == "llm":
+        return await providers.llm_complete(
+            prompt=full_prompt,
+            provider_name=default_provider,
+            model=model,
+            max_tokens=max_tokens,
+        )
+
+    # --- Search tools ---
+    if provider_type == "search":
+        return await providers.search(
+            query=prompt,
+            provider_name=default_provider,
+            max_results=int(tool_cfg.get("default_results", "5")),
+        )
+
+    # --- DB tools (read-only, delegated to db_sync when ready) ---
+    if provider_type == "db":
+        # db_sync not yet implemented — return informative message
+        logger.info("db_query tool called — db_sync.py not yet active.")
+        return "Database query tool is not yet active. Configure db_sync.py first."
+
+    # --- Unknown provider type ---
+    logger.warning(f"Tool '{tool_name}' has unknown provider_type '{provider_type}' — skipped.")
+    return f"Tool '{tool_name}' provider type '{provider_type}' is not yet implemented."
+
+
+# =============================================================================
+# Registry helpers — used by mcp.py and system tools
+# =============================================================================
+
+def get(tool_name: str) -> Dict[str, Any]:
+    """
+    Get full config dict for a tool.
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Tool config dict, or empty dict if not found.
+    """
+    return _registry.get(tool_name, {})
+
+
+def get_description(tool_name: str) -> str:
+    """
+    Get the description of a tool (from .pyfun).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Description string, or empty string if not found.
+    """
+    return _registry.get(tool_name, {}).get("description", "")
+
+
+def get_system_prompt(tool_name: str) -> str:
+    """
+    Get the system_prompt of a tool (from .pyfun).
+    Returns empty string if no system_prompt is defined.
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        System prompt string, or empty string if not configured.
+    """
+    return _registry.get(tool_name, {}).get("system_prompt", "")
+
+
+def get_timeout(tool_name: str) -> int:
+    """
+    Get the timeout in seconds for a tool (from .pyfun).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Timeout in seconds (int). Defaults to 60 if not configured.
+    """
+    return int(_registry.get(tool_name, {}).get("timeout_sec", "60"))
+
+
+def get_provider_type(tool_name: str) -> str:
+    """
+    Get the provider_type of a tool (llm | search | db | image | sandbox).
+
+    Args:
+        tool_name: Tool name as defined in .pyfun [TOOLS].
+
+    Returns:
+        Provider type string, or empty string if not found.
+    """
+    return _registry.get(tool_name, {}).get("provider_type", "")
+
+
+def list_all() -> list:
+    """
+    List all active tool names from registry.
+
+    Returns:
+        List of active tool name strings.
+    """
+    return list(_registry.keys())
+
+
+def list_by_type(provider_type: str) -> list:
+    """
+    List all active tools of a specific provider_type.
+
+    Args:
+        provider_type: e.g. 'llm', 'search', 'db', 'image', 'sandbox'.
+
+    Returns:
+        List of tool name strings matching the provider_type.
+    """
+    return [
+        name for name, cfg in _registry.items()
+        if cfg.get("provider_type", "") == provider_type
+    ]
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/web/tmp/__init__py

@@ -0,0 +1 @@
+

app/web/tools/README.md

@@ -0,0 +1 @@
+> where will be tmp + do_work for webhooks

app/web/tools/__init__.py

@@ -0,0 +1 @@
+