npm package: @sparrowengg/nexgate-mcp
Description: MCP server for Nexgate app scaffolding
Latest version: 0.0.1-beta.7

# @sparrowengg/nexgate-mcp

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

[![npm version](https://img.shields.io/npm/v/@sparrowengg/nexgate-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@sparrowengg/nexgate-mcp)
[![Node.js version](https://img.shields.io/node/v/@sparrowengg/nexgate-mcp.svg?style=flat-square)](https://nodejs.org/)

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

```bash
npm install -g @sparrowengg/nexgate-mcp
```

### Local Installation

For project-specific usage:

```bash
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)

```bash
nexgate-mcp
```

Or if installed locally:

```bash
npx nexgate-mcp
```

### Configuring MCP Clients

Add the following to your Mcp configuration file:

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

For using npx (no installation required):

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](https://vitest.dev/) |
| 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) - CLI tool for initializing Nexgate projects

## Model Context Protocol

This package implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), 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.