talkops-kargo-mcp-server 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- talkops_kargo_mcp_server-0.2.0/.dockerignore +85 -0
- talkops_kargo_mcp_server-0.2.0/.gitignore +15 -0
- talkops_kargo_mcp_server-0.2.0/.python-version +1 -0
- talkops_kargo_mcp_server-0.2.0/PKG-INFO +173 -0
- talkops_kargo_mcp_server-0.2.0/README.md +145 -0
- talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-Comprehensive.md +633 -0
- talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-Design.md +545 -0
- talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-MCP-Internal-Impl.md +393 -0
- talkops_kargo_mcp_server-0.2.0/docs/kargo-research/interal-reference.md +976 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/APPROVAL_TEST_GUIDE.md +15 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/ONBOARDING_TEST_GUIDE.md +27 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/PROMOTION_TEST_GUIDE.md +16 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/ROLLBACK_TEST_GUIDE.md +15 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/TROUBLESHOOTING_TEST_GUIDE.md +17 -0
- talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/WORKFLOW_JOURNEYS.md +94 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/__init__.py +3 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/config.py +290 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/exceptions/__init__.py +27 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/exceptions/custom.py +76 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/main.py +40 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/__init__.py +113 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/common.py +19 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/credentials.py +18 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/freight.py +204 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/project.py +112 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/promotion.py +91 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/promotion_task.py +26 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/schemas.py +267 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/stage.py +230 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/warehouse.py +93 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/__init__.py +29 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/base.py +22 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/credentials_resources.py +74 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/freight_resources.py +46 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/project_resources.py +168 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/promotion_resources.py +75 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/promotion_task_resources.py +47 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/registry.py +19 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/stage_resources.py +75 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/verification_resources.py +111 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/warehouse_resources.py +51 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/__init__.py +9 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/bootstrap.py +51 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/core.py +32 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/middleware.py +135 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/services/__init__.py +7 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/services/kargo_service.py +1947 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/static/KARGO_MCP_INSTRUCTIONS.md +23 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/static/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/__init__.py +25 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/base.py +201 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/credentials/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/credentials/credentials_tools.py +145 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/diagnostics/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/diagnostics/diagnostics_tools.py +136 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/pipeline/__init__.py +5 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/pipeline/pipeline_tools.py +701 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/promotion/promotion_tools.py +801 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/rbac/__init__.py +5 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/rbac/rbac_tools.py +148 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/registry.py +37 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/verification/__init__.py +5 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/verification/verification_tools.py +243 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/__init__.py +49 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/kargo_helpers.py +378 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/redaction.py +141 -0
- talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/warehouse_spec_builder.py +347 -0
- talkops_kargo_mcp_server-0.2.0/mcp.json +62 -0
- talkops_kargo_mcp_server-0.2.0/plugin.json +12 -0
- talkops_kargo_mcp_server-0.2.0/pyproject.toml +68 -0
- talkops_kargo_mcp_server-0.2.0/scripts/get_kargo_token.py +82 -0
- talkops_kargo_mcp_server-0.2.0/skills/managing-kargo-credentials-and-access/SKILL.md +35 -0
- talkops_kargo_mcp_server-0.2.0/skills/managing-kargo-credentials-and-access/references/credentials-and-rbac.md +56 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/SKILL.md +49 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/argocd-integration.md +41 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/promotion-steps-catalog.md +82 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/warehouse-subscriptions.md +92 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/scripts/render_promotion_steps.py +275 -0
- talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/scripts/validate_pipeline_manifests.py +179 -0
- talkops_kargo_mcp_server-0.2.0/skills/promoting-and-approving-freight/SKILL.md +35 -0
- talkops_kargo_mcp_server-0.2.0/skills/promoting-and-approving-freight/references/promotion-gates.md +55 -0
- talkops_kargo_mcp_server-0.2.0/skills/rolling-back-kargo-stages/SKILL.md +33 -0
- talkops_kargo_mcp_server-0.2.0/skills/rolling-back-kargo-stages/references/rollback-sop.md +35 -0
- talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/SKILL.md +33 -0
- talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/references/diagnosis-catalog.md +116 -0
- talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/scripts/summarize_promotion_failure.py +110 -0
- talkops_kargo_mcp_server-0.2.0/tests/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/tests/conftest.py +654 -0
- talkops_kargo_mcp_server-0.2.0/tests/fixtures/analysis-run-failed.json +19 -0
- talkops_kargo_mcp_server-0.2.0/tests/fixtures/pipeline-invalid.yaml +70 -0
- talkops_kargo_mcp_server-0.2.0/tests/fixtures/pipeline-valid.yaml +106 -0
- talkops_kargo_mcp_server-0.2.0/tests/fixtures/promotion-failed.json +27 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_dry_run_defaults.py +123 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_elicitation_and_confirm.py +71 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_error_is_error_flag.py +49 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_no_prompts_registered.py +18 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_resources_live_and_redacted.py +105 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_tool_schema_budgets.py +81 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_toolsets_and_readonly.py +56 -0
- talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_workflows_e2e.py +249 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/test_plugin_and_mcp_manifest_schema.py +65 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_frontmatter_and_budgets.py +69 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_gate_markers.py +21 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_scripts_offline_execution.py +148 -0
- talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_tool_and_resource_integrity.py +103 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/__init__.py +1 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_config_and_cli.py +65 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_diagnose_and_trace_service.py +215 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_error_translation.py +67 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_kargo_service_rest.py +370 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_middleware_caching_and_coercion.py +51 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_models_and_builders.py +176 -0
- talkops_kargo_mcp_server-0.2.0/tests/unit/test_redaction_and_sanitization.py +81 -0
- talkops_kargo_mcp_server-0.2.0/uv.lock +1349 -0
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Git
|
|
2
|
+
.git
|
|
3
|
+
.gitignore
|
|
4
|
+
|
|
5
|
+
# Python
|
|
6
|
+
__pycache__
|
|
7
|
+
*.pyc
|
|
8
|
+
*.pyo
|
|
9
|
+
*.pyd
|
|
10
|
+
.Python
|
|
11
|
+
env
|
|
12
|
+
pip-log.txt
|
|
13
|
+
pip-delete-this-directory.txt
|
|
14
|
+
.tox
|
|
15
|
+
.coverage
|
|
16
|
+
.coverage.*
|
|
17
|
+
.cache
|
|
18
|
+
nosetests.xml
|
|
19
|
+
coverage.xml
|
|
20
|
+
*.cover
|
|
21
|
+
*.log
|
|
22
|
+
.git
|
|
23
|
+
.mypy_cache
|
|
24
|
+
.pytest_cache
|
|
25
|
+
.hypothesis
|
|
26
|
+
|
|
27
|
+
# Virtual environments
|
|
28
|
+
.env
|
|
29
|
+
.venv
|
|
30
|
+
env/
|
|
31
|
+
venv/
|
|
32
|
+
ENV/
|
|
33
|
+
env.bak/
|
|
34
|
+
venv.bak/
|
|
35
|
+
|
|
36
|
+
# IDEs
|
|
37
|
+
.vscode/
|
|
38
|
+
.idea/
|
|
39
|
+
*.swp
|
|
40
|
+
*.swo
|
|
41
|
+
*~
|
|
42
|
+
|
|
43
|
+
# OS
|
|
44
|
+
.DS_Store
|
|
45
|
+
.DS_Store?
|
|
46
|
+
._*
|
|
47
|
+
.Spotlight-V100
|
|
48
|
+
.Trashes
|
|
49
|
+
ehthumbs.db
|
|
50
|
+
Thumbs.db
|
|
51
|
+
|
|
52
|
+
# Documentation
|
|
53
|
+
docs/
|
|
54
|
+
|
|
55
|
+
# Tests
|
|
56
|
+
tests/
|
|
57
|
+
test_*
|
|
58
|
+
*_test.py
|
|
59
|
+
|
|
60
|
+
# Development files
|
|
61
|
+
.pre-commit-config.yaml
|
|
62
|
+
.ruff.toml
|
|
63
|
+
.mypy.ini
|
|
64
|
+
pyproject.toml.bak
|
|
65
|
+
|
|
66
|
+
# Build artifacts
|
|
67
|
+
build/
|
|
68
|
+
dist/
|
|
69
|
+
*.egg-info/
|
|
70
|
+
|
|
71
|
+
# Reference files
|
|
72
|
+
reference/
|
|
73
|
+
|
|
74
|
+
# Docker
|
|
75
|
+
Dockerfile*
|
|
76
|
+
docker-compose*.yml
|
|
77
|
+
.dockerignore
|
|
78
|
+
|
|
79
|
+
# Logs
|
|
80
|
+
*.log
|
|
81
|
+
logs/
|
|
82
|
+
|
|
83
|
+
# Temporary files
|
|
84
|
+
tmp/
|
|
85
|
+
temp/
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.12
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: talkops-kargo-mcp-server
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Execution-only MCP server and Agent Skills package for Kargo v1.12 continuous promotion orchestration.
|
|
5
|
+
Project-URL: Homepage, https://talkops.ai
|
|
6
|
+
Project-URL: Repository, https://github.com/talkops-ai/talkops-mcp
|
|
7
|
+
Project-URL: Documentation, https://github.com/talkops-ai/talkops-mcp/tree/main/src/kargo-mcp-server
|
|
8
|
+
Project-URL: Issues, https://github.com/talkops-ai/talkops-mcp/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/talkops-ai/talkops-mcp/releases
|
|
10
|
+
Author-email: TalkOps <contact@talkops.ai>
|
|
11
|
+
License: Apache-2.0
|
|
12
|
+
Keywords: ai,continuous-delivery,devops,gitops,kargo,kubernetes,mcp,model-context-protocol,promotion
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: System Administrators
|
|
16
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Classifier: Topic :: System :: Systems Administration
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: fastmcp>=2.13.3
|
|
24
|
+
Requires-Dist: httpx>=0.28.0
|
|
25
|
+
Requires-Dist: pydantic>=2.12.5
|
|
26
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# Kargo MCP Server & Agent Skills (`v0.2.0`)
|
|
30
|
+
|
|
31
|
+
An Agent Plugin v1.0.0 package that pairs **5 Agent Skills** (`skills/<gerund>/SKILL.md`) with a **20-tool, 18-resource execution-only MCP server** for **Kargo v1.10+ (tested against v1.12.5)** progressive delivery pipelines.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Architecture: Skill & Execution Separation
|
|
36
|
+
|
|
37
|
+
Following the TalkOps **Skill & Execution Separation** specification:
|
|
38
|
+
|
|
39
|
+
1. **Reasoning Layer (`skills/*/SKILL.md`)**:
|
|
40
|
+
- Progressive-disclosure procedural workflows, GitOps step composition catalogs (61 Kargo v1.12 steps + `expr-lang` functions), diagnosis code runbooks, and offline deterministic Python helper scripts (`skills/*/scripts/*.py`).
|
|
41
|
+
- Zero MCP Prompts (`list_prompts() == []`) and zero static prose MCP Resources.
|
|
42
|
+
2. **Execution Data Plane (`kargo_mcp_server/`)**:
|
|
43
|
+
- **18 Live MCP Resources (`kargo://...`)**: Read-only cluster state, pipeline DAG topology, stage YAML manifests, promotion step traces, verification `AnalysisRun` logs, RBAC roles, and redacted credentials.
|
|
44
|
+
- **20 Execution Tools (`kargo_*`)**: Server-side filtering (`kargo_query_freight`), N-to-1 cross-resource correlation (`kargo_trace_freight`, `kargo_diagnose_stage`, `kargo_diagnose_warehouse`), and cluster mutations gated by `--allow-write`, `dry_run=True` previews, and MCP Elicitation / `confirm=True`.
|
|
45
|
+
- **Zero-Secret (`0->1`) Guarantee**: Credential tools never accept or return raw passwords, tokens, or private keys; secrets are resolved strictly on the server side via `secret_ref`.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Bundled Agent Skills (5)
|
|
50
|
+
|
|
51
|
+
| Skill Directory | Purpose | Companion References & Offline Scripts |
|
|
52
|
+
|-----------------|---------|----------------------------------------|
|
|
53
|
+
| `skills/onboarding-kargo-pipelines/` | Scaffolds Projects, ProjectConfigs, Warehouses, PromotionTasks, Stages, and Argo CD authorization | `references/warehouse-subscriptions.md`, `references/promotion-steps-catalog.md`, `references/argocd-integration.md`, `scripts/render_promotion_steps.py`, `scripts/validate_pipeline_manifests.py` |
|
|
54
|
+
| `skills/promoting-and-approving-freight/` | Evaluates Freight eligibility, approves Freight, promotes single stages or downstream subscribers, and manages verification gates | `references/promotion-gates.md` |
|
|
55
|
+
| `skills/rolling-back-kargo-stages/` | Executes emergency roll-forward Stage rollbacks from `freightHistory` and manages Kargo v1.11+ `autoPromotionHolds` | `references/rollback-sop.md` |
|
|
56
|
+
| `skills/troubleshooting-kargo-pipelines/` | Diagnoses Warehouse polling failures, Promotion step errors, Argo CD auth mismatches, and Verification failures | `references/diagnosis-catalog.md`, `scripts/summarize_promotion_failure.py` |
|
|
57
|
+
| `skills/managing-kargo-credentials-and-access/` | Manages repo/generic credentials via server-side `secret_ref`, shared credential replication, and Kargo RBAC roles/grants | `references/credentials-and-rbac.md` |
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## MCP Tools (20 Tools across 6 Toolsets)
|
|
62
|
+
|
|
63
|
+
Every tool enforces `<= 8` parameters and carries explicit `ToolAnnotations`.
|
|
64
|
+
|
|
65
|
+
| Toolset | Tool Name | Mode | Default Gate | Description |
|
|
66
|
+
|---------|-----------|------|--------------|-------------|
|
|
67
|
+
| `pipeline` | `kargo_manage_project` | Write / Destructive | `dry_run=True` (create) / `confirm` (delete) | Create or delete a Kargo `Project` (`v1.7+` metadata-only). |
|
|
68
|
+
| `pipeline` | `kargo_apply_project_config` | Write | `dry_run=True` | Create/update `ProjectConfig` (`promotionPolicies`, `webhookReceivers`, `freightLinks`, `stageLinks`). |
|
|
69
|
+
| `pipeline` | `kargo_apply_warehouse` | Write | `dry_run=True` | Create/update `Warehouse` with Kargo v1.12 `constraint` and `allowTagsRegexes`/`ignoreTagsRegexes`. |
|
|
70
|
+
| `pipeline` | `kargo_apply_stage` | Write | `dry_run=True` | Create/update `Stage` (merging existing spec and validating DAG cycles). |
|
|
71
|
+
| `pipeline` | `kargo_apply_promotion_task` | Write | `dry_run=True` | Create/update `PromotionTask` or `ClusterPromotionTask` with Kargo v1.12 step validation. |
|
|
72
|
+
| `pipeline` | `kargo_delete_resource` | Destructive | `confirm` | Delete a `Stage`, `Warehouse`, `PromotionTask`, `ClusterPromotionTask`, or `ProjectConfig`. |
|
|
73
|
+
| `promotion` | `kargo_query_freight` | **Read-Only** | None | Query/filter Freight by stage availability, origin Warehouse, or alias. |
|
|
74
|
+
| `promotion` | `kargo_refresh` | Write | None | Trigger immediate reconciliation/discovery on a Warehouse, Stage, Promotion, ProjectConfig, or ClusterConfig. |
|
|
75
|
+
| `promotion` | `kargo_promote` | Write | `confirm` (when `downstream=True`) | Promote Freight to a Stage (by ID, alias, or `origin_warehouse`) or downstream subscribers via native REST API. |
|
|
76
|
+
| `promotion` | `kargo_rollback_stage` | Destructive (N-to-1) | `confirm` | Roll back a Stage to the previous verified Freight in `status.freightHistory` (and warn on v1.11+ holds). |
|
|
77
|
+
| `promotion` | `kargo_approve_freight` | Destructive | `confirm` | Manually approve Freight for a restricted Stage. |
|
|
78
|
+
| `promotion` | `kargo_manage_promotion` | Write / Destructive | `confirm` (abort) | Abort a running Promotion or refresh (wake) a Promotion. |
|
|
79
|
+
| `promotion` | `kargo_manage_freight` | Write / Destructive | `confirm` (delete) | Update Freight alias (`set_alias`), manually assemble Freight (`create`), or delete unused Freight (`delete`). |
|
|
80
|
+
| `verification` | `kargo_apply_analysis_template` | Write | `dry_run=True` | Create/update an `AnalysisTemplate` or `ClusterAnalysisTemplate`. |
|
|
81
|
+
| `verification` | `kargo_manage_verification` | Write / Destructive | `confirm` (abort / delete) | Trigger `reverify`, `abort` active Stage verification, or `delete_template`. |
|
|
82
|
+
| `credentials` | `kargo_manage_credentials` | Write / Destructive | `confirm` (delete) | Create, update, or delete `repo`/`generic`/`configmap` credentials across `project`/`shared`/`system` scopes using `secret_ref`. |
|
|
83
|
+
| `rbac` | `kargo_manage_roles` | Write / Destructive | `confirm` (delete / revoke) | Create/delete Kargo RBAC Roles or grant/revoke OIDC claims and stage `promote` permissions. |
|
|
84
|
+
| `diagnostics` | `kargo_trace_freight` | **Read-Only (N-to-1)** | None | Trace a Freight or artifact across the entire Stage DAG, surfacing upstream verification and soak-time blockers. |
|
|
85
|
+
| `diagnostics` | `kargo_diagnose_stage` | **Read-Only (N-to-1)** | None | Correlate Stage health, Promotion step errors, Verification AnalysisRuns, holds, and Warning events into diagnosis codes. |
|
|
86
|
+
| `diagnostics` | `kargo_diagnose_warehouse` | **Read-Only (N-to-1)** | None | Diagnose Warehouse artifact discovery, conditions, and deprecated Kargo v1.7–v1.12 subscription fields. |
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Live MCP Resources (18 URIs)
|
|
91
|
+
|
|
92
|
+
| URI | Description |
|
|
93
|
+
|-----|-------------|
|
|
94
|
+
| `kargo://server/capabilities` | Server write mode (`allow_write`), enabled toolsets, Kargo API connectivity, and version |
|
|
95
|
+
| `kargo://projects` | List all Kargo Projects with readiness status |
|
|
96
|
+
| `kargo://projects/{project}` | Project status and `ProjectConfig` (`promotionPolicies`, `webhookReceivers`, generated webhook URLs) |
|
|
97
|
+
| `kargo://projects/{project}/pipeline` | Complete pipeline DAG topology (`Warehouses -> Stages`), current Freight, health, auto-promotion, and holds |
|
|
98
|
+
| `kargo://projects/{project}/events` | Recent Kubernetes Events in the project |
|
|
99
|
+
| `kargo://projects/{project}/roles` | Kargo RBAC Roles, OIDC claim bindings, and permissions |
|
|
100
|
+
| `kargo://projects/{project}/stages/{stage}` | Detailed Stage status, `freightHistory`, `currentPromotion`, verification history, and `autoPromotionHolds` |
|
|
101
|
+
| `kargo://projects/{project}/stages/{stage}/manifest` | Sanitized Stage YAML manifest |
|
|
102
|
+
| `kargo://projects/{project}/warehouses/{warehouse}` | Warehouse subscriptions, `discoveredArtifacts`, and conditions |
|
|
103
|
+
| `kargo://projects/{project}/freight/{freight_or_alias}` | Detailed Freight resource (by SHA-1 ID or alias) with commits, images, charts, and stage states |
|
|
104
|
+
| `kargo://projects/{project}/promotions` | Recent Promotions summary list in the project |
|
|
105
|
+
| `kargo://projects/{project}/promotions/{promotion}` | Detailed Promotion status and per-step `stepExecutionMetadata` |
|
|
106
|
+
| `kargo://projects/{project}/promotion-tasks/{task}` | Project-scoped `PromotionTask` specification |
|
|
107
|
+
| `kargo://cluster-promotion-tasks/{task}` | Cluster-scoped `ClusterPromotionTask` specification |
|
|
108
|
+
| `kargo://projects/{project}/analysis-templates` | Project `AnalysisTemplates` and shared `ClusterAnalysisTemplates` |
|
|
109
|
+
| `kargo://projects/{project}/analysis-runs/{run}` | Verification `AnalysisRun` status and metric results |
|
|
110
|
+
| `kargo://projects/{project}/analysis-runs/{run}/logs` | Verification `AnalysisRun` job metric logs |
|
|
111
|
+
| `kargo://projects/{project}/credentials` | Redacted repository credentials, generic secrets, and ConfigMaps (`redacted: true`) |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## CLI Flags & Environment Variables
|
|
116
|
+
|
|
117
|
+
By default, `kargo-mcp-server` starts in **read-only mode** (`allow_write=False`) over **stdio** transport. Both `stdio` and `http` (`streamable-http`) transports are supported.
|
|
118
|
+
|
|
119
|
+
| CLI Flag | Environment Variable | Default | Description |
|
|
120
|
+
|----------|----------------------|---------|-------------|
|
|
121
|
+
| `--transport {stdio,http,streamable-http}` | `MCP_TRANSPORT` | `stdio` | MCP transport protocol (`streamable-http` normalizes to `http`) |
|
|
122
|
+
| `--host` | `MCP_HOST` | `0.0.0.0` | HTTP bind host |
|
|
123
|
+
| `--port` | `MCP_PORT` | `8766` | HTTP bind port |
|
|
124
|
+
| `--path` | `MCP_PATH` | `/mcp` | HTTP endpoint path |
|
|
125
|
+
| `--allow-write` | `MCP_ALLOW_WRITE` | `false` | Enable mutating and destructive tools |
|
|
126
|
+
| `--read-only` | `MCP_READ_ONLY` | `false` | Force read-only mode (overrides `--allow-write`) |
|
|
127
|
+
| `--toolsets` | `MCP_TOOLSETS` | `all` | Comma-separated toolsets (`all,readonly,pipeline,promotion,verification,credentials,rbac,diagnostics`) |
|
|
128
|
+
| `--kargo-url` | `KARGO_BASE_URL` | `http://localhost:8080` | Kargo API server base URL |
|
|
129
|
+
| `--auth-mode` | `KARGO_AUTH_MODE` | `admin` | Authentication mode (`admin`, `static`, `passthrough`) |
|
|
130
|
+
| `--project` | `KARGO_PROJECT` | `None` | Default Kargo project name |
|
|
131
|
+
| `--insecure-skip-tls-verify` | `KARGO_VERIFY_SSL` | `true` | Verify Kargo API TLS certificates |
|
|
132
|
+
| — | `KARGO_ADMIN_PASSWORD` | `None` | Admin password when `KARGO_AUTH_MODE=admin` |
|
|
133
|
+
| — | `KARGO_STATIC_BEARER_TOKEN` | `None` | Bearer token when `KARGO_AUTH_MODE=static` |
|
|
134
|
+
| — | `KARGO_CRED_<REF>_USERNAME` / `_PASSWORD` | `None` | Server-side secret material referenced by `secret_ref` |
|
|
135
|
+
| — | `KARGO_CREDENTIALS_FILE` | `None` | Path to server-side YAML/JSON credentials map |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Migration Guide (`v0.1.0` → `v0.2.0`)
|
|
140
|
+
|
|
141
|
+
| Legacy `v0.1.0` Primitive | New `v0.2.0` Replacement |
|
|
142
|
+
|---------------------------|--------------------------|
|
|
143
|
+
| `kargo_project_mgmt(action="list"\|"get")` | Read `kargo://projects` or `kargo://projects/{project}` |
|
|
144
|
+
| `kargo_project_mgmt(action="create"\|"delete")` | `kargo_manage_project(action="create"\|"delete", ...)` |
|
|
145
|
+
| `kargo_project_mgmt(promotion_policies=...)` | `kargo_apply_project_config(project=..., promotion_policies=...)` |
|
|
146
|
+
| `kargo_warehouse_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/pipeline` or `kargo://projects/{project}/warehouses/{warehouse}` |
|
|
147
|
+
| `kargo_warehouse_mgmt(action="create"\|"update")` | `kargo_apply_warehouse(...)` |
|
|
148
|
+
| `kargo_warehouse_mgmt(action="refresh")` | `kargo_refresh(project=..., kind="warehouse", name=...)` |
|
|
149
|
+
| `kargo_warehouse_mgmt(action="delete")` | `kargo_delete_resource(project=..., kind="Warehouse", name=...)` |
|
|
150
|
+
| `kargo_stage_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/pipeline` or `kargo://projects/{project}/stages/{stage}` |
|
|
151
|
+
| `kargo_stage_mgmt(action="create"\|"update")` | `kargo_apply_stage(...)` |
|
|
152
|
+
| `kargo_stage_mgmt(action="refresh")` | `kargo_refresh(project=..., kind="stage", name=...)` |
|
|
153
|
+
| `kargo_stage_mgmt(action="reverify"\|"abort_verification")` | `kargo_manage_verification(action="reverify"\|"abort", ...)` |
|
|
154
|
+
| `kargo_stage_mgmt(action="delete")` | `kargo_delete_resource(project=..., kind="Stage", name=...)` |
|
|
155
|
+
| `kargo_describe_topology` | Read `kargo://projects/{project}/pipeline` |
|
|
156
|
+
| `kargo_freight_mgmt(action="list"\|"get")` | `kargo_query_freight(...)` or read `kargo://projects/{project}/freight/{freight_or_alias}` |
|
|
157
|
+
| `kargo_freight_mgmt(action="approve")` | `kargo_approve_freight(...)` |
|
|
158
|
+
| `kargo_promotion_mgmt(action="promote"\|"promote_Subscribers")` | `kargo_promote(..., downstream=False\|True)` |
|
|
159
|
+
| `kargo_promotion_mgmt(action="abort")` | `kargo_manage_promotion(action="abort", ...)` |
|
|
160
|
+
| `kargo_promotion_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/promotions` or `kargo://projects/{project}/promotions/{promotion}` |
|
|
161
|
+
| `kargo_promotion_task_mgmt` | `kargo_apply_promotion_task` / `kargo_delete_resource(kind="PromotionTask")` / `kargo://projects/{project}/promotion-tasks/{task}` |
|
|
162
|
+
| `kargo_credentials_mgmt` | `kargo_manage_credentials` (with `secret_ref`) / `kargo://projects/{project}/credentials` |
|
|
163
|
+
| `kargo://best-practices`, `kargo://promotion-steps` | Agent Skills under `skills/*/SKILL.md` and `skills/*/references/*.md` |
|
|
164
|
+
| MCP Prompts (`kargo_onboard_project`, etc.) | Agent Skills under `skills/*/SKILL.md` |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Running Tests & Type Checking
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
uv run pytest -v
|
|
172
|
+
uv run pyright kargo_mcp_server tests skills
|
|
173
|
+
```
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Kargo MCP Server & Agent Skills (`v0.2.0`)
|
|
2
|
+
|
|
3
|
+
An Agent Plugin v1.0.0 package that pairs **5 Agent Skills** (`skills/<gerund>/SKILL.md`) with a **20-tool, 18-resource execution-only MCP server** for **Kargo v1.10+ (tested against v1.12.5)** progressive delivery pipelines.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Architecture: Skill & Execution Separation
|
|
8
|
+
|
|
9
|
+
Following the TalkOps **Skill & Execution Separation** specification:
|
|
10
|
+
|
|
11
|
+
1. **Reasoning Layer (`skills/*/SKILL.md`)**:
|
|
12
|
+
- Progressive-disclosure procedural workflows, GitOps step composition catalogs (61 Kargo v1.12 steps + `expr-lang` functions), diagnosis code runbooks, and offline deterministic Python helper scripts (`skills/*/scripts/*.py`).
|
|
13
|
+
- Zero MCP Prompts (`list_prompts() == []`) and zero static prose MCP Resources.
|
|
14
|
+
2. **Execution Data Plane (`kargo_mcp_server/`)**:
|
|
15
|
+
- **18 Live MCP Resources (`kargo://...`)**: Read-only cluster state, pipeline DAG topology, stage YAML manifests, promotion step traces, verification `AnalysisRun` logs, RBAC roles, and redacted credentials.
|
|
16
|
+
- **20 Execution Tools (`kargo_*`)**: Server-side filtering (`kargo_query_freight`), N-to-1 cross-resource correlation (`kargo_trace_freight`, `kargo_diagnose_stage`, `kargo_diagnose_warehouse`), and cluster mutations gated by `--allow-write`, `dry_run=True` previews, and MCP Elicitation / `confirm=True`.
|
|
17
|
+
- **Zero-Secret (`0->1`) Guarantee**: Credential tools never accept or return raw passwords, tokens, or private keys; secrets are resolved strictly on the server side via `secret_ref`.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Bundled Agent Skills (5)
|
|
22
|
+
|
|
23
|
+
| Skill Directory | Purpose | Companion References & Offline Scripts |
|
|
24
|
+
|-----------------|---------|----------------------------------------|
|
|
25
|
+
| `skills/onboarding-kargo-pipelines/` | Scaffolds Projects, ProjectConfigs, Warehouses, PromotionTasks, Stages, and Argo CD authorization | `references/warehouse-subscriptions.md`, `references/promotion-steps-catalog.md`, `references/argocd-integration.md`, `scripts/render_promotion_steps.py`, `scripts/validate_pipeline_manifests.py` |
|
|
26
|
+
| `skills/promoting-and-approving-freight/` | Evaluates Freight eligibility, approves Freight, promotes single stages or downstream subscribers, and manages verification gates | `references/promotion-gates.md` |
|
|
27
|
+
| `skills/rolling-back-kargo-stages/` | Executes emergency roll-forward Stage rollbacks from `freightHistory` and manages Kargo v1.11+ `autoPromotionHolds` | `references/rollback-sop.md` |
|
|
28
|
+
| `skills/troubleshooting-kargo-pipelines/` | Diagnoses Warehouse polling failures, Promotion step errors, Argo CD auth mismatches, and Verification failures | `references/diagnosis-catalog.md`, `scripts/summarize_promotion_failure.py` |
|
|
29
|
+
| `skills/managing-kargo-credentials-and-access/` | Manages repo/generic credentials via server-side `secret_ref`, shared credential replication, and Kargo RBAC roles/grants | `references/credentials-and-rbac.md` |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## MCP Tools (20 Tools across 6 Toolsets)
|
|
34
|
+
|
|
35
|
+
Every tool enforces `<= 8` parameters and carries explicit `ToolAnnotations`.
|
|
36
|
+
|
|
37
|
+
| Toolset | Tool Name | Mode | Default Gate | Description |
|
|
38
|
+
|---------|-----------|------|--------------|-------------|
|
|
39
|
+
| `pipeline` | `kargo_manage_project` | Write / Destructive | `dry_run=True` (create) / `confirm` (delete) | Create or delete a Kargo `Project` (`v1.7+` metadata-only). |
|
|
40
|
+
| `pipeline` | `kargo_apply_project_config` | Write | `dry_run=True` | Create/update `ProjectConfig` (`promotionPolicies`, `webhookReceivers`, `freightLinks`, `stageLinks`). |
|
|
41
|
+
| `pipeline` | `kargo_apply_warehouse` | Write | `dry_run=True` | Create/update `Warehouse` with Kargo v1.12 `constraint` and `allowTagsRegexes`/`ignoreTagsRegexes`. |
|
|
42
|
+
| `pipeline` | `kargo_apply_stage` | Write | `dry_run=True` | Create/update `Stage` (merging existing spec and validating DAG cycles). |
|
|
43
|
+
| `pipeline` | `kargo_apply_promotion_task` | Write | `dry_run=True` | Create/update `PromotionTask` or `ClusterPromotionTask` with Kargo v1.12 step validation. |
|
|
44
|
+
| `pipeline` | `kargo_delete_resource` | Destructive | `confirm` | Delete a `Stage`, `Warehouse`, `PromotionTask`, `ClusterPromotionTask`, or `ProjectConfig`. |
|
|
45
|
+
| `promotion` | `kargo_query_freight` | **Read-Only** | None | Query/filter Freight by stage availability, origin Warehouse, or alias. |
|
|
46
|
+
| `promotion` | `kargo_refresh` | Write | None | Trigger immediate reconciliation/discovery on a Warehouse, Stage, Promotion, ProjectConfig, or ClusterConfig. |
|
|
47
|
+
| `promotion` | `kargo_promote` | Write | `confirm` (when `downstream=True`) | Promote Freight to a Stage (by ID, alias, or `origin_warehouse`) or downstream subscribers via native REST API. |
|
|
48
|
+
| `promotion` | `kargo_rollback_stage` | Destructive (N-to-1) | `confirm` | Roll back a Stage to the previous verified Freight in `status.freightHistory` (and warn on v1.11+ holds). |
|
|
49
|
+
| `promotion` | `kargo_approve_freight` | Destructive | `confirm` | Manually approve Freight for a restricted Stage. |
|
|
50
|
+
| `promotion` | `kargo_manage_promotion` | Write / Destructive | `confirm` (abort) | Abort a running Promotion or refresh (wake) a Promotion. |
|
|
51
|
+
| `promotion` | `kargo_manage_freight` | Write / Destructive | `confirm` (delete) | Update Freight alias (`set_alias`), manually assemble Freight (`create`), or delete unused Freight (`delete`). |
|
|
52
|
+
| `verification` | `kargo_apply_analysis_template` | Write | `dry_run=True` | Create/update an `AnalysisTemplate` or `ClusterAnalysisTemplate`. |
|
|
53
|
+
| `verification` | `kargo_manage_verification` | Write / Destructive | `confirm` (abort / delete) | Trigger `reverify`, `abort` active Stage verification, or `delete_template`. |
|
|
54
|
+
| `credentials` | `kargo_manage_credentials` | Write / Destructive | `confirm` (delete) | Create, update, or delete `repo`/`generic`/`configmap` credentials across `project`/`shared`/`system` scopes using `secret_ref`. |
|
|
55
|
+
| `rbac` | `kargo_manage_roles` | Write / Destructive | `confirm` (delete / revoke) | Create/delete Kargo RBAC Roles or grant/revoke OIDC claims and stage `promote` permissions. |
|
|
56
|
+
| `diagnostics` | `kargo_trace_freight` | **Read-Only (N-to-1)** | None | Trace a Freight or artifact across the entire Stage DAG, surfacing upstream verification and soak-time blockers. |
|
|
57
|
+
| `diagnostics` | `kargo_diagnose_stage` | **Read-Only (N-to-1)** | None | Correlate Stage health, Promotion step errors, Verification AnalysisRuns, holds, and Warning events into diagnosis codes. |
|
|
58
|
+
| `diagnostics` | `kargo_diagnose_warehouse` | **Read-Only (N-to-1)** | None | Diagnose Warehouse artifact discovery, conditions, and deprecated Kargo v1.7–v1.12 subscription fields. |
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Live MCP Resources (18 URIs)
|
|
63
|
+
|
|
64
|
+
| URI | Description |
|
|
65
|
+
|-----|-------------|
|
|
66
|
+
| `kargo://server/capabilities` | Server write mode (`allow_write`), enabled toolsets, Kargo API connectivity, and version |
|
|
67
|
+
| `kargo://projects` | List all Kargo Projects with readiness status |
|
|
68
|
+
| `kargo://projects/{project}` | Project status and `ProjectConfig` (`promotionPolicies`, `webhookReceivers`, generated webhook URLs) |
|
|
69
|
+
| `kargo://projects/{project}/pipeline` | Complete pipeline DAG topology (`Warehouses -> Stages`), current Freight, health, auto-promotion, and holds |
|
|
70
|
+
| `kargo://projects/{project}/events` | Recent Kubernetes Events in the project |
|
|
71
|
+
| `kargo://projects/{project}/roles` | Kargo RBAC Roles, OIDC claim bindings, and permissions |
|
|
72
|
+
| `kargo://projects/{project}/stages/{stage}` | Detailed Stage status, `freightHistory`, `currentPromotion`, verification history, and `autoPromotionHolds` |
|
|
73
|
+
| `kargo://projects/{project}/stages/{stage}/manifest` | Sanitized Stage YAML manifest |
|
|
74
|
+
| `kargo://projects/{project}/warehouses/{warehouse}` | Warehouse subscriptions, `discoveredArtifacts`, and conditions |
|
|
75
|
+
| `kargo://projects/{project}/freight/{freight_or_alias}` | Detailed Freight resource (by SHA-1 ID or alias) with commits, images, charts, and stage states |
|
|
76
|
+
| `kargo://projects/{project}/promotions` | Recent Promotions summary list in the project |
|
|
77
|
+
| `kargo://projects/{project}/promotions/{promotion}` | Detailed Promotion status and per-step `stepExecutionMetadata` |
|
|
78
|
+
| `kargo://projects/{project}/promotion-tasks/{task}` | Project-scoped `PromotionTask` specification |
|
|
79
|
+
| `kargo://cluster-promotion-tasks/{task}` | Cluster-scoped `ClusterPromotionTask` specification |
|
|
80
|
+
| `kargo://projects/{project}/analysis-templates` | Project `AnalysisTemplates` and shared `ClusterAnalysisTemplates` |
|
|
81
|
+
| `kargo://projects/{project}/analysis-runs/{run}` | Verification `AnalysisRun` status and metric results |
|
|
82
|
+
| `kargo://projects/{project}/analysis-runs/{run}/logs` | Verification `AnalysisRun` job metric logs |
|
|
83
|
+
| `kargo://projects/{project}/credentials` | Redacted repository credentials, generic secrets, and ConfigMaps (`redacted: true`) |
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## CLI Flags & Environment Variables
|
|
88
|
+
|
|
89
|
+
By default, `kargo-mcp-server` starts in **read-only mode** (`allow_write=False`) over **stdio** transport. Both `stdio` and `http` (`streamable-http`) transports are supported.
|
|
90
|
+
|
|
91
|
+
| CLI Flag | Environment Variable | Default | Description |
|
|
92
|
+
|----------|----------------------|---------|-------------|
|
|
93
|
+
| `--transport {stdio,http,streamable-http}` | `MCP_TRANSPORT` | `stdio` | MCP transport protocol (`streamable-http` normalizes to `http`) |
|
|
94
|
+
| `--host` | `MCP_HOST` | `0.0.0.0` | HTTP bind host |
|
|
95
|
+
| `--port` | `MCP_PORT` | `8766` | HTTP bind port |
|
|
96
|
+
| `--path` | `MCP_PATH` | `/mcp` | HTTP endpoint path |
|
|
97
|
+
| `--allow-write` | `MCP_ALLOW_WRITE` | `false` | Enable mutating and destructive tools |
|
|
98
|
+
| `--read-only` | `MCP_READ_ONLY` | `false` | Force read-only mode (overrides `--allow-write`) |
|
|
99
|
+
| `--toolsets` | `MCP_TOOLSETS` | `all` | Comma-separated toolsets (`all,readonly,pipeline,promotion,verification,credentials,rbac,diagnostics`) |
|
|
100
|
+
| `--kargo-url` | `KARGO_BASE_URL` | `http://localhost:8080` | Kargo API server base URL |
|
|
101
|
+
| `--auth-mode` | `KARGO_AUTH_MODE` | `admin` | Authentication mode (`admin`, `static`, `passthrough`) |
|
|
102
|
+
| `--project` | `KARGO_PROJECT` | `None` | Default Kargo project name |
|
|
103
|
+
| `--insecure-skip-tls-verify` | `KARGO_VERIFY_SSL` | `true` | Verify Kargo API TLS certificates |
|
|
104
|
+
| — | `KARGO_ADMIN_PASSWORD` | `None` | Admin password when `KARGO_AUTH_MODE=admin` |
|
|
105
|
+
| — | `KARGO_STATIC_BEARER_TOKEN` | `None` | Bearer token when `KARGO_AUTH_MODE=static` |
|
|
106
|
+
| — | `KARGO_CRED_<REF>_USERNAME` / `_PASSWORD` | `None` | Server-side secret material referenced by `secret_ref` |
|
|
107
|
+
| — | `KARGO_CREDENTIALS_FILE` | `None` | Path to server-side YAML/JSON credentials map |
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Migration Guide (`v0.1.0` → `v0.2.0`)
|
|
112
|
+
|
|
113
|
+
| Legacy `v0.1.0` Primitive | New `v0.2.0` Replacement |
|
|
114
|
+
|---------------------------|--------------------------|
|
|
115
|
+
| `kargo_project_mgmt(action="list"\|"get")` | Read `kargo://projects` or `kargo://projects/{project}` |
|
|
116
|
+
| `kargo_project_mgmt(action="create"\|"delete")` | `kargo_manage_project(action="create"\|"delete", ...)` |
|
|
117
|
+
| `kargo_project_mgmt(promotion_policies=...)` | `kargo_apply_project_config(project=..., promotion_policies=...)` |
|
|
118
|
+
| `kargo_warehouse_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/pipeline` or `kargo://projects/{project}/warehouses/{warehouse}` |
|
|
119
|
+
| `kargo_warehouse_mgmt(action="create"\|"update")` | `kargo_apply_warehouse(...)` |
|
|
120
|
+
| `kargo_warehouse_mgmt(action="refresh")` | `kargo_refresh(project=..., kind="warehouse", name=...)` |
|
|
121
|
+
| `kargo_warehouse_mgmt(action="delete")` | `kargo_delete_resource(project=..., kind="Warehouse", name=...)` |
|
|
122
|
+
| `kargo_stage_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/pipeline` or `kargo://projects/{project}/stages/{stage}` |
|
|
123
|
+
| `kargo_stage_mgmt(action="create"\|"update")` | `kargo_apply_stage(...)` |
|
|
124
|
+
| `kargo_stage_mgmt(action="refresh")` | `kargo_refresh(project=..., kind="stage", name=...)` |
|
|
125
|
+
| `kargo_stage_mgmt(action="reverify"\|"abort_verification")` | `kargo_manage_verification(action="reverify"\|"abort", ...)` |
|
|
126
|
+
| `kargo_stage_mgmt(action="delete")` | `kargo_delete_resource(project=..., kind="Stage", name=...)` |
|
|
127
|
+
| `kargo_describe_topology` | Read `kargo://projects/{project}/pipeline` |
|
|
128
|
+
| `kargo_freight_mgmt(action="list"\|"get")` | `kargo_query_freight(...)` or read `kargo://projects/{project}/freight/{freight_or_alias}` |
|
|
129
|
+
| `kargo_freight_mgmt(action="approve")` | `kargo_approve_freight(...)` |
|
|
130
|
+
| `kargo_promotion_mgmt(action="promote"\|"promote_Subscribers")` | `kargo_promote(..., downstream=False\|True)` |
|
|
131
|
+
| `kargo_promotion_mgmt(action="abort")` | `kargo_manage_promotion(action="abort", ...)` |
|
|
132
|
+
| `kargo_promotion_mgmt(action="list"\|"get")` | Read `kargo://projects/{project}/promotions` or `kargo://projects/{project}/promotions/{promotion}` |
|
|
133
|
+
| `kargo_promotion_task_mgmt` | `kargo_apply_promotion_task` / `kargo_delete_resource(kind="PromotionTask")` / `kargo://projects/{project}/promotion-tasks/{task}` |
|
|
134
|
+
| `kargo_credentials_mgmt` | `kargo_manage_credentials` (with `secret_ref`) / `kargo://projects/{project}/credentials` |
|
|
135
|
+
| `kargo://best-practices`, `kargo://promotion-steps` | Agent Skills under `skills/*/SKILL.md` and `skills/*/references/*.md` |
|
|
136
|
+
| MCP Prompts (`kargo_onboard_project`, etc.) | Agent Skills under `skills/*/SKILL.md` |
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Running Tests & Type Checking
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
uv run pytest -v
|
|
144
|
+
uv run pyright kargo_mcp_server tests skills
|
|
145
|
+
```
|