# Custom MCP Server

A custom **MCP (Model Control Proxy)** server that sits between clients and an
OpenAI-compatible chat-completion backend. It provides:

- Input validation, normalization, and chunking
- Session-based conversational memory (in-memory store, swappable)
- Sliding-window context management with rough token capping
- Prompt construction with injectable system instructions
- Resilient async agent calls (timeout + single retry on 429/5xx)

This is the **MVP scope** (milestones M1 + M2). Streaming, real summarization,
persistent stores, and auth are deferred.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (package & environment manager)

## Install

```bash
uv sync --all-extras
# activate the environment
source .venv/bin/activate
```

## Configure

```bash
cp .env.example .env
# edit .env and set AGENT_API_KEY, AGENT_API_BASE_URL, AGENT_MODEL
```

## Run

```bash
uv run uvicorn app.main:app --reload --port 8000
```

## Endpoints

### `POST /agent/input`

```bash
curl -s http://localhost:8000/agent/input \
  -H 'Content-Type: application/json' \
  -d '{"user_input": "Hello!"}'
```

### `GET /session/{id}`

```bash
curl -s http://localhost:8000/session/<session_id>
```

### `DELETE /session/{id}`

```bash
curl -X DELETE http://localhost:8000/session/<session_id>
```

### `GET /health`

```bash
curl -s http://localhost:8000/health
```

## Test

```bash
uv run pytest -q
```

## Layout

```
app/
  main.py              FastAPI app, logging, health
  config.py            Settings (pydantic-settings)
  api/                 HTTP routers
  models/schemas.py    Pydantic request/response models
  core/                input_processor, context_manager, prompt_builder, agent_client
  storage/             SessionStore protocol + in-memory implementation
  utils/               logging + token estimation
tests/                 pytest suite (agent backend mocked)
docs/                  Design documentation (architecture, data model, API, ADRs)
```

## Design documentation

See [`docs/`](./docs/) for the full design package:

- [`docs/architecture.md`](./docs/architecture.md) — system context, container,
  component, sequence, and deployment diagrams (Mermaid)
- [`docs/data-model.md`](./docs/data-model.md) — Session / Message ER diagram
  and lifecycle
- [`docs/api.md`](./docs/api.md) — HTTP API spec and error model
- [`docs/adr/`](./docs/adr/) — Architecture Decision Records