af-jupyterlab-mcp: Instructions file for Claude Code

af-jupyterlab-mcp — Contributor Guide

MCP server that lets AF users create, inspect, and delete their own per-user JupyterLab servers on the UChicago ATLAS Analysis Facility Kubernetes cluster — the same notebooks af-portal deploys today — exposed as tools for LLMs, behind the af-mcp-platform credential broker.

Architecture

LLM <--MCP/HTTP--> af-mcp-platform aggregator <--Bearer: broker JWT--> af-jupyterlab-mcp <--k8s API--> notebook namespace

Design philosophy: unlike ami-mcp (which exposes a query DSL and lets the LLM be expressive), this backend exposes six fixed, typed tools over Kubernetes Pod/Service/Secret/Ingress objects. There is no raw-k8s-manifest escape hatch: the value here is the AF-specific policy layered on top (guardrail validation, dual-writer safety, owner-scoping), not a thin pass-through to the Kubernetes API.

Phase 1 (this repo, today) is the six CRD-management tools only. Phase 2 (tracked in maniaclab/af-mcp-platform#189, not built here) adds a typed proxy to the Datalayer jupyter-mcp-server running inside the notebook itself, so a session can drive code execution inside the user's own notebook without the notebook token ever entering LLM context.

Project layout

src/af_jupyterlab_mcp/
├── cli.py               # argparse: `af-jupyterlab-mcp serve` (HTTP transport only)
├── config.py             # env-driven Settings + the server-side guardrail constants
├── server.py             # FastMCP setup, lifespan (k8s client + broker verifier), tool registration
├── auth/
│   └── broker.py          # extract_bearer(), get_broker_claims() -- broker-issued JWT verification
├── k8s/
│   ├── errors.py           # GuardrailError, NameConflictError, NotFoundOrNotYoursError, QuotaExceededError, ...
│   ├── guardrails.py       # CPU/memory/duration range + image allowlist validation (compute_limits)
│   ├── names.py            # sanitize_k8s_pod_name, name availability, default-name generation
│   ├── templates.py        # Jinja rendering of the four ported manifests
│   ├── notebooks.py        # create/get/list/delete notebook (ported af-portal logic + rollback/owner-scoping)
│   ├── gpu.py               # get_gpu_availability (ported af-portal logic)
│   └── templates/           # pod.yaml.j2, service.yaml.j2, secret.yaml.j2, ingress.yaml.j2
│                             # verbatim port of af-portal/portal/templates/jupyterlab/*.yaml
└── tools/
    ├── _helpers.py          # format_error(), append_next_actions(), format_notebook[_list]()
    └── jupyterlab.py         # the six @mcp.tool() functions
tests/
├── conftest.py (none needed yet -- fixtures live per-module)
├── auth/test_broker.py       # bearer extraction + claims retrieval
├── k8s/
│   ├── fakes.py                # in-memory kubernetes client stand-in (no cluster access needed)
│   ├── test_names.py
│   ├── test_guardrails.py
│   ├── test_templates.py
│   ├── test_notebooks.py       # owner-scoping, 409-rollback, quota tests
│   └── test_gpu.py
├── tools/test_jupyterlab.py   # the six tools registered + invoked end-to-end against fakes
├── test_server.py             # HTTP transport + broker-mode ASGI app (real af_credentials, no mocks of our own auth code)
└── test_cli.py