carto-md 2.0.9 → 2.1.0

package/docs/api/README.md

@@ -0,0 +1,99 @@
+# Carto MCP Tools — API Reference
+
+Auto-generated from `src/mcp/server.js`. Re-run `node scripts/gen-api-docs.js` after adding tools.
+
+**76 tools** across 8 categories.
+
+## Categories
+
+### Core graph (16)
+- [`get_routes`](./get_routes.md)
+- [`get_blast_radius`](./get_blast_radius.md)
+- [`get_structure`](./get_structure.md)
+- [`get_domain`](./get_domain.md)
+- [`get_neighbors`](./get_neighbors.md)
+- [`get_cross_domain`](./get_cross_domain.md)
+- [`get_context`](./get_context.md)
+- [`search_routes`](./search_routes.md)
+- [`get_models`](./get_models.md)
+- [`get_high_impact_files`](./get_high_impact_files.md)
+- [`get_env_vars`](./get_env_vars.md)
+- [`get_domains_list`](./get_domains_list.md)
+- [`get_file_summary`](./get_file_summary.md)
+- [`get_change_plan`](./get_change_plan.md)
+- [`get_similar_patterns`](./get_similar_patterns.md)
+- [`simulate_change_impact`](./simulate_change_impact.md)
+
+### Episodic Memory (5)
+- [`validate_diff`](./validate_diff.md)
+- [`get_recent_decisions`](./get_recent_decisions.md)
+- [`get_session_context`](./get_session_context.md)
+- [`did_we_discuss_this`](./did_we_discuss_this.md)
+- [`get_intervention_history`](./get_intervention_history.md)
+
+### Temporal (9)
+- [`get_architecture`](./get_architecture.md)
+- [`get_architectural_drift`](./get_architectural_drift.md)
+- [`get_domain_evolution`](./get_domain_evolution.md)
+- [`get_hotspot_files`](./get_hotspot_files.md)
+- [`get_complexity_trend`](./get_complexity_trend.md)
+- [`get_churn_vs_blast_radius`](./get_churn_vs_blast_radius.md)
+- [`get_arch_events`](./get_arch_events.md)
+- [`get_domain_health`](./get_domain_health.md)
+- [`get_temporal_context`](./get_temporal_context.md)
+
+### Brain (10)
+- [`get_invariants`](./get_invariants.md)
+- [`get_canonical_pattern`](./get_canonical_pattern.md)
+- [`get_conventions`](./get_conventions.md)
+- [`get_action_patterns`](./get_action_patterns.md)
+- [`scaffold_for_intent`](./scaffold_for_intent.md)
+- [`get_working_memory`](./get_working_memory.md)
+- [`get_pending_decisions`](./get_pending_decisions.md)
+- [`get_active_drift`](./get_active_drift.md)
+- [`get_active_suggestions`](./get_active_suggestions.md)
+- [`dismiss_suggestion`](./dismiss_suggestion.md)
+
+### AI-native (14)
+- [`get_minimal_context_for_intent`](./get_minimal_context_for_intent.md)
+- [`get_progressive_disclosure_tree`](./get_progressive_disclosure_tree.md)
+- [`get_token_budget_report`](./get_token_budget_report.md)
+- [`get_decision_log`](./get_decision_log.md)
+- [`get_evolution_delta`](./get_evolution_delta.md)
+- [`get_change_velocity`](./get_change_velocity.md)
+- [`get_test_coverage_map`](./get_test_coverage_map.md)
+- [`get_safety_checklist`](./get_safety_checklist.md)
+- [`get_data_flow`](./get_data_flow.md)
+- [`get_interface_contract`](./get_interface_contract.md)
+- [`explain_change_in_natural_language`](./explain_change_in_natural_language.md)
+- [`get_stale_docs`](./get_stale_docs.md)
+- [`get_dependency_surface`](./get_dependency_surface.md)
+- [`get_upgrade_risk`](./get_upgrade_risk.md)
+
+### Adjacent (8)
+- [`get_cross_language_call_graph`](./get_cross_language_call_graph.md)
+- [`get_iac_resources`](./get_iac_resources.md)
+- [`ingest_otlp_traces`](./ingest_otlp_traces.md)
+- [`get_risk_weighted_blast_radius`](./get_risk_weighted_blast_radius.md)
+- [`get_dead_code_with_confidence`](./get_dead_code_with_confidence.md)
+- [`get_hot_in_prod_no_tests`](./get_hot_in_prod_no_tests.md)
+- [`get_semantic_diff`](./get_semantic_diff.md)
+- [`get_llm_enrichment`](./get_llm_enrichment.md)
+
+### Predictive (7)
+- [`get_predictive_risk`](./get_predictive_risk.md)
+- [`get_microservice_cut_points`](./get_microservice_cut_points.md)
+- [`validate_change`](./validate_change.md)
+- [`get_file_ownership`](./get_file_ownership.md)
+- [`get_cross_team_coupling`](./get_cross_team_coupling.md)
+- [`get_drift_digest`](./get_drift_digest.md)
+- [`get_ai_cost_attribution`](./get_ai_cost_attribution.md)
+
+### Org-wide (7)
+- [`get_org_architecture`](./get_org_architecture.md)
+- [`get_service_dependency_graph`](./get_service_dependency_graph.md)
+- [`get_cross_repo_blast_radius`](./get_cross_repo_blast_radius.md)
+- [`find_consumers_of_api`](./find_consumers_of_api.md)
+- [`get_org_domain_mapping`](./get_org_domain_mapping.md)
+- [`get_service_boundary_violations`](./get_service_boundary_violations.md)
+- [`get_microservices_migration_cut_points`](./get_microservices_migration_cut_points.md)

package/docs/api/did_we_discuss_this.md

@@ -0,0 +1,34 @@
+# `did_we_discuss_this`
+
+Substring search over the episodic memory log (decisions + interventions) for prior discussions of a topic. Use to avoid re-deciding settled questions.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "description": "Topic to search for, e.g. \"auth\", \"snake_case\", \"blast radius\"."
+    }
+  },
+  "required": [
+    "topic"
+  ]
+}
+```
+
+## Required arguments
+
+- `topic`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `topic` | string | Topic to search for, e.g. "auth", "snake_case", "blast radius". |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/dismiss_suggestion.md

@@ -0,0 +1,34 @@
+# `dismiss_suggestion`
+
+Mark a suggestion ID as dismissed for the current session. Acknowledgment-only; the underlying signal still exists.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Suggestion id from get_active_suggestions."
+    }
+  },
+  "required": [
+    "id"
+  ]
+}
+```
+
+## Required arguments
+
+- `id`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | string | Suggestion id from get_active_suggestions. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/explain_change_in_natural_language.md

@@ -0,0 +1,33 @@
+# `explain_change_in_natural_language`
+
+Given a unified diff, returns a plain-language summary + risk + violation list + suggestions. Powered by validate_diff.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "diff": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "diff"
+  ]
+}
+```
+
+## Required arguments
+
+- `diff`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `diff` | string |  |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/find_consumers_of_api.md

@@ -0,0 +1,34 @@
+# `find_consumers_of_api`
+
+Across all org repos, find every file importing a given npm/pypi/go/maven target.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "Target package or module name"
+    }
+  },
+  "required": [
+    "target"
+  ]
+}
+```
+
+## Required arguments
+
+- `target`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | string | Target package or module name |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_action_patterns.md

@@ -0,0 +1,32 @@
+# `get_action_patterns`
+
+Procedural patterns mined from git history: "when developers add X, they also touch Y". Filter by natural-language intent.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Optional intent filter (e.g. \"add route\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Optional intent filter (e.g. "add route"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_active_drift.md

@@ -0,0 +1,32 @@
+# `get_active_drift`
+
+Domains with active drift in the last 7d: growth, threshold breaches. Use to spot domains drifting before they reach a critical event.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "threshold": {
+      "type": "number",
+      "description": "Drift threshold 0-1 (default 0.2 = 20%)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `threshold` | number | Drift threshold 0-1 (default 0.2 = 20%). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_active_suggestions.md

@@ -0,0 +1,25 @@
+# `get_active_suggestions`
+
+Active Suggestion Engine output. 4 triggers: cross-domain coupling jump, AI session conflict, convention violation mid-session, hotspot threshold crossed. Read periodically.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_ai_cost_attribution.md

@@ -0,0 +1,32 @@
+# `get_ai_cost_attribution`
+
+Per-AI-client decision counts + violation counts. Use to attribute cross-domain coupling cost to individual AI sessions / developers.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "hours": {
+      "type": "number",
+      "description": "Lookback hours (default 168 = 7d)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hours` | number | Lookback hours (default 168 = 7d). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_arch_events.md

@@ -0,0 +1,42 @@
+# `get_arch_events`
+
+Architectural events (domain split, merge, growth, hotspot emergence). Severity filter: minor | major | critical.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "severity": {
+      "type": "string",
+      "description": "Filter: minor | major | critical."
+    },
+    "kind": {
+      "type": "string",
+      "description": "Optional kind filter (e.g. domain_growth, hotspot_active)."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"90d\" (default \"90d\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `severity` | string | Filter: minor \| major \| critical. |
+| `kind` | string | Optional kind filter (e.g. domain_growth, hotspot_active). |
+| `time_range` | string | Window like "90d" (default "90d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_architectural_drift.md

@@ -0,0 +1,37 @@
+# `get_architectural_drift`
+
+Per-domain growth/shrink and event count over a time window. Run `carto temporal init` first to backfill from git history.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "domain": {
+      "type": "string",
+      "description": "Optional domain filter (e.g. AUTH)."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"30d\", \"90d\", \"1y\" (default \"30d\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `domain` | string | Optional domain filter (e.g. AUTH). |
+| `time_range` | string | Window like "30d", "90d", "1y" (default "30d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_architecture.md

@@ -0,0 +1,25 @@
+# `get_architecture`
+
+Get a 500-word markdown summary of the project: domains, entry points, tech stack, key patterns, and size metrics. Use this as your first call when entering a new repo.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+_None._
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_blast_radius.md

@@ -0,0 +1,34 @@
+# `get_blast_radius`
+
+Get all files, routes, and domains affected by changing a specific file. Includes risk level per route.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Relative file path from project root"
+    }
+  },
+  "required": [
+    "file"
+  ]
+}
+```
+
+## Required arguments
+
+- `file`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string | Relative file path from project root |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_canonical_pattern.md

@@ -0,0 +1,39 @@
+# `get_canonical_pattern`
+
+Highest-quality example of a pattern in the codebase (e.g. canonical route handler). Use as a copy-paste template before writing similar code.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "pattern_type": {
+      "type": "string",
+      "description": "route_handler | model_definition"
+    },
+    "domain": {
+      "type": "string",
+      "description": "Optional domain filter."
+    }
+  },
+  "required": [
+    "pattern_type"
+  ]
+}
+```
+
+## Required arguments
+
+- `pattern_type`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pattern_type` | string | route_handler \| model_definition |
+| `domain` | string | Optional domain filter. |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_change_plan.md

@@ -0,0 +1,34 @@
+# `get_change_plan`
+
+Given a natural-language intent (e.g. "add rate limiting to /api/users"), returns: files to touch, domains affected, blast radius, and similar patterns in the codebase.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "intent": {
+      "type": "string",
+      "description": "Natural language description of the change you want to make"
+    }
+  },
+  "required": [
+    "intent"
+  ]
+}
+```
+
+## Required arguments
+
+- `intent`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `intent` | string | Natural language description of the change you want to make |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_change_velocity.md

@@ -0,0 +1,32 @@
+# `get_change_velocity`
+
+Commits-per-day over a window (requires temporal store). Useful for spotting development tempo shifts.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "days": {
+      "type": "number",
+      "description": "Lookback days (default 30)."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `days` | number | Lookback days (default 30). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_churn_vs_blast_radius.md

@@ -0,0 +1,32 @@
+# `get_churn_vs_blast_radius`
+
+Scatter data of churn vs blast_radius for every changed file in a window. Use to find risk hotspots.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"90d\" (default \"90d\")."
+    }
+  },
+  "required": []
+}
+```
+
+## Required arguments
+
+_None._
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `time_range` | string | Window like "90d" (default "90d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)

package/docs/api/get_complexity_trend.md

@@ -0,0 +1,39 @@
+# `get_complexity_trend`
+
+A single file's presence across snapshots + commit count + current blast_radius. Use to track how a file's footprint evolved.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file": {
+      "type": "string",
+      "description": "Relative file path."
+    },
+    "time_range": {
+      "type": "string",
+      "description": "Window like \"90d\" (default \"90d\")."
+    }
+  },
+  "required": [
+    "file"
+  ]
+}
+```
+
+## Required arguments
+
+- `file`
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `file` | string | Relative file path. |
+| `time_range` | string | Window like "90d" (default "90d"). |
+
+## See also
+
+- [Index of all MCP tools](./README.md)