@terreno/mcp 0.23.1 → 0.25.0

package/src/docs/versioned/0.24.0/reference/mcp-server.md

@@ -0,0 +1,586 @@
+# @terreno/mcp
+
+Published npm package for the Terreno Model Context Protocol (MCP) server. The monorepo directory is still `mcp-server/`. The package exposes:
+
+- **`terreno-mcp`** — HTTP server used in Cloud Run and local debugging (`src/index.ts`)
+- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate` (gated by `TERRENO_MCP_EVAL`), `navigate` (CDP wiring planned)
+
+It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Resources](#resources)
+- [Tools](#tools)
+- [Prompts](#prompts)
+- [Environment Variables](#environment-variables)
+- [Development](#development)
+
+## Overview
+
+The MCP server exposes Terreno's documentation and code generation capabilities through the Model Context Protocol, enabling AI assistants (like Claude in Cursor or Claude Desktop) to:
+
+- Access up-to-date documentation for all Terreno packages
+- Generate boilerplate code following Terreno conventions
+- Provide multi-step workflows for common development tasks
+
+**Key concepts:**
+
+- **Resources**: Read-only documentation from `docs/` directory
+- **Tools**: Code generators that return text (AI writes files), documentation search (`terreno_search_docs`, `terreno_get_component_docs`), upgrade notes (`terreno_get_upgrade_guide`), plus local-only tools when using `terreno-mcp-local`
+- **Prompts**: Pre-built multi-step instructions for complex workflows
+
+## Installation
+
+### With Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+``````json
+{
+  "mcpServers": {
+    "terreno": {
+      "command": "bun",
+      "args": ["/absolute/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"]
+    }
+  }
+}
+``````
+
+### Building from Source
+
+``````bash
+# From monorepo root
+bun install
+bun run mcp:build
+
+# Or from mcp-server directory
+cd mcp-server
+bun run build
+``````
+
+## Resources
+
+Documentation resources accessible via `terreno://` protocol:
+
+| URI | Description |
+|-----|-------------|
+| `terreno://docs/overview` | Monorepo overview and architecture |
+| `terreno://docs/api` | @terreno/api reference documentation |
+| `terreno://docs/ui` | @terreno/ui reference documentation |
+| `terreno://docs/rtk` | @terreno/rtk reference documentation |
+| `terreno://docs/patterns` | Common patterns and best practices |
+
+**How it works:**
+
+- Resources are loaded from markdown files in `docs/` directory
+- Content is transformed and served via MCP protocol
+- AI assistants cache resources for fast lookup
+- Updates require MCP server restart
+
+**Custom docs directory:**
+
+Set `TERRENO_MCP_DOCS_DIR` environment variable to override default path.
+
+## Tools
+
+Code generation tools that return TypeScript/JavaScript code as text. **Tools do not write files** — the AI assistant receives the code and writes it to appropriate locations.
+
+### terreno_search_docs
+
+BM25-style keyword search over markdown bundled with the MCP server: `docs/resources/*.md`, synced Diátaxis docs under `docs/versioned/`, and per-component excerpts derived from `ui-types-documentation.json`. **Prefer this tool before guessing** Terreno APIs (same posture as Laravel Boost `search-docs`).
+
+**Parameters:**
+
+``````typescript
+{
+  queries: string[];       // Required — one or more search phrases
+  packages?: string[];     // Optional — filter by package id or scope, e.g. ["api", "@terreno/ui"]
+  tokenLimit?: number;      // Approximate max tokens of markdown (default 3000)
+}
+``````
+
+### terreno_get_component_docs
+
+Returns the full props table for a single `@terreno/ui` component from `ui-types-documentation.json`, plus short related markdown excerpts when the search index finds matches.
+
+**Parameters:**
+
+``````typescript
+{
+  component: string;        // e.g. "Button", "TextField"
+}
+``````
+
+### terreno_generate_model
+
+Generate a Mongoose model with Terreno conventions (timestamps, soft delete, owner tracking, type definitions).
+
+**Parameters:**
+
+``````typescript
+{
+  name: string;              // Model name (PascalCase)
+  fields: Array<{
+    name: string;            // Field name (camelCase)
+    type: string;            // "String" | "Number" | "Boolean" | "Date" | "ObjectId"
+    required?: boolean;
+    default?: string;        // Default value as string
+    ref?: string;            // Referenced model name (for ObjectId)
+    description?: string;    // Field description (recommended)
+  }>;
+  hasOwner?: boolean;        // Add ownerId field (default: false)
+  softDelete?: boolean;      // Add deleted field (default: false)
+  timestamps?: boolean;      // Add created/updated fields (default: true)
+}
+``````
+
+**Example:**
+
+``````json
+{
+  "name": "Product",
+  "fields": [
+    {"name": "title", "type": "String", "required": true, "description": "Product title"},
+    {"name": "price", "type": "Number", "required": true, "description": "Price in cents"},
+    {"name": "active", "type": "Boolean", "default": "true", "description": "Is product active"}
+  ],
+  "hasOwner": true,
+  "softDelete": true
+}
+``````
+
+**Returns:**
+
+- Model schema code with proper type definitions
+- Methods and statics structure
+- Plugin configuration
+- Export statements
+
+### terreno_generate_route
+
+Generate modelRouter configuration with permissions and query options.
+
+**Parameters:**
+
+``````typescript
+{
+  modelName: string;         // Model name (PascalCase)
+  routePath: string;         // API path (e.g., "/products")
+  permissions?: {
+    create?: "any" | "authenticated" | "admin" | "owner";
+    list?: "any" | "authenticated" | "admin" | "owner";
+    read?: "any" | "authenticated" | "admin" | "owner";
+    update?: "any" | "authenticated" | "admin" | "owner";
+    delete?: "any" | "authenticated" | "admin" | "owner";
+  };
+  queryFields?: string[];    // Allowed query parameters
+  ownerFiltered?: boolean;   // Apply OwnerQueryFilter (default: false)
+  sort?: string;             // Default sort order (e.g., "-created")
+  populate?: Array<{path: string; fields?: string[]}>;
+}
+``````
+
+**Example:**
+
+``````json
+{
+  "modelName": "Product",
+  "routePath": "/products",
+  "permissions": {
+    "create": "authenticated",
+    "list": "any",
+    "read": "any",
+    "update": "owner",
+    "delete": "admin"
+  },
+  "queryFields": ["active", "category"],
+  "ownerFiltered": true,
+  "sort": "-created"
+}
+``````
+
+**Returns:**
+
+- Router setup code with modelRouter configuration
+- Permission mapping
+- Lifecycle hooks structure
+- Instructions for registering route
+
+### terreno_generate_screen
+
+Generate React Native screen component with Terreno UI components.
+
+**Parameters:**
+
+``````typescript
+{
+  name: string;              // Screen name (PascalCase)
+  type: "list" | "detail" | "form" | "empty";
+  modelName?: string;        // Model name for CRUD screens
+  fields?: string[];         // Fields to display/edit
+  hasSearch?: boolean;       // Add search bar (list screens)
+  hasPagination?: boolean;   // Add pagination (list screens)
+}
+``````
+
+**Example:**
+
+``````json
+{
+  "name": "ProductList",
+  "type": "list",
+  "modelName": "Product",
+  "fields": ["title", "price", "active"],
+  "hasSearch": true,
+  "hasPagination": true
+}
+``````
+
+**Returns:**
+
+- React Native functional component
+- RTK Query hooks integration
+- @terreno/ui components (Box, Text, Button, Card, etc.)
+- Loading/error/empty states
+
+### terreno_generate_form_fields
+
+Generate form field components for a model.
+
+**Parameters:**
+
+``````typescript
+{
+  modelName: string;         // Model name (PascalCase)
+  fields: Array<{
+    name: string;
+    type: "text" | "number" | "boolean" | "date" | "select";
+    required?: boolean;
+    options?: string[];      // For select fields
+  }>;
+}
+``````
+
+**Example:**
+
+``````json
+{
+  "modelName": "Product",
+  "fields": [
+    {"name": "title", "type": "text", "required": true},
+    {"name": "price", "type": "number", "required": true},
+    {"name": "category", "type": "select", "options": ["electronics", "books", "clothing"]}
+  ]
+}
+``````
+
+**Returns:**
+
+- TextField, NumberField, SelectField components
+- Validation logic structure
+- Form state management pattern
+
+### terreno_validate_model_schema
+
+Validate a Mongoose schema against Terreno conventions.
+
+**Parameters:**
+
+``````typescript
+{
+  schemaCode: string;        // Full schema code to validate
+}
+``````
+
+**Returns:**
+
+- List of convention violations
+- Recommendations for fixes
+- Severity levels (error, warning, info)
+
+### terreno_bootstrap_app
+
+Scaffold a new full-stack Terreno application (Expo frontend, Express/Mongoose backend, Cursor rules, MCP settings).
+
+**Parameters:**
+
+``````typescript
+{
+  appName: string;           // kebab-case (e.g., "my-app")
+  appDisplayName: string;    // Human-readable name
+  description?: string;
+  mcpServerUrl?: string;     // Default: https://mcp.terreno.flourish.health
+}
+``````
+
+**Returns:** File list, setup instructions, and full file contents for backend, frontend, CI workflows, and MCP configuration.
+
+### terreno_bootstrap_ai_rules
+
+Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).
+
+**Parameters:**
+
+``````typescript
+{
+  appName: string;
+  appDisplayName: string;
+  description?: string;
+  /** Optional — which @terreno/* packages to merge into rules. Use ids like `api`, `ui`, `rtk`, `admin-backend`, `admin-frontend`, or `@terreno/api`. Omit or pass only what the app uses so admin guidelines stay out of projects without the admin panel. */
+  packages?: string[];
+}
+``````
+
+Guideline bodies are composed from per-package `.ai/guidelines/core.md` files, copied into this package at build time (`bun run sync-package-guidelines` in `mcp-server/`).
+
+**Returns:** Rules files and instructions for installing/syncing with rulesync.
+
+### terreno_install_admin
+
+Generate admin panel integration for `@terreno/admin-backend` and `@terreno/admin-frontend`.
+
+**Parameters:** Model configurations with `modelName`, `routePath`, `displayName`, `listFields`, etc.
+
+**Returns:** Frontend screen files and backend/frontend setup snippets.
+
+## Prompts
+
+Multi-step workflow prompts that guide AI assistants through complex tasks.
+
+### terreno_bootstrap
+
+Workflow prompt for scaffolding a new Terreno app. Delegates to `terreno_bootstrap_app` and `terreno_bootstrap_ai_rules` tools.
+
+**Arguments:**
+
+- `appName` (string) — Application name in kebab-case
+- `appDisplayName` (string) — Human-readable display name
+
+### terreno_create_crud_feature
+
+Generate complete CRUD feature: backend model + routes + frontend screens.
+
+**Arguments:**
+
+- `name` (string) — Feature name (e.g., "Product")
+- `fields` (string) — Comma-separated fields: `title:string,price:number,active:boolean`
+- `hasOwner` (string) — "yes" or "no" (default: "no")
+
+**Workflow:**
+
+1. Generate Mongoose model with type definitions
+2. Generate API routes with permissions
+3. Generate list screen with DataTable
+4. Generate detail screen
+5. Generate form screen with validation
+6. Provide instructions for:
+   - Registering routes in `server.ts`
+   - Regenerating SDK: `bun run sdk`
+   - Adding navigation
+
+### terreno_create_api_endpoint
+
+Generate custom (non-CRUD) API endpoint with OpenAPI documentation.
+
+**Arguments:**
+
+- `path` (string) — Endpoint path (e.g., "/stats/summary")
+- `method` (string) — HTTP method ("get", "post", "patch", "delete")
+- `description` (string) — What the endpoint does
+
+**Workflow:**
+
+1. Generate route handler with asyncHandler
+2. Generate OpenAPI builder configuration
+3. Generate response types
+4. Provide authentication setup instructions
+5. Provide SDK regeneration instructions
+
+### terreno_create_ui_component
+
+Generate reusable UI component following @terreno/ui patterns.
+
+**Arguments:**
+
+- `name` (string) — Component name (PascalCase)
+- `type` (string) — "display" | "interactive" | "form" | "layout"
+- `description` (string) — Component purpose
+
+**Workflow:**
+
+1. Generate component structure with TypeScript types
+2. Include @terreno/ui imports (Box, Text, Button, etc.)
+3. Add prop definitions with JSDoc
+4. Include usage example
+5. Provide testing setup
+
+### terreno_create_form_screen
+
+Generate form screen with validation and error handling.
+
+**Arguments:**
+
+- `name` (string) — Screen name (e.g., "CreateProduct")
+- `modelName` (string) — Model being created/edited
+- `fields` (string) — Comma-separated: `title:text,price:number,active:boolean`
+
+**Workflow:**
+
+1. Generate screen component with Page layout
+2. Add form fields from @terreno/ui
+3. Include validation logic
+4. Add RTK mutation hooks
+5. Add loading/error/success states
+6. Provide navigation setup
+
+### terreno_add_authentication
+
+Generate authentication setup for new projects.
+
+**Arguments:**
+
+- `strategies` (string) — Comma-separated: "email", "github", "google"
+- `includeRefreshToken` (string) — "yes" or "no" (default: "yes")
+
+**Workflow:**
+
+1. Configure User model with passport-local-mongoose
+2. Set up auth routes in backend
+3. Configure Redux auth slice in frontend
+4. Generate login screen
+5. Generate signup screen
+6. Set up token storage
+7. Provide environment variable list
+
+### terreno_migrate_to_terreno_app
+
+Guide for migrating from `setupServer` to the `TerrenoApp` fluent API pattern.
+
+**Arguments:**
+
+- `serverFile` (string, optional) — Path to server file to migrate (e.g., `src/server.ts`)
+
+### terreno_style_guide
+
+Returns comprehensive code style guide from project documentation.
+
+**No arguments required.**
+
+**Returns:**
+
+- TypeScript conventions
+- React/React Native patterns
+- Backend API conventions
+- Testing practices
+- Logging guidelines
+
+## Environment Variables
+
+### Server Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | HTTP server port |
+| `MCP_HOST` or `HOST` | `0.0.0.0` | Server host address |
+| `TERRENO_MCP_DOCS_DIR` | `../docs` | Path to documentation directory (relative to dist/) |
+
+**Example:**
+
+``````bash
+PORT=3001 HOST=localhost bun run start
+``````
+
+## Development
+
+``````bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# (Build runs sync-ui-docs, sync-versioned-docs, and sync-package-guidelines before tsc.)
+# To refresh only bundled package AI guidelines from the monorepo:
+# bun run sync-package-guidelines
+
+# Watch mode (rebuilds on changes)
+bun run dev
+
+# Start server
+bun run start
+
+# Lint
+bun run lint
+
+# Fix lint issues
+bun run lint:fix
+``````
+
+### Docker
+
+``````bash
+# Build image
+docker build -t terreno-mcp-server ./mcp-server
+
+# Run container
+docker run --rm -p 8080:8080 terreno-mcp-server
+``````
+
+### Testing with MCP Inspector
+
+``````bash
+# Start server
+bun run start
+
+# In another terminal, use MCP inspector
+npx @modelcontextprotocol/inspector bun run ./mcp-server/dist/index.js
+``````
+
+## Architecture
+
+``````
+mcp-server/
+├── src/
+│   ├── index.ts          # Express server + JSON-RPC handlers
+│   ├── resources.ts      # Documentation resource loader
+│   ├── tools.ts          # Code generation tools
+│   ├── prompts.ts        # Workflow prompts
+│   └── docs/             # Inline documentation content
+├── dist/                 # Compiled output
+└── Dockerfile            # Container image
+``````
+
+**JSON-RPC 2.0 handlers:**
+
+- `resources/list` — List available documentation
+- `resources/read` — Read documentation content
+- `tools/list` — List available tools
+- `tools/call` — Execute a tool
+- `prompts/list` — List available prompts
+- `prompts/get` — Get prompt details
+
+## Deployment
+
+See [mcp-server/README.md](../../mcp-server/README.md#cicd) for:
+
+- GitHub Actions workflows
+- Google Cloud Run deployment
+- Required secrets configuration
+- Workload Identity Federation setup