MCP Server Core 🚀

Universal MCP Server Framework for Streamable HTTP ASGI, Cloudflare Tunnel, OAuth 2.1, System Tray & Process Supervisor

Decoupled, reusable transport, lifecycle, and scaffolding foundation for FastMCP services (e.g. Codexen, Literary Workflow).

📦 Features

• ⚡ Fast Project Scaffolding (mcp-server-core init): Bootstrap complete, production-ready, standardized MCP services in seconds with tray supervisor, console launcher, batch scripts, and .env pre-configured.
• 🌐 ASGI Streamable HTTP Transport: Starlette + FastMCP integration supporting SSE, streaming, and atomic JSON-RPC responses.
• 🛡️ Cache-Busting & Anti-Stale Guarantees: Built-in NoCacheMiddleware ensuring Cache-Control: no-cache, no-store, must-revalidate across all discovery and tool execution routes.
• 🔐 Embedded OAuth 2.1 Server: Full RFC 9728, RFC 8414, RFC 7591 (Dynamic Client Registration), and PKCE S256 support for ChatGPT Developer Mode & third-party AI agents.
• 🚇 Cloudflare Tunnel Singleton Supervisor: Outbound named tunnel daemon lifecycle management with automated health check and heartbeat recovery.
• 🔍 Cascading Cloudflared Discovery:
  1. Direct parameter cloudflared_path
  2. Environment variable CLOUDFLARED_PATH or CLOUDFLARED_BIN
  3. Package binary directory (mcp_server_core/bin/cloudflared.exe)
  4. Project workspace directory (./bin/cloudflared.exe)
  5. User global cache directory (~/.mcp/bin/cloudflared.exe)
  6. System PATH (shutil.which)
  7. Automated download via mcp-server-core download-cloudflared
• 🖥️ System Tray Supervisor (BaseTrayApp): Clean Windows tray app supporting dynamic High-DPI icon drawing, single-instance process supervision via Windows Job Objects, URL/Token copy menus, and custom project management actions.
• 🚀 Unified Console Launcher (launch_service): Port checking, stale PID cleanup, tunnel heartbeat monitoring, and credential masking.
• 📋 Envelope Response Model (ToolResultListDict): Dual-access envelope format supporting both dict indexing (res["projects"]) and list sequence operations (len(res), res[0]).

🛠️ CLI Utilities

1. Rapidly Scaffold a New MCP Service

mcp-server-core init my-novel-service --port 8790 --char N --color "#0984e3"

Generated project structure:

my-novel-service/
├── my_novel_service/
│   ├── __init__.py
│   ├── __main__.py      # python -m my_novel_service entrypoint
│   ├── config.py        # Typed DeploymentEnvConfig loader
│   ├── server.py        # FastMCP + serve_http setup
│   ├── launcher.py      # Unified console launcher with tunnel guards
│   ├── tray.py          # Windows System Tray supervisor
│   └── tools/           # Modular MCP tools
│       ├── __init__.py
│       └── system.py
├── tests/               # Built-in unit tests
│   ├── __init__.py
│   └── test_tools.py
├── start.bat            # One-click start (tray silent mode preferred)
├── stop.bat             # One-click stop
├── .env.example         # Configuration template
├── .env                 # Pre-generated secure MCP_API_KEY
├── pyproject.toml
└── README.md

2. Check Tunnel, Ports & Environment Status

mcp-server-core status

3. Download Official Cloudflared Binary

# Downloads official release for current OS & architecture
mcp-server-core download-cloudflared

💻 Installation & Usage

1. From PyPI

pip install mcp-server-core
# or with tray support
pip install "mcp-server-core[tray]"

# or using uv
uv add "mcp-server-core[tray]"

2. Python Code Usage

Launcher (launcher.py):

from mcp_server_core import launch_service
from app.server import main as server_main

if __name__ == "__main__":
    launch_service(
        service_name="My Custom MCP Server",
        default_port=8790,
        server_runner=server_main,
    )

System Tray App (tray_app.py):

from mcp_server_core import BaseTrayApp

class CustomTrayApp(BaseTrayApp):
    def __init__(self):
        super().__init__(
            service_name="My Custom MCP Server",
            port=8790,
            tray_title="My Custom MCP Server",
            icon_text="M",
            icon_bg_color="#00b894",
        )

if __name__ == "__main__":
    app = CustomTrayApp()
    app.run()

Dual-Access Response Format:

from mcp_server_core import ToolResultListDict

@mcp.tool()
def list_projects() -> dict:
    projects = [{"id": 1, "name": "demo"}]
    return ToolResultListDict(projects, key="projects", status="success")

📄 License

MIT License.