latitude-mcp-server 2.2.3 → 2.2.5

package/dist/api.js

@@ -31,6 +31,7 @@ exports.deployToLive = deployToLive;
 exports.getPromptNames = getPromptNames;
 const logger_util_js_1 = require("./utils/logger.util.js");
 const config_util_js_1 = require("./utils/config.util.js");
+const promptl_ai_1 = require("promptl-ai");
 const logger = logger_util_js_1.Logger.forContext('api.ts');
 const DEFAULT_BASE_URL = 'https://gateway.latitude.so';
 const API_VERSION = 'v3';
@@ -398,39 +399,254 @@ async function runDocument(path, parameters, versionUuid = 'live') {
     });
 }
 /**
- * Identify which documents fail validation by testing each one individually.
- * Used when a batch publish fails to provide actionable error messages.
+ * Error code to human-readable fix suggestion mapping
+ */
+const ERROR_SUGGESTIONS = {
+    'message-tag-inside-message': {
+        rootCause: 'Message/role tags (<system>, <user>, <assistant>, <tool>) cannot be nested inside each other.',
+        suggestion: 'Move the nested tag outside its parent. If showing an example, use a code block (```yaml) instead of actual role tags.',
+    },
+    'content-tag-inside-content': {
+        rootCause: 'Content tags (<text>, <image>, <file>, <tool-call>) must be directly inside message tags.',
+        suggestion: 'Restructure so content tags are direct children of message tags, not nested in other content.',
+    },
+    'step-tag-inside-step': {
+        rootCause: 'Step/response tags cannot be nested inside each other.',
+        suggestion: 'Move the <response> tag outside its parent <response> tag.',
+    },
+    'config-not-found': {
+        rootCause: 'PromptL files require a YAML configuration section at the top.',
+        suggestion: 'Add config at the beginning:\n---\nprovider: openai\nmodel: gpt-4\n---',
+    },
+    'config-already-declared': {
+        rootCause: 'Only one configuration section is allowed per file.',
+        suggestion: 'Remove the duplicate --- config --- section.',
+    },
+    'invalid-config': {
+        rootCause: 'The YAML configuration has syntax or validation errors.',
+        suggestion: 'Check YAML syntax. Required fields: model. Optional: provider, temperature, schema.',
+    },
+    'unclosed-block': {
+        rootCause: 'A tag or block was opened but never closed.',
+        suggestion: 'Add the missing closing tag. Check for typos in tag names.',
+    },
+    'unexpected-eof': {
+        rootCause: 'The file ended unexpectedly, likely due to unclosed tags or blocks.',
+        suggestion: 'Ensure all opened tags ({#if}, {#each}, <system>, etc.) are properly closed.',
+    },
+    'variable-not-defined': {
+        rootCause: 'A variable is used but not provided in parameters.',
+        suggestion: 'Either pass this variable when calling the prompt, or define it with {#let}.',
+    },
+    'invalid-tool-call-placement': {
+        rootCause: 'Tool calls (<tool-call>) can only appear inside <assistant> messages.',
+        suggestion: 'Move the <tool-call> tag inside an <assistant> block.',
+    },
+};
+/**
+ * Get snippet from content around a position
+ */
+function getSnippet(content, startIndex, endIndex) {
+    const snippet = content.substring(startIndex, Math.min(endIndex, startIndex + 100));
+    return snippet.split('\n')[0] || snippet;
+}
+/**
+ * Pre-validate PromptL content using the official promptl-ai library.
+ * Returns detailed, actionable error messages.
+ */
+async function validatePromptLContent(content, path) {
+    const issues = [];
+    try {
+        // Use official promptl-ai scan function for validation
+        const result = await (0, promptl_ai_1.scan)({
+            prompt: content,
+            fullPath: path,
+            requireConfig: false, // Don't require config for flexibility
+        });
+        // Convert CompileErrors to our ValidationIssue format
+        for (const compileError of result.errors) {
+            // CompileError has start?.line (Position) and startIndex (number)
+            const lineNumber = compileError.start?.line;
+            const snippet = getSnippet(content, compileError.startIndex, compileError.endIndex);
+            // Get human-readable suggestion based on error code
+            const suggestionInfo = ERROR_SUGGESTIONS[compileError.code] || {
+                rootCause: compileError.message,
+                suggestion: 'Review the PromptL documentation for correct syntax.',
+            };
+            issues.push({
+                type: 'error',
+                message: compileError.message,
+                rootCause: suggestionInfo.rootCause,
+                suggestion: suggestionInfo.suggestion,
+                lineNumber,
+                snippet,
+            });
+        }
+    }
+    catch (err) {
+        // Handle parse errors (thrown, not accumulated)
+        if (err instanceof promptl_ai_1.CompileError) {
+            const lineNumber = err.start?.line;
+            const snippet = getSnippet(content, err.startIndex, err.endIndex);
+            const suggestionInfo = ERROR_SUGGESTIONS[err.code] || {
+                rootCause: err.message,
+                suggestion: 'Fix the syntax error at the indicated location.',
+            };
+            issues.push({
+                type: 'error',
+                message: err.message,
+                rootCause: suggestionInfo.rootCause,
+                suggestion: suggestionInfo.suggestion,
+                lineNumber,
+                snippet,
+            });
+        }
+        else {
+            // Unknown error - still report it
+            issues.push({
+                type: 'error',
+                message: err instanceof Error ? err.message : 'Unknown validation error',
+                rootCause: 'An unexpected error occurred during validation.',
+                suggestion: 'Check the prompt content for syntax errors.',
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Identify failing documents using binary search for efficiency.
+ * For N documents, worst case is O(N log N) API calls instead of O(N).
  */
 async function identifyFailingDocuments(changes) {
     const failed = [];
-    for (const change of changes) {
-        if (change.status === 'deleted')
-            continue; // Deletes don't have content validation
-        try {
-            // Create a test draft for this single document
-            const testDraft = await createVersion(`validation-test-${change.path}`);
-            // Push just this document
-            await pushChanges(testDraft.uuid, [change]);
-            // Try to publish - this will fail if document has validation errors
-            await publishVersion(testDraft.uuid);
-            // If we get here, document is valid - the draft was published but that's ok
-            logger.debug(`Document ${change.path} validated successfully`);
-        }
-        catch (error) {
-            // This document failed - capture the error
-            const errorMsg = error instanceof LatitudeApiError
-                ? error.message
-                : (error instanceof Error ? error.message : 'Unknown validation error');
+    const nonDeleteChanges = changes.filter(c => c.status !== 'deleted');
+    if (nonDeleteChanges.length === 0)
+        return failed;
+    // First, run local validation to catch obvious issues without API calls
+    for (const change of nonDeleteChanges) {
+        if (!change.content)
+            continue;
+        const localIssues = await validatePromptLContent(change.content, change.path);
+        const errors = localIssues.filter((i) => i.type === 'error');
+        if (errors.length > 0) {
+            const mainError = errors[0];
             failed.push({
                 path: change.path,
-                error: errorMsg,
-                content: change.content?.substring(0, 200) + (change.content && change.content.length > 200 ? '...' : ''),
+                error: mainError.message,
+                rootCause: mainError.rootCause,
+                suggestion: mainError.suggestion,
+                lineNumber: mainError.lineNumber,
+                snippet: mainError.snippet,
             });
-            logger.debug(`Document ${change.path} failed validation: ${errorMsg}`);
+        }
+    }
+    // If we found local validation errors, return those first
+    if (failed.length > 0) {
+        logger.info(`Found ${failed.length} document(s) with local validation errors`);
+        return failed;
+    }
+    // If local validation passed, use binary search to find API-level failures
+    logger.info(`Local validation passed, testing ${nonDeleteChanges.length} document(s) against API...`);
+    // For small batches (<=5), test individually
+    if (nonDeleteChanges.length <= 5) {
+        return await testDocumentsIndividually(nonDeleteChanges);
+    }
+    // For larger batches, use binary search
+    return await binarySearchFailures(nonDeleteChanges);
+}
+/**
+ * Test documents individually (for small batches)
+ */
+async function testDocumentsIndividually(changes) {
+    const failed = [];
+    for (const change of changes) {
+        const result = await testSingleDocument(change);
+        if (result) {
+            failed.push(result);
         }
     }
     return failed;
 }
+/**
+ * Test a single document and return failure details if it fails
+ */
+async function testSingleDocument(change) {
+    try {
+        const testDraft = await createVersion(`val-${Date.now()}-${change.path.slice(0, 20)}`);
+        await pushChanges(testDraft.uuid, [change]);
+        await publishVersion(testDraft.uuid);
+        return null; // Success
+    }
+    catch (error) {
+        const errorMsg = error instanceof LatitudeApiError
+            ? error.message
+            : (error instanceof Error ? error.message : 'Unknown error');
+        // Try to provide better root cause based on error patterns
+        let rootCause = 'The Latitude API rejected this document during publish validation.';
+        let suggestion = 'Review the document content for syntax errors or invalid configuration.';
+        if (errorMsg.includes('errors in the updated documents')) {
+            rootCause = 'The document has PromptL syntax or configuration errors that passed local validation but failed server-side validation.';
+            suggestion = 'Check for: 1) Invalid model/provider combination, 2) Malformed schema definition, 3) Invalid template syntax ({{ }}).';
+        }
+        // Run local validation to give more context
+        if (change.content) {
+            const localIssues = await validatePromptLContent(change.content, change.path);
+            if (localIssues.length > 0) {
+                const warnings = localIssues.filter((i) => i.type === 'warning');
+                if (warnings.length > 0) {
+                    suggestion += `\n\nAdditional observations:\n${warnings.map((w) => `- ${w.message}: ${w.suggestion}`).join('\n')}`;
+                }
+            }
+        }
+        return {
+            path: change.path,
+            error: errorMsg,
+            rootCause,
+            suggestion,
+            snippet: change.content?.substring(0, 300),
+        };
+    }
+}
+/**
+ * Use binary search to efficiently find failures in large batches.
+ * Splits the batch in half, tests each half, and recurses on failing halves.
+ */
+async function binarySearchFailures(changes) {
+    // Base case: single document
+    if (changes.length === 1) {
+        const result = await testSingleDocument(changes[0]);
+        return result ? [result] : [];
+    }
+    // Test the entire batch first
+    const batchValid = await testBatch(changes);
+    if (batchValid) {
+        return []; // All documents in this batch are valid
+    }
+    // Batch has failures - split and recurse
+    const mid = Math.floor(changes.length / 2);
+    const left = changes.slice(0, mid);
+    const right = changes.slice(mid);
+    // Test both halves in parallel
+    const [leftFailures, rightFailures] = await Promise.all([
+        binarySearchFailures(left),
+        binarySearchFailures(right),
+    ]);
+    return [...leftFailures, ...rightFailures];
+}
+/**
+ * Test if a batch of documents can be published successfully
+ */
+async function testBatch(changes) {
+    try {
+        const testDraft = await createVersion(`batch-val-${Date.now()}`);
+        await pushChanges(testDraft.uuid, changes);
+        await publishVersion(testDraft.uuid);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Create a synthetic Version object for no-op deploys.
  * Returns a fully populated Version with all required fields.
@@ -511,12 +727,30 @@ async function deployToLive(changes, _versionName) {
         logger.warn('Batch publish failed, identifying problematic documents...');
         const failedDocs = await identifyFailingDocuments(actualChanges);
         if (failedDocs.length > 0) {
-            const errorDetails = failedDocs.map(f => `- ${f.path}: ${f.error}`).join('\n');
+            // Build detailed, actionable error message for LLM consumption
+            const errorLines = [];
+            for (const doc of failedDocs) {
+                errorLines.push(`\n## ❌ ${doc.path}`);
+                errorLines.push(`**Error:** ${doc.error}`);
+                errorLines.push(`**Root Cause:** ${doc.rootCause}`);
+                if (doc.lineNumber) {
+                    errorLines.push(`**Location:** Line ${doc.lineNumber}`);
+                }
+                if (doc.snippet) {
+                    errorLines.push(`**Snippet:** \`${doc.snippet}\``);
+                }
+                errorLines.push(`**Fix:** ${doc.suggestion}`);
+            }
+            const message = `${failedDocs.length} document(s) failed validation:${errorLines.join('\n')}`;
             throw new LatitudeApiError({
                 name: 'DocumentValidationError',
                 errorCode: 'DOCUMENT_VALIDATION_FAILED',
-                message: `${failedDocs.length} document(s) failed validation:\n${errorDetails}`,
-                details: { failedDocuments: failedDocs },
+                message,
+                details: {
+                    failedDocuments: failedDocs,
+                    totalFailed: failedDocs.length,
+                    failedPaths: failedDocs.map(d => d.path),
+                },
             }, 422);
         }
         // Re-throw original error if we couldn't identify specific failures

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "latitude-mcp-server",
-	"version": "2.2.3",
+	"version": "2.2.5",
 	"description": "Simplified MCP server for Latitude.so prompt management - 8 focused tools for push, pull, run, and manage prompts",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -74,6 +74,7 @@
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.23.0",
 		"dotenv": "^17.2.3",
+		"promptl-ai": "^0.9.4",
 		"zod": "^4.1.13"
 	},
 	"publishConfig": {