# MCP Remote Suite

A production-ready Model Context Protocol (MCP) suite over **Streamable HTTP**,
demonstrating remote connectivity, a filesystem **roots** security boundary, and
where **sampling** (server-initiated LLM requests) fits in.

It ships three runnable apps on top of one transport layer:

| Component | Role | Default URL |
|-----------|------|-------------|
| **Server** (`mcp-server`) | FastMCP file server: tools, resources, prompts, sandboxed to a workspace root | `http://127.0.0.1:8000` |
| **GUI client** (`mcp-gui`) | Manual Gradio UI to discover/run tools, read resources, render prompts | `http://127.0.0.1:7861` |
| **AI host** (`mcp-host`) | Gradio chat where an OpenAI model drives the MCP tools | `http://127.0.0.1:7862` |

## Architecture

```
src/mcp_remote_suite/
├── config.py            # env-driven settings (pydantic-settings)
├── logging_config.py    # shared logging setup
├── _content.py          # unwrap MCP result objects -> text/dicts
├── server/
│   ├── security.py      # WorkspaceGuard — path-traversal protection
│   ├── files.py         # WorkspaceFiles — testable file operations
│   ├── app.py           # FastMCP factory + entry point
│   └── __main__.py      # python -m mcp_remote_suite.server
├── client/
│   └── base.py          # MCPHTTPClient — transport only, no UI/LLM deps
└── apps/
    ├── gui.py           # MCPHTTPClientApp (manual)
    └── host.py          # MCPHTTPHostApp (LLM-driven, multi-round tool loop)
tests/                   # pytest unit tests for the security boundary + files
```

**Layering:** `apps` depend on `client` and `_content`; `server` depends on
`security` + `files`. Nothing hardcodes ports/URLs/models — all configuration
flows from `config.py`.

## Setup

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate    |    Unix: source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # optional — adjust ports, model, OpenAI creds
```

## Run

Start the server, then either app (each in its own terminal):

```bash
mcp-server          # http://127.0.0.1:8000
mcp-gui             # http://127.0.0.1:7861  (manual)
mcp-host            # http://127.0.0.1:7862  (AI chat; needs OpenAI creds)
```

Equivalent module form: `python -m mcp_remote_suite.server`, etc.

## Configuration

All settings come from environment variables or `.env` (see `.env.example`).
Key ones: `SERVER_HOST`/`SERVER_PORT`, `WORKSPACE_DIR`, `SERVER_URL`,
`GUI_PORT`/`HOST_PORT`, `LOG_LEVEL`, and `OPENAI_API_KEY` / `OPENAI_BASE_URL` /
`OPENAI_MODEL` for the AI host.

## Security boundary

Every server-side path goes through `WorkspaceGuard.resolve()`, which resolves
the path and rejects anything escaping the workspace root (`..`, absolute paths,
symlink escapes) with `AccessDeniedError`. This is the "roots" enforcement that
makes the server safe to expose remotely.

## Tests

```bash
pytest
```