diff --git a/neon-branching-tutorial/README.md b/neon-branching-tutorial/README.md index 5ab53c6..04338f3 100644 --- a/neon-branching-tutorial/README.md +++ b/neon-branching-tutorial/README.md @@ -340,8 +340,185 @@ neonctl branches list --project-id Only the `main` branch remains. +## Agent-Driven Workflow with Cursor + +The CLI workflow above works well, but AI coding agents can automate the entire process. The Signadot MCP (Model Context Protocol) server connects directly to AI-powered IDEs, allowing you to manage sandboxes through natural language prompts. No YAML editing. No terminal switching. Just describe what you want, and the agent handles the rest. + +### Prerequisites for Agent Workflow + +Before proceeding, ensure you have: + +- Signadot CLI v1.4.0 or later (run `signadot --version` to check) +- Completed baseline setup from the previous sections (Resource Plugin installed, secrets configured) + +### Install Signadot MCP Server in Cursor + +Add the Signadot MCP server to Cursor by editing your `~/.cursor/mcp.json` file: + +```json title="~/.cursor/mcp.json" +{ + "mcpServers": { + "signadot": { + "command": "signadot", + "args": ["mcp"] + } + } +} +``` + +After adding the configuration, restart Cursor to activate the Signadot MCP server. + +To verify the installation, open Cursor's AI chat (Cmd+L or Ctrl+L) and ask it to `list available Signadot sandboxes or clusters.` The AI should use the MCP tools to interact with your Signadot environment: + +![Verify installation](./images/img-008.png) + +### The Workflow + +The following prompts demonstrate a complete cycle: checking your environment, creating a sandbox with an isolated database branch, testing data isolation, and cleaning up. + +### Prompt 1: Check Environment and Clean Up + +Start with a clean slate. Open Cursor Chat and enter: + +**Prompt:** + +> “Check my Signadot setup. List all clusters and sandboxes, then delete any sandboxes +that start with "neon-" to clean up from earlier runs.” +> + +**Expected Response:** + +The agent calls the Signadot MCP tools to list your clusters and sandboxes. It then checks for any sandboxes matching the pattern. + +![List cluster and sandboxes](./images/img-009.png) + +### Prompt 2: Create Sandbox with Isolated Database + +Now create a sandbox that provisions an isolated Neon database branch. The agent resolves the workload, constructs the sandbox specification, and applies it via the MCP tools. + +Ensure you add your actual `project-id` below. + +**Prompt:** + +> “Create a sandbox called "neon-agent-test" for the users-service deployment in the +default namespace on my test-cluster. Use the neon-branch resource plugin with +these parameters: +- project-id: +- parent-branch: main +- database-name: neondb + +The sandbox should override the DATABASE_URL environment variable with the +connection string from the resource plugin output. Give me the preview URL +when it's ready.” +> + +**Expected Response:** + +The agent resolves the workload, builds the sandbox specification, and presents it for review before creating. + +![Resolve workload](./images/img-010.png) + +![Resolve workload](./images/img-011.png) + +![Resolve workload](./images/img-012.png) + +### Verify Sandbox in Signadot Dashboard + +Open the [Signadot Dashboard](https://app.signadot.com/) and navigate to **Sandboxes**. You should see the `neon-agent-test` sandbox in the list with a **Ready** status. + +![Dashboard](./images/img-013.png) + +### Verify Branch in Neon Console + +Open the [Neon Console](https://console.neon.tech/) and navigate to your project. Under **Branches**, you should see the newly created branch alongside the `main` branch. + +![Neon console](./images/img-014.png) + +The branch name follows the pattern `sandbox` with hyphens removed. The Resource Plugin created this branch automatically when Signadot provisioned the sandbox. + +### Prompt 3: Verify Data Isolation + +Test that the sandbox has its own isolated data. The agent runs curl commands and shows you exactly what it executed. + +**Prompt:** + +> ‘Query the sandbox endpoint at https://users-service--neon-agent-test.preview.signadot.com/users +to list users. Then create a new test user with name "Agent Test User" and +email "agent@test.example". Show me the commands you're running.’ +> + +**Expected Response:** + +The agent uses the `signadot-api-key` header with your API key and shows the exact commands. + +![Query sandbox](./images/img-015.png) + +![Query sandbox](./images/img-016.png) + +![Query sandbox](./images/img-017.png) + +### Prompt 4: Teardown + +Clean up the sandbox when you're done. The Resource Plugin automatically deletes the Neon branch. + +**Prompt:** + +> “Delete the neon-agent-test sandbox.” +> + +**Expected Response:** + +The agent uses the Signadot CLI to delete the sandbox and waits for full teardown. + +![Delete sandox](./images/img-018.png) + +### Verify Sandbox Removal in Signadot Dashboard + +Return to the [Signadot Dashboard](https://app.signadot.com/) and navigate to **Sandboxes**. The `neon-agent-test` sandbox should no longer appear in the list. + +### Verify Branch Removal in Neon Console + +Open the [Neon Console](https://console.neon.tech/) and navigate to your project's **Branches** page. The `sandboxneonagenttest` branch should be gone. Only the `main` branch remains: + +![Neon console](./images/img-019.png) + +The Resource Plugin's delete workflow ran automatically when the sandbox was deleted, removing the isolated database branch along with all test data. No manual cleanup required. + +### What Happens Behind the Scenes + +When you ask the agent to create a sandbox, several systems coordinate: + +1. **Cursor Agent** receives your natural language prompt +2. **Signadot MCP Server** translates the request into Signadot API calls +3. **Signadot Control Plane** processes the sandbox specification +4. **Resource Plugin** runs the create workflow in your cluster +5. **Neon API** creates the database branch +6. **Sandbox Pod** starts with the connection string injected + +The same Resource Plugin that powers the CLI workflow also powers the agent workflow. You write the plugin once and use it from any interface. + +### Benefits of Agent-Driven Workflows + +Using an AI agent to manage sandboxes offers several advantages: + +- **No YAML editing**: Describe what you want in plain English. The agent generates correct specifications. +- **No context switching**: Stay in your IDE. No terminal windows or browser tabs needed. +- **Consistent cleanup**: Agents don't forget to delete sandboxes. Ask once and it's done. +- **Faster iteration**: Create, test, and tear down environments as fast as you can type prompts. + +### Other MCP-Compatible Clients + +While this guide focuses on Cursor, Signadot's MCP server works with other clients too: + +- **VS Code**: Add the configuration to `.vscode/mcp.json` in your workspace +- **Claude Code**: Run `claude mcp add --transport stdio signadot -- signadot mcp` + +See the [Signadot MCP documentation](https://www.signadot.com/docs/integrations/mcp) for setup instructions for each client. + ## Conclusion Each Signadot Sandbox now gets its own forked microservice pods and its own isolated Neon database branch. The Resource Plugin handles the entire lifecycle: creating branches on sandbox creation, exposing connection strings through built-in outputs, and cleaning them up on deletion. Test data cannot leak between sandboxes, and schema migrations in one branch cannot break tests in another. -The cost efficiency makes this practical for everyday use. Neon branches use copy-on-write storage, so you only pay for data that changes. Signadot sandboxes share baseline cluster resources. Branch creation and teardown complete in seconds. Every developer gets an isolated app and database for every pull request. \ No newline at end of file +You can manage sandboxes through the CLI for scripted workflows, or through an AI agent for interactive development. Both approaches use the same Resource Plugin and produce identical results. + +The cost efficiency makes this practical for everyday use. Neon branches use copy-on-write storage, so you only pay for data that changes. Signadot sandboxes share baseline cluster resources. Branch creation and teardown complete in minutes. Every developer gets an isolated app and database for every pull request. diff --git a/neon-branching-tutorial/images/img-008.png b/neon-branching-tutorial/images/img-008.png new file mode 100644 index 0000000..16f68ae Binary files /dev/null and b/neon-branching-tutorial/images/img-008.png differ diff --git a/neon-branching-tutorial/images/img-009.png b/neon-branching-tutorial/images/img-009.png new file mode 100644 index 0000000..4d932f0 Binary files /dev/null and b/neon-branching-tutorial/images/img-009.png differ diff --git a/neon-branching-tutorial/images/img-010.png b/neon-branching-tutorial/images/img-010.png new file mode 100644 index 0000000..9b4fef5 Binary files /dev/null and b/neon-branching-tutorial/images/img-010.png differ diff --git a/neon-branching-tutorial/images/img-011.png b/neon-branching-tutorial/images/img-011.png new file mode 100644 index 0000000..c19b6ff Binary files /dev/null and b/neon-branching-tutorial/images/img-011.png differ diff --git a/neon-branching-tutorial/images/img-012.png b/neon-branching-tutorial/images/img-012.png new file mode 100644 index 0000000..d730370 Binary files /dev/null and b/neon-branching-tutorial/images/img-012.png differ diff --git a/neon-branching-tutorial/images/img-013.png b/neon-branching-tutorial/images/img-013.png new file mode 100644 index 0000000..bc049e4 Binary files /dev/null and b/neon-branching-tutorial/images/img-013.png differ diff --git a/neon-branching-tutorial/images/img-014.png b/neon-branching-tutorial/images/img-014.png new file mode 100644 index 0000000..fc73335 Binary files /dev/null and b/neon-branching-tutorial/images/img-014.png differ diff --git a/neon-branching-tutorial/images/img-015.png b/neon-branching-tutorial/images/img-015.png new file mode 100644 index 0000000..107ea95 Binary files /dev/null and b/neon-branching-tutorial/images/img-015.png differ diff --git a/neon-branching-tutorial/images/img-016.png b/neon-branching-tutorial/images/img-016.png new file mode 100644 index 0000000..c031322 Binary files /dev/null and b/neon-branching-tutorial/images/img-016.png differ diff --git a/neon-branching-tutorial/images/img-017.png b/neon-branching-tutorial/images/img-017.png new file mode 100644 index 0000000..051f77d Binary files /dev/null and b/neon-branching-tutorial/images/img-017.png differ diff --git a/neon-branching-tutorial/images/img-018.png b/neon-branching-tutorial/images/img-018.png new file mode 100644 index 0000000..a3d36df Binary files /dev/null and b/neon-branching-tutorial/images/img-018.png differ diff --git a/neon-branching-tutorial/images/img-019.png b/neon-branching-tutorial/images/img-019.png new file mode 100644 index 0000000..b762282 Binary files /dev/null and b/neon-branching-tutorial/images/img-019.png differ