@baasix/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,12 +1,14 @@
-# Baasix MCP Server
+# Baasix Local MCP Server
 
-A Model Context Protocol (MCP) server that provides Claude Desktop and other MCP clients with direct access to Baasix Backend-as-a-Service operations.
+A Model Context Protocol (MCP) server that provides Claude Desktop and other MCP clients with local access to Baasix Backend-as-a-Service operations.
+
+> **Note:** This is the **Local MCP** package that runs on your machine. Baasix also has a **Remote MCP** built into the core server at `/mcp` endpoint. See [Choosing Local vs Remote MCP](#choosing-local-vs-remote-mcp) for guidance.
 
 **Baasix** is an open-source BaaS that generates REST APIs from data models, featuring 50+ filter operators, visual workflows, multi-tenancy, and real-time subscriptions.
 
 ## Features
 
-- **45+ MCP Tools** for comprehensive Baasix operations
+- **57 MCP Tools** for comprehensive Baasix operations
 - **Schema Management** - Create, update, delete collections and relationships
 - **CRUD Operations** - Full item management with powerful query capabilities
 - **50+ Filter Operators** - From basic comparison to geospatial and JSONB queries
@@ -18,24 +20,36 @@ A Model Context Protocol (MCP) server that provides Claude Desktop and other MCP
 - **Multi-tenancy** - Tenant management and switching
 - **Realtime** - Enable/disable WAL-based realtime per collection
 
+## Choosing Local vs Remote MCP
+
+| Feature | Local MCP (this package) | Remote MCP (built-in) |
+|---------|--------------------------|----------------------|
+| **Transport** | stdio | HTTP (Streamable HTTP) |
+| **Setup** | Install `@baasix/mcp` | Enable `MCP_ENABLED=true` on server |
+| **Authentication** | Environment variables | HTTP headers |
+| **Best For** | Claude Desktop, local dev | Production, cloud, remote servers |
+| **Process** | Runs locally | Runs on Baasix server |
+| **Config File** | `.mcp.json` | `.mcp.json` or `.vscode/mcp.json` |
+
+**Use Local MCP when:**
+- Using Claude Desktop (requires stdio transport)
+- Working offline with local Baasix server
+- Need environment-based configuration
+
+**Use Remote MCP when:**
+- Connecting to remote/cloud Baasix servers
+- Using VS Code with GitHub Copilot (supports HTTP)
+- Want simpler setup without npm packages
+
 ## Quick Start
 
 ### 1. Install dependencies
 ```bash
-cd mcp
-npm install
+npm install @baasix/mcp
 ```
 
-### 2. Configure environment
-```bash
-cp .env.example .env
-# Edit .env with your Baasix server details
-```
-
-### 3. Start the MCP server
-```bash
-npm start
-```
+### 2. Configure your AI tool
+See [IDE Integration](#ide-integration) below.
 
 ## Configuration
 
@@ -50,34 +64,18 @@ npm start
 
 *Either `BAASIX_AUTH_TOKEN` OR both `BAASIX_EMAIL` and `BAASIX_PASSWORD` must be provided.
 
-### Environment Files
-- `.env` - Development environment (default)
-- `.env.production` - Production environment
-
-### Available Scripts
-- `npm run development` - Start with development environment
-- `npm start` - Start with production environment
-- `npm run dev` - Development mode with auto-restart
-- `npm test` - Run tests
-- `npm run debug` - Start with MCP inspector for debugging
-
 ## IDE Integration
 
-Baasix MCP Server integrates with various AI-powered development tools. Below are configuration examples for popular IDEs and tools.
-
-### Claude Desktop
+### Claude Code / Anthropic CLI
 
-Add to your Claude Desktop configuration (`claude_desktop_config.json`):
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+Create a `.mcp.json` file in your project root:
 
 ```json
 {
   "mcpServers": {
     "baasix": {
-      "command": "node",
-      "args": ["/path/to/baasix/mcp/server.js"],
+      "command": "npx",
+      "args": ["@baasix/mcp"],
       "env": {
         "BAASIX_URL": "http://localhost:8056",
         "BAASIX_EMAIL": "admin@baasix.com",
@@ -88,16 +86,24 @@ Add to your Claude Desktop configuration (`claude_desktop_config.json`):
 }
 ```
 
-### Claude Code (Anthropic CLI)
+Or add via CLI:
+```bash
+claude mcp add baasix -- npx @baasix/mcp
+```
+
+### Claude Desktop
 
-For Claude Code CLI, create a `.mcp.json` file in your project root:
+Add to your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "baasix": {
-      "command": "node",
-      "args": ["./mcp-server.js"],
+      "command": "npx",
+      "args": ["@baasix/mcp"],
       "env": {
         "BAASIX_URL": "http://localhost:8056",
         "BAASIX_EMAIL": "admin@baasix.com",
@@ -108,56 +114,51 @@ For Claude Code CLI, create a `.mcp.json` file in your project root:
 }
 ```
 
-Or add via CLI:
-```bash
-claude mcp add baasix npm run start
-```
-
 ### VS Code with GitHub Copilot
 
-For VS Code with GitHub Copilot, create `.vscode/mcp.json` in your project:
+For VS Code, you can use either Local MCP (stdio) or Remote MCP (HTTP).
+
+**Local MCP (stdio)** - Create `.vscode/mcp.json`:
 
 ```jsonc
 {
   "servers": {
     "baasix": {
       "type": "stdio",
-      "command": "node",
-      "args": ["./mcp-server.js"],
+      "command": "npx",
+      "args": ["@baasix/mcp"],
       "env": {
         "BAASIX_URL": "http://localhost:8056",
         "BAASIX_EMAIL": "admin@baasix.com",
         "BAASIX_PASSWORD": "admin@123"
       }
     }
-  },
-  "inputs": []
+  }
 }
 ```
 
-### Cursor IDE
-
-For Cursor, add to your Cursor settings or create a project-level configuration:
+**Remote MCP (HTTP)** - Create `.vscode/mcp.json`:
 
-```json
+```jsonc
 {
-  "mcpServers": {
+  "servers": {
     "baasix": {
-      "command": "node",
-      "args": ["./mcp-server.js"],
-      "env": {
-        "BAASIX_URL": "http://localhost:8056",
-        "BAASIX_EMAIL": "admin@baasix.com",
-        "BAASIX_PASSWORD": "admin@123"
+      "type": "http",
+      "url": "http://localhost:8056/mcp",
+      "headers": {
+        "X-MCP-Email": "${input:mcpEmail}",
+        "X-MCP-Password": "${input:mcpPassword}"
       }
     }
-  }
+  },
+  "inputs": [
+    { "id": "mcpEmail", "type": "promptString", "description": "Baasix Email" },
+    { "id": "mcpPassword", "type": "promptString", "description": "Password", "password": true }
+  ]
 }
 ```
 
-### Using the npm Package
-
-If you're using the published npm package instead of the source:
+### Cursor IDE
 
 ```json
 {
@@ -187,7 +188,6 @@ If you're using the published npm package instead of the source:
 | `baasix_delete_schema` | Delete a collection schema |
 | `baasix_add_index` | Add index to collection |
 | `baasix_remove_index` | Remove index from collection |
-| `baasix_migrate_indexes` | Add missing FK indexes to all collections |
 | `baasix_create_relationship` | Create M2O/O2M/M2M/M2A relationship |
 | `baasix_update_relationship` | Update existing relationship |
 | `baasix_delete_relationship` | Delete a relationship |
@@ -202,6 +202,7 @@ If you're using the published npm package instead of the source:
 | `baasix_create_item` | Create new item |
 | `baasix_update_item` | Update existing item |
 | `baasix_delete_item` | Delete item |
+| `baasix_sort_items` | Reorder items in collection |
 
 ### File Management (3 tools)
 | Tool | Description |
@@ -251,11 +252,14 @@ If you're using the published npm package instead of the source:
 | `baasix_send_notification` | Send notification to users |
 | `baasix_mark_notification_seen` | Mark notification as seen |
 
-### Settings (2 tools)
+### Settings & Templates (4 tools)
 | Tool | Description |
 |------|-------------|
 | `baasix_get_settings` | Get application settings |
 | `baasix_update_settings` | Update settings |
+| `baasix_list_templates` | List email templates |
+| `baasix_get_template` | Get email template |
+| `baasix_update_template` | Update email template |
 
 ### Realtime (5 tools)
 | Tool | Description |
@@ -270,7 +274,6 @@ If you're using the published npm package instead of the source:
 | Tool | Description |
 |------|-------------|
 | `baasix_server_info` | Get server health/info |
-| `baasix_sort_items` | Reorder items in collection |
 
 ## Filter Operators Reference
 
@@ -291,21 +294,8 @@ When using `baasix_list_items`, the `filter` parameter supports 50+ operators:
 {"field": {"contains": "text"}}       // Contains substring
 {"field": {"icontains": "text"}}      // Contains (case-insensitive)
 {"field": {"startswith": "pre"}}      // Starts with
-{"field": {"istartswith": "pre"}}     // Starts with (case-insensitive)
-{"field": {"endswith": "fix"}}        // Ends with
-{"field": {"iendswith": "fix"}}       // Ends with (case-insensitive)
 {"field": {"like": "pat%tern"}}       // SQL LIKE pattern
-{"field": {"ilike": "pat%tern"}}      // LIKE (case-insensitive)
 {"field": {"regex": "^\\d+$"}}        // Regular expression
-{"field": {"iregex": "pattern"}}      // Regex (case-insensitive)
-```
-
-### Null/Empty Operators
-```json
-{"field": {"isNull": true}}           // IS NULL
-{"field": {"isNull": false}}          // IS NOT NULL
-{"field": {"empty": true}}            // Empty string or null
-{"field": {"empty": false}}           // Not empty
 ```
 
 ### List Operators
@@ -313,34 +303,6 @@ When using `baasix_list_items`, the `filter` parameter supports 50+ operators:
 {"field": {"in": ["a", "b", "c"]}}    // In list
 {"field": {"nin": ["x", "y"]}}        // Not in list
 {"field": {"between": [10, 100]}}     // Between range
-{"field": {"nbetween": [10, 100]}}    // Not between
-```
-
-### Array Operators
-```json
-{"tags": {"arraycontains": ["a", "b"]}}    // Contains all elements
-{"tags": {"arraycontainsany": ["a", "b"]}} // Contains any element
-{"tags": {"arraylength": 3}}               // Array has exact length
-{"tags": {"arrayempty": true}}             // Array is empty
-```
-
-### JSONB Operators (PostgreSQL)
-```json
-{"meta": {"jsoncontains": {"key": "val"}}}      // JSON contains
-{"meta": {"jsoncontainedby": {"a": 1}}}         // JSON contained by
-{"meta": {"jsonhaskey": "key"}}                 // Has key
-{"meta": {"jsonhasanykeys": ["a", "b"]}}        // Has any keys
-{"meta": {"jsonhasallkeys": ["a", "b"]}}        // Has all keys
-{"meta": {"jsonpath": "$.store.book[0].title"}} // JSONPath query
-```
-
-### Geospatial Operators (PostGIS)
-```json
-{"location": {"dwithin": {"geometry": {"type": "Point", "coordinates": [-73.9, 40.7]}, "distance": 5000}}}
-{"location": {"intersects": {"type": "Polygon", "coordinates": [...]}}}
-{"location": {"contains": {"type": "Point", "coordinates": [...]}}}
-{"location": {"within": {"type": "Polygon", "coordinates": [...]}}}
-{"location": {"overlaps": {"type": "Polygon", "coordinates": [...]}}}
 ```
 
 ### Logical Operators
@@ -353,251 +315,10 @@ When using `baasix_list_items`, the `filter` parameter supports 50+ operators:
 ### Dynamic Variables
 ```json
 {"author_Id": {"eq": "$CURRENT_USER"}}    // Current user's ID
-{"createdAt": {"gte": "$NOW"}}            // Current timestamp
 {"createdAt": {"gte": "$NOW-DAYS_7"}}     // 7 days ago
-{"dueDate": {"lte": "$NOW+MONTHS_1"}}     // 1 month from now
 ```
 
-### Relation Filtering
-```json
-// Filter by related collection fields
-{"category.name": {"eq": "Electronics"}}
-{"author.role.name": {"eq": "admin"}}
-```
-
-## Query Parameters for baasix_list_items
-
-```javascript
-{
-  collection: "products",           // Required: collection name
-  filter: {...},                    // Filter object (see above)
-  sort: "createdAt:desc",          // Sort: "field:asc" or "field:desc"
-  page: 1,                         // Page number
-  limit: 10,                       // Items per page (-1 for all)
-  fields: ["*", "category.*"],     // Fields to include (* for all)
-  search: "keyword",               // Full-text search
-  searchFields: ["name", "desc"],  // Fields to search in
-  aggregate: {                     // Aggregation functions
-    total: {function: "sum", field: "price"},
-    count: {function: "count", field: "id"}
-  },
-  groupBy: ["category_Id"],        // Group by fields
-  relConditions: {                 // Filter related records
-    "reviews": {"approved": {"eq": true}}
-  }
-}
-```
-
-## Schema Definition Example
-
-When using `baasix_create_schema`:
-
-```javascript
-{
-  collection: "products",
-  schema: {
-    name: "Product",
-    timestamps: true,        // Adds createdAt, updatedAt
-    paranoid: false,         // Set true for soft deletes
-    fields: {
-      id: {
-        type: "UUID",
-        primaryKey: true,
-        defaultValue: {type: "UUIDV4"}
-      },
-      sku: {
-        type: "SUID",
-        unique: true,
-        defaultValue: {type: "SUID"}
-      },
-      name: {
-        type: "String",
-        allowNull: false,
-        values: {length: 255},
-        validate: {notEmpty: true, len: [3, 255]}
-      },
-      price: {
-        type: "Decimal",
-        values: {precision: 10, scale: 2},
-        defaultValue: 0.00,
-        validate: {min: 0, max: 999999.99}
-      },
-      quantity: {
-        type: "Integer",
-        defaultValue: 0,
-        validate: {isInt: true, min: 0}
-      },
-      email: {
-        type: "String",
-        validate: {isEmail: true}
-      },
-      tags: {
-        type: "Array",
-        values: {type: "String"},
-        defaultValue: []
-      },
-      metadata: {
-        type: "JSONB",
-        defaultValue: {}
-      }
-    }
-  }
-}
-```
-
-### Field Validation Rules
-
-| Rule | Type | Description |
-|------|------|-------------|
-| `min` | number | Minimum value for numeric fields |
-| `max` | number | Maximum value for numeric fields |
-| `isInt` | boolean | Validate as integer |
-| `notEmpty` | boolean | String cannot be empty |
-| `isEmail` | boolean | Valid email format |
-| `isUrl` | boolean | Valid URL format |
-| `len` | [min, max] | String length range |
-| `is` / `matches` | regex | Pattern matching |
-
-```javascript
-// Validation examples
-{
-  "email": {
-    "type": "String",
-    "validate": {"isEmail": true, "notEmpty": true}
-  },
-  "age": {
-    "type": "Integer",
-    "validate": {"isInt": true, "min": 0, "max": 120}
-  },
-  "username": {
-    "type": "String",
-    "validate": {"notEmpty": true, "len": [3, 50]}
-  },
-  "phone": {
-    "type": "String",
-    "validate": {"matches": "^\\+?[1-9]\\d{1,14}$"}
-  }
-}
-```
-
-### Default Value Types
-
-| Type | Description |
-|------|-------------|
-| `UUIDV4` | Random UUID v4 |
-| `SUID` | Short unique ID (compact, URL-safe) |
-| `NOW` | Current timestamp |
-| `AUTOINCREMENT` | Auto-incrementing integer |
-| `SQL` | Custom SQL expression |
-| Static | Any constant value (`"active"`, `false`, `0`) |
-
-```javascript
-// Default value examples
-{
-  "id": {"type": "UUID", "defaultValue": {"type": "UUIDV4"}},
-  "shortCode": {"type": "SUID", "defaultValue": {"type": "SUID"}},
-  "createdAt": {"type": "DateTime", "defaultValue": {"type": "NOW"}},
-  "orderNum": {"type": "Integer", "defaultValue": {"type": "AUTOINCREMENT"}},
-  "sortOrder": {"type": "Integer", "defaultValue": {"type": "SQL", "value": "(SELECT MAX(sort)+1 FROM items)"}},
-  "status": {"type": "String", "defaultValue": "pending"},
-  "isActive": {"type": "Boolean", "defaultValue": true}
-}
-```
-
-### Supported Field Types
-- **String**: `values: {length: 255}` for VARCHAR
-- **Text**: Unlimited length text
-- **Integer**, **BigInt**: Whole numbers
-- **Decimal**: `values: {precision: 10, scale: 2}`
-- **Float**, **Real**, **Double**: Floating point
-- **Boolean**: true/false
-- **Date**, **DateTime**, **Time**: Date/time values
-- **UUID**: `defaultValue: {type: "UUIDV4"}`
-- **SUID**: `defaultValue: {type: "SUID"}` - Short unique ID
-- **JSONB**: JSON with indexing
-- **Array**: `values: {type: "String|Integer|etc"}`
-- **Geometry**, **Geography**: PostGIS spatial types
-- **Enum**: `values: {values: ["A", "B", "C"]}`
-
-## Relationship Types
-
-When using `baasix_create_relationship`:
-
-```javascript
-// Many-to-One (products.category_Id → categories.id)
-{
-  sourceCollection: "products",
-  relationshipData: {
-    type: "M2O",
-    name: "category",      // Creates category_Id field
-    target: "categories",
-    alias: "products"      // Reverse relation name
-  }
-}
-
-// Many-to-Many (products ↔ tags)
-// Auto-generates junction table: products_tags_tags_junction
-{
-  sourceCollection: "products",
-  relationshipData: {
-    type: "M2M",
-    name: "tags",
-    target: "tags",
-    alias: "products"
-  }
-}
-
-// Many-to-Many with custom junction table name
-// Useful when auto-generated name exceeds PostgreSQL's 63 char limit
-{
-  sourceCollection: "products",
-  relationshipData: {
-    type: "M2M",
-    name: "tags",
-    target: "tags",
-    alias: "products",
-    through: "product_tags"  // Custom junction table name (max 63 chars)
-  }
-}
-
-// Many-to-Any (polymorphic - comments can belong to posts OR products)
-{
-  sourceCollection: "comments",
-  relationshipData: {
-    type: "M2A",
-    name: "commentable",
-    tables: ["posts", "products"],
-    alias: "comments",
-    through: "comment_refs"  // Optional custom junction table name
-  }
-}
-```
-
-### Junction Tables (M2M/M2A)
-
-- **Auto-generated name**: `{source}_{target}_{name}_junction`
-- **Custom name**: Use `through` property (max 63 characters for PostgreSQL)
-- **Schema property**: Junction tables have `isJunction: true` in their schema definition
-- **Auto-indexed**: Foreign key columns are automatically indexed for better query performance
-
-## Permission Structure
-
-When using `baasix_create_permission`:
-
-```javascript
-{
-  role_Id: "uuid-of-role",
-  collection: "products",
-  action: "read",                    // read, create, update, delete
-  fields: ["*"],                     // Or specific: ["name", "price"]
-  conditions: {                      // Row-level security
-    "published": {"eq": true}
-  },
-  relConditions: {                   // Filter related data
-    "reviews": {"approved": {"eq": true}}
-  }
-}
-```
+For the complete list of 50+ operators, see the [Filter Reference](https://baasix.dev/docs/complete-filter-reference).
 
 ## Package Usage
 
@@ -606,7 +327,7 @@ When using `baasix_create_permission`:
 npm install @baasix/mcp
 ```
 
-### Usage
+### Programmatic Usage
 ```javascript
 import { startMCPServer } from '@baasix/mcp';
 
@@ -616,51 +337,18 @@ startMCPServer().catch((error) => {
 });
 ```
 
-### Custom Server Instance
-```javascript
-import { BaasixMCPServer } from '@baasix/mcp';
-
-const server = new BaasixMCPServer();
-server.run().catch(console.error);
-```
-
-## Claude Code CLI Commands
-
-```bash
-# Add MCP server
-claude mcp add baasix npm run start
-
-# Remove MCP server
-claude mcp remove baasix
-```
-
-## File Structure
-
-```
-mcp/
-├── server.js              # Entry point
-├── package.json           # Dependencies and scripts
-├── .env                   # Development config
-├── .env.example           # Template
-├── .env.production        # Production config
-├── README.md              # This file
-└── baasix/
-    ├── index.js           # MCP server implementation
-    └── config.js          # Configuration management
-```
-
 ## Requirements
 
 - Node.js 18+
-- Baasix server running (v0.1.0-alpha.2+)
+- Baasix server running (v0.1.0+)
 - PostgreSQL 14+ (with PostGIS for geospatial)
 
 ## Links
 
 - **Baasix Website**: https://baasix.dev
-- **Documentation**: https://baasix.dev/docs
+- **Documentation**: https://baasix.dev/docs/mcp-server-docs
 - **GitHub**: https://github.com/baasix/baasix
-- **npm Package**: https://www.npmjs.com/package/@baasix/baasix
+- **npm Package**: https://www.npmjs.com/package/@baasix/mcp
 
 ## License
 

package/bin/baasix-mcp.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+/**
+ * Baasix MCP Server CLI
+ *
+ * This is the entry point for running the MCP server via npx.
+ * Usage: npx @baasix/mcp
+ *
+ * Environment variables:
+ *   BAASIX_URL - URL of your Baasix server (default: http://localhost:8056)
+ *   BAASIX_AUTH_TOKEN - Static auth token (optional)
+ *   BAASIX_EMAIL - Email for auto-login (optional)
+ *   BAASIX_PASSWORD - Password for auto-login (optional)
+ */
+
+import { startMCPServer } from "../baasix/index.js";
+
+startMCPServer().catch((error) => {
+  console.error("Failed to start MCP server:", error);
+  process.exit(1);
+});

package/package.json

@@ -1,11 +1,15 @@
 {
     "name": "@baasix/mcp",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Model Context Protocol (MCP) server for Baasix Backend-as-a-Service - provides 40+ tools for schema management, CRUD operations with 50+ filter operators, relationships, permissions, files, workflows, and more",
     "type": "module",
     "main": "baasix/index.js",
+    "bin": {
+        "baasix-mcp": "./bin/baasix-mcp.js"
+    },
     "files": [
         "baasix/",
+        "bin/",
         "README.md"
     ],
     "scripts": {