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.
Files changed (116) hide show
  1. talkops_kargo_mcp_server-0.2.0/.dockerignore +85 -0
  2. talkops_kargo_mcp_server-0.2.0/.gitignore +15 -0
  3. talkops_kargo_mcp_server-0.2.0/.python-version +1 -0
  4. talkops_kargo_mcp_server-0.2.0/PKG-INFO +173 -0
  5. talkops_kargo_mcp_server-0.2.0/README.md +145 -0
  6. talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-Comprehensive.md +633 -0
  7. talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-Design.md +545 -0
  8. talkops_kargo_mcp_server-0.2.0/docs/kargo-research/Kargo-MCP-Internal-Impl.md +393 -0
  9. talkops_kargo_mcp_server-0.2.0/docs/kargo-research/interal-reference.md +976 -0
  10. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/APPROVAL_TEST_GUIDE.md +15 -0
  11. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/ONBOARDING_TEST_GUIDE.md +27 -0
  12. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/PROMOTION_TEST_GUIDE.md +16 -0
  13. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/ROLLBACK_TEST_GUIDE.md +15 -0
  14. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/TROUBLESHOOTING_TEST_GUIDE.md +17 -0
  15. talkops_kargo_mcp_server-0.2.0/docs/workflow-docs/WORKFLOW_JOURNEYS.md +94 -0
  16. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/__init__.py +3 -0
  17. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/config.py +290 -0
  18. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/exceptions/__init__.py +27 -0
  19. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/exceptions/custom.py +76 -0
  20. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/main.py +40 -0
  21. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/__init__.py +113 -0
  22. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/common.py +19 -0
  23. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/credentials.py +18 -0
  24. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/freight.py +204 -0
  25. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/project.py +112 -0
  26. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/promotion.py +91 -0
  27. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/promotion_task.py +26 -0
  28. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/schemas.py +267 -0
  29. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/stage.py +230 -0
  30. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/models/warehouse.py +93 -0
  31. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/__init__.py +29 -0
  32. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/base.py +22 -0
  33. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/credentials_resources.py +74 -0
  34. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/freight_resources.py +46 -0
  35. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/project_resources.py +168 -0
  36. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/promotion_resources.py +75 -0
  37. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/promotion_task_resources.py +47 -0
  38. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/registry.py +19 -0
  39. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/stage_resources.py +75 -0
  40. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/verification_resources.py +111 -0
  41. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/resources/warehouse_resources.py +51 -0
  42. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/__init__.py +9 -0
  43. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/bootstrap.py +51 -0
  44. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/core.py +32 -0
  45. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/server/middleware.py +135 -0
  46. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/services/__init__.py +7 -0
  47. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/services/kargo_service.py +1947 -0
  48. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/static/KARGO_MCP_INSTRUCTIONS.md +23 -0
  49. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/static/__init__.py +1 -0
  50. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/__init__.py +25 -0
  51. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/base.py +201 -0
  52. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/credentials/__init__.py +1 -0
  53. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/credentials/credentials_tools.py +145 -0
  54. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/diagnostics/__init__.py +1 -0
  55. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/diagnostics/diagnostics_tools.py +136 -0
  56. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/pipeline/__init__.py +5 -0
  57. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/pipeline/pipeline_tools.py +701 -0
  58. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/promotion/promotion_tools.py +801 -0
  59. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/rbac/__init__.py +5 -0
  60. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/rbac/rbac_tools.py +148 -0
  61. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/registry.py +37 -0
  62. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/verification/__init__.py +5 -0
  63. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/tools/verification/verification_tools.py +243 -0
  64. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/__init__.py +49 -0
  65. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/kargo_helpers.py +378 -0
  66. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/redaction.py +141 -0
  67. talkops_kargo_mcp_server-0.2.0/kargo_mcp_server/utils/warehouse_spec_builder.py +347 -0
  68. talkops_kargo_mcp_server-0.2.0/mcp.json +62 -0
  69. talkops_kargo_mcp_server-0.2.0/plugin.json +12 -0
  70. talkops_kargo_mcp_server-0.2.0/pyproject.toml +68 -0
  71. talkops_kargo_mcp_server-0.2.0/scripts/get_kargo_token.py +82 -0
  72. talkops_kargo_mcp_server-0.2.0/skills/managing-kargo-credentials-and-access/SKILL.md +35 -0
  73. talkops_kargo_mcp_server-0.2.0/skills/managing-kargo-credentials-and-access/references/credentials-and-rbac.md +56 -0
  74. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/SKILL.md +49 -0
  75. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/argocd-integration.md +41 -0
  76. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/promotion-steps-catalog.md +82 -0
  77. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/references/warehouse-subscriptions.md +92 -0
  78. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/scripts/render_promotion_steps.py +275 -0
  79. talkops_kargo_mcp_server-0.2.0/skills/onboarding-kargo-pipelines/scripts/validate_pipeline_manifests.py +179 -0
  80. talkops_kargo_mcp_server-0.2.0/skills/promoting-and-approving-freight/SKILL.md +35 -0
  81. talkops_kargo_mcp_server-0.2.0/skills/promoting-and-approving-freight/references/promotion-gates.md +55 -0
  82. talkops_kargo_mcp_server-0.2.0/skills/rolling-back-kargo-stages/SKILL.md +33 -0
  83. talkops_kargo_mcp_server-0.2.0/skills/rolling-back-kargo-stages/references/rollback-sop.md +35 -0
  84. talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/SKILL.md +33 -0
  85. talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/references/diagnosis-catalog.md +116 -0
  86. talkops_kargo_mcp_server-0.2.0/skills/troubleshooting-kargo-pipelines/scripts/summarize_promotion_failure.py +110 -0
  87. talkops_kargo_mcp_server-0.2.0/tests/__init__.py +1 -0
  88. talkops_kargo_mcp_server-0.2.0/tests/conftest.py +654 -0
  89. talkops_kargo_mcp_server-0.2.0/tests/fixtures/analysis-run-failed.json +19 -0
  90. talkops_kargo_mcp_server-0.2.0/tests/fixtures/pipeline-invalid.yaml +70 -0
  91. talkops_kargo_mcp_server-0.2.0/tests/fixtures/pipeline-valid.yaml +106 -0
  92. talkops_kargo_mcp_server-0.2.0/tests/fixtures/promotion-failed.json +27 -0
  93. talkops_kargo_mcp_server-0.2.0/tests/integration/__init__.py +1 -0
  94. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_dry_run_defaults.py +123 -0
  95. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_elicitation_and_confirm.py +71 -0
  96. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_error_is_error_flag.py +49 -0
  97. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_no_prompts_registered.py +18 -0
  98. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_resources_live_and_redacted.py +105 -0
  99. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_tool_schema_budgets.py +81 -0
  100. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_toolsets_and_readonly.py +56 -0
  101. talkops_kargo_mcp_server-0.2.0/tests/integration/test_mcp_workflows_e2e.py +249 -0
  102. talkops_kargo_mcp_server-0.2.0/tests/skills/__init__.py +1 -0
  103. talkops_kargo_mcp_server-0.2.0/tests/skills/test_plugin_and_mcp_manifest_schema.py +65 -0
  104. talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_frontmatter_and_budgets.py +69 -0
  105. talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_gate_markers.py +21 -0
  106. talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_scripts_offline_execution.py +148 -0
  107. talkops_kargo_mcp_server-0.2.0/tests/skills/test_skill_tool_and_resource_integrity.py +103 -0
  108. talkops_kargo_mcp_server-0.2.0/tests/unit/__init__.py +1 -0
  109. talkops_kargo_mcp_server-0.2.0/tests/unit/test_config_and_cli.py +65 -0
  110. talkops_kargo_mcp_server-0.2.0/tests/unit/test_diagnose_and_trace_service.py +215 -0
  111. talkops_kargo_mcp_server-0.2.0/tests/unit/test_error_translation.py +67 -0
  112. talkops_kargo_mcp_server-0.2.0/tests/unit/test_kargo_service_rest.py +370 -0
  113. talkops_kargo_mcp_server-0.2.0/tests/unit/test_middleware_caching_and_coercion.py +51 -0
  114. talkops_kargo_mcp_server-0.2.0/tests/unit/test_models_and_builders.py +176 -0
  115. talkops_kargo_mcp_server-0.2.0/tests/unit/test_redaction_and_sanitization.py +81 -0
  116. 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,15 @@
1
+ .cursor/
2
+ .venv/
3
+ .pytest_cache/
4
+ .mypy_cache/
5
+ .ruff_cache/
6
+ .vscode/
7
+ .idea/
8
+ .DS_Store/
9
+ .env
10
+ .env/
11
+ .env.local/
12
+ .env.development.local/
13
+ .env.test.local/
14
+ .env.production.local/
15
+ reference/
@@ -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
+ ```