Skip to content

Commit a160eca

Browse files
viragtripathiviragtripathi
committed
feat: add Cloud MCP and ccloud CLI GA support, replace skill symlinks with real directories
 - Update mcp.json: cockroachdb-cloud backend with mcp-cluster-id header, remove stale ccloud entry - Replace skills symlink with 29 real directories from latest upstream submodule (7f13257) - Add Available MCP Tools section to all 4 rules (sql, app, developer, operator patterns) - Update README with Cloud MCP and ccloud CLI GA documentation, tool tables, OAuth/API key examples - Add weekly CI workflow to sync upstream cockroachdb-skills changes
1 parent b659aee commit a160eca

99 files changed

Lines changed: 27260 additions & 38 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/update-skills.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
name: Update cockroachdb-skills submodule
2+
3+
on:
4+
schedule:
5+
- cron: '0 9 * * 1' # Weekly on Monday at 9am UTC
6+
workflow_dispatch: # Allow manual trigger
7+
8+
permissions:
9+
contents: write
10+
pull-requests: write
11+
12+
jobs:
13+
check-update:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
submodules: true
19+
fetch-depth: 0
20+
21+
- name: Check for upstream updates
22+
id: check
23+
run: |
24+
cd submodules/cockroachdb-skills
25+
CURRENT=$(git rev-parse HEAD)
26+
git fetch origin main
27+
LATEST=$(git rev-parse origin/main)
28+
echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
29+
echo "latest=$LATEST" >> "$GITHUB_OUTPUT"
30+
if [ "$CURRENT" != "$LATEST" ]; then
31+
echo "behind=true" >> "$GITHUB_OUTPUT"
32+
COMMITS=$(git log --oneline "$CURRENT..$LATEST" | wc -l | tr -d ' ')
33+
echo "commits=$COMMITS" >> "$GITHUB_OUTPUT"
34+
git log --oneline "$CURRENT..$LATEST" > /tmp/changelog.txt
35+
echo "changelog<<EOF" >> "$GITHUB_OUTPUT"
36+
cat /tmp/changelog.txt >> "$GITHUB_OUTPUT"
37+
echo "EOF" >> "$GITHUB_OUTPUT"
38+
else
39+
echo "behind=false" >> "$GITHUB_OUTPUT"
40+
fi
41+
42+
- name: Update submodule
43+
if: steps.check.outputs.behind == 'true'
44+
run: |
45+
cd submodules/cockroachdb-skills
46+
git checkout origin/main
47+
48+
- name: Sync skills from submodule
49+
if: steps.check.outputs.behind == 'true'
50+
run: |
51+
# Build list of upstream skill names
52+
upstream_skills=""
53+
for skill_dir in submodules/cockroachdb-skills/skills/*/; do
54+
for skill in "$skill_dir"*/; do
55+
if [ -f "$skill/SKILL.md" ]; then
56+
skill_name=$(basename "$skill")
57+
upstream_skills="$upstream_skills $skill_name"
58+
59+
# Copy new or updated skills
60+
if [ -d "skills/$skill_name" ]; then
61+
rm -rf "skills/$skill_name"
62+
cp -r "$skill" "skills/$skill_name"
63+
echo "Updated: $skill_name"
64+
else
65+
cp -r "$skill" "skills/$skill_name"
66+
echo "Added: $skill_name"
67+
fi
68+
fi
69+
done
70+
done
71+
72+
# Remove skills that no longer exist upstream
73+
for existing in skills/*/; do
74+
existing_name=$(basename "$existing")
75+
if ! echo "$upstream_skills" | grep -qw "$existing_name"; then
76+
rm -rf "skills/$existing_name"
77+
echo "Removed (no longer upstream): $existing_name"
78+
fi
79+
done
80+
81+
echo "Total skills: $(ls -d skills/*/ 2>/dev/null | wc -l | tr -d ' ')"
82+
83+
- name: Create Pull Request
84+
if: steps.check.outputs.behind == 'true'
85+
uses: peter-evans/create-pull-request@v7
86+
with:
87+
commit-message: "chore: update cockroachdb-skills submodule"
88+
title: "chore: update cockroachdb-skills submodule (${{ steps.check.outputs.commits }} new commits)"
89+
body: |
90+
Updates `cockroachdb-skills` submodule from `${{ steps.check.outputs.current }}` to `${{ steps.check.outputs.latest }}`.
91+
92+
### Upstream changes
93+
```
94+
${{ steps.check.outputs.changelog }}
95+
```
96+
97+
This PR was auto-generated by the [update-skills](${{ github.server_url }}/${{ github.repository }}/actions/workflows/update-skills.yml) workflow.
98+
branch: chore/update-cockroachdb-skills
99+
delete-branch: true
100+
labels: dependencies,automated

‎README.md‎

Lines changed: 144 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -39,43 +39,159 @@ export COCKROACHDB_DATABASE="your-database"
3939

4040
For CockroachDB Cloud, find connection details in the [Cloud Console](https://cockroachlabs.cloud/).
4141

42+
## MCP Backends
43+
44+
<details>
45+
<summary><strong>MCP Toolbox</strong> (self-hosted, any cluster) — Default</summary>
46+
47+
Connect to any CockroachDB cluster (Cloud, self-hosted, local) via [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox).
48+
49+
**Install:** `brew install mcp-toolbox` (v0.27.0+)
50+
51+
**Run (stdio, default):** `toolbox --tools-file tools.yaml --stdio`
52+
53+
**Run (HTTP):** `toolbox --tools-file tools.yaml --address 0.0.0.0:5000`
54+
</details>
55+
56+
<details>
57+
<summary><strong>ccloud CLI</strong> (cluster lifecycle, backups, DR, networking)</summary>
58+
59+
The [`ccloud` CLI](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/) is an agent-ready command-line tool for full cluster lifecycle management. AI agents call ccloud directly via shell commands (not MCP protocol) -- every command supports `-o json` for structured output.
60+
61+
**Install:** `brew install cockroachdb/tap/ccloud`
62+
63+
**Authenticate (interactive):** `ccloud auth login` (opens browser; supports SSO via OIDC/SAMLv2)
64+
65+
**Authenticate (org-scoped):** `ccloud auth login --org {organization-label}`
66+
67+
**Authenticate (headless/CI):** `ccloud auth login --no-redirect` or use a service account API key as a bearer token.
68+
69+
**Example agent commands:**
70+
```bash
71+
# Provision
72+
ccloud cluster create serverless my-cluster us-east-1 --cloud AWS -o json
73+
ccloud cluster database create my-cluster myapp -o json
74+
75+
# Connect
76+
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json
77+
# Composable: pipe into jq + psql
78+
ccloud cluster connection-string my-cluster --database myapp --sql-user maxroach -o json \
79+
| jq -r '.connection_url' | xargs -I{} psql {} -c "SELECT count(*) FROM users"
80+
81+
# Operate
82+
ccloud cluster list -o json
83+
ccloud cluster info my-cluster -o json
84+
ccloud cluster backup config update my-cluster --frequency 60 --retention 60
85+
86+
# Observe
87+
ccloud audit list --limit 10 -o json
88+
ccloud cluster versions -o json
89+
ccloud cluster cmek get my-cluster -o json
90+
91+
# Scale & DR
92+
ccloud replication create --primary-cluster prod-east --standby-cluster dr-west
93+
ccloud cluster networking allowlist list <cluster-id> -o json
94+
95+
# Organize
96+
ccloud folder create Production -o json
97+
ccloud folder contents <folder-id> -o json
98+
99+
# Test resilience
100+
ccloud cluster disruption set my-cluster --region us-east-1 --whole-region
101+
```
102+
103+
**Coverage:** Provision, Connect, Operate, Observe, Scale & DR, Organize, Test resilience. See the [ccloud reference](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-reference) for full command list.
104+
</details>
105+
106+
<details>
107+
<summary><strong>CockroachDB Cloud MCP Server</strong> (OAuth/API key)</summary>
108+
109+
The official [managed MCP server](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/) is hosted by Cockroach Labs and requires no infrastructure setup. Authenticate via OAuth 2.1 (PKCE) or a service account API key. Read-only by default; write access requires explicit consent.
110+
111+
**OAuth (recommended — opens browser for consent, scopes: `mcp:read`, `mcp:write`):**
112+
```json
113+
{
114+
"mcpServers": {
115+
"cockroachdb-cloud": {
116+
"type": "http",
117+
"url": "https://cockroachlabs.cloud/mcp",
118+
"headers": {
119+
"mcp-cluster-id": "{your-cluster-id}"
120+
}
121+
}
122+
}
123+
}
124+
```
125+
126+
**API Key (headless/autonomous agents):**
127+
```json
128+
{
129+
"mcpServers": {
130+
"cockroachdb-cloud": {
131+
"type": "http",
132+
"url": "https://cockroachlabs.cloud/mcp",
133+
"headers": {
134+
"mcp-cluster-id": "{your-cluster-id}",
135+
"Authorization": "Bearer {your-service-account-api-key}"
136+
}
137+
}
138+
}
139+
}
140+
```
141+
142+
See the [quickstart guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server) for detailed setup.
143+
</details>
144+
42145
## What's Included
43146

44147
### MCP Backends
45148

46-
| Backend | Status | Transport | Use Case |
47-
|----------------------------|----------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
48-
| `cockroachdb-toolbox` | ✅ Available | stdio | Any CockroachDB cluster via [MCP Toolbox](https://github.com/googleapis/genai-toolbox) |
49-
| `cockroachdb-toolbox-http` | ✅ Available | Streamable HTTP | Same as above, remote/multi-user via HTTP |
50-
| `ccloud` | 🔜 Coming soon | stdio | Cluster lifecycle, backups, DR, networking via [ccloud CLI](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-get-started) |
51-
| `cockroachdb-cloud` | 🔜 Coming soon | HTTP | CockroachDB Cloud MCP Server (OAuth/API key) |
149+
| Backend | Status | Transport | Use Case |
150+
|----------------------------|-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
151+
| `cockroachdb-toolbox` | Active | stdio | Any CockroachDB cluster via [MCP Toolbox](https://github.com/googleapis/genai-toolbox) |
152+
| `cockroachdb-cloud` | Active | Streamable HTTP | [Managed MCP Server](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/) — CockroachDB Cloud (OAuth/API key) |
153+
| `cockroachdb-toolbox-http` | Available | Streamable HTTP | MCP Toolbox remote/multi-user via HTTP |
154+
155+
### CLI Tools
156+
157+
| Tool | Status | Use Case |
158+
|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------|
159+
| `ccloud` | Active | [Agent-ready CLI](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/) — cluster lifecycle, backups, DR, networking, audit. Agents call directly via shell. |
52160

53161
### Tools
54162

163+
**MCP Toolbox** (self-hosted, any cluster):
164+
55165
| Tool | Description |
56166
|----------------------------|--------------------------------------------------|
57167
| `cockroachdb-execute-sql` | Execute SQL statements (SELECT, DDL, DML) |
58168
| `cockroachdb-list-schemas` | List all schemas in the database |
59169
| `cockroachdb-list-tables` | List tables with columns, types, and constraints |
60170

61-
### Skills
171+
**CockroachDB Cloud MCP** (managed, read tools):
62172

63-
22 skills from [cockroachdb-skills](https://github.com/cockroachlabs/cockroachdb-skills) across 10 operational domains:
173+
| Tool | Description |
174+
|-------------------------|---------------------------------------------|
175+
| `list_clusters` | List all accessible clusters |
176+
| `get_cluster` | Get detailed cluster information |
177+
| `list_databases` | List databases in the cluster |
178+
| `list_tables` | List tables in a database |
179+
| `get_table_schema` | Get detailed schema for a table |
180+
| `select_query` | Execute a SELECT statement |
181+
| `explain_query` | Execute an EXPLAIN statement |
182+
| `show_running_queries` | List currently executing queries |
64183

65-
| Domain | Skills | Examples |
66-
|---------------------------------|--------|-----------------------------------------------------------------|
67-
| **Query & Schema Design** | 1 | cockroachdb-sql |
68-
| **Observability & Diagnostics** | 7 | profiling-statement-fingerprints, triaging-live-sql-activity |
69-
| **Security & Governance** | 11 | auditing-cloud-cluster-security, hardening-user-privileges |
70-
| **Onboarding & Migrations** | 3 | molt-fetch, molt-verify, molt-replicator |
71-
| **Application Development** | — | (planned) |
72-
| **Performance & Scaling** | — | (planned) |
73-
| **Operations & Lifecycle** | — | (planned) |
74-
| **Cost & Usage Management** | — | (planned) |
75-
| **Integrations & Ecosystem** | — | (planned) |
76-
| **Resilience & Disaster Recovery** | — | (planned) |
184+
**CockroachDB Cloud MCP** (managed, write tools — requires write consent):
185+
186+
| Tool | Description |
187+
|-------------------------|---------------------------------------------|
188+
| `create_database` | Create a new database |
189+
| `create_table` | Create a new table |
190+
| `insert_rows` | Insert rows into a table |
191+
192+
### Skills
77193

78-
Skills are sourced from the [`cockroachdb-skills`](https://github.com/cockroachlabs/cockroachdb-skills) submodule via symlink — a single source of truth shared across CockroachDB agent integrations.
194+
Skills are sourced from the [`cockroachdb-skills`](https://github.com/cockroachlabs/cockroachdb-skills) submodule — a single source of truth shared across CockroachDB agent integrations.
79195

80196
### Rules
81197

@@ -97,9 +213,9 @@ cd cursor-plugin
97213

98214
```
99215
.cursor-plugin/plugin.json # Plugin manifest
100-
skills -> submodules/... # Symlink to cockroachdb-skills (22 skills)
101-
rules/ # 2 rule sets (.mdc files)
102-
mcp.json # MCP server definitions
216+
skills/ # Skills from cockroachdb-skills submodule
217+
rules/ # 4 rule sets (.mdc files)
218+
mcp.json # MCP server definitions (Toolbox + Cloud MCP)
103219
tools.yaml # Toolbox source & tool configuration
104220
submodules/cockroachdb-skills # Shared skills submodule
105221
assets/logo.svg # Plugin logo
@@ -117,7 +233,10 @@ This repo uses [Release Please](https://github.com/googleapis/release-please) fo
117233

118234
- [CockroachDB Documentation](https://www.cockroachlabs.com/docs/)
119235
- [CockroachDB Cloud Console](https://cockroachlabs.cloud/)
120-
- [ccloud CLI](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-get-started)
236+
- [Managed MCP Server Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-managed-mcp-server/)
237+
- [Cloud MCP Quickstart Guide](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-the-cockroachdb-cloud-mcp-server)
238+
- [ccloud CLI for AI Agents Blog Post](https://www.cockroachlabs.com/blog/cockroachdb-ai-agents-cli-database-automation/)
239+
- [ccloud CLI Reference](https://www.cockroachlabs.com/docs/cockroachcloud/ccloud-get-started)
121240
- [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox)
122241
- [Report Issues](https://github.com/cockroachdb/cursor-plugin/issues)
123242

‎mcp.json‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,11 @@
1616
"url": "http://127.0.0.1:5000/mcp",
1717
"_comment": "Streamable HTTP transport — run 'toolbox --tools-file tools.yaml' first, then connect via this URL"
1818
},
19-
"ccloud": {
20-
"command": "ccloud",
21-
"args": ["mcp"],
22-
"_comment": "CockroachDB Cloud CLI — manage clusters, backups, networking, and infrastructure. Coming soon.",
23-
"env": {
24-
"CCLOUD_API_KEY": "${CCLOUD_API_KEY}"
25-
}
26-
},
2719
"cockroachdb-cloud": {
2820
"type": "http",
2921
"url": "https://cockroachlabs.cloud/mcp",
30-
"_comment": "Official CockroachDB Cloud MCP Server — OAuth 2.0 + API key auth. 12 tools: get_cluster_status, show_running_queries, list_databases, switch_database, create_database, list_tables, describe_table, create_table, list_columns, list_indexes, execute_query, explain_query. Read-only by default. Requires CockroachDB Cloud account.",
31-
"env": {
32-
"COCKROACHDB_CLOUD_API_KEY": "${COCKROACHDB_CLOUD_API_KEY}"
22+
"headers": {
23+
"mcp-cluster-id": "${COCKROACHDB_CLUSTER_ID}"
3324
}
3425
}
3526
}

‎rules/cockroachdb-app-patterns.mdc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -677,6 +677,24 @@ rows, err := db.QueryContext(ctx,
677677

678678
---
679679

680+
## Available MCP Tools
681+
682+
**Via MCP Toolbox** (self-hosted, any cluster):
683+
- `cockroachdb-execute-sql`: Execute any SQL statement (test queries, validate schema changes)
684+
- `cockroachdb-list-schemas`: List database schemas
685+
- `cockroachdb-list-tables`: List tables with column details (verify ORM mappings)
686+
687+
**Via CockroachDB Cloud MCP** (managed, CockroachDB Cloud clusters):
688+
- `list_databases`, `list_tables`, `get_table_schema`: Validate schema against ORM models
689+
- `select_query`, `explain_query`: Test queries and verify execution plans
690+
- `create_database`, `create_table`, `insert_rows`: Write operations (requires write consent)
691+
692+
**Via ccloud CLI** (shell commands, `-o json` for structured output):
693+
- `ccloud cluster connection-string <name> --database <db> --sql-user <user>`: Programmatic connection strings for app configuration
694+
- `ccloud cluster info <name>`: Cluster details, version, regions
695+
696+
---
697+
680698
## 14. General Rules (Quick Reference)
681699

682700
1. **Keep transactions SHORT** — <10 statements, <4MB total payload

‎rules/cockroachdb-developer-patterns.mdc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,6 +440,24 @@ ranges.forEach(range -> pool.submit(() -> {
440440

441441
---
442442

443+
## Available MCP Tools
444+
445+
**Via MCP Toolbox** (self-hosted, any cluster):
446+
- `cockroachdb-execute-sql`: Execute any SQL statement
447+
- `cockroachdb-list-schemas`: List database schemas
448+
- `cockroachdb-list-tables`: List tables with column details
449+
450+
**Via CockroachDB Cloud MCP** (managed, CockroachDB Cloud clusters):
451+
- `list_databases`, `list_tables`, `get_table_schema`: Schema exploration
452+
- `select_query`, `explain_query`: Read queries and execution plans
453+
- `create_database`, `create_table`, `insert_rows`: Write operations (requires write consent)
454+
455+
**Via ccloud CLI** (shell commands, `-o json` for structured output):
456+
- `ccloud cluster connection-string <name> --database <db> --sql-user <user>`: Programmatic connection strings
457+
- `ccloud cluster info <name>`: Cluster details for app configuration
458+
459+
---
460+
443461
## Anti-Pattern Quick Reference (Developer-Specific)
444462

445463
| ❌ Anti-Pattern | Why | ✅ Fix |

0 commit comments

Comments
 (0)