# AI Developer Tools

Build Quickback apps faster with AI. The Quickback CLI ships with an MCP server, Claude Code skill, and Cursor IDE rules — so any AI tool can help you write security configurations, define features, and understand your project.

## Quick Install

```bash
# Install the CLI (includes all AI tools)
npm install -g @quickback-dev/cli

# Claude Code skill
quickback claude install

# Cursor IDE rules
quickback cursor install

# MCP server (configure in your AI tool, see below)
quickback mcp
```

## MCP Server

The MCP server makes Quickback documentation and project context available to **any** MCP-compatible AI tool.

### Configuration

Add to your AI tool's MCP config:

```json
{
  "mcpServers": {
    "quickback": {
      "command": "npx",
      "args": ["@quickback-dev/cli", "mcp"]
    }
  }
}
```

| Tool | Config File |
|------|-------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Cursor | `.cursor/mcp.json` in your project |
| VS Code | `.vscode/mcp.json` in your project |

### Available Tools

| Tool | Description |
|------|-------------|
| `list_topics` | List all 100+ documentation topics |
| `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
| `search_docs` | Search documentation by keyword |
| `read_config` | Read your project's `quickback.config.ts` |
| `list_features` | List features and their table files |
| `read_feature` | Read a specific feature's source code |
| `read_schema_registry` | Read the compiled `schema-registry.json` |

All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.

## Claude Code Skill

### Installation

Install via the CLI (recommended):

```bash
quickback claude install --global    # All projects (~/.claude/)
quickback claude install --local     # This project only
```

Or install the standalone npm package:

```bash
npm install -g @quickback-dev/skill
```

Or when creating a new project, the skill is included automatically:

```bash
npx @quickback-dev/cli create cloudflare my-app
```

## What You Get

When you install the Quickback skill, you get:

### Quickback Skill

Claude understands Quickback concepts and can answer questions about:

- **Security layers** - Firewall, Access, Guards, Masking, Actions
- **Common patterns** - Multi-tenant, owner-scoped, hierarchical access
- **Best practices** - Field protection, role-based access, PII handling
- **Database dialects** - SQLite (Cloudflare D1) and PostgreSQL (Neon) syntax — the two supported database providers

### Quickback Specialist Agent

Claude also gets a specialized agent that activates automatically when you're:

- Creating new resources with schemas and security configurations
- Configuring security layers (Firewall, Access, Guards, Masking)
- Defining actions for business logic
- Debugging configuration issues

The agent generates complete, working code in your `quickback/features/` directory.

## Usage

### Let Claude help automatically

Just describe what you need. Claude will use Quickback knowledge when relevant:

```
"Create a tasks resource where users can only see their own tasks,
but admins can see all tasks in the organization"
```

### Invoke directly

Use `/quickback` to explicitly activate the skill:

```
/quickback How do I configure soft delete?
```

## Example Conversations

### Building a New Resource

**You:** "I need a resource for invoices. Users should only see invoices from their organization. The status field should only be changeable through approve/reject actions. Mask the customer email for non-admins."

**Claude:** Creates complete configuration with:
- Firewall scoped to organization
- Protected status field with approve/reject actions
- Email masking with admin bypass
- Appropriate guards for createable/updatable fields

### Understanding Existing Code

**You:** "Explain what this firewall configuration does"

**Claude:** Breaks down the WHERE clauses, explains the security implications, and identifies potential issues.

### Debugging Configuration

**You:** "My users can see records from other organizations. What's wrong?"

**Claude:** Analyzes your firewall setup, checks for `exception: true` or missing organization scope, and suggests fixes.

## What Claude Knows

### Security Layers

| Layer | What Claude Helps With |
|-------|------------------------|
| **Firewall** | Data isolation patterns, WHERE clause generation, soft delete |
| **Access** | Role-based permissions, record-level conditions, combining rules |
| **Guards** | Field protection, createable vs updatable, immutable fields |
| **Masking** | PII redaction, role-based visibility, mask types |
| **Actions** | Custom endpoints, protected field updates, input validation |

### Common Patterns

Claude recognizes and can implement these patterns:

- **Multi-tenant SaaS** - Organization-scoped with role hierarchy
- **Personal data apps** - Owner-scoped resources
- **Hierarchical access** - Admins see all, users see own
- **Public resources** - Reference data, system tables
- **Workflow resources** - Status fields with action-based transitions

### Database Support

Claude generates correct syntax for your database:

```typescript
// SQLite / Cloudflare D1
createdAt: text("created_at").notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString())

// PostgreSQL / Neon
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
```

In the `q` DSL you write `...q.audit()` instead and the compiler emits the
dialect-correct line for you.

## Tips for Best Results

**Be specific about security requirements:**

```
// Good
"Users can only see their own tasks. Admins can see all tasks
in the organization. The priority field can only be set by admins."

// Less helpful
"Create a tasks resource"
```

**Describe your user types:**

```
"We have three roles: admin (full access), manager (can approve),
and member (can only edit their own records)"
```

**Mention sensitive fields:**

```
"The ssn field should be masked for everyone except HR admins"
```

## Common Tasks

### Create a complete resource

```
"Create an employees resource for a multi-tenant HR app. Include
fields for name, email, department, salary. Mask salary for
non-admins. Only HR can create/delete employees."
```

### Add an action to existing resource

```
"Add an 'approve' action to the expenses resource that sets
status to 'approved' and records the approver"
```

### Configure access control

```
"Update the projects resource so managers can edit any project
in their organization, but members can only edit projects they created"
```

### Set up masking

```
"Add masking to the customers resource: email partially masked,
phone last 4 digits only, SSN fully redacted except for finance role"
```

## Troubleshooting

### Skill not found

Verify the skill is installed:

```bash
ls ~/.claude/skills/quickback/SKILL.md
```

If missing, reinstall:

```bash
npm install -g @quickback-dev/skill
```

### Claude doesn't understand Quickback

Make sure the skill file exists and Claude Code is restarted. You can also invoke it directly with `/quickback` to force it to load.

### Generated code has errors

Run `quickback compile` to validate. Share the error messages with Claude for fixes.

## Cursor IDE Rules

Cursor rules provide Quickback context when editing `quickback/**/*.ts` files.

### Installation

```bash
quickback cursor install
```

This installs `quickback.mdc` to `.cursor/rules/` in your project. Commit this file so your team gets the rules automatically.

### Management

```bash
quickback cursor status    # Check installation
quickback cursor update    # Update to latest version
quickback cursor remove    # Remove the rules
```

## Updating

To update all AI tools to the latest version:

```bash
npm update -g @quickback-dev/cli
quickback claude update    # Update Claude skill
quickback cursor update    # Update Cursor rules
```

The MCP server always uses the latest installed version automatically.

## Resources

- [Getting Started with AI Tools](/tooling/claude-code) - Setup guide
- [Getting Started](/start/quickstart) - Get your first Quickback project running
- [Definitions Overview](/define) - Understand the security layer model
- [npm package](https://www.npmjs.com/package/@quickback-dev/cli) - CLI package

## Feedback

Found an issue with the AI tools integration?

- [GitHub Issues](https://github.com/kardoe/quickback/issues)
- [Quickback Documentation](https://docs.quickback.dev)