latitude-mcp-server 3.2.1 → 3.2.3

package/PROMPT_GUIDE.md

@@ -3,107 +3,200 @@ description: Complete guide for LLMs to autonomously manage, test, and optimize
 auto_execution_mode: 3
 ---
 
-# LATITUDE MCP SERVER - LLM GUIDE
+# LATITUDE MCP SERVER - LLM AUTONOMOUS GUIDE
 
-> "Autonomous prompt engineering: Create → Validate → Test → Iterate → Optimize"
+> "File-first workflow: Pull → Edit → Push → Test → Iterate"
 
-## CRITICAL WORKFLOW
+## GOLDEN RULE: FILE PATHS ONLY
 
 ```
-1. pull_prompts  → Download all prompts to ./prompts/*.promptl
-2. Edit locally  → Your IDE, full context
-3. add_prompt    → Push with validation (overwrites if exists)
-4. run_prompt    → Test with parameters
-5. Iterate       → Analyze output → improve → re-push → re-test
+❌ NEVER: Write prompt content directly in tool calls
+✅ ALWAYS: Create .promptl files, use filePaths parameter
 ```
 
-**7 MCP tools. Client-side validation. Dynamic descriptions. Git-style versioning.**
+**Why?** Files are versionable, editable, reviewable. Inline content is messy and hard to iterate.
 
 ---
 
 ## THE 7 TOOLS
 
-| Tool | Type | Purpose | Dynamic Feature |
-|------|------|---------|-----------------|
-| `list_prompts` | Read | List all prompt names in LIVE | — |
-| `get_prompt` | Read | Get full prompt content by name | — |
-| `run_prompt` | Execute | Execute prompt with parameters | 🎯 Shows all prompts with their params |
-| `pull_prompts` | Sync | Download LIVE → `./prompts/*.promptl` (FULL SYNC) | — |
-| `add_prompt` | Write | Add/update prompts (overwrites if exists, never deletes others) | 🎯 Shows available prompts |
-| `push_prompts` | Sync | Replace ALL prompts (FULL SYNC, deletes extras) | — |
-| `docs` | Read | Documentation (52 topics, semantic search) | — |
+| Tool | Purpose | Key Param |
+|------|---------|-----------|
+| `list_prompts` | See what exists | — |
+| `get_prompt` | Read prompt content | `name` |
+| `run_prompt` | Execute with params | `name`, `parameters` |
+| `pull_prompts` | Download all → `./prompts/` | `outputDir?` |
+| `add_prompt` | Add/update (never deletes) | `filePaths` ✅ |
+| `push_prompts` | Replace ALL (FULL SYNC) | `filePaths` ✅ |
+| `docs` | Learn PromptL | `action`, `query`/`topic` |
 
-### 🎯 Dynamic Descriptions
+---
+
+## FILE-FIRST WORKFLOW
 
-**run_prompt** shows you what parameters each prompt needs:
+### Step 1: Pull
+
+```json
+{ "tool": "pull_prompts" }
 ```
-Available prompts (10):
-- email-writer (params: recipient, topic, tone)
-- sentiment-analyzer (no params)
+Creates `./prompts/*.promptl`
+
+### Step 2: Create/Edit File
+
+```bash
+# Create new file
+echo '---
+provider: openai
+model: gpt-4o
+temperature: 0.2
+---
+<user>Extract email from: {{ text }}</user>' > ./prompts/email-extractor.promptl
 ```
 
-**add_prompt** shows you what prompts already exist:
+### Step 3: Push via File Path
+
+```json
+{
+  "tool": "add_prompt",
+  "filePaths": ["./prompts/email-extractor.promptl"],
+  "versionName": "feat/add-email-extractor"
+}
 ```
-Available prompts (10): email-writer, sentiment-analyzer, ...
+
+### Step 4: Test
+
+```json
+{
+  "tool": "run_prompt",
+  "name": "email-extractor",
+  "parameters": { "text": "Contact john@example.com" }
+}
 ```
 
+### Step 5: Iterate
+
+Edit file → `add_prompt` again → `run_prompt` → repeat until quality is perfect
+
 ---
 
-## AUTONOMOUS WORKFLOWS
+## 📚 LEARN PROMPTL WITH `docs` TOOL
 
-### Create → Test → Iterate
+### How to Use
+
+```json
+{ "tool": "docs", "action": "help" }           // Overview of all 52 topics
+{ "tool": "docs", "action": "find", "query": "json schema" }  // Search
+{ "tool": "docs", "action": "get", "topic": "config-json-output" }  // Get specific
+```
+
+### Learning Menu: "To build X, call Y"
+
+| I want to... | Call this |
+|--------------|-----------|
+| **Understand PromptL basics** | `docs(action: "get", topic: "overview")` |
+| **Learn file structure** | `docs(action: "get", topic: "structure")` |
+| **Use variables** | `docs(action: "get", topic: "variables")` |
+| **Add conditionals (if/else)** | `docs(action: "get", topic: "conditionals")` |
+| **Loop through items** | `docs(action: "get", topic: "loops")` |
+
+| I want to... | Call this |
+|--------------|-----------|
+| **Configure provider/model** | `docs(action: "get", topic: "config-basics")` |
+| **Get JSON output (schema)** | `docs(action: "get", topic: "config-json-output")` |
+| **Set temperature/tokens** | `docs(action: "get", topic: "config-generation")` |
+| **Use OpenAI models** | `docs(action: "get", topic: "providers-openai")` |
+| **Use Anthropic models** | `docs(action: "get", topic: "providers-anthropic")` |
+
+| I want to... | Call this |
+|--------------|-----------|
+| **Write system/user/assistant** | `docs(action: "get", topic: "messages-roles")` |
+| **Use images (multimodal)** | `docs(action: "get", topic: "messages-multimodal")` |
+
+| I want to... | Call this |
+|--------------|-----------|
+| **Add few-shot examples** | `docs(action: "get", topic: "technique-few-shot")` |
+| **Chain of thought reasoning** | `docs(action: "get", topic: "technique-cot")` |
+| **Build agents with tools** | `docs(action: "get", topic: "agents")` |
+| **Define custom tools** | `docs(action: "get", topic: "tools-custom")` |
+| **Multi-step chains** | `docs(action: "get", topic: "chains")` |
+
+| I want to build... | Call this |
+|--------------------|-----------|
+| **Data extraction** | `docs(action: "get", topic: "recipe-extraction")` |
+| **Classification** | `docs(action: "get", topic: "recipe-classification")` |
+| **Chatbot** | `docs(action: "get", topic: "recipe-chatbot")` |
+| **RAG system** | `docs(action: "get", topic: "recipe-rag")` |
+| **Content moderation** | `docs(action: "get", topic: "recipe-moderation")` |
+
+### Quick Search Examples
+
+```json
+// Don't know exact topic? Search!
+{ "tool": "docs", "action": "find", "query": "extract structured data" }
+{ "tool": "docs", "action": "find", "query": "few shot examples" }
+{ "tool": "docs", "action": "find", "query": "agent autonomous" }
+{ "tool": "docs", "action": "find", "query": "loop array items" }
+{ "tool": "docs", "action": "find", "query": "temperature settings" }
+```
 
-```javascript
-// 1. Create prompt
-add_prompt({
-  prompts: [{
-    name: "email-extractor",
-    content: `---
-provider: openai
-model: gpt-4o
-temperature: 0.2
-schema:
-  type: object
-  properties:
-    email: { type: string }
-  required: [email]
 ---
-<user>Extract from: {{ text }}</user>`
-  }],
-  versionName: "feat/email-extractor-v1"
-})
 
-// 2. Test
-run_prompt({
-  name: "email-extractor",
-  parameters: { text: "Contact john@example.com" }
-})
+## 🎯 DYNAMIC TOOL DESCRIPTIONS
 
-// 3. Analyze output → if needs improvement, iterate
-add_prompt({
-  prompts: [{
-    name: "email-extractor",
-    content: "... improved version ..."
-  }],
-  versionName: "fix/improve-accuracy"
-})
+**No need to call `list_prompts` first!**
 
-// 4. Re-test → repeat until quality threshold met
+`run_prompt` description shows:
 ```
+Available prompts (10):
+- email-extractor (params: text)
+- sentiment (params: input, language)
+- cover-letter (params: job_details, patterns, company)
+```
+
+`add_prompt` description shows:
+```
+Available prompts (10): email-extractor, sentiment, cover-letter, ...
+```
+
+**Check tool description → know what exists + what params needed**
+
+---
 
-### Bulk Testing for Optimization
+## AUTONOMOUS ITERATION LOOP
+
+```
+1. Learn pattern    → docs(action: "find", query: "...")
+2. Create file      → ./prompts/my-prompt.promptl
+3. Push             → add_prompt(filePaths: [...], versionName: "v1")
+4. Test             → run_prompt(name: "...", parameters: {...})
+5. Analyze output   → Good? Done. Bad? Continue.
+6. Edit file        → Improve based on output analysis
+7. Re-push          → add_prompt(filePaths: [...], versionName: "v2")
+8. Re-test          → run_prompt again
+9. Repeat 5-8       → Until quality threshold met
+```
+
+---
+
+## BULK TESTING WITH MCP INSPECTOR
 
 ```bash
-# Test multiple prompts with MCP Inspector
-for prompt in email-extractor sentiment-analyzer; do
-  npx @modelcontextprotocol/inspector \
-    -e LATITUDE_API_KEY=$KEY \
-    -e LATITUDE_PROJECT_ID=$ID \
-    --cli npx -y latitude-mcp-server@3.2.0 \
-    --method tools/call \
-    --tool-name run_prompt \
-    --tool-arg name=$prompt \
-    --tool-arg 'parameters={"text":"test"}'
+# Test single prompt
+npx @modelcontextprotocol/inspector \
+  -e LATITUDE_API_KEY=$KEY -e LATITUDE_PROJECT_ID=$ID \
+  --cli npx -y latitude-mcp-server@3.2.1 \
+  --method tools/call \
+  --tool-name run_prompt \
+  --tool-arg name=email-extractor \
+  --tool-arg 'parameters={"text":"john@example.com"}'
+
+# Test multiple prompts in loop
+for p in email-extractor sentiment classifier; do
+  echo "=== $p ===" && npx @modelcontextprotocol/inspector \
+    -e LATITUDE_API_KEY=$KEY -e LATITUDE_PROJECT_ID=$ID \
+    --cli npx -y latitude-mcp-server@3.2.1 \
+    --method tools/call --tool-name run_prompt \
+    --tool-arg name=$p --tool-arg 'parameters={"text":"test"}'
 done
 
 # Analyze outputs → update weak prompts → re-test
@@ -113,15 +206,27 @@ done
 
 ## VERSION NAMING
 
-```javascript
-// Git-style naming (optional)
-versionName: "feat/add-email-extractor"
-versionName: "fix/typo-in-system-message"
-versionName: "refactor/simplify-logic"
-versionName: "perf/reduce-tokens"
-
-// If omitted → auto-generates timestamp
 ```
+feat/add-email-extractor    # New feature
+fix/improve-accuracy        # Bug fix
+refactor/simplify-prompt    # Cleanup
+perf/reduce-tokens          # Performance
+test/add-examples           # Testing
+```
+
+Omit → auto-generates timestamp
+
+---
+
+## SYNC BEHAVIOR
+
+| Tool | Behavior |
+|------|----------|
+| `add_prompt` | ADDITIVE - adds/updates, never deletes |
+| `push_prompts` | FULL SYNC - replaces ALL, deletes extras |
+| `pull_prompts` | FULL SYNC - deletes local first |
+
+**Use `add_prompt` for normal work. Use `push_prompts` only for reset/init.**
 
 ---
 
@@ -129,35 +234,147 @@ versionName: "perf/reduce-tokens"
 
 All writes validate BEFORE API calls:
 
-```javascript
-add_prompt({
-  prompts: [{
-    name: "broken",
-    content: `<user><assistant>Nested!</assistant></user>`  // ❌
-  }]
-})
+```
+❌ Validation Failed
+
+Error Code: `message-tag-inside-message`
+Location: Line 4, Column 7
+Code Context:
+4: <user><assistant>Nested!</assistant></user>
+          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Fix: Move nested tag outside parent.
+```
+
+**Fix file → re-push → validation passes**
+
+---
+
+## PROMPTL QUICK REFERENCE
 
-// Error Code: `message-tag-inside-message`
-// Location: Line 1, Column 7
-// Fix: Move the nested tag outside its parent.
+### Basic Structure
+
+```yaml
+---
+provider: openai
+model: gpt-4o
+temperature: 0.2
+---
+<system>You are a helpful assistant.</system>
+<user>{{ user_input }}</user>
 ```
 
+### With Schema (JSON Output)
+
+```yaml
 ---
+provider: openai
+model: gpt-4o
+schema:
+  type: object
+  properties:
+    result: { type: string }
+  required: [result]
+---
+<user>{{ input }}</user>
+```
 
-## SYNC BEHAVIOR
+### Few-Shot Examples
 
-- `push_prompts` - FULL SYNC (deletes extras)
-- `pull_prompts` - FULL SYNC (deletes local first)
-- `add_prompt` - ADDITIVE (never deletes)
+```yaml
+---
+provider: openai
+model: gpt-4o
+---
+<user>Classify: Great product!</user>
+<assistant>positive</assistant>
+
+<user>Classify: Terrible experience</user>
+<assistant>negative</assistant>
+
+<user>Classify: {{ text }}</user>
+```
+
+### Temperature Guide
+
+```
+0.0-0.2  Deterministic (extraction, classification)
+0.3-0.5  Balanced (Q&A, analysis)
+0.6-0.8  Creative (writing, brainstorming)
+```
+
+---
+
+## COMPLETE EXAMPLE: BUILD EMAIL EXTRACTOR
+
+```bash
+# 1. Learn JSON schema pattern
+docs(action: "get", topic: "config-json-output")
+
+# 2. Create file
+cat > ./prompts/email-extractor.promptl << 'EOF'
+---
+provider: openai
+model: gpt-4o
+temperature: 0.1
+schema:
+  type: object
+  properties:
+    email: { type: string }
+    name: { type: [string, "null"] }
+  required: [email]
+---
+<system>
+Extract email and name. Return null for name if not found.
+</system>
+<user>{{ text }}</user>
+EOF
+
+# 3. Push
+add_prompt(filePaths: ["./prompts/email-extractor.promptl"], versionName: "v1")
+
+# 4. Test
+run_prompt(name: "email-extractor", parameters: { text: "John at john@example.com" })
+
+# 5. Output not good? Edit file, re-push as v2, re-test
+# 6. Repeat until perfect
+```
+
+---
+
+## ANTI-PATTERNS
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Write content in tool call | Create .promptl file, use filePaths |
+| Guess PromptL syntax | `docs(action: "find", query: "...")` |
+| Call list_prompts first | Check run_prompt tool description |
+| Use push_prompts casually | Use add_prompt (safer) |
+| Skip testing | run_prompt after every change |
 
 ---
 
 ## QUICK COMMANDS
 
 ```
-"Pull all"          → pull_prompts
-"Add this file"     → add_prompt(filePaths: ["./prompts/x.promptl"])
-"Test prompt"       → run_prompt(name: "x", parameters: {...})
-"What params?"      → Check run_prompt description (dynamic)
-"What exists?"      → Check add_prompt description (dynamic)
+"What prompts exist?"      → Check run_prompt description (dynamic)
+"What params does X need?" → Check run_prompt description (dynamic)
+"Learn about schemas"      → docs(action: "get", topic: "config-json-output")
+"Search for X"             → docs(action: "find", query: "X")
+"Add my file"              → add_prompt(filePaths: ["./prompts/x.promptl"])
+"Test prompt"              → run_prompt(name: "x", parameters: {...})
+"Pull all prompts"         → pull_prompts
 ```
+
+---
+
+## WISDOM
+
+**File-First:** "Never write prompt content in tool calls. Always use filePaths."
+
+**Learn-First:** "docs(find) → docs(get) → create file → push → test"
+
+**Iterate:** "Edit file → add_prompt → run_prompt → analyze → repeat"
+
+**Dynamic:** "Tool descriptions show prompts + params. No listing needed."
+
+**Validate:** "Client-side validation catches errors before API calls."

package/dist/api.d.ts

@@ -46,9 +46,18 @@ interface PushResponse {
  * This is the CLI-style push that sends all changes at once
  */
 export declare function pushChanges(versionUuid: string, changes: DocumentChange[]): Promise<PushResponse>;
+/**
+ * Normalize document path for consistent comparison.
+ * Handles leading/trailing slashes, whitespace, and ensures consistent format.
+ * API may return paths with or without leading slash - this normalizes them.
+ */
+export declare function normalizePath(path: string): string;
 /**
  * Compute diff between incoming prompts and existing prompts
  * Returns only the changes that need to be made
+ *
+ * IMPORTANT: Uses normalized paths to handle API inconsistencies where
+ * paths may be returned with or without leading slashes.
  */
 export declare function computeDiff(incoming: Array<{
     path: string;

package/dist/api.js

@@ -18,6 +18,7 @@ exports.getProjectId = getProjectId;
 exports.listDocuments = listDocuments;
 exports.getDocument = getDocument;
 exports.pushChanges = pushChanges;
+exports.normalizePath = normalizePath;
 exports.computeDiff = computeDiff;
 exports.runDocument = runDocument;
 exports.validatePromptLContent = validatePromptLContent;
@@ -301,17 +302,34 @@ async function pushChanges(versionUuid, changes) {
         body: { changes: apiChanges },
     });
 }
+/**
+ * Normalize document path for consistent comparison.
+ * Handles leading/trailing slashes, whitespace, and ensures consistent format.
+ * API may return paths with or without leading slash - this normalizes them.
+ */
+function normalizePath(path) {
+    return path
+        .trim()
+        .replace(/^\/+/, '') // Remove leading slashes
+        .replace(/\/+$/, '') // Remove trailing slashes
+        .replace(/\/+/g, '/'); // Collapse multiple slashes
+}
 /**
  * Compute diff between incoming prompts and existing prompts
  * Returns only the changes that need to be made
+ *
+ * IMPORTANT: Uses normalized paths to handle API inconsistencies where
+ * paths may be returned with or without leading slashes.
  */
 function computeDiff(incoming, existing) {
     const changes = [];
-    const existingMap = new Map(existing.map((d) => [d.path, d]));
-    const incomingPaths = new Set(incoming.map((p) => p.path));
+    // Build map with NORMALIZED paths as keys for reliable matching
+    const existingMap = new Map(existing.map((d) => [normalizePath(d.path), d]));
+    const incomingPaths = new Set(incoming.map((p) => normalizePath(p.path)));
     // Check each incoming prompt
     for (const prompt of incoming) {
-        const existingDoc = existingMap.get(prompt.path);
+        const normalizedPath = normalizePath(prompt.path);
+        const existingDoc = existingMap.get(normalizedPath);
         if (!existingDoc) {
             // New prompt
             changes.push({
@@ -321,9 +339,9 @@ function computeDiff(incoming, existing) {
             });
         }
         else if (existingDoc.content !== prompt.content) {
-            // Modified prompt
+            // Modified prompt - use the EXISTING path to ensure API compatibility
             changes.push({
-                path: prompt.path,
+                path: existingDoc.path,
                 content: prompt.content,
                 status: 'modified',
             });
@@ -331,10 +349,10 @@ function computeDiff(incoming, existing) {
         // If content is same, no change needed (don't include in changes)
     }
     // Check for deleted prompts (exist remotely but not in incoming)
-    for (const path of existingMap.keys()) {
-        if (!incomingPaths.has(path)) {
+    for (const [normalizedExistingPath, doc] of existingMap.entries()) {
+        if (!incomingPaths.has(normalizedExistingPath)) {
             changes.push({
-                path,
+                path: doc.path,
                 content: '',
                 status: 'deleted',
             });

package/dist/tools.js

@@ -417,16 +417,19 @@ async function handleAddPrompt(args) {
         logger.info(`All ${prompts.length} prompt(s) passed validation`);
         // Get existing prompts
         const existingDocs = await (0, api_js_1.listDocuments)('live');
-        const existingMap = new Map(existingDocs.map((d) => [d.path, d]));
+        // Use NORMALIZED paths as keys for reliable matching (handles /path vs path inconsistencies)
+        const existingMap = new Map(existingDocs.map((d) => [(0, api_js_1.normalizePath)(d.path), d]));
         // Build changes - ALWAYS overwrite if exists, add if new, NEVER delete
         const changes = [];
         for (const prompt of prompts) {
-            const existingDoc = existingMap.get(prompt.name);
+            const normalizedName = (0, api_js_1.normalizePath)(prompt.name);
+            const existingDoc = existingMap.get(normalizedName);
             if (existingDoc) {
                 // Only include if content is different
                 if (existingDoc.content !== prompt.content) {
+                    // Use the EXISTING path from API to ensure compatibility
                     changes.push({
-                        path: prompt.name,
+                        path: existingDoc.path,
                         content: prompt.content,
                         status: 'modified',
                     });

package/package.json

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