npm package: @hubspire/hubai-mcp
Description: A mcp server for hubai project.
Author: Hubspire Team
Latest version: 1.1.4

# HubAI MCP

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that generates full-stack Hubspire projects from a unified schema. It provides AI-powered scaffolding tools for Nx monorepo workspaces with Apollo GraphQL backends and Vite/React frontends, all accessible through Cursor IDE.

## Prerequisites

- **Node.js** >= 24.13.0
- **npm** >= 11.6.2
- **Cursor IDE** (for MCP integration and auto-discovered rules/skills)

## Installation

```bash
npm install -g @hubspire/hubai-mcp
```

## Getting Started

Setting up HubAI MCP involves two steps: configuring Cursor rules/skills in your workspace and connecting the MCP server.

### 1. Configure Cursor Rules and Skills

Before using the MCP tools, run the `setup` command to write Cursor rules and skills into your workspace. This is a **one-time configuration step** per workspace:

```bash
hubai-mcp setup <absolute-path-to-workspace>
```

For example:

```bash
hubai-mcp setup /Users/you/projects/my-app
```

This writes the following into `<workspace>/.cursor/`:

| Directory | Contents |
|-----------|----------|
| `.cursor/rules/` | `hubspire-mcp.mdc` -- MCP usage guide and available tools reference |
| | `schema-design.mdc` -- Database, field type, and frontend design conventions |
| | `code-review.mdc` -- Code review criteria for generated backend code |
| `.cursor/skills/` | `create-hubspire-project/` -- End-to-end project creation workflow |
| | `design-project/` -- Unified Project Schema generation from requirements |
| | `review-project/` -- Code review workflow for generated code |

Cursor auto-discovers these files and makes them available as inline rules and invocable skills during AI-assisted development.

### 2. Start the MCP Server

```bash
hubai-mcp start
```

By default the server runs on port **4000**. Use `--port` to change it:

```bash
hubai-mcp start --port 8080
```

The server exposes:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | `POST` | Initialize a new MCP session |
| `/mcp` | `GET` / `DELETE` | Interact with or close an existing session (requires `mcp-session-id` header) |
| `/health` | `GET` | Health check (returns version and active session count) |

### 3. Connect Cursor to the MCP Server

Add the following to your workspace's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "HubAI MCP": {
      "url": "http://localhost:4000/mcp",
      "alwaysAllow": [
        "create_project",
        "create_workspace",
        "create_app",
        "create_lib",
        "create_crud",
        "create_relation",
        "validate_schema"
      ]
    }
  }
}
```

Cursor will now connect to the HubAI MCP server and make all tools available in agent mode.

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `validate_schema` | Validates a Unified Project Schema JSON against the schema definition |
| `create_project` | Takes a validated ProjectConfig and returns a step-by-step execution plan |
| `create_workspace` | Creates an Nx monorepo workspace with all config files |
| `create_app` | Creates an application (Apollo, subgraph, gateway, Express, serverless, Vite, Cypress) |
| `create_lib` | Creates a shared TypeScript library in `libs/` |
| `create_crud` | Generates a full CRUD module (GraphQL schema, model, resolver, datasource, loader, tests) |
| `create_relation` | Adds a relationship between two entities (one-to-one, many-to-one, many-to-many) |

All file-creating tools accept an optional `targetDir` parameter. When provided, files are written directly to disk and only a compact summary is returned -- this dramatically reduces AI context memory usage. **Always pass `targetDir`** when creating projects.

## Workflows

### Create a New Project

1. **Design the schema** -- Use the `design-project` skill to generate a Unified Project Schema from your requirements
2. **Validate** -- Call `validate_schema` with the generated JSON to check for errors
3. **Generate the plan** -- Call `create_project` with the validated schema
4. **Set the target directory** -- Replace `<WORKSPACE_DIR>` in the plan with your absolute workspace path
5. **Execute steps in order** -- Call each tool from the plan sequentially (`create_workspace` -> `create_app` -> `create_crud` -> `create_relation` -> `create_app`)
6. **Write supplementary files** -- Write the codegen config and DataLoader config files listed in the plan
7. **Run post-setup commands** -- Execute `npm install` and `npx graphql-codegen` in the workspace
8. **Review** -- Use the `review-project` skill to review generated backend code

### Add a New Entity

1. Call `create_crud` with the entity definition, field types, permissions, and `targetDir`
2. Call `create_relation` for any relationships to existing entities
3. Update the DataLoader config (`libs/config.ts`) and codegen config (`codegen.type.yaml`)

### Add a Relationship

1. Call `create_relation` with module names, foreign key, and relation type
2. Apply the returned modification instructions to existing files

## CLI Reference

```
Usage: hubai-mcp [command] [options]

Commands:
  start [options]    Start the MCP server
  setup <dir>        Write Cursor rules and skills into a workspace

Options:
  -v, --version      Output the current version

Start options:
  -p, --port <number>  Port to start the MCP server on (default: 4000)
```

## Development

### Build

```bash
npm run build
```

### Inspect with MCP Inspector

Start the server, then in another terminal:

```bash
npm run inspect
```

This opens the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) UI connected to `http://localhost:4000/mcp`.

### Release

```bash
npm run release
```

Uses [standard-version](https://github.com/conventional-changelog/standard-version) with conventional commits to bump the version and generate a changelog.

## License

[MIT](LICENSE)