# @terreno/mcp

MCP (Model Context Protocol) server for Terreno. Provides documentation, tools, and prompts for building full-stack applications with Terreno packages.

## Features

### Resources

Documentation resources accessible via MCP:

- `terreno://docs/overview` - Overview of the Terreno monorepo
- `terreno://docs/api` - @terreno/api documentation
- `terreno://docs/ui` - @terreno/ui documentation
- `terreno://docs/rtk` - @terreno/rtk documentation
- `terreno://docs/patterns` - Common patterns and best practices

### Tools

Code generation tools:

- `terreno_bootstrap_app` - Scaffold a new full-stack Terreno app (frontend, backend, rules, MCP)
- `terreno_bootstrap_ai_rules` - Scaffold AI assistant rules files for Cursor, Claude Code, etc.
- `terreno_generate_model` - Generate a Mongoose model with proper Terreno conventions
- `terreno_generate_route` - Generate a modelRouter route configuration
- `terreno_generate_screen` - Generate a React Native screen component
- `terreno_generate_form_fields` - Generate form field components
- `terreno_validate_model_schema` - Validate a Mongoose schema follows conventions
- `terreno_install_admin` - Generate admin panel integration files and instructions

### Prompts

Code generation prompts:

- `terreno_bootstrap` - Prompt workflow for scaffolding a new Terreno application
- `terreno_create_crud_feature` - Generate complete CRUD feature (model, routes, screens)
- `terreno_create_api_endpoint` - Generate custom API endpoint with OpenAPI docs
- `terreno_create_ui_component` - Generate reusable UI component
- `terreno_create_form_screen` - Generate form screen with validation
- `terreno_add_authentication` - Generate authentication setup
- `terreno_migrate_to_terreno_app` - Migrate from setupServer to TerrenoApp pattern
- `terreno_style_guide` - Get the Terreno code style guide

## Installation

```bash
# From the monorepo root
bun install
bun run mcp:build
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "terreno": {
      "command": "bun",
      "args": ["/path/to/terreno/mcp-server/dist/index.js"]
    }
  }
}
```

### With Claude Code CLI

Add to your project's `.claude/settings.json`:

```json
{
  "mcpServers": {
    "terreno": {
      "command": "bun",
      "args": ["./mcp-server/dist/index.js"]
    }
  }
}
```

## Development

```bash
# Build
bun run build

# Watch mode
bun run dev

# Start server
bun run start

# Run tests
bun run test

# Lint
bun run lint
```

## Docker

Build and run the MCP server in Docker:

```bash
# Build the image
docker build -t terreno-mcp-server ./mcp-server

# Run the container
docker run --rm terreno-mcp-server
```

## CI/CD

The MCP server includes GitHub Actions workflows:

### CI Workflow (`.github/workflows/mcp-server-ci.yml`)
- Runs on every push/PR to `mcp-server/**`
- Lints, builds, and tests the code
- Builds Docker image to verify it works

### Deploy Workflow (`.github/workflows/mcp-server-deploy.yml`)
- Runs on push to `master`/`main` branch
- Deploys to Google Cloud Run

### Required GitHub Secrets for Deployment

Configure these secrets in your GitHub repository:

| Secret | Description |
|--------|-------------|
| `GCP_PROJECT_ID` | Your Google Cloud project ID |
| `GCP_WORKLOAD_IDENTITY_PROVIDER` | Workload Identity Federation provider |
| `GCP_SERVICE_ACCOUNT` | Service account email for deployment |
| `GCP_ARTIFACT_REGISTRY` | Artifact Registry repository name |

### Setting up GCP for Deployment

1. Create an Artifact Registry repository:
   ```bash
   gcloud artifacts repositories create terreno \
     --repository-format=docker \
     --location=us-central1
   ```

2. Set up Workload Identity Federation for GitHub Actions:
   ```bash
   # Create workload identity pool
   gcloud iam workload-identity-pools create "github" \
     --location="global" \
     --display-name="GitHub Actions"

   # Create provider
   gcloud iam workload-identity-pools providers create-oidc "github" \
     --location="global" \
     --workload-identity-pool="github" \
     --display-name="GitHub" \
     --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository" \
     --issuer-uri="https://token.actions.githubusercontent.com"
   ```

3. Grant permissions to the service account:
   ```bash
   # Cloud Run deployment
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SA_EMAIL" \
     --role="roles/run.admin"

   # Artifact Registry push
   gcloud artifacts repositories add-iam-policy-binding terreno \
     --location=us-central1 \
     --member="serviceAccount:SA_EMAIL" \
     --role="roles/artifactregistry.writer"
   ```

## How Tools Work

**Important**: MCP tools return generated code as text content. They do not create files directly. When using these tools with an AI assistant (like Claude in Cursor), the assistant should:

1. Call the appropriate tool to generate code
2. Take the returned code text and write it to the appropriate file in your project
3. Follow up with any necessary steps (registering routes, regenerating SDK, etc.)

This design allows the AI assistant to:
- Review and adapt the generated code to your project structure
- Make any necessary modifications before writing
- Handle file paths based on your project's conventions

## Example Tool Usage

### Generate a Model

```json
{
  "name": "terreno_generate_model",
  "arguments": {
    "name": "Product",
    "fields": [
      { "name": "title", "type": "String", "required": true },
      { "name": "price", "type": "Number", "required": true },
      { "name": "active", "type": "Boolean", "default": "true" }
    ],
    "hasOwner": true,
    "softDelete": true
  }
}
```

The tool returns TypeScript code that should be written to `backend/src/models/product.ts` (or your project's model directory).

### Generate a Route

```json
{
  "name": "terreno_generate_route",
  "arguments": {
    "modelName": "Product",
    "routePath": "/products",
    "permissions": {
      "create": "authenticated",
      "list": "any",
      "read": "any",
      "update": "owner",
      "delete": "admin"
    },
    "queryFields": ["active", "category"],
    "ownerFiltered": true,
    "sort": "-created"
  }
}
```

The tool returns route configuration code that should be written to `backend/src/api/product.ts`, then exported from `backend/src/api/index.ts` and registered in your server setup.

### Generate a Screen

```json
{
  "name": "terreno_generate_screen",
  "arguments": {
    "name": "ProductList",
    "type": "list",
    "modelName": "Product",
    "fields": ["title", "price"]
  }
}
```

The tool returns React Native screen code that should be written to `frontend/src/screens/ProductListScreen.tsx` (or your project's screen directory).

## Example Prompt Usage

### Create CRUD Feature

```
Prompt: terreno_create_crud_feature
Arguments:
  - name: "Product"
  - fields: "title:string,price:number,description:string,active:boolean"
  - hasOwner: "yes"
```

This will generate a comprehensive prompt with instructions for creating:
- Backend model with proper schema
- API routes with permissions
- Frontend list, detail, and form screens