Metadata-Version: 2.4
Name: mcp-server-core
Version: 0.3.4
Summary: Universal MCP Server Framework: Streamable HTTP ASGI, Cloudflare Tunnel, OAuth 2.1 & Process Supervisor
Author: yimmr
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: pywin32>=306; platform_system == "Windows"
Provides-Extra: test
Requires-Dist: httpx>=0.27.0; extra == "test"
Provides-Extra: tray
Requires-Dist: pystray>=0.19.5; extra == "tray"
Requires-Dist: pillow>=10.0.0; extra == "tray"
Dynamic: license-file

# 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).

[![PyPI version](https://img.shields.io/pypi/v/mcp-server-core.svg)](https://pypi.org/project/mcp-server-core/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-server-core.svg)](https://pypi.org/project/mcp-server-core/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 📦 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
```bash
mcp-server-core init my-novel-service --port 8790 --char N --color "#0984e3"
```
Generated project structure:
```text
my-novel-service/
├── app/
│   ├── __init__.py
│   ├── __main__.py      # python -m app entrypoint
│   ├── server.py        # FastMCP + serve_http setup
│   └── tools.py         # MCP tool functions
├── launcher.py          # Unified console launcher with tunnel guards
├── tray_app.py          # Windows System Tray supervisor
├── 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
```bash
mcp-server-core status
```

### 3. Download Official Cloudflared Binary
```bash
# Downloads official release for current OS & architecture
mcp-server-core download-cloudflared
```

---

## 💻 Installation & Usage

### 1. From PyPI
```bash
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`):
```python
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`):
```python
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:
```python
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.
