causely-oss · enlinxu · Apr 22, 2026 · Apr 22, 2026
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -0,0 +1,25 @@
+{
+  "name": "causely",
+  "displayName": "Causely",
+  "version": "1.0.0",
+  "description": "Use Causely directly in Cursor through a preconfigured MCP server. Query service health, root causes, SLOs, metrics, and topology through natural conversation — grounded in system ontology and live causal intelligence.",
+  "author": {
+    "name": "Causely",
+    "email": "support@causely.ai"
+  },
+  "license": "Apache-2.0",
+  "logo": "logo.svg",
+  "homepage": "https://causely.ai",
+  "repository": "https://github.com/causely-oss/cursor-plugin",
+  "keywords": [
+    "causely",
+    "observability",
+    "kubernetes",
+    "root-cause-analysis",
+    "incidents",
+    "slo",
+    "causal-intelligence",
+    "ontology",
+    "reliability"
+  ]
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0 — 2026-04-22
+
+Initial release of the Causely Cursor Marketplace plugin.
+
+### What's included
+
+- MCP server connection to `https://api.causely.app/mcp` (Streamable HTTP)
+- Six packaged skills covering the most common Causely workflows:
+  - `causely-alert-triage` — map incoming alerts to root causes
+  - `causely-change-impact` — post-deploy regression and blast radius analysis
+  - `causely-correlated-incidents` — multi-service failure correlation
+  - `causely-health-reporting` — scheduled and on-demand health summaries
+  - `causely-k8s-investigation` — Kubernetes infrastructure deep-dives
+  - `causely-postmortem` — structured post-mortems and ticket drafts
+- OAuth 2.0 authorization code flow (browser sign-in via Causely)
+- API credentials fallback (`X-Causely-Client-Basic` header for non-interactive environments)
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Causely, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -1,2 +1,99 @@
-# cursor-plugin
-Cursor Marketplace plugin for Causely — system ontology and causal intelligence for application reliability
+# Causely for Cursor
+
+Use Causely directly in Cursor through a preconfigured MCP server. Query service health, root causes, SLOs, metrics, and topology through natural conversation — grounded in system ontology and live causal intelligence.
+
+## Prerequisites
+
+- A [Causely](https://causely.ai) account. Contact support@causely.ai if you need access.
+- Cursor with MCP support.
+
+## Installation
+
+Install via **Cursor Settings → Plugins**, search for **Causely**, and click **Install**. Cursor will prompt you to sign in to Causely and grant access.
+
+## Authentication
+
+### OAuth (recommended)
+
+Cursor initiates the OAuth flow automatically on install. Sign in to Causely once — Cursor manages token refresh from that point on.
+
+### API credentials
+
+For non-interactive or CI environments, generate API credentials at [auth.causely.app/oauth/portal/api-tokens](https://auth.causely.app/oauth/portal/api-tokens) and configure the server manually:
+
+```json
+{
+  "mcpServers": {
+    "causely": {
+      "url": "https://api.causely.app/mcp",
+      "transport": "Streamable HTTP",
+      "headers": {
+        "X-Causely-Client-Basic": "Basic <base64(client_id:client_secret)>"
+      }
+    }
+  }
+}
+```
+
+## What you can ask
+
+- "What's the root cause of the checkout service degradation?"
+- "Which services are burning their error budget?"
+- "What changed before this incident started?"
+- "Show me the blast radius of the database slowdown."
+- "Are there correlated failures across namespaces?"
+- "Write a post-mortem for the incident that resolved an hour ago."
+- "What are the top slow queries on the orders database?"
+- "Give me a morning health report for the production namespace."
+
+## Packaged skills
+
+This plugin includes six skills that activate automatically for the right type of question:
+
+| Skill | Activates for |
+|---|---|
+| `causely-alert-triage` | Incoming alerts — PagerDuty, Datadog, Prometheus, OpsGenie |
+| `causely-change-impact` | Post-deploy regression checks and rollout validation |
+| `causely-correlated-incidents` | Multi-service failures and blast radius analysis |
+| `causely-health-reporting` | Health summaries, SLO status, morning briefings |
+| `causely-k8s-investigation` | Kubernetes infrastructure — pods, nodes, namespaces |
+| `causely-postmortem` | Post-mortems, incident reports, and ticket drafts |
+
+## Available tools
+
+All tools are read-only. Causely does not execute changes through this connection.
+
+| Tool | Description |
+|---|---|
+| `get_environment_health` | Global health overview: active root causes, symptoms, status |
+| `get_root_causes` | Root causes with remediation, blast radius, and supporting symptoms |
+| `get_symptoms` | Raw observable signals feeding into root cause detection |
+| `triage` | Deep investigation of a single service |
+| `get_service_summary` | Comprehensive health summary for a service |
+| `get_entity_health` | Health for databases, pods, queues, and other entity types |
+| `team_health` | Health summary for all services owned by a team |
+| `get_metrics` | Time-series or snapshot metrics for any entity |
+| `get_logs` | Logs for an entity or evidence logs for a root cause |
+| `get_alerts` | Alert history with mapping state |
+| `get_events` | Lifecycle events: restarts, deployments, scaling, config changes |
+| `get_topology` | Dependency graph: upstream, downstream, or end-to-end dataflow |
+| `get_slo` | Error budget, burn rate, at-risk and violated SLOs |
+| `get_slow_queries` | Slow SQL queries ranked by total execution time |
+| `get_entities` | Resolve service and infrastructure entity names to IDs |
+| `get_scopes` | Discover available clusters, namespaces, customers, and products |
+| `get_label_values` | Enumerate distinct values for a label key (e.g. team, product) |
+| `list_namespaces` | List all Kubernetes namespace names |
+| `list_clusters` | List all cluster names |
+| `get_integration_status` | Scraper and integration status per cluster |
+| `get_config` | Raw configuration files for an entity |
+| `reliability_delta` | Post-deploy regression check for a single service |
+| `fleet_reliability_delta` | Post-deploy regression check across a team or namespace |
+| `postmortem` | Structured post-mortem draft from a resolved incident |
+| `generate_ticket` | Ticket draft for Jira, GitHub, or Linear from an incident |
+| `ask_causely` | Natural-language question answering (markdown response) |
+
+## Support
+
+Email: support@causely.ai
+Website: https://causely.ai
+Docs: https://docs.causely.ai/agent-integration/mcp-server
diff --git a/logo.svg b/logo.svg
diff --git a/mcp.json b/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "causely": {
+      "url": "https://api.causely.app/mcp",
+      "transport": "Streamable HTTP"
+    }
+  }
+}
diff --git a/skills/causely-alert-triage/SKILL.md b/skills/causely-alert-triage/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: causely-alert-triage
+description: >
+  Use this skill when the user is starting from an alert — they received a PagerDuty page, Datadog alert, Prometheus/Alertmanager notification, Slack alert, or OpsGenie notification and want to understand what it means. Trigger for questions like "I got paged for KubeContainerWaiting", "what does this alert mean?", "PagerDuty woke me up for high error rate on checkout", "Datadog says memory is high on X", "what alerts are firing on X?", "how many unmapped alerts do we have?", "is this alert noise or real?", "which alerts map to Causely symptoms?", or "audit alert noise". Also trigger when the user pastes an alert name, alert payload, or references an external alerting system. Use this skill over generic causely-mcp when the investigation starts from an alert rather than from a service name or health question.
+---
+
+# Causely Alert Triage Skill
+
+Read `references/complete-investigation.md` for the full 25-tool inventory and evidence strategy.
+
+---
+
+## Core tools for alert-driven triage
+
+| Tool | Use when | What it returns |
+|---|---|---|
+| `get_entities(query=, entity_types=)` | Resolve the service/entity from the alert | Entity IDs for the affected service |
+| `get_alerts(entity_ids=)` | See all alerts firing + mapping state | Alert name, symptom mapping, severity, count, timestamps |
+| `get_root_causes(symptom_ids=)` | Find diagnosed cause behind a mapped alert | Root causes with evidence, blast radius, remediation |
+| `triage(entity_name=)` | Quick full-picture health check | Root causes, symptoms, impact — all in one call |
+| `get_symptoms(entity_ids=)` | Check which alerts promoted to symptoms | Named signals in the causal graph |
+| `ask_causely(question=)` | Free-form query when alert name doesn't resolve | NL fallback for complex alert-to-cause questions |
+
+---
+
+## Core rule: alerts → entities → causes
+
+External alerting systems (PagerDuty, Datadog, Alertmanager) fire raw alert names. Causely maps some alerts to named symptoms in its causal model. The workflow bridges from alert → entity → mapped symptom → root cause.
+
+**`ask_causely` cannot resolve raw alert names.** Don't use it for "what is causing KubeContainerWaiting?" — use the structured workflow below.
+
+---
+
+## Decision tree
+
+**Alert received — service name known:**
+```
+triage(entity_name="<service>")                            ← 1 call
+  → if root causes found: that's likely what triggered the alert
+  → description = evidence, remediation = what to do
+  → done in most cases
+```
+
+If you need to see the specific alert and its mapping status:
+```
+get_entities(query="<service>", entity_types=["Service"])   ← 1 call
+get_alerts(entity_ids=[id], active_only=true)               ← 1 call
+  → find the alert by name
+  → mapping_state = "mapped" → Causely has incorporated it
+  → mapping_state = "unmapped" → Causely hasn't promoted it to a symptom
+  → if mapped: symptom_name → get_root_causes(symptom_ids=[...]) for cause
+```
+
+**Alert received — service name unknown:**
+```
+ask_causely("What active root causes are there right now?")  ← 1 call
+  → scan results for the alert pattern or affected service
+  → then triage the identified service
+```
+
+**Alert name known, want to check if Causely knows about it:**
+```
+get_entities(query="<service>")                             ← 1 call
+get_alerts(entity_ids=[id], alert_name_filters=["<alert-name>"])  ← 1 call
+  → mapping_state tells you if Causely has incorporated this alert
+  → if mapped: follow symptom_name → root cause chain
+  → if unmapped: alert is noise or not yet incorporated
+```
+
+**Alert noise audit ("how noisy are our alerts?"):**
+```
+get_entities(query="<service>")                             ← 1 call
+get_alerts(entity_ids=[id], mapping_state_filters=["unmapped"])  ← 1 call
+  → high-count unmapped alerts = noise candidates for tuning
+  → compare with get_alerts(mapping_state_filters=["mapped"]) for signal-to-noise
+```
+
+**Multiple alerts firing at once:**
+```
+get_root_causes(active_only=true)                           ← 1 call
+  → check if multiple alerts map to the same root cause
+  → impact_service_graph shows propagation → many alerts, one origin
+```
+
+---
+
+## Mapping state guide
+
+| mapping_state | Meaning | Action |
+|---|---|---|
+| `mapped` | Causely has promoted this alert to a named symptom | Follow `symptom_name` → `get_root_causes(symptom_ids=)` for diagnosis |
+| `unmapped` | Causely hasn't incorporated this alert | May be noise, or a new signal type not yet configured |
+
+---
+
+## Output format
+
+### 🔔 Alert triage: [alert name]
+
+**Alert:** [alert_name from get_alerts or user's description]
+**Service:** [entity name]
+**Status:** [firing / resolved] · **Severity:** [from alert]
+**Causely mapping:** ✅ Mapped to symptom "[symptom_name]" / ❌ Unmapped
+
+**Root cause:** [from triage or get_root_causes — name + entity + portal link]
+
+**Evidence:** [from description field]
+
+**Blast radius:** [from impacted_services]
+
+**Customer impact:** [from impacted_customers]
+
+**Owner:** [from causely.ai/team label]
+
+**Recommended actions:** [from remediation field]
+
+**Links:** [portal links]
+
+---
+
+## Important behaviours
+
+- **Start with `triage` when you have a service name.** It's faster and gives the full picture without needing to resolve alert → symptom → root cause manually.
+- **Use `get_alerts` when the user specifically wants to see alert-level detail** — mapping status, alert counts, firing times.
+- **Don't use `ask_causely` for alert name resolution** — it can't resolve raw Alertmanager or Datadog alert names to Causely entities.
+- **Unmapped ≠ irrelevant**: an unmapped alert might be a real signal that Causely hasn't been configured to ingest yet. Don't dismiss it.
+- **Multiple alerts, one cause**: when the user reports several alerts, check `get_root_causes` first — they often share a single origin visible in the impact graph.