@sparrowengg/nexgate-mcp

Model Context Protocol (MCP) server for intelligent Nexgate app scaffolding and code generation

Features

• 🎯 Intelligent Code Generation - Analyzes existing code patterns and generates matching code
• 🏗️ Comprehensive Scaffolding - Create features, routes, components, services, hooks, pages, and utilities
• 🧪 TDD-first - Every tool returns test file(s) before implementation; follow test-driven development out of the box
• 📐 Pattern Recognition - Automatically detects and matches your project's coding conventions
• 🔍 Project-Aware - Automatically detects project root and structure
• 🚀 MCP Compatible - Works with Claude Desktop, Cursor, and other MCP clients
• ⚡ Type-Safe - Full TypeScript support with Zod schema validation
• 🎨 Twigs React UI - Generates components using @sparrowengg/twigs-react library
• 🛣️ React Router v7 - Creates routes compatible with React Router v7 patterns

Prerequisites

• Node.js >= 20.0.0
• npm or yarn package manager
• An existing Nexgate project with package.json and tsconfig.json in the root
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

Installation

Global Installation (Recommended)

Install the MCP server globally:

npm install -g @sparrowengg/nexgate-mcp

Local Installation

For project-specific usage:

npm install --save-dev @sparrowengg/nexgate-mcp

Usage

Running the MCP Server

The MCP server runs on stdio transport and communicates with MCP-compatible clients. It automatically detects your project root by searching for package.json and tsconfig.json files.

Standalone (for testing)

nexgate-mcp

Or if installed locally:

npx nexgate-mcp

Configuring MCP Clients

Add the following to your Mcp configuration file:

{
  "mcpServers": {
    "nexgate-mcp": {
      "command": "nexgate-mcp",
      "args": []
    }
  }
}

For using npx (no installation required):

{
  "mcpServers": {
    "nexgate-mcp": {
      "command": "npx",
      "args": ["-y", "@sparrowengg/nexgate-mcp"]
    }
  }
}

The -y flag automatically accepts the package installation prompt.

Available Tools

The MCP server provides 7 intelligent scaffolding tools that analyze your existing codebase and generate matching code. All tools follow TDD (Test-Driven Development): they return test file(s) first, then implementation files, then barrel exports. Apply the returned files array in order and use the contents property for each file body.

1. create_feature

Create a new feature directory with organized structure.

Parameters:

• name (string, required): Feature name in kebab-case (e.g., "auth", "settings", "home")
• nested (boolean, optional): Whether this is a nested feature (default: false)
• initializeStructure (boolean, optional): Create subdirectories (default: true)

Creates:

• src/features/{name}/ directory
• Subdirectories: pages/, components/, services/, hooks/, types/, utils/
• Barrel export files (index.ts) in each subdirectory
• __tests__/unit/hooks/, __tests__/unit/services/, __tests__/unit/pages/, __tests__/unit/components/, __tests__/unit/utils/, __tests__/integration/, __tests__/pages/ — each with a .gitkeep
• routes.tsx file for React Router v7 route definitions
• tdd.md — default testing approach playbook (stack, run commands, strategy placeholders, coverage goals)

Example:

{
  "name": "auth",
  "initializeStructure": true
}

Naming Rules:

• Must be lowercase
• Must start with a letter
• Can contain letters, numbers, and hyphens
• Maximum nesting depth: 2 levels

2. create_route

Create a route with corresponding page component using React Router v7. Automatically creates the page component and adds route entry to the feature's routes.tsx file. Follows TDD: returns page test first, then page component, then route entry and pages index.

Parameters:

• route (string, required): Route path (e.g., "login", "settings/general", "profile")
• feature (string, required): Feature name where this route belongs (e.g., "auth", "settings", "home")
• isPublic (boolean, optional): Whether this is a public route accessible without auth (default: false)
• componentName (string, optional): Custom component name in PascalCase (auto-generated if not provided)

TDD file order: Page test (__tests__/pages/<page>.test.tsx) → page component → route entry + pages index.

Example:

{
  "route": "login",
  "feature": "auth",
  "isPublic": true
}

3. create_component

Create a React component using Twigs React UI library. Analyzes existing component patterns and generates matching code. Follows TDD: returns test file first, then component. File will be created in kebab-case.

Parameters:

• name (string, required): Component name in PascalCase (e.g., "UserCard", "AuthLayout")
• feature (string, optional): Feature name to place component in feature directory (e.g., "auth", "settings")
• type (enum, optional): "component" | "layout" | "page" (default: "component")
• props (array, optional): List of prop names the component should accept
• hasChildren (boolean, optional): Whether component accepts children prop (default: false)

TDD file order: Test (__tests__/unit/components/<kebab>.test.tsx or src/components/__tests__/<kebab>.test.tsx) → component → barrel if feature.

Example:

{
  "name": "AuthLayout",
  "feature": "auth",
  "props": ["title"],
  "hasChildren": true
}

Note: File will be created as auth-layout.tsx (kebab-case).

4. create_service

Create service functions with TypeScript interfaces. Uses configured Axios instance from @lib/axios. Analyzes existing patterns and generates matching code. Follows TDD: returns test file first, then types, then service.

Parameters:

• name (string, required): Service name in kebab-case (e.g., "user", "auth", "product"). File will be created as {name}-service.ts
• feature (string, optional): Feature name to place service in feature directory (e.g., "auth", "settings")
• methods (array, optional): HTTP methods ["get", "post", "put", "delete", "patch"] (default: ["get"])
• endpoints (array, optional): API endpoints (default: uses the name parameter)
• hasInterfaces (boolean, optional): Generate TypeScript interfaces (default: true)

TDD file order: Test (__tests__/unit/services/<name>-service.test.ts or src/services/__tests__/<name>-service.test.ts) → types → service → barrel.

Example:

{
  "name": "auth",
  "feature": "auth",
  "methods": ["get", "post"],
  "hasInterfaces": true
}

Note: File will be created as auth-service.ts in features/auth/services/.

5. create_hook

Create a custom React hook. Analyzes existing hook patterns and generates matching code. Follows TDD: returns test file first, then hook. File will be created in kebab-case.

Parameters:

• name (string, required): Hook name (e.g., "useAuth", "useUserData"). Will be prefixed with "use" if not provided.
• feature (string, optional): Feature name to place hook in feature directory (e.g., "auth", "settings")
• usesReactQuery (boolean, optional): Use TanStack Query / React Query patterns (default: true)
• returnType (enum, optional): "object" | "array" | "primitive" (default: "object")

TDD file order: Test (__tests__/unit/hooks/<kebab>.test.tsx or src/hooks/__tests__/<kebab>.test.tsx) → hook → barrel.

Note: Hook names will automatically be prefixed with "use" if not provided. File will be created in kebab-case (e.g., use-auth.ts).

Example:

{
  "name": "useAuth",
  "feature": "auth",
  "usesReactQuery": true,
  "returnType": "object"
}

6. create_page

Create a page component within a feature using Twigs React UI library. The feature must exist before creating a page. Follows TDD: returns test file first, then page. File will be created in kebab-case.

Parameters:

• name (string, required): Page name in PascalCase (e.g., "LoginPage", "GeneralSettings")
• feature (string, required): Feature name where the page will be created (e.g., "auth", "settings")
• hasAuth (boolean, optional): Whether this is a protected page requiring authentication (default: true)

TDD file order: Test (__tests__/pages/<kebab>.test.tsx) → page → pages index.

Note: Layouts are handled by the routing layer, not individual pages. Consider using create_route instead, which creates both the page and route entry automatically.

Example:

{
  "name": "LoginPage",
  "feature": "auth",
  "hasAuth": false
}

Note: File will be created as login-page.tsx (kebab-case).

7. create_util

Create a utility function, constant, or class. Analyzes existing code patterns and generates matching utilities. Follows TDD: returns test file first, then utility.

Parameters:

• name (string, required): Utility name in camelCase (e.g., "formatDate", "calculateTotal")
• feature (string, optional): Feature name to place utility in feature directory (e.g., "auth", "settings")
• type (enum, optional): "function" | "constant" | "class" (default: "function")
• exportType (enum, optional): "named" | "default" (default: "named")

TDD file order: Test (__tests__/unit/utils/<name>.test.ts or src/utils/__tests__/<name>.test.ts) → util → barrel.

Example:

{
  "name": "formatDate",
  "feature": "settings",
  "type": "function",
  "exportType": "named"
}

How It Works

1. Project Detection: Automatically finds the project root by looking for package.json and tsconfig.json
2. Pattern Analysis: Analyzes existing code to understand your project's patterns and conventions
3. TDD Code Generation: Generates test files first, followed by implementation files, matching your existing patterns
4. File Instructions: Returns a files array of FileInstruction objects. Each object has: path, contents, action, and description. Apply them in order using the contents property

TDD Workflow

Every tool (except create_feature) follows this cycle:

1. Test file is generated first — a Vitest test with render/mock stubs
2. Implementation file follows — the actual component, service, hook, page, or utility
3. Barrel export — index file update (when applicable)

The developer then:

1. Creates the test file (it should fail initially)
2. Creates the implementation file
3. Runs the tests to confirm they pass
4. Iterates on both test and implementation as needed

Project Structure Requirements

The MCP server automatically detects your project root by searching upward from the current working directory until it finds both:

• package.json file
• tsconfig.json file

Expected project structure:

your-project/
├── package.json
├── tsconfig.json
├── src/
│   ├── features/
│   │   └── [feature-name]/
│   │       ├── pages/
│   │       ├── components/
│   │       ├── services/
│   │       ├── hooks/
│   │       ├── types/
│   │       ├── utils/
│   │       ├── __tests__/
│   │       │   ├── unit/
│   │       │   │   ├── hooks/
│   │       │   │   ├── services/
│   │       │   │   ├── components/
│   │       │   │   ├── pages/
│   │       │   │   └── utils/
│   │       │   ├── integration/
│   │       │   └── pages/
│   │       ├── tdd.md
│   │       └── routes.tsx
│   ├── components/
│   ├── services/
│   ├── hooks/
│   ├── utils/
│   ├── lib/
│   │   └── axios.ts
│   ├── test/
│   │   └── test-utils.tsx
│   ├── routes/
│   │   ├── index.tsx
│   │   ├── protected.tsx
│   │   └── public.tsx
│   └── ...
└── ...

Naming Conventions

The MCP server follows and enforces these naming conventions:

• Features: kebab-case, lowercase (e.g., auth, settings, user-management)
• Components: PascalCase for code, kebab-case for files (e.g., UserCard → user-card.tsx)
• Hooks: camelCase with "use" prefix, kebab-case for files (e.g., useAuth → use-auth.ts)
• Services: kebab-case with "-service" suffix (e.g., auth-service.ts)
• Pages: PascalCase for code, kebab-case for files (e.g., LoginPage → login-page.tsx)
• Files: All files use kebab-case naming

Testing Stack

The generated test files are built for the following stack (as configured in the Nexgate template):

| Concern | Tool | |---------|------| | Test runner | Vitest | | Component / hook rendering | @testing-library/react via @test/test-utils | | DOM assertions | @testing-library/jest-dom | | HTTP mocking | vi.mock("@lib/axios") (Axios) | | Data-fetching mocking | vi.mock("@tanstack/react-query") |

All generated tests use describe / it blocks and vi for mocking, consistent with Vitest conventions.

Troubleshooting

Project Root Not Found

If the server can't find your project root:

• Ensure package.json and tsconfig.json exist in your project root
• Run the server from within your project directory or a subdirectory
• Check that the files are not in a nested location

Tools Not Working

• Verify the MCP server is running and properly configured in your client
• Check that you're in a valid Nexgate project directory
• Ensure Node.js version is >= 20.0.0

Stdio Errors

• Verify Node.js version: node --version (should be >= 20.0.0)
• Check that the server binary is executable
• Review MCP client logs for detailed error messages

License

MIT

Related Packages

• @sparrowengg/nexgate - CLI tool for initializing Nexgate projects

Model Context Protocol

This package implements the Model Context Protocol (MCP), an open standard for connecting AI assistants to external data sources and tools. MCP enables AI assistants to interact with your codebase intelligently and generate code that matches your project's conventions.