mcp-server

Imported from kubeflow/mcp-server (AGENTS.md). Install upstream with npx skills add kubeflow/mcp-server. Copyright stays with the author.

Who This Is For

• AI agents: Automate repository tasks with minimal context
• Contributors: Humans using AI assistants or working directly
• Maintainers: Ensure assistants follow project conventions and CI rules

Agent Behavior Policy

AI agents should:

• Make atomic, minimal, and reversible changes.
• Prefer local analysis (uv run, make verify, make test-python) before proposing commits.
• NEVER modify configuration, CI/CD, or release automation unless explicitly requested.
• Avoid non-deterministic code or random seeds without fixtures.
• Use AGENTS.md and Makefile as the source of truth for development commands.

Agents must NOT:

• Bypass tests or linters
• Introduce dependencies without updating pyproject.toml
• Generate or commit large autogenerated files
• Change MCP tool schemas, names, or required parameters without KEP / maintainer discussion

Context Awareness

Before writing code, agents should:

• Read docstrings and existing test cases for pattern alignment
• Match import patterns from neighboring files
• Preserve existing logging, audit wrapping, and error-handling conventions

Repository Map

.github/                         # GitHub Actions (CI, issue/PR templates)
docs/                            # Architecture assets and diagrams
tests/                           # Integration, e2e, conformance suites; shared test helpers
kubeflow_mcp/                    # Main Python package (unit tests co-located as *_test.py)
├── cli.py                       # Click CLI entry (`kubeflow-mcp serve`)
├── __main__.py                  # python -m kubeflow_mcp
├── common/                      # Shared constants, types, and utils
├── core/                        # MCP server runtime
│   ├── server.py                # FastMCP factory, client loading, tool wrapping
│   ├── auth.py                  # Bearer / JWT auth for HTTP
│   ├── policy.py                # Personas and policy YAML filtering
│   ├── security.py              # Input validation, masking, namespace checks
│   ├── resilience.py            # Rate limiter and circuit breaker
│   ├── dynamic_tools.py         # full / progressive / semantic tool modes
│   ├── health.py                # health_check, get_server_logs
│   ├── telemetry.py             # Optional OpenTelemetry tracing
│   ├── middleware.py            # Audit identity ContextVars
│   ├── config.py                # Config precedence (CLI > env > file)
│   ├── logging.py               # Structured logging
│   └── resources.py             # MCP resource registration
├── trainer/                     # Trainer client (implemented)
│   ├── api/                     # Tools by phase (planning, discovery, …)
│   ├── constants/               # Trainer constants
│   ├── types/                   # Trainer types
│   └── resources/               # Markdown guidance for agents
├── optimizer/                   # Optimizer client (stub)
└── hub/                         # Hub / Model Registry client (stub)

Architecture Notes

• Plugin clients: Every client module exports TOOLS. The implemented trainer client also exports CLIENT_TOOL_DESCRIPTIONS, CLIENT_TOOL_ANNOTATIONS, INSTRUCTION_SECTIONS, and CLIENT_RESOURCES; optimizer and hub are currently stubs. core/server.py loads selected clients dynamically.
• Workflow phases: Plan → Discover → Train → Monitor → Lifecycle / Platform / Health.
• Confirm gate: All mutating tools must preview when confirmed=False and execute only with confirmed=True.
• Personas: readonly, data-scientist, ml-engineer, platform-admin (see core/policy.py). New tools must be added to the correct persona allowlists.
• Tool modes: full, progressive, and semantic (see core/dynamic_tools.py).

Tool Naming & Schema Conventions

Full cross-client rules (module exports, personas, confirm gate, testing checklist): docs/CONVENTIONS.md.

• Tool function names are the MCP tool names — use snake_case verbs (list_training_jobs, fine_tune, get_training_logs).
• Keep names stable; renaming is a breaking change for agents and clients.
• Mutating tools MUST accept confirmed: bool = False and return a preview first.
• Prefer shared response shapes from kubeflow_mcp.common.types (ToolResponse, PreviewResponse, ToolError).
• Register new tools in the client module TOOLS list and update CLIENT_TOOL_DESCRIPTIONS / CLIENT_TOOL_ANNOTATIONS.
• Do not change tool schemas (parameters, required fields, return contracts) without KEP discussion or explicit maintainer approval.

Environment & Tooling

• Package manager: uv (creates .venv via Makefile targets)
• Lint/format: ruff (isort integrated; line length 100, Python 3.10+)
• Tests: pytest with coverage
• Build: Hatchling
• Pre-commit: Config provided and enforced in CI

Commands

Setup:

make install-dev              # Install uv, sync deps, install pre-commit hooks

Verify (CI parity):

make verify                   # uv lock --check + ruff check + ruff format --check

Testing:

make test-python              # Unit tests + coverage
make test                     # Broader suite under tests/ and kubeflow_mcp/
make test-python report=xml   # XML coverage report
uv run pytest -q kubeflow_mcp/core/security_test.py
uv run pytest -q kubeflow_mcp/trainer/api/sdk_contracts_test.py
uv run pytest -q path/to/file.py::test_name -k "pattern"

Local lint/format:

make format                   # ruff check --fix + ruff format
uv run ruff check path/to/file.py
uv run ruff format path/to/file.py

Pre-commit / Inspector:

uv run pre-commit install
uv run pre-commit run --all-files
make inspector                 # MCP Inspector (TRANSPORT=stdio|http|sse, default stdio)

Development Workflow for AI Agents

Preferred commands: use uv run ... / make ... for consistent tooling.

Before making changes:

1. Read neighboring modules, docstrings, and tests
2. Follow the Core Development Principles below
3. Run validation before proposing commits

Validation before proposing changes:

• Lint/format: make verify
• Tests: make test-python or targeted pytest

Commit/PR hygiene:

• Conventional Commits — allowed types: chore, fix, feat, revert (scopes include docs, core, trainer, ci, …)
• Example titles: feat(trainer): add wait hint, chore(docs): add AGENTS.md
• Subject must start with a lowercase letter
• Sign off commits: git commit -s (DCO)
• Include rationale ("why") in commit messages / PR descriptions
• Do not push secrets or change git config
• Scope discipline: only modify files relevant to the task; keep diffs minimal

Core Development Principles

1. Maintain Stable MCP Interfaces ⚠️ CRITICAL

• Preserve public tool names, parameter names, and response shapes
• New optional parameters should be keyword-only with safe defaults
• Update personas / policy allowlists when adding tools
• Mark experimental behavior clearly in tool descriptions

2. Code Quality Standards

• All Python code MUST include type hints and return types
• Line length 100, Python 3.10 target, double quotes, spaces indent
• Imports: isort via ruff; first-party is kubeflow_mcp; prefer absolute imports
• Naming: functions/vars snake_case, classes PascalCase, constants UPPER_SNAKE_CASE; prefix private with _
• Follow existing patterns in the package you are modifying
• Keep copyright headers on new Python files

3. Testing Requirements

• Every new feature or bug fix MUST be covered by tests
• Prefer co-located *_test.py next to modules when matching existing patterns (e.g. kubeflow_mcp/cli_test.py, kubeflow_mcp/trainer/api/sdk_contracts_test.py)
• Shared test helpers live in tests/common.py; integration and conformance suites under tests/
• SDK contract tests guard compatibility with the Kubeflow SDK — do not delete or weaken them
• Unit tests must not require a live cluster or network unless clearly marked integration/e2e

4. Security

• Never bypass the confirm gate on mutating tools
• No eval(), exec(), or pickle on user-controlled input
• Validate Kubernetes names/namespaces and mask sensitive data (core/security.py)
• Proper exception handling (no bare except:) with descriptive errors
• No secrets in code, logs, examples, or commits

5. Documentation Standards

• Use clear docstrings for public tools and helpers
• Types belong in signatures, not duplicated in docstrings
• Focus on "why" rather than restating "what"
• Update README / ARCHITECTURE / CONTRIBUTING when user-facing behavior changes

What NOT to Change Without Discussion

• MCP tool names, required parameters, or response contracts
• Default persona (readonly) or confirm-gate semantics
• Auth / policy fail-closed behavior
• CI release title rules or Dependabot / release automation
• Broad refactors unrelated to the task at hand