multisite-cms-mcp 1.0.13 → 1.0.16

package/README.md

@@ -13,7 +13,10 @@ Add to your MCP configuration (e.g., `.cursor/mcp.json`):
   "mcpServers": {
     "multisite-cms": {
       "command": "npx",
-      "args": ["-y", "multisite-cms-mcp"]
+      "args": ["-y", "multisite-cms-mcp"],
+      "env": {
+        "FASTMODE_API_URL": "https://api.fastmode.ai"
+      }
     }
   }
 }
@@ -31,7 +34,63 @@ Then configure:
 {
   "mcpServers": {
     "multisite-cms": {
-      "command": "multisite-cms-mcp"
+      "command": "multisite-cms-mcp",
+      "env": {
+        "FASTMODE_API_URL": "https://api.fastmode.ai"
+      }
+    }
+  }
+}
+```
+
+## Authentication
+
+The MCP server uses **automatic browser-based authentication**. When you use a tool that requires authentication (`list_projects`, `get_tenant_schema`), the server will:
+
+1. **Open your browser** to app.fastmode.ai/device
+2. **Display a code** in your terminal (e.g., "ABCD-1234")
+3. You **log in** (if not already) and **click Authorize**
+4. **Done!** Credentials are saved and auto-refresh
+
+### How It Works
+
+```
+AI: Let me list your projects...
+[calls list_projects]
+
+MCP: Opening browser for authentication...
+     Visit: https://app.fastmode.ai/device
+     Code: ABCD-1234
+     
+     Waiting for authorization...
+
+[Browser opens, you click "Authorize"]
+
+MCP: Authenticated as you@email.com
+     Credentials saved to ~/.fastmode/credentials.json
+
+[Returns project list]
+```
+
+### Credentials
+
+- Stored in `~/.fastmode/credentials.json`
+- Access tokens auto-refresh (90-day refresh tokens)
+- No need to manually copy/paste tokens!
+
+### Manual Token (Optional)
+
+If you prefer manual setup, you can still set `FASTMODE_AUTH_TOKEN`:
+
+```json
+{
+  "mcpServers": {
+    "multisite-cms": {
+      "command": "npx",
+      "args": ["-y", "multisite-cms-mcp"],
+      "env": {
+        "FASTMODE_AUTH_TOKEN": "your-token-here"
+      }
     }
   }
 }
@@ -47,6 +106,49 @@ AI: What fields are available for blog posts?
 [calls get_schema]
 ```
 
+### `list_projects`
+List all FastMode projects you have access to. Use this to discover project IDs for `get_tenant_schema`.
+
+**Triggers authentication if needed.**
+
+```
+AI: Let me see what projects you have access to...
+[calls list_projects]
+
+Response:
+# Your FastMode Projects
+
+Found 2 projects:
+
+## 1. My Business Site
+- Project ID: abc-123-def-456
+- Subdomain: mybusiness.fastmode.ai
+- Your Role: owner
+
+## 2. Portfolio
+- Project ID: xyz-789-uvw-012
+- Subdomain: portfolio.fastmode.ai
+- Your Role: editor
+```
+
+### `get_tenant_schema`
+Fetch the complete schema for a specific project, including custom collections and custom fields on built-in collections.
+
+**Triggers authentication if needed.**
+
+**Parameters:**
+- `projectId` (string, required): The project ID (UUID from `list_projects`) or project name
+
+```
+AI: Let me get the schema for your "My Business Site" project...
+[calls get_tenant_schema with projectId: "My Business Site"]
+
+Response: Returns full schema including:
+- Built-in collections with any custom fields added
+- All custom collections with their fields
+- Correct token syntax for each field
+```
+
 ### `validate_manifest`
 Validate a manifest.json file structure.
 
@@ -103,6 +205,16 @@ Get the complete conversion documentation.
 **Parameters:**
 - `section` (string, optional): One of: `full`, `analysis`, `structure`, `manifest`, `templates`, `tokens`, `forms`, `assets`, `checklist`
 
+## Custom Collections & Custom Fields
+
+The CMS supports:
+
+1. **Custom Collections** - Tenant-defined content types (e.g., "services", "testimonials")
+2. **Custom Fields on Built-in Collections** - Additional fields added to Blog Posts, Authors, Team, Downloads
+
+Use `get_schema` for static documentation about how these work.
+Use `list_projects` + `get_tenant_schema` to fetch the actual custom collections and fields for a specific project.
+
 ## CMS Template Configuration
 
 Templates can be configured two ways:
@@ -132,20 +244,64 @@ This allows for a faster workflow: upload pages first, then configure templates
 When converting a website, an AI agent can:
 
 1. **Start** → Call `get_conversion_guide` for requirements
-2. **Check fields** → Call `get_schema` to see exact token names
-3. **Need example?** → Call `get_example` for specific pattern
-4. **Create manifest** → Call `validate_manifest` to check it
-5. **Create template** → Call `validate_template` to verify tokens
-6. **Final check** → Call `validate_package` for full validation
+2. **Check generic fields** → Call `get_schema` to see built-in token names
+3. **Discover projects** → Call `list_projects` (triggers auth if needed)
+4. **Get project schema** → Call `get_tenant_schema` with project ID/name for custom collections & fields
+5. **Need example?** → Call `get_example` for specific pattern
+6. **Create manifest** → Call `validate_manifest` to check it
+7. **Create template** → Call `validate_template` to verify tokens
+8. **Final check** → Call `validate_package` for full validation
+
+### Example Conversion Flow
+
+```
+User: Convert example.com for the "My Business" project
+
+AI: Let me first check what projects you have access to...
+[calls list_projects]
+
+[Browser opens for auth if needed]
+[User clicks Authorize]
+
+→ Found "My Business" with ID: abc-123
+
+AI: Now let me get the custom schema for this project...
+[calls get_tenant_schema with projectId: "abc-123"]
+→ Found custom collection "Services" with fields: title, description, icon
+→ Found custom field "category" on Blog Posts
+
+AI: I'll create templates using these tokens...
+- {{#each services}} {{title}} {{description}} {{/each}}
+- {{#each blogs}} {{name}} {{category}} {{/each}}
+```
+
+## Managing Device Sessions
+
+You can manage your authorized devices from the FastMode dashboard:
+
+1. Go to **app.fastmode.ai → Settings → Security**
+2. View all authorized MCP/CLI sessions
+3. Revoke access to any device
+
+Credentials are stored locally at `~/.fastmode/credentials.json`.
 
 ## Key Benefits
 
+- **One-click authentication** - No manual token copying
+- **Auto-refresh** - Tokens refresh automatically (90-day sessions)
+- **Project discovery** - `list_projects` shows all accessible projects
+- **Tenant-specific schemas** - `get_tenant_schema` fetches exact custom fields
 - **Validates as you work** - Catch errors during conversion, not after
 - **Correct field names** - No more guessing `{{title}}` vs `{{name}}`
 - **Triple brace reminders** - Ensures rich text uses `{{{...}}}`
 - **Structure validation** - Confirms package layout is correct
-- **Settings UI support** - Templates can be configured after upload
-- **Editor warnings** - Detects unconfigured CMS paths
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FASTMODE_API_URL` | No | `https://api.fastmode.ai` | API base URL |
+| `FASTMODE_AUTH_TOKEN` | No | - | Manual auth token (optional, device flow is preferred) |
 
 ## License
 

package/dist/index.js

@@ -10,6 +10,8 @@ const validate_template_1 = require("./tools/validate-template");
 const validate_package_1 = require("./tools/validate-package");
 const get_example_1 = require("./tools/get-example");
 const get_conversion_guide_1 = require("./tools/get-conversion-guide");
+const get_tenant_schema_1 = require("./tools/get-tenant-schema");
+const list_projects_1 = require("./tools/list-projects");
 const server = new index_js_1.Server({
     name: 'multisite-cms',
     version: '1.0.0',
@@ -139,6 +141,29 @@ const TOOLS = [
             required: [],
         },
     },
+    {
+        name: 'list_projects',
+        description: 'List all FastMode projects you have access to. Use this to discover project IDs and names for use with get_tenant_schema. Requires FASTMODE_AUTH_TOKEN environment variable to be set.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'get_tenant_schema',
+        description: 'Fetch the complete schema for a specific project including custom collections and custom fields on built-in collections. Use this when converting a website for an existing project to see their specific CMS configuration. Requires FASTMODE_AUTH_TOKEN environment variable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: {
+                    type: 'string',
+                    description: 'The project ID (UUID from list_projects) or project name',
+                },
+            },
+            required: ['projectId'],
+        },
+    },
 ];
 // Handle list tools request
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
@@ -179,6 +204,12 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'get_conversion_guide':
                 result = await (0, get_conversion_guide_1.getConversionGuide)(params.section || 'full');
                 break;
+            case 'list_projects':
+                result = await (0, list_projects_1.listProjects)();
+                break;
+            case 'get_tenant_schema':
+                result = await (0, get_tenant_schema_1.getTenantSchema)(params.projectId);
+                break;
             default:
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/dist/lib/api-client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Centralized API client for FastMode API requests
+ * Uses stored credentials with automatic refresh, or falls back to env var
+ */
+export interface ApiConfig {
+    apiUrl: string;
+    authToken: string | null;
+}
+/**
+ * Get API URL from environment or default
+ */
+export declare function getApiUrl(): string;
+/**
+ * Get API configuration - tries stored credentials first, then env var
+ */
+export declare function getApiConfigAsync(): Promise<ApiConfig>;
+/**
+ * Synchronous version - only checks env var (for quick checks)
+ */
+export declare function getApiConfig(): ApiConfig;
+/**
+ * Check if authentication is configured (either stored credentials or env var)
+ */
+export declare function isAuthConfigured(): boolean;
+/**
+ * Check if we need to trigger the device flow
+ */
+export declare function needsAuthentication(): Promise<boolean>;
+/**
+ * Get a helpful message for authentication
+ */
+export declare function getAuthRequiredMessage(): string;
+/**
+ * API request options
+ */
+export interface ApiRequestOptions {
+    tenantId?: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: unknown;
+}
+/**
+ * API error response
+ */
+export interface ApiError {
+    success: false;
+    error: string;
+    statusCode: number;
+    needsAuth?: boolean;
+}
+/**
+ * Make an authenticated API request
+ * Uses stored credentials with auto-refresh, or falls back to env var
+ */
+export declare function apiRequest<T>(endpoint: string, options?: ApiRequestOptions): Promise<{
+    data: T;
+} | ApiError>;
+/**
+ * Check if a response is an error
+ */
+export declare function isApiError(response: unknown): response is ApiError;
+/**
+ * Check if error requires authentication
+ */
+export declare function needsAuthError(error: ApiError): boolean;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/lib/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAgB5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAKxC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG,QAAQ,CAAC,CAoEjC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,QAAQ,CAOlE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEvD"}

package/dist/lib/api-client.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Centralized API client for FastMode API requests
+ * Uses stored credentials with automatic refresh, or falls back to env var
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApiUrl = getApiUrl;
+exports.getApiConfigAsync = getApiConfigAsync;
+exports.getApiConfig = getApiConfig;
+exports.isAuthConfigured = isAuthConfigured;
+exports.needsAuthentication = needsAuthentication;
+exports.getAuthRequiredMessage = getAuthRequiredMessage;
+exports.apiRequest = apiRequest;
+exports.isApiError = isApiError;
+exports.needsAuthError = needsAuthError;
+const credentials_1 = require("./credentials");
+/**
+ * Get API URL from environment or default
+ */
+function getApiUrl() {
+    return process.env.FASTMODE_API_URL || 'https://api.fastmode.ai';
+}
+/**
+ * Get API configuration - tries stored credentials first, then env var
+ */
+async function getApiConfigAsync() {
+    // First, try to get valid stored credentials
+    const credentials = await (0, credentials_1.getValidCredentials)();
+    if (credentials) {
+        return {
+            apiUrl: getApiUrl(),
+            authToken: credentials.accessToken,
+        };
+    }
+    // Fall back to environment variable (for backward compatibility)
+    return {
+        apiUrl: getApiUrl(),
+        authToken: process.env.FASTMODE_AUTH_TOKEN || null,
+    };
+}
+/**
+ * Synchronous version - only checks env var (for quick checks)
+ */
+function getApiConfig() {
+    return {
+        apiUrl: getApiUrl(),
+        authToken: process.env.FASTMODE_AUTH_TOKEN || null,
+    };
+}
+/**
+ * Check if authentication is configured (either stored credentials or env var)
+ */
+function isAuthConfigured() {
+    return (0, credentials_1.hasCredentials)() || !!process.env.FASTMODE_AUTH_TOKEN;
+}
+/**
+ * Check if we need to trigger the device flow
+ */
+async function needsAuthentication() {
+    const credentials = await (0, credentials_1.getValidCredentials)();
+    if (credentials)
+        return false;
+    if (process.env.FASTMODE_AUTH_TOKEN)
+        return false;
+    return true;
+}
+/**
+ * Get a helpful message for authentication
+ */
+function getAuthRequiredMessage() {
+    return `# Authentication Required
+
+You need to authenticate to use this tool.
+
+**Starting authentication flow...**
+
+A browser window will open for you to log in. If it doesn't open automatically, you'll see a URL to visit.
+`;
+}
+/**
+ * Make an authenticated API request
+ * Uses stored credentials with auto-refresh, or falls back to env var
+ */
+async function apiRequest(endpoint, options = {}) {
+    const config = await getApiConfigAsync();
+    if (!config.authToken) {
+        return {
+            success: false,
+            error: 'Not authenticated',
+            statusCode: 401,
+            needsAuth: true,
+        };
+    }
+    const url = `${config.apiUrl}${endpoint.startsWith('/') ? endpoint : '/' + endpoint}`;
+    const headers = {
+        'Authorization': `Bearer ${config.authToken}`,
+        'Content-Type': 'application/json',
+    };
+    if (options.tenantId) {
+        headers['X-Tenant-Id'] = options.tenantId;
+    }
+    try {
+        const response = await fetch(url, {
+            method: options.method || 'GET',
+            headers,
+            body: options.body ? JSON.stringify(options.body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            // Check if this is an auth error
+            if (response.status === 401) {
+                return {
+                    success: false,
+                    error: 'Authentication expired or invalid',
+                    statusCode: 401,
+                    needsAuth: true,
+                };
+            }
+            return {
+                success: false,
+                error: data.error || `API request failed with status ${response.status}`,
+                statusCode: response.status,
+            };
+        }
+        return data;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('fetch') || message.includes('network') || message.includes('ECONNREFUSED')) {
+            return {
+                success: false,
+                error: `Network error: Unable to connect to ${config.apiUrl}`,
+                statusCode: 0,
+            };
+        }
+        return {
+            success: false,
+            error: message,
+            statusCode: 0,
+        };
+    }
+}
+/**
+ * Check if a response is an error
+ */
+function isApiError(response) {
+    return (typeof response === 'object' &&
+        response !== null &&
+        'success' in response &&
+        response.success === false);
+}
+/**
+ * Check if error requires authentication
+ */
+function needsAuthError(error) {
+    return error.needsAuth === true || error.statusCode === 401;
+}

package/dist/lib/credentials.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stored credentials for the MCP server
+ */
+export interface StoredCredentials {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    email: string;
+    name?: string;
+}
+/**
+ * Get the path to the credentials file
+ */
+export declare function getCredentialsPath(): string;
+/**
+ * Load stored credentials from disk
+ */
+export declare function loadCredentials(): StoredCredentials | null;
+/**
+ * Save credentials to disk
+ */
+export declare function saveCredentials(credentials: StoredCredentials): void;
+/**
+ * Delete stored credentials
+ */
+export declare function deleteCredentials(): void;
+/**
+ * Check if credentials exist
+ */
+export declare function hasCredentials(): boolean;
+/**
+ * Check if the access token is expired or about to expire
+ */
+export declare function isTokenExpired(credentials: StoredCredentials, bufferMinutes?: number): boolean;
+/**
+ * Get the API URL from environment or default
+ */
+export declare function getApiUrl(): string;
+/**
+ * Refresh the access token using the refresh token
+ */
+export declare function refreshAccessToken(credentials: StoredCredentials): Promise<StoredCredentials | null>;
+/**
+ * Get valid credentials, refreshing if needed
+ * Returns null if no credentials or refresh fails
+ */
+export declare function getValidCredentials(): Promise<StoredCredentials | null>;
+/**
+ * Get the current auth token (access token) if available and valid
+ */
+export declare function getAuthToken(): Promise<string | null>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/lib/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/lib/credentials.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAYD;;GAEG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,GAAG,IAAI,CAoB1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAUpE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAUxC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,iBAAiB,EAAE,aAAa,GAAE,MAAU,GAAG,OAAO,CAIjG;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAyC1G;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAoB7E;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG3D"}