latitude-mcp-server 2.2.4 → 2.2.6

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,84 +399,114 @@ async function runDocument(path, parameters, versionUuid = 'live') {
     });
 }
 /**
- * Pre-validate PromptL content locally to catch common issues before API call.
- * Returns detailed, actionable error messages.
+ * Error code to human-readable fix suggestion mapping
  */
-function validatePromptLContent(content, _path) {
+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.',
+    },
+};
+/**
+ * Pre-validate PromptL content using the official promptl-ai library.
+ * Returns detailed, actionable error messages with code frames.
+ */
+async function validatePromptLContent(content, path) {
     const issues = [];
-    const lines = content.split('\n');
-    // Check for YAML frontmatter
-    if (!content.startsWith('---')) {
-        issues.push({
-            type: 'error',
-            message: 'Missing YAML frontmatter',
-            rootCause: 'PromptL files must start with YAML frontmatter (---).',
-            suggestion: 'Add frontmatter at the beginning:\n---\nprovider: YourProvider\nmodel: your-model\n---',
+    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
         });
-    }
-    // Check for nested role tags (common mistake)
-    const roleStack = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const lineNum = i + 1;
-        // Check for opening role tags
-        const openMatches = line.matchAll(/<(system|user|assistant|tool)>/gi);
-        for (const match of openMatches) {
-            const tag = match[1].toLowerCase();
-            if (roleStack.length > 0) {
-                const parent = roleStack[roleStack.length - 1];
-                issues.push({
-                    type: 'error',
-                    message: `Nested role tag: <${tag}> inside <${parent.tag}>`,
-                    rootCause: `Role tags (<system>, <user>, <assistant>, <tool>) cannot be nested. Found <${tag}> at line ${lineNum} inside <${parent.tag}> that started at line ${parent.line}.`,
-                    suggestion: `Move the <${tag}> block outside of <${parent.tag}>. Each role tag must be at the top level. If showing an example, use a code block (\`\`\`yaml) instead of actual role tags.`,
-                    lineNumber: lineNum,
-                    snippet: line.trim(),
-                });
-            }
-            roleStack.push({ tag, line: lineNum });
-        }
-        // Check for closing role tags
-        const closeMatches = line.matchAll(/<\/(system|user|assistant|tool)>/gi);
-        for (const match of closeMatches) {
-            const tag = match[1].toLowerCase();
-            if (roleStack.length > 0 && roleStack[roleStack.length - 1].tag === tag) {
-                roleStack.pop();
-            }
+        // Convert CompileErrors to our ValidationIssue format
+        for (const compileError of result.errors) {
+            // 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',
+                code: compileError.code,
+                message: compileError.message,
+                rootCause: suggestionInfo.rootCause,
+                suggestion: suggestionInfo.suggestion,
+                location: compileError.start ? {
+                    line: compileError.start.line,
+                    column: compileError.start.column,
+                } : undefined,
+                codeFrame: compileError.frame, // The beautiful formatted code frame!
+            });
         }
     }
-    // Check for unclosed role tags
-    for (const unclosed of roleStack) {
-        issues.push({
-            type: 'error',
-            message: `Unclosed role tag: <${unclosed.tag}>`,
-            rootCause: `The <${unclosed.tag}> tag opened at line ${unclosed.line} is never closed.`,
-            suggestion: `Add </${unclosed.tag}> to close the tag.`,
-            lineNumber: unclosed.line,
-        });
-    }
-    // Check frontmatter has required fields
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (frontmatterMatch) {
-        const frontmatter = frontmatterMatch[1];
-        if (!frontmatter.includes('model:') && !frontmatter.includes('model :')) {
+    catch (err) {
+        // Handle parse errors (thrown, not accumulated)
+        if (err instanceof promptl_ai_1.CompileError) {
+            const suggestionInfo = ERROR_SUGGESTIONS[err.code] || {
+                rootCause: err.message,
+                suggestion: 'Fix the syntax error at the indicated location.',
+            };
             issues.push({
                 type: 'error',
-                message: 'Missing model in frontmatter',
-                rootCause: 'PromptL requires a model to be specified in the frontmatter.',
-                suggestion: 'Add model field:\n---\nmodel: gpt-4\n---\n\nOr with provider:\n---\nprovider: openai\nmodel: gpt-4\n---',
+                code: err.code,
+                message: err.message,
+                rootCause: suggestionInfo.rootCause,
+                suggestion: suggestionInfo.suggestion,
+                location: err.start ? {
+                    line: err.start.line,
+                    column: err.start.column,
+                } : undefined,
+                codeFrame: err.frame,
+            });
+        }
+        else {
+            // Unknown error - still report it
+            issues.push({
+                type: 'error',
+                code: 'unknown-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.',
             });
         }
-    }
-    // Check for empty content after frontmatter
-    const contentAfterFrontmatter = content.replace(/^---[\s\S]*?---/, '').trim();
-    if (!contentAfterFrontmatter) {
-        issues.push({
-            type: 'warning',
-            message: 'Empty prompt content',
-            rootCause: 'The prompt has no content after the frontmatter.',
-            suggestion: 'Add prompt content using role tags:\n<system>\nYour system prompt here\n</system>',
-        });
     }
     return issues;
 }
@@ -492,17 +523,18 @@ async function identifyFailingDocuments(changes) {
     for (const change of nonDeleteChanges) {
         if (!change.content)
             continue;
-        const localIssues = validatePromptLContent(change.content, change.path);
-        const errors = localIssues.filter(i => i.type === 'error');
+        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: mainError.message,
+                code: mainError.code,
                 rootCause: mainError.rootCause,
                 suggestion: mainError.suggestion,
-                lineNumber: mainError.lineNumber,
-                snippet: mainError.snippet,
+                location: mainError.location,
+                codeFrame: mainError.codeFrame,
             });
         }
     }
@@ -556,20 +588,20 @@ async function testSingleDocument(change) {
         }
         // Run local validation to give more context
         if (change.content) {
-            const localIssues = validatePromptLContent(change.content, change.path);
+            const localIssues = await validatePromptLContent(change.content, change.path);
             if (localIssues.length > 0) {
-                const warnings = localIssues.filter(i => i.type === 'warning');
+                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')}`;
+                    suggestion += `\n\nAdditional observations:\n${warnings.map((w) => `- ${w.message}: ${w.suggestion}`).join('\n')}`;
                 }
             }
         }
         return {
             path: change.path,
             error: errorMsg,
+            code: 'api-validation-error',
             rootCause,
             suggestion,
-            snippet: change.content?.substring(0, 300),
         };
     }
 }
@@ -697,13 +729,14 @@ async function deployToLive(changes, _versionName) {
             const errorLines = [];
             for (const doc of failedDocs) {
                 errorLines.push(`\n## ❌ ${doc.path}`);
+                errorLines.push(`**Error Code:** \`${doc.code}\``);
                 errorLines.push(`**Error:** ${doc.error}`);
                 errorLines.push(`**Root Cause:** ${doc.rootCause}`);
-                if (doc.lineNumber) {
-                    errorLines.push(`**Location:** Line ${doc.lineNumber}`);
+                if (doc.location) {
+                    errorLines.push(`**Location:** Line ${doc.location.line}, Column ${doc.location.column}`);
                 }
-                if (doc.snippet) {
-                    errorLines.push(`**Snippet:** \`${doc.snippet}\``);
+                if (doc.codeFrame) {
+                    errorLines.push(`**Code Context:**\n\`\`\`\n${doc.codeFrame}\n\`\`\``);
                 }
                 errorLines.push(`**Fix:** ${doc.suggestion}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "latitude-mcp-server",
-	"version": "2.2.4",
+	"version": "2.2.6",
 	"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": {