Metadata-Version: 2.4
Name: rationalbloks-mcp
Version: 0.4.2
Summary: Unified MCP Server for RationalBloks - Backend API + Frontend Generation for AI agents
Project-URL: Homepage, https://rationalbloks.com
Project-URL: Documentation, https://rationalbloks.com/docs/mcp
Project-URL: Repository, https://github.com/rationalbloks/rationalbloks-mcp
Project-URL: Issues, https://github.com/rationalbloks/rationalbloks-mcp/issues
Author-email: RationalBloks <support@rationalbloks.com>
License: Proprietary
License-File: LICENSE
Keywords: ai,api,backend,claude,cursor,database,frontend,fullstack,gpt,mcp,smithery
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: certifi>=2024.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: sse-starlette>=2.1.0
Requires-Dist: starlette>=0.41.0
Requires-Dist: uvicorn>=0.32.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# RationalBloks MCP Server

**Unified MCP Server for RationalBloks** - Build fullstack applications with AI agents. Connect Claude Desktop, Cursor, VS Code Copilot, or any MCP-compatible client to create complete backends AND generate frontends.

[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/rationalbloks-mcp.svg)](https://pypi.org/project/rationalbloks-mcp/)

## 🚀 What's New in v0.4.1

**Major Architecture Redesign** - Frontend MCP completely rewritten with granular, flexible tools:

- **Full Mode**: All 32 tools (18 backend + 14 frontend) - DEFAULT
- **Backend Mode**: 18 API/database tools
- **Frontend Mode**: 14 frontend generation tools

**Key Changes:**
- 14 granular frontend tools that work on ANY existing project
- `scaffold_frontend` - Apply all generators to your project (no cloning required)
- `generate_types`, `generate_api_service`, `generate_entity_view`, etc.
- All file operations use `encoding="utf-8"` for Windows compatibility
- `create_app` still available for full automation (clone + backend + scaffold)

## Installation

```bash
# Using uv (recommended)
uv pip install rationalbloks-mcp

# Using pip
pip install rationalbloks-mcp

# Using pipx (isolated environment)
pipx install rationalbloks-mcp
```

## Quick Start

### 1. Get Your API Key

1. Visit [rationalbloks.com/settings](https://rationalbloks.com/settings)
2. Create an API Key
3. Copy the key (format: `rb_sk_...`)

### 2. Configure Your AI Agent

#### VS Code / Cursor

Add to `settings.json`:

```json
{
  "mcp.servers": {
    "rationalbloks": {
      "command": "rationalbloks-mcp",
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here",
        "RATIONALBLOKS_MODE": "full"
      }
    }
  }
}
```

**Reload window:** Ctrl+Shift+P → "Developer: Reload Window"

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rationalbloks": {
      "command": "rationalbloks-mcp",
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here",
        "RATIONALBLOKS_MODE": "full"
      }
    }
  }
}
```

**Config location:**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### Smithery (One-Click Install)

```bash
npx @smithery/cli install @rationalbloks/mcp
```

## Modes

### Full Mode (Default) - 32 Tools

All tools for complete fullstack development:

```bash
export RATIONALBLOKS_MODE=full
rationalbloks-mcp
# or just: rationalbloks-mcp (full is default)
```

### Backend Mode - 18 Tools

API and database operations only:

```bash
export RATIONALBLOKS_MODE=backend
rationalbloks-mcp
# or: rationalbloks-mcp-backend
```

### Frontend Mode - 14 Tools

Frontend generation only:

```bash
export RATIONALBLOKS_MODE=frontend
rationalbloks-mcp
# or: rationalbloks-mcp-frontend
```

## Available Tools

### Backend Tools (18)

**Read Operations (11):**
| Tool | Description |
|------|-------------|
| `list_projects` | List all projects |
| `get_project` | Get project details |
| `get_schema` | Get JSON schema |
| `get_user_info` | Get user information |
| `get_job_status` | Check deployment status |
| `get_project_info` | Detailed project info |
| `get_version_history` | Git commit history |
| `get_template_schemas` | Available templates ⭐ Start here! |
| `get_subscription_status` | Plan and limits |
| `get_project_usage` | Resource metrics |
| `get_schema_at_version` | Schema at specific commit |

**Write Operations (7):**
| Tool | Description |
|------|-------------|
| `create_project` | Create new project from schema |
| `update_schema` | Update project schema |
| `deploy_staging` | Deploy to staging |
| `deploy_production` | Deploy to production |
| `delete_project` | Delete project |
| `rollback_project` | Rollback to previous version |
| `rename_project` | Rename project |

### Frontend Tools (14)

**Generation Tools (8) - Work on ANY existing project:**
| Tool | Description |
|------|-------------|
| `generate_types` | Generate TypeScript interfaces from schema |
| `generate_api_service` | Generate API client with CRUD operations |
| `generate_entity_view` | Generate list view for ONE entity |
| `generate_entity_form` | Generate create/edit form for ONE entity |
| `generate_all_views` | Generate all views for all entities |
| `generate_dashboard` | Generate dashboard with entity stats |
| `update_routes` | Add routes to App.tsx |
| `update_navbar` | Update navigation configuration |

**Scaffold Tools (2):**
| Tool | Description |
|------|-------------|
| `scaffold_frontend` | 🚀 **RECOMMENDED** - Apply ALL generators to existing project |
| `create_app` | Full automation (clone + backend + scaffold) |

**Utility Tools (4):**
| Tool | Description |
|------|-------------|
| `clone_template` | Clone rationalbloksfront template from GitHub |
| `configure_api_url` | Set API URL in frontend .env |
| `create_backend` | Create backend via Backend MCP |
| `get_template_structure` | Explore template file structure |

## Recommended Workflow

### If You Already Have a Project (Most Common)

Use `scaffold_frontend` - the RECOMMENDED approach for most use cases:

```
"Scaffold my frontend at ~/projects/my-app using this schema..."
```

This:
1. Generates TypeScript types
2. Creates API service with CRUD operations
3. Generates list views for each entity
4. Generates create/edit forms for each entity
5. Creates a dashboard with entity stats
6. Updates App.tsx with routes
7. Updates Navbar with navigation
8. Optionally sets API URL in .env

**Benefits:** Works on ANY existing project. No cloning. No backend creation.

### If You Need a Fresh Template First

Use `clone_template`, then `scaffold_frontend`:

```
"Clone the template to ~/projects/my-app, then scaffold using this schema..."
```

### If You Want Everything Automated

Use `create_app` for the full automation flow (clone + backend + scaffold):

```
"Create a complete task manager app in ~/projects"
```

## The `create_app` Tool

This is the primary tool that transforms a JSON schema into a complete working application:

### What It Does (13 Automated Steps)

1. **Clone Template** - Clone rationalbloksfront from GitHub
2. **Create Backend** - Create project via Backend MCP API
3. **Wait for Deployment** - Poll until staging is ready
4. **Generate Types** - Create TypeScript interfaces from schema
5. **Generate API Service** - Create typed HTTP client
6. **Generate Entity Views** - Create list/detail views for each entity
7. **Generate Forms** - Create add/edit forms with validation
8. **Generate Dashboard** - Create dashboard with entity cards
9. **Update Routes** - Configure React Router
10. **Update Navbar** - Add navigation links
11. **Cleanup** - Remove placeholder files
12. **Update package.json** - Set project name and description
13. **Install Dependencies** - Run `npm install`

### Usage

```
"Create a task manager app with projects and tasks in ~/projects"
```

The AI will:
1. Infer the schema (projects, tasks tables)
2. Call `create_app` with the schema
3. Return a complete working React app connected to a live REST API

### Input Schema

```json
{
  "name": "TaskManager",
  "description": "A task management application",
  "destination": "~/projects",
  "schema": {
    "projects": {
      "name": {"type": "string", "required": true},
      "description": {"type": "text"}
    },
    "tasks": {
      "title": {"type": "string", "required": true},
      "status": {"type": "string", "enum": ["todo", "in_progress", "done"]},
      "project_id": {"type": "uuid", "foreign_key": "projects.id"}
    }
  }
}
```

## Schema Format

⚠️ **CRITICAL: Use FLAT format (no 'fields' nesting)**

✅ **Correct:**
```json
{
  "users": {
    "email": {"type": "string", "required": true, "unique": true},
    "name": {"type": "string", "required": true}
  },
  "posts": {
    "title": {"type": "string", "required": true},
    "user_id": {"type": "uuid", "foreign_key": "users.id"}
  }
}
```

❌ **Wrong (will fail):**
```json
{
  "users": {
    "fields": {
      "email": {"type": "string"}
    }
  }
}
```

### Field Types

| Type | Description |
|------|-------------|
| `string` | Text (varchar) |
| `text` | Long text |
| `integer` | Whole numbers |
| `decimal` | Decimal numbers |
| `boolean` | True/false |
| `uuid` | Primary/foreign keys |
| `date` | Date only |
| `timestamp` | Date and time |
| `json` | JSON data |

### Field Properties

| Property | Type | Description |
|----------|------|-------------|
| `type` | string | **REQUIRED** - Field type |
| `required` | boolean | Field is required |
| `unique` | boolean | Unique constraint |
| `default` | any | Default value |
| `foreign_key` | string | Reference (format: `table.id`) |
| `enum` | array | Allowed values |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `RATIONALBLOKS_API_KEY` | Your API key | Required for STDIO |
| `RATIONALBLOKS_MODE` | Mode: full, backend, frontend | `full` |
| `RATIONALBLOKS_BASE_URL` | API Gateway URL | `https://businessblok.rationalbloks.com` |
| `RATIONALBLOKS_TIMEOUT` | Request timeout (seconds) | `30` |
| `RATIONALBLOKS_LOG_LEVEL` | Logging level | `INFO` |
| `TRANSPORT` | Transport: stdio, http | `stdio` |

## Entry Points

Three entry points for different use cases:

```bash
# Full mode (all 24 tools)
rationalbloks-mcp

# Backend only (18 tools)
rationalbloks-mcp-backend

# Frontend only (6 tools)
rationalbloks-mcp-frontend
```

## Example Prompts

### Quick Start (Recommended)

> "Create a todo app with projects and tasks in ~/projects"

This single prompt will create a complete working application!

### Backend Operations

> "List all my RationalBloks projects"

> "Create a project called 'e-commerce' with products, orders, and customers"

> "Deploy my project to staging"

> "Show me the deployment history"

> "Get me some template schemas to start with"

### Frontend Operations

> "Clone the frontend template to ~/projects/my-store"

> "What files are in the template?"

> "Connect my-store to the e-commerce backend"

### Fullstack (Full Mode)

> "Create a complete inventory management system with products, categories, and suppliers"

> "Build me an e-commerce store with product catalog and shopping cart"

> "Create a CRM with customers, contacts, and deals"

## Troubleshooting

### "Command not found"
```bash
pip show rationalbloks-mcp
which rationalbloks-mcp  # Unix
where rationalbloks-mcp  # Windows
```

### "API key required"
Ensure your key starts with `rb_sk_`

### Tools not loading
1. Check IDE Output panel for errors
2. Reload window (Ctrl+Shift+P → "Developer: Reload Window")
3. Verify settings.json syntax

### Schema errors
1. Use `get_template_schemas` to see correct format
2. Ensure FLAT format (no 'fields' nesting)
3. Every field needs a 'type' property

### Deployment stuck
1. Use `get_job_status` to check deployment status
2. Use `get_project_info` for detailed pod status
3. Common cause: schema format error (nested 'fields' key)

## Architecture

```
rationalbloks-mcp/
├── src/rationalbloks_mcp/
│   ├── __init__.py      # Unified entry point (32 tools)
│   ├── core/            # Shared infrastructure
│   │   ├── auth.py      # API key validation
│   │   ├── transport.py # STDIO + HTTP transport
│   │   └── server.py    # Base MCP server
│   ├── backend/         # 18 backend tools
│   │   ├── client.py    # LogicBlok HTTP client
│   │   └── tools.py     # Tool definitions
│   └── frontend/        # 14 frontend tools
│       ├── client.py        # Generation methods
│       ├── tools.py         # Tool definitions
│       └── app_generator.py # Full app automation
├── pyproject.toml       # Package configuration
├── smithery.yaml        # Smithery marketplace config
└── README.md            # This file
```

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 0.4.1 | 2026-02-03 | Major redesign: 14 granular frontend tools, scaffold_frontend |
| 0.3.5 | 2026-02-03 | Fixed encoding for Windows (utf-8) |
| 0.3.4 | 2026-02-03 | Fixed client to use /api/mcp/execute gateway pattern |
| 0.3.3 | 2026-02-03 | Added certifi for SSL cert resolution |
| 0.3.2 | 2026-02-03 | Fixed API URL (businessblok → logicblok) |
| 0.3.1 | 2026-02-03 | Fixed wildcard handler lookup bug |
| 0.3.0 | 2026-02-03 | Added create_app tool for complete app generation |
| 0.2.2 | 2026-01-28 | Fixed frontend template URL |
| 0.2.0 | 2026-01-25 | Unified backend + frontend package |
| 0.1.0 | 2026-01-20 | Initial release (backend only) |

## Support

- **Email:** support@rationalbloks.com
- **Docs:** [rationalbloks.com/docs/mcp](https://rationalbloks.com/docs/mcp)
- **Issues:** [github.com/rationalbloks/rationalbloks-mcp/issues](https://github.com/rationalbloks/rationalbloks-mcp/issues)

## License

Proprietary - Copyright 2026 RationalBloks. All Rights Reserved.
