feat: add core MCP server, TrainerClient tools and Resources (#2)

* feat: add core MCP server, TrainerClient tools, and Cli/SDK contract tests

Signed-off-by: abhijeet-dhumal <abhijeetdhumal652@gmail.com>

* fix: reviews round 1

Signed-off-by: abhijeet-dhumal <abhijeetdhumal652@gmail.com>

* refactor: dedupe tool registration, relocate health tools + persona state to policy

Signed-off-by: abhijeet-dhumal <abhijeetdhumal652@gmail.com>

---------

Signed-off-by: abhijeet-dhumal <abhijeetdhumal652@gmail.com>

Author: abhijeet-dhumal

.gitignore

@@ -1,75 +1,32 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Virtual environments
-.venv/
-venv/
-ENV/
-env/
-
-# uv
-.uv/
-uv.lock
-
-# IDE
-.idea/
+# IDEs
 .vscode/
+.idea/
 __debug_bin
+.DS_Store
 *.swp
-*.swo
 *~
 
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
-.tox/
-.nox/
-
-# Type checking
-.mypy_cache/
-.pytype/
+# Python cache files
+__pycache__/
+*.egg-info/
 
-# Jupyter
-.ipynb_checkpoints/
+# Build artifacts
+build/
+dist/
 
-# OS
-.DS_Store
-Thumbs.db
+# Testing / coverage
+.coverage
+coverage.xml
+coverage.json
+htmlcov/
 
-# Benchmarks
-benchmark-results.json
-.benchmarks/
+# Documentation build
+docs/_build/
 
-# Local dev
+# Environment / secrets
 .env
-.env.local
-*.local
+.env.*
 
-# Build artifacts
-*.whl
-
-# Docs build output
-docs/_build/
-
-# Test artifacts
-coverage.json
+# Virtual environments
+.venv/
+venv/

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "kubeflow-mcp-dev": {
+      "command": "uv",
+      "args": ["run", "kubeflow-mcp", "serve"],
+      "env": {}
+    }
+  }
+}

CONTRIBUTING.md

@@ -14,8 +14,8 @@ We encourage the judicious use of AI/LLM tools; please refer to the [Kubeflow AI
 1. Fork the repository
 2. Clone your fork:
    ```bash
-   git clone https://github.com/<your-username>/kubeflow-mcp-server.git
-   cd kubeflow-mcp-server
+   git clone https://github.com/<your-username>/mcp-server.git
+   cd mcp-server
    ```
 
 3. Set up development environment:

Makefile

@@ -14,11 +14,16 @@ uv: ## Install UV
 	}
 
 .PHONY: verify
-verify: ## Run linting, formatting and type checking
+verify: install-dev ## Run linting and formatting checks
 	@uv lock --check
 	@uv run ruff check .
 	@uv run ruff format --check .
 
+.PHONY: format
+format: ## Auto-fix lint and formatting issues
+	@uv run ruff check --fix .
+	@uv run ruff format .
+
 .PHONY: test-python
 test-python: ## Run Python unit tests
 	@uv sync --all-extras
@@ -29,3 +34,21 @@ install-dev: uv ## Install dependencies and tools
 	@echo "Syncing dependencies with uv..."
 	@uv sync --all-extras
 	@echo "Environment is ready."
+
+TRANSPORT ?= stdio
+
+.PHONY: inspector
+inspector: install-dev ## Launch MCP Inspector (TRANSPORT=stdio|http|sse)
+ifeq ($(TRANSPORT),stdio)
+	@npx @modelcontextprotocol/inspector uv run kubeflow-mcp serve
+else ifeq ($(TRANSPORT),sse)
+	@echo "Start the server first in another terminal:"
+	@echo "  uv run kubeflow-mcp serve --transport sse"
+	@echo ""
+	@npx @modelcontextprotocol/inspector --transport sse --server-url $(or $(SERVER_URL),http://127.0.0.1:8000/sse)
+else
+	@echo "Start the server first in another terminal:"
+	@echo "  uv run kubeflow-mcp serve --transport http"
+	@echo ""
+	@npx @modelcontextprotocol/inspector --transport http --server-url $(or $(SERVER_URL),http://127.0.0.1:8000/mcp)
+endif

README.md

@@ -1,66 +1,193 @@
 # Kubeflow MCP Server
 
-AI-powered interface for Kubeflow Training via [Model Context Protocol](https://modelcontextprotocol.io/).
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org) [![Join Slack](https://img.shields.io/badge/Join_Slack-blue?logo=slack)](https://www.kubeflow.org/docs/about/community/#kubeflow-slack-channels)
 
-Proposal: https://github.com/kubeflow/community/tree/master/proposals/936-kubeflow-mcp-server
-
-> ⚠️ **Note:** This project is in early development. We currently accept PRs only after prior discussion on Slack — join `#kubeflow-ml-experience` on the [CNCF Slack](https://www.kubeflow.org/docs/about/community/). For more discussion, join on bi-weekly ML Experience WG call on Wednesdays.
+Proposal: [KEP-936](https://github.com/kubeflow/community/tree/master/proposals/936-kubeflow-mcp-server) · [ROADMAP](ROADMAP.md) · [SECURITY](SECURITY.md) · [CONTRIBUTING](CONTRIBUTING.md)
 
 ## Overview
 
-This MCP server enables LLM agents (Claude, Cursor, etc.) to interact with Kubeflow Training through natural language. It wraps the [Kubeflow SDK](https://github.com/kubeflow/sdk) with MCP tools for fine-tuning, training job management, and monitoring.
+The Kubeflow MCP Server exposes Kubeflow Training operations as [Model Context Protocol](https://modelcontextprotocol.io/) tools, enabling AI agents (Claude, Cursor, Claude Code, or any custom agents etc.) to plan, submit, monitor, and manage training jobs through natural language — without users needing to learn Kubernetes or the Kubeflow SDK directly.
+
+### Benefits
 
-## Compatibility
+- **Agent-Native**: Tools auto-discovered via MCP — no manual API wiring
+- **Guided Workflow**: Phase ordering with next-step hints (Plan → Discover → Train → Monitor)
+- **Preview-Before-Submit**: Every mutating operation requires explicit confirmation
+- **Security-First**: Persona gating, namespace enforcement, input validation, bearer/JWT auth
+- **Multi-Platform**: Auto-detects OpenShift, EKS, GKE with platform-specific guidance
+- **Token-Efficient**: Progressive/semantic modes compress 23 tools into 2-3 meta-tools
+- **Extensible**: Plugin architecture for additional Kubeflow clients (TODO: optimizer, hub)
 
-| MCP Server | Kubeflow SDK | Python      | Kubernetes |
-|------------|-------------|-------------|------------|
-| 0.1.x      | ≥ 0.4.0     | 3.10 – 3.12 | ≥ 1.27     |
+## Get Started
 
-## Status
+### Install from source
 
-| Component | Status |
-|-----------|--------|
-| Core Infrastructure | 🚧 In Progress |
-| TrainerClient Tools | 🚧 In Progress |
-| OptimizerClient Tools | ⬜ Planned (Contributors Welcome) |
-| ModelRegistryClient Tools | ⬜ Planned (Contributors Welcome) |
-| PipelinesClient Tools | ⬜ Planned (Contributors Welcome) |
-| SparkClient Tools | ⬜ Planned (Contributors Welcome) |
-| FeastClient Tools | ⬜ Planned (Contributors Welcome) |
+```bash
+git clone https://github.com/kubeflow/mcp-server.git
+cd mcp-server
+pip install .
+```
 
-## Quick Start
+### Run the server
 
 ```bash
-# Install (trainer + optimizer included by default)
-pip install kubeflow-mcp
+kubeflow-mcp serve
+```
+
+> Once published to PyPI, install with `pip install kubeflow-mcp`.
 
-# Install with hub or spark extras
-pip install kubeflow-mcp[hub]
-pip install kubeflow-mcp[spark]
+### Example: Fine-tune a model via AI agent
 
-# Run
-kubeflow-mcp serve --clients trainer
+Once connected, your AI agent can run a complete training workflow through natural language:
+
+```
+User: "Fine-tune gemma-2b on the alpaca dataset"
+
+Agent calls: check_compatibility()        → ✅ K8s 1.29, Trainer CRD installed
+Agent calls: get_cluster_resources()      → 4x A100 GPUs available
+Agent calls: estimate_resources("google/gemma-2b") → needs ~16GB GPU, 1x A100
+Agent calls: list_runtimes()              → torchtune-llama, torchtune-gemma, ...
+Agent calls: fine_tune(                   → preview config (confirmed=False)
+    model="hf://google/gemma-2b",
+    dataset="hf://tatsu-lab/alpaca",
+    runtime="torchtune-gemma-2b"
+)
+Agent calls: fine_tune(..., confirmed=True) → TrainJob "train-gemma-abc" created
+Agent calls: get_training_logs("train-gemma-abc") → training progress...
 ```
 
-## Development
+Every mutating tool requires `confirmed=True` — agents always preview before submitting.
+
+### MCP Client Config
+
+
+<details>
+<summary>Cursor</summary>
 
-The project uses `uv` and a `Makefile` to manage the development environment.
+Add to `.cursor/mcp.json` (or use the `.mcp.json` at the repo root for local dev):
+
+```json
+{
+  "mcpServers": {
+    "kubeflow": {
+      "command": "uv",
+      "args": ["run", "kubeflow-mcp", "serve"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
 
 ```bash
-# Setup development environment
-make install-dev
+claude mcp add kubeflow -- kubeflow-mcp serve
+```
+
+</details>
+
+## Tools
+
+23 tools organized by workflow phase:
+
+| Phase | Tools | Description |
+|-------|-------|-------------|
+| Planning | `pre_flight`, `check_compatibility`, `get_cluster_resources`, `estimate_resources` | Environment validation and resource estimation |
+| Discovery | `list_training_jobs`, `get_training_job`, `list_runtimes`, `get_runtime` | Browse jobs and available runtimes |
+| Training | `fine_tune`, `run_custom_training`, `run_container_training` | Submit LoRA/QLoRA fine-tuning, custom scripts, or container jobs |
+| Monitoring | `get_training_logs`, `get_training_events`, `wait_for_training` | Track progress, debug failures |
+| Lifecycle | `delete_training_job`, `update_training_job` | Manage existing jobs (ownership-guarded) |
+| Platform | `inspect_crd`, `inspect_controller`, `patch_runtime`, `create_runtime`, `delete_runtime` | Cluster inspection and runtime management |
+| Health | `health_check`, `get_server_logs` | Server diagnostics |
+
+
+### Requirements
+
+| MCP Server | Kubeflow Trainer | Kubeflow SDK | Python      | Kubernetes |
+|------------|------------------|--------------|-------------|------------|
+| 0.1.x      | >= 2.2.0         | >= 0.4.0     | 3.10 - 3.12 | >= 1.27    |
 
-# Run verification (lint, format)
-make verify
+## CLI Reference
 
-# Run unit tests
-make test-python
+### `kubeflow-mcp serve`
+
+```bash
+kubeflow-mcp serve \
+  --clients trainer \             # modules: trainer, optimizer (stub), hub (stub)
+  --persona ml-engineer \         # readonly | data-scientist | ml-engineer | platform-admin
+  --mode full \                   # full | progressive | semantic
+  --instruction-tier full \       # full | compact | minimal
+  --transport stdio \             # stdio | http | sse
+  --auth-token SECRET \           # bearer token for HTTP auth (dev/staging)
+  --log-level INFO \              # DEBUG | INFO | WARNING | ERROR
+  --log-format console \          # console | json (auto-detected if omitted)
+  --no-banner                     # suppress startup banner
+```
+
+`--mode progressive` exposes 3 meta-tools (~85 tokens) for hierarchical discovery. `--mode semantic` exposes 2 meta-tools (~69 tokens) using embedding search. Both reduce token consumption significantly for agent workflows.
+
+<details>
+<summary> HTTP Authentication</summary>
+
+When using `--transport http`, configure auth to secure the endpoint:
+
+```bash
+# Simple API key (dev/staging)
+kubeflow-mcp serve --transport http --auth-token my-secret-token
+
+# Or via env var
+export KUBEFLOW_MCP_AUTH_TOKEN=my-secret-token
+kubeflow-mcp serve --transport http
+
+# JWT verification (production)
+export KUBEFLOW_MCP_JWKS_URI=https://auth.example.com/.well-known/jwks.json
+export KUBEFLOW_MCP_JWT_ISSUER=https://auth.example.com
+export KUBEFLOW_MCP_JWT_AUDIENCE=kubeflow-mcp
+kubeflow-mcp serve --transport http
 ```
 
-## Contributing
+Without auth configured, the server logs a warning that the HTTP endpoint is open.
+
+</details>
+
+<details>
+<summary>Agent Subcommand</summary>
+
+```bash
+kubeflow-mcp agent \
+  --backend ollama \              # ollama (default; more backends planned)
+  --model qwen3:8b \              # model name for the backend
+  --mode full \                   # full | progressive | semantic
+  --thinking                      # enable thinking output (supported models)
+```
+
+</details>
+
+## Development
+
+```bash
+make install-dev                  # setup environment
+make verify                       # lint + format check
+make test-python                  # run tests
+make inspector                    # launch MCP Inspector (stdio)
+make inspector TRANSPORT=http     # Inspector + Streamable HTTP (start server separately)
+make inspector TRANSPORT=sse      # Inspector + SSE (start server separately)
+```
+
+## Community
+
+- **Slack**: Join [#kubeflow-ml-experience](https://www.kubeflow.org/docs/about/community/#kubeflow-slack-channels) on CNCF Slack
+- **Meetings**: Attend the [Kubeflow SDK and ML Experience](https://bit.ly/kf-ml-experience) bi-weekly call
+- **GitHub**: Issues and contributions at [kubeflow/mcp-server](https://github.com/kubeflow/mcp-server)
+
+## Documentation
+
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+- **[CONTRIBUTING](CONTRIBUTING.md)**: Development workflow and PR guidelines
+- **[KEP-936](https://github.com/kubeflow/community/tree/master/proposals/936-kubeflow-mcp-server)**: Design proposal
 
 ## License
 
-Apache License 2.0 - See [LICENSE](LICENSE)
+Apache License 2.0 — see [LICENSE](LICENSE).