HubAI MCP

An MCP (Model Context Protocol) 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

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:

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

For example:

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

hubai-mcp start

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

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:

{
  "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

npm run build

Inspect with MCP Inspector

Start the server, then in another terminal:

npm run inspect

This opens the MCP Inspector UI connected to http://localhost:4000/mcp.

Release

npm run release

Uses standard-version with conventional commits to bump the version and generate a changelog.

License

MIT