Metadata-Version: 2.4
Name: openroland-mcp-core
Version: 0.1.22
Summary: Shared MCP server host runtime, HTTP transport, and Windows tray.
License-Expression: MIT
Project-URL: Homepage, https://github.com/OpenRoLand/python
Project-URL: Repository, https://github.com/OpenRoLand/python
Project-URL: Issues, https://github.com/OpenRoLand/python/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: attrs==26.1.0
Requires-Dist: mcp==2.0.0
Requires-Dist: pydantic>=2.13.4
Provides-Extra: http
Requires-Dist: fastapi>=0.139.0; extra == "http"
Requires-Dist: starlette>=1.3.1; extra == "http"
Requires-Dist: uvicorn>=0.51.0; extra == "http"
Provides-Extra: windows-tray
Requires-Dist: pystray>=0.19.5; extra == "windows-tray"
Requires-Dist: Pillow>=12.3.0; extra == "windows-tray"
Requires-Dist: pyperclip>=1.11.0; extra == "windows-tray"
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"

# openroland-mcp-core

Shared Python library for local MCP server hosting.

## Features

- Transport-neutral `McpServerDefinition` registry (entry points + TOML).
- STDIO runner for agent clients (`run_stdio`, stderr-only logs).
- Local HTTP host on `127.0.0.1:3333` with per-server Streamable HTTP mounts.
- HTML dashboard at `/` and health routes.
- Windows system tray (`openroland-mcp-host`) with one icon for all servers.
- Per-server nested tray submenus, start/stop/restart, endpoint copy.
- Host tray actions: logs folder, config folder, start with Windows, LAN
  toggle (with warning), about, quit.
- Windows single-instance mutex and `POST /_host/activate` for second launches.
- Generic tkinter credential forms (no secrets on stdout).
- Local origin validation on HTTP when LAN access is disabled.

## Install

```bash
pip install openroland-mcp-core[http,windows-tray]
```

## STDIO (single server)

```python
from openroland_mcp_core.mcp.stdio import run_stdio

run_stdio(definition, config)
```

## Windows tray host

```text
openroland-mcp-host
```

From baseroot after `make init`:

```bash
make mcp-host
make forgejo-mcp-tray FORGEJO_MCP_CONFIG=D:/path/to/manifest.json
```

Host config: `%APPDATA%\AdvpyMcpHost\config.toml`

Logs: `%LOCALAPPDATA%\AdvpyMcpHost\logs\`

## Register a server package

```toml
[project.entry-points."advpy.mcp_servers"]
my-server = "my_package.mcp_definition:create"
```

The callable must return an `McpServerDefinition`.

## Cursor (HTTP)

Start the tray host first, then point Cursor at:

```text
http://127.0.0.1:3333/servers/<server-id>/mcp
```

Example `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "forgejo-actions": {
      "url": "http://127.0.0.1:3333/servers/forgejo-actions/mcp"
    }
  }
}
```

Do not put API tokens in `mcp.json`; use the tray **Set Credentials...**
action or environment variables read by the server package.
