@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

# 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):

{
  "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:

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

Development

# 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:

# 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:

   gcloud artifacts repositories create terreno \
     --repository-format=docker \
     --location=us-central1

2. Set up Workload Identity Federation for GitHub Actions:

   # 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:

   # 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

{
  "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

{
  "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

{
  "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