# mcp-hub

A self-hosted remote MCP server that provides reusable prompts and conventions across AI tools.

## Structure

```
modules/
└── dev/
    └── python.py    # Python/uv conventions → prompt: dev_python_uv
```

Each domain is a subfolder under `modules/`. Each file exposes a `router` (a `FastMCP` instance) that gets mounted in `main.py`.

## Configuration

Copy `.env.example` to `.env` and adjust as needed:

```
MCP_HOST=0.0.0.0
MCP_PORT=9001
```

## Run

```bash
uv run main.py
```

## Local Verification

Use FastMCP CLI to verify the server without starting it:

```bash
# List all registered tools
uv run fastmcp list main.py

# List tools + prompts
uv run fastmcp list main.py --prompts

# Inspect server details (JSON report)
uv run fastmcp inspect main.py

# Launch MCP Inspector (interactive browser UI for testing tools/prompts)
uv run fastmcp dev inspector main.py
```

## Connect

Add as an MCP server in your AI tool using:

- **Transport:** Streamable HTTP
- **URL:** `http://<host>:<port>/mcp`

## Deploy on Linux

**Option 1 — screen (recommended):** lets you detach and reattach to the session anytime.

```bash
screen -S mcp-hub
uv run main.py
# Ctrl+A then D to detach

# Reattach later:
screen -r mcp-hub
```

**Option 2 — nohup:** fire-and-forget, no reattach.

```bash
nohup uv run main.py > mcp-hub.log 2>&1 &

# stop later
pkill -f "mcp-hub"
```

## Add a new module

1. Create `modules/<domain>/<topic>.py` with a `router = FastMCP(...)` and `@router.prompt` functions
2. Mount it in `main.py`: `mcp.mount(router, namespace="<domain>")`

Prompts are namespaced as `<namespace>_<prompt_name>` (e.g. `dev_python_uv`).