Name: 00-mcp-server
Author: TerrenoLabs

Instruction file imported from TerrenoLabs/terreno (.cursor/rules/mcp-server/00-mcp-server.mdc). Copyright stays with the author.

description: '@terreno/mcp-server - MCP server for AI assistant integration' globs: */

@terreno/mcp

Model Context Protocol (MCP) server that provides tools, prompts, and resources for AI coding assistants to generate Terreno-compatible code. Built with Express and JSON-RPC 2.0.

Commands

bun run compile          # Type-check only (tsc) — no doc bundling; used by the monorepo build
bun run build            # Full shippable artifact: sync docs + tsc + copy docs into dist/
bun run dev              # Development mode
bun run start            # Start the server (needs dist/docs — run `bun run build` first)
bun run lint             # Lint code

compile is type-check only so the monorepo bun run compile stays fast and free of the sync-versioned-docs filesystem race under concurrent builds. prepublishOnly runs bun run build on every npm publish (GitHub Actions and CircleCI alike), so the published @terreno/mcp always bundles dist/docs (versioned + guidelines + ui-types).

Architecture

File Structure

src/
  index.ts               # Express HTTP server with JSON-RPC handlers
  tools.ts               # Code generation tools (models, routes, screens, forms)
  prompts.ts             # Multi-step workflow prompts (CRUD, auth, components)
  resources.ts           # Documentation resources loaded from markdown

Available Tools

Tool	Description
`terreno_bootstrap_ai_rules`	Scaffold AI assistant rules for Cursor, Claude Code, Copilot, etc.
`terreno_generate_model`	Creates Mongoose schemas with Terreno conventions (plugins, types, methods/statics)
`terreno_generate_route`	Creates modelRouter configurations with permission setup
`terreno_generate_screen`	Creates React Native screens (list, detail, form, empty types)
`terreno_generate_form_fields`	Generates form field components with validation
`terreno_validate_model_schema`	Validates schemas against Terreno conventions
`terreno_install_admin`	Generates admin panel integration files and instructions

Each tool returns generated code wrapped with file path instructions and additional setup steps.

The local stdio server also exposes runtime diagnostics. For SyncDB use:

Tool	Description
`get_syncdb_state`	Read entities, outbox, conflicts, cursors, streams, repair markers, status, and debug events
`syncdb_snapshot`	Capture, list, read, compare, and delete in-memory snapshots
`syncdb_action`	Mutate or directly edit local state, flush, reconcile/resync, resolve/retry, toggle offline, clear events, and merge snapshots

SyncDB state changes require TERRENO_MCP_EVAL=1. Read and snapshot operations remain available without that opt-in. Follow docs/how-to/debug-with-mcp.md.

Available Prompts

Prompt	Description
`terreno_bootstrap`	Workflow for scaffolding a new Terreno application
`terreno_create_crud_feature`	Full CRUD generation: model + routes + screens
`terreno_create_api_endpoint`	Custom API endpoint with OpenAPI docs
`terreno_create_ui_component`	Reusable UI component (display, interactive, form, layout)
`terreno_create_form_screen`	Form screen with validation
`terreno_add_authentication`	Auth setup with feature selection
`terreno_migrate_to_terreno_app`	Migrate from setupServer to TerrenoApp pattern
`terreno_style_guide`	Code style guide from project markdown

Prompts provide detailed requirements, example code patterns, and step-by-step setup instructions.

Available Resources

Terreno overview documentation
@terreno/api documentation
@terreno/ui documentation
@terreno/rtk documentation
Patterns and best practices

Resources are loaded from markdown files with dynamic path resolution.

Server

Express-based HTTP server with JSON-RPC 2.0 protocol
Handles: ListResources, ReadResource, ListTools, CallTool, ListPrompts, GetPrompt
Configurable port and host via environment variables
Health check endpoint at root

Adding a New Tool

// In src/tools.ts
{
  name: "terreno_my_tool",
  description: "What it does",
  inputSchema: {
    type: "object",
    properties: {
      name: {type: "string", description: "Resource name"},
    },
    required: ["name"],
  },
  handler: (args) => {
    return {content: [{type: "text", text: generatedCode}]};
  },
}

Conventions

Use TypeScript with ES modules
Prefer const arrow functions
Named exports preferred
Use logger.info/warn/error/debug for permanent logs

{ "ocm": "1", "id": "terrenolabs-terreno-00-mcp-server-rule", "kind": "skill", "name": "00-mcp-server", "description": "Model Context Protocol (MCP) server that provides tools, prompts, and resources for AI coding assistants to generate Terreno-compatible code. Built with Express and JSON-RPC 2.0.", "publisher": "TerrenoLabs", "version": "1.0.0", "capabilities": { "domains": [ "coding" ], "tags": [ "skill-md", "github-cursor-rules" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Model Context Protocol (MCP) server that provides tools, prompts, and resources for AI coding assistants to generate Terreno-compatible code. Built with Express and JSON-RPC 2.0." ], "primary": false, "metadata": { "source": { "provider": "github-cursor-rules", "repository": "https://github.com/TerrenoLabs/terreno", "path": ".cursor/rules/mcp-server/00-mcp-server.mdc", "ref": "9f69bdbb71d3ae49394a5682fd82ad215b6f2dc3", "url": "https://github.com/TerrenoLabs/terreno/blob/9f69bdbb71d3ae49394a5682fd82ad215b6f2dc3/.cursor/rules/mcp-server/00-mcp-server.mdc", "key": "TerrenoLabs/terreno/.cursor/rules/mcp-server/00-mcp-server.mdc" } }, "instructions": "---\ndescription: '@terreno/mcp-server - MCP server for AI assistant integration'\nglobs: **/*\n---\n\n# @terreno/mcp\n\nModel Context Protocol (MCP) server that provides tools, prompts, and resources for AI coding assistants to generate Terreno-compatible code. Built with Express and JSON-RPC 2.0.\n\n## Commands\n\n```bash\nbun run compile # Type-check only (tsc) — no doc bundling; used by the monorepo build\nbun run build # Full shippable artifact: sync docs + tsc + copy docs into dist/\nbun run dev # Development mode\nbun run start # Start the server (needs dist", "cost": { "context_tokens": 1158 } }

00-mcp-server

About