latitude-mcp-server 3.1.0 → 3.2.1

package/PROMPT_GUIDE.md

@@ -0,0 +1,163 @@
+---
+description: Complete guide for LLMs to autonomously manage, test, and optimize PromptL prompts via MCP
+auto_execution_mode: 3
+---
+
+# LATITUDE MCP SERVER - LLM GUIDE
+
+> "Autonomous prompt engineering: Create → Validate → Test → Iterate → Optimize"
+
+## CRITICAL WORKFLOW
+
+```
+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
+```
+
+**7 MCP tools. Client-side validation. Dynamic descriptions. Git-style versioning.**
+
+---
+
+## 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) | — |
+
+### 🎯 Dynamic Descriptions
+
+**run_prompt** shows you what parameters each prompt needs:
+```
+Available prompts (10):
+- email-writer (params: recipient, topic, tone)
+- sentiment-analyzer (no params)
+```
+
+**add_prompt** shows you what prompts already exist:
+```
+Available prompts (10): email-writer, sentiment-analyzer, ...
+```
+
+---
+
+## AUTONOMOUS WORKFLOWS
+
+### Create → Test → Iterate
+
+```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" }
+})
+
+// 3. Analyze output → if needs improvement, iterate
+add_prompt({
+  prompts: [{
+    name: "email-extractor",
+    content: "... improved version ..."
+  }],
+  versionName: "fix/improve-accuracy"
+})
+
+// 4. Re-test → repeat until quality threshold met
+```
+
+### Bulk Testing for Optimization
+
+```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"}'
+done
+
+# Analyze outputs → update weak prompts → re-test
+```
+
+---
+
+## 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
+```
+
+---
+
+## VALIDATION
+
+All writes validate BEFORE API calls:
+
+```javascript
+add_prompt({
+  prompts: [{
+    name: "broken",
+    content: `<user><assistant>Nested!</assistant></user>`  // ❌
+  }]
+})
+
+// Error Code: `message-tag-inside-message`
+// Location: Line 1, Column 7
+// Fix: Move the nested tag outside its parent.
+```
+
+---
+
+## SYNC BEHAVIOR
+
+- `push_prompts` - FULL SYNC (deletes extras)
+- `pull_prompts` - FULL SYNC (deletes local first)
+- `add_prompt` - ADDITIVE (never deletes)
+
+---
+
+## 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)
+```

package/README.md

@@ -1,22 +1,23 @@
 # Latitude MCP Server
 
-> Model Context Protocol server for [Latitude.so](https://latitude.so) prompt management
+> **AI-powered prompt management** for [Latitude.so](https://latitude.so) via Model Context Protocol
 
-Manage AI prompts directly from your MCP-compatible AI assistant. Push, pull, run, and version PromptL prompts with 8 focused tools.
+Manage PromptL prompts directly from Claude, Windsurf, or any MCP client. Features **intelligent validation**, **dynamic tool descriptions**, and **git-style versioning**.
 
 [![npm version](https://img.shields.io/npm/v/latitude-mcp-server.svg)](https://www.npmjs.com/package/latitude-mcp-server)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
 ---
 
-## Features
+## ✨ Key Features
 
-- **8 MCP Tools** - Push, pull, run, and manage prompts
-- **52 Documentation Topics** - Comprehensive PromptL syntax guide
-- **Semantic Search** - Find docs by natural language query
-- **File Operations** - Pull prompts to local `.promptl` files
-- **Version Control** - Manage LIVE and draft versions
-- **Zero Config** - Works with `LATITUDE_API_KEY` environment variable
+- **🤖 Smart Validation** - Client-side PromptL validation with AST-powered error messages
+- **📋 Dynamic Descriptions** - Tools show available prompts and their parameters automatically
+- **🔄 Full Sync** - Push/pull with automatic conflict resolution
+- **🎯 Atomic Operations** - Validate ALL before pushing ANY (all-or-nothing)
+- **📚 52 Doc Topics** - Comprehensive PromptL syntax guide with semantic search
+- **🏷️ Git-Style Versioning** - Name your changes like commits (feat/add-auth, fix/typo)
+- **⚡ Zero Config** - Just set `LATITUDE_API_KEY` and go
 
 ---
 
@@ -60,86 +61,209 @@ Add to your MCP client config (e.g., Claude Desktop):
 
 ---
 
-## Available Tools
+## 🛠️ Available Tools (7)
 
-| Tool | Description |
-|------|-------------|
-| `list_prompts` | List all prompts in LIVE version |
-| `get_prompt` | Get full prompt content by name |
-| `run_prompt` | Execute a prompt with parameters |
-| `push_prompts` | Replace ALL prompts (destructive) |
-| `append_prompts` | Add prompts without removing existing |
-| `pull_prompts` | Download prompts to local files |
-| `replace_prompt` | Replace or create single prompt |
-| `docs` | Get documentation (52 topics) |
+| Tool | Type | Description |
+|------|------|-------------|
+| `list_prompts` | Read | List all prompts in LIVE |
+| `get_prompt` | Read | Get full prompt content by name |
+| `run_prompt` | Execute | 🎯 **Dynamic:** Shows all prompts with their parameters |
+| `push_prompts` | Write | 🔄 **FULL SYNC:** Replace ALL prompts (deletes extras) |
+| `pull_prompts` | Read | 🔄 **FULL SYNC:** Download all prompts (deletes local first) |
+| `add_prompt` | Write | 🎯 **Dynamic:** Add/update prompts (shows available prompts) |
+| `docs` | Read | Get documentation (52 topics, semantic search) |
+
+### 🎯 What Makes This Special?
+
+**Dynamic Tool Descriptions** - The MCP server updates tool descriptions in real-time:
+- `run_prompt` shows: `"my-prompt" (params: name, email, company)`
+- `add_prompt` shows: `"Available prompts (10): prompt-a, prompt-b, ..."`
+
+Your AI assistant sees exactly what prompts exist and what parameters they need!
 
 ---
 
-## Common Workflows
+## 🚀 Real-World Workflows
 
-### Pull Prompts to Local Files
+### Workflow 1: New Project Setup
 
-```
+```bash
+# Pull all prompts from LIVE to start local development
 pull_prompts({ outputDir: "./prompts" })
+# Downloads 10 files to ./prompts/
+# Deletes any existing local .promptl files first (FULL SYNC)
 ```
 
-Downloads all LIVE prompts to `./prompts/*.promptl` files.
+**What you see:**
+```
+✅ Prompts Pulled from LIVE
 
-### List Available Prompts
+Directory: /Users/you/project/prompts
+Deleted: 0 existing files
+Written: 10 files
 
-```
-list_prompts()
+Files:
+- cover-letter-generate.promptl
+- sentiment-analyzer.promptl
+...
+
+Tip: Edit files locally, then use `add_prompt` to push changes.
 ```
 
-Returns all prompt names in your project.
+### Workflow 2: Add New Prompt (with Dynamic Guidance)
+
+```bash
+# The tool description shows you what prompts already exist!
+add_prompt({
+  prompts: [{
+    name: "email-writer",
+    content: `---
+provider: openai
+model: gpt-4o
+---
+<user>
+Write email to {{ recipient }} about {{ topic }}
+</user>`
+  }],
+  versionName: "feat/add-email-writer"  # Optional git-style naming
+})
+```
 
-### Get Prompt Content
+**Dynamic Description Shows:**
+```
+Add or update prompt(s) in LIVE without deleting others.
 
+Available prompts (10): cover-letter-generate, sentiment-analyzer, ...
 ```
-get_prompt({ name: "my-prompt" })
+
+**Result:**
 ```
+✅ Prompts Added to LIVE
 
-Retrieves full PromptL content including config and messages.
+Summary:
+- Added: 1
+- Updated: 0
 
-### Run a Prompt
+Added:
+- email-writer
 
+Current LIVE prompts (11): cover-letter-generate, ..., email-writer
 ```
-run_prompt({ 
-  name: "my-prompt",
-  parameters: { user_name: "Alice" }
+
+### Workflow 3: Run Prompt (with Parameter Discovery)
+
+```bash
+# The tool description shows you what parameters each prompt needs!
+run_prompt({
+  name: "email-writer",
+  parameters: {
+    recipient: "Alice",
+    topic: "project update"
+  }
 })
 ```
 
-Executes the prompt and returns AI response.
+**Dynamic Description Shows:**
+```
+Execute a prompt with parameters.
 
-### Update a Prompt
+Available prompts (11):
+- cover-letter-generate (params: job_details, career_patterns, company_name)
+- email-writer (params: recipient, topic)
+- sentiment-analyzer (no params)
+...
+```
 
+**Result:**
 ```
-replace_prompt({
-  name: "greeting",
-  content: `---
-provider: OpenAI
-model: gpt-4o
+✅ Prompt Executed
+
+Prompt: email-writer
+
+Parameters:
+{
+  "recipient": "Alice",
+  "topic": "project update"
+}
+
+Response:
+Subject: Project Update
+
+Dear Alice,
+
+I wanted to share an update on our project...
+
+Tokens: 245 total
+```
+
+### Workflow 4: Validation Catches Errors
+
+```bash
+# Try to add a prompt with nested tags (invalid PromptL)
+add_prompt({
+  prompts: [{
+    name: "broken",
+    content: `---
+model: gpt-4
 ---
-Hello {{ user_name }}!`
+<user><assistant>Nested!</assistant></user>`
+  }]
 })
 ```
 
-Creates or updates a single prompt in LIVE.
+**Validation Error (Before ANY API Call):**
+```
+❌ Validation Failed - No Changes Made
 
-### Get Documentation
+1 prompt(s) have errors. Fix all errors before pushing.
 
+### broken
+Error Code: `message-tag-inside-message`
+Error: Message tags cannot be inside of another message
+Root Cause: Message/role tags (<system>, <user>, <assistant>, <tool>) cannot be nested.
+Location: Line 4, Column 7
+Code Context:
 ```
-docs({ action: "help" })                    # Overview
-docs({ action: "find", query: "variables" }) # Search
-docs({ action: "get", topic: "chains" })     # Specific topic
+2: model: gpt-4
+3: ---
+4: <user><assistant>Nested!</assistant></user>
+
+          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ```
+Fix: Move the nested tag outside its parent. Use code block (```yaml) for examples.
 
-Access comprehensive PromptL documentation (52 topics).
+Action Required: Fix the errors above, then retry.
+```
+
+### Workflow 5: Full Sync (Initialization)
+
+```bash
+# Push local prompts to LIVE - deletes remote prompts not in your list
+push_prompts({
+  filePaths: [
+    "./prompts/prompt-a.promptl",
+    "./prompts/prompt-b.promptl",
+    "./prompts/prompt-c.promptl"
+  ],
+  versionName: "feat/initial-prompts"  # Optional
+})
+```
+
+**Result:**
+```
+✅ Prompts Pushed to LIVE
+
+Summary:
+- Added: 3
+- Modified: 0
+- Deleted: 8  # Removed old prompts not in your list
+
+Current LIVE prompts (3): prompt-a, prompt-b, prompt-c
+```
 
 ---
 
-## Documentation Topics (52)
+## 📚 Documentation Topics (52)
 
 ### Core Syntax (12)
 `overview`, `structure`, `variables`, `conditionals`, `loops`, `references`, `tools`, `chains`, `agents`, `techniques`, `agent-patterns`, `mocking`
@@ -164,24 +288,48 @@ Access comprehensive PromptL documentation (52 topics).
 
 ---
 
-## Development
+## 🛠️ Development
 
 ### Build
 
 ```bash
-npm run build
+npm run build  # Compiles TypeScript to dist/
 ```
 
-Compiles TypeScript to `dist/`.
-
-### Test with MCP Inspector
+### Testing with MCP Inspector
 
 ```bash
+# List all tools
 npx @modelcontextprotocol/inspector \
   -e LATITUDE_API_KEY=your-key \
   -e LATITUDE_PROJECT_ID=your-id \
   --cli node dist/index.js \
   --method tools/list
+
+# Test list_prompts
+npx @modelcontextprotocol/inspector \
+  -e LATITUDE_API_KEY=your-key \
+  -e LATITUDE_PROJECT_ID=your-id \
+  --cli node dist/index.js \
+  --method tools/call \
+  --tool-name list_prompts
+
+# Test add_prompt with file
+npx @modelcontextprotocol/inspector \
+  -e LATITUDE_API_KEY=your-key \
+  -e LATITUDE_PROJECT_ID=your-id \
+  --cli node dist/index.js \
+  --method tools/call \
+  --tool-name add_prompt \
+  --tool-arg 'filePaths=["./prompts/test.promptl"]'
+
+# Test from npm package
+npx @modelcontextprotocol/inspector \
+  -e LATITUDE_API_KEY=your-key \
+  -e LATITUDE_PROJECT_ID=your-id \
+  --cli npx -y latitude-mcp-server@3.1.0 \
+  --method tools/call \
+  --tool-name list_prompts
 ```
 
 ### Local Development
@@ -193,6 +341,10 @@ node dist/index.js
 
 # With environment variables
 LATITUDE_API_KEY=xxx LATITUDE_PROJECT_ID=yyy node dist/index.js
+
+# Watch mode (requires nodemon)
+npm install -g nodemon
+nodemon --watch src --exec "npm run build && node dist/index.js"
 ```
 
 ---
@@ -281,63 +433,103 @@ Use `docs({ action: "get", topic: "overview" })` for complete guide.
 
 ---
 
-## API Reference
+## 📖 Tool Reference
 
 ### list_prompts()
 
 List all prompts in LIVE version.
 
-**Returns:** Array of prompt names
+**Returns:** Array of prompt names with project ID
+
+**Example:**
+```javascript
+list_prompts()
+// Returns: cover-letter-generate, sentiment-analyzer, email-writer (10 total)
+```
+
+---
 
 ### get_prompt({ name })
 
-Get full prompt content.
+Get full prompt content by name.
 
 **Parameters:**
 - `name` (string) - Prompt name
 
-**Returns:** Prompt content with config and messages
+**Returns:** Full PromptL content with config and messages
+
+**Example:**
+```javascript
+get_prompt({ name: "email-writer" })
+// Returns full .promptl content
+```
+
+---
 
 ### run_prompt({ name, parameters })
 
-Execute a prompt.
+🎯 **Dynamic:** Execute a prompt. Tool description shows all prompts with their parameters!
 
 **Parameters:**
 - `name` (string) - Prompt name
-- `parameters` (object) - Input parameters
+- `parameters` (object, optional) - Input parameters
 
-**Returns:** AI response
+**Returns:** AI response with token usage
 
-### pull_prompts({ outputDir? })
+**Dynamic Description:**
+```
+Available prompts (10):
+- email-writer (params: recipient, topic)
+- sentiment-analyzer (no params)
+- cover-letter-generate (params: job_details, career_patterns, company_name)
+```
 
-Download prompts to local files.
+**Example:**
+```javascript
+run_prompt({
+  name: "email-writer",
+  parameters: { recipient: "Alice", topic: "update" }
+})
+```
 
-**Parameters:**
-- `outputDir` (string, optional) - Output directory (default: `./prompts`)
+---
 
-**Returns:** List of created files
+### add_prompt({ prompts?, filePaths?, versionName? })
 
-### replace_prompt({ name?, content?, filePath? })
+🎯 **Dynamic:** Add or update prompts without deleting others. Tool description shows available prompts!
 
-Replace or create a single prompt. **Shows all available prompts in description.**
+**Behavior:** If prompt exists → overwrites. If new → adds. Never deletes other prompts.
 
-**Parameters (choose one approach):**
+**Parameters (choose one):**
 
 **Option A - Direct content:**
-- `name` (string) - Prompt name
-- `content` (string) - Full PromptL content
+- `prompts` (array) - Array of `{ name, content }`
+
+**Option B - From files:**
+- `filePaths` (array) - Array of paths to `.promptl` files
+
+**Common:**
+- `versionName` (string, optional) - Git-style name like `feat/add-auth` or `fix/typo`
+
+**Returns:** Summary of added/updated prompts
 
-**Option B - From file:**
-- `filePath` (string) - Path to `.promptl` file (name auto-detected from filename)
-- `name` (string, optional) - Override name from filename
+**Example:**
+```javascript
+add_prompt({
+  filePaths: ["./prompts/new-prompt.promptl"],
+  versionName: "feat/add-new-prompt"
+})
+```
 
-**Returns:** Success confirmation + updated list of all LIVE prompts
+---
+
+### push_prompts({ prompts?, filePaths?, versionName? })
 
-### append_prompts({ prompts?, filePaths?, overwrite? })
+🔄 **FULL SYNC:** Replace ALL prompts in LIVE. Deletes remote prompts not in your list.
 
-Add prompts without removing existing ones.
+**Use for:** Initial setup, complete sync, resetting LIVE to match local.
 
-**Parameters (choose one approach):**
+**Parameters (choose one):**
 
 **Option A - Direct content:**
 - `prompts` (array) - Array of `{ name, content }`
@@ -346,106 +538,196 @@ Add prompts without removing existing ones.
 - `filePaths` (array) - Array of paths to `.promptl` files
 
 **Common:**
-- `overwrite` (boolean, optional) - Overwrite existing (default: false)
+- `versionName` (string, optional) - Git-style name like `feat/initial-setup`
 
-**Returns:** Success confirmation + updated list of all LIVE prompts
+**Returns:** Summary of added/modified/deleted prompts
 
-### push_prompts({ prompts?, filePaths? })
+**Example:**
+```javascript
+push_prompts({
+  filePaths: ["./prompts/prompt-a.promptl", "./prompts/prompt-b.promptl"],
+  versionName: "feat/complete-rewrite"
+})
+```
 
-⚠️ **Destructive:** Replaces ALL prompts in LIVE.
+---
 
-**Parameters (choose one approach):**
+### pull_prompts({ outputDir? })
 
-**Option A - Direct content:**
-- `prompts` (array) - Array of `{ name, content }`
+🔄 **FULL SYNC:** Download all prompts from LIVE. Deletes existing local `.promptl` files first.
 
-**Option B - From files:**
-- `filePaths` (array) - Array of paths to `.promptl` files
+**Use for:** Initial clone, resetting local to match LIVE.
 
-**Returns:** Success confirmation + updated list of all LIVE prompts
+**Parameters:**
+- `outputDir` (string, optional) - Output directory (default: `./prompts`)
+
+**Returns:** List of downloaded files
+
+**Example:**
+```javascript
+pull_prompts({ outputDir: "./my-prompts" })
+```
+
+---
 
 ### docs({ action, topic?, query? })
 
-Get documentation.
+Access comprehensive PromptL documentation (52 topics).
 
 **Parameters:**
-- `action` (string) - `"help"`, `"get"`, or `"find"`
+- `action` (string) - `"help"` (overview), `"get"` (topic), or `"find"` (search)
 - `topic` (string, optional) - Topic name for `"get"`
 - `query` (string, optional) - Search query for `"find"`
 
 **Returns:** Documentation content
 
+**Examples:**
+```javascript
+docs({ action: "help" })                      // Overview
+docs({ action: "find", query: "json output" }) // Semantic search
+docs({ action: "get", topic: "chains" })       // Specific topic
+```
+
 ---
 
-## Examples
+## ✅ Validation Features
 
-### Example 1: Pull → Edit → Push Workflow (Recommended)
+### Client-Side Validation with AST
 
-```javascript
-// 1. Pull all prompts to local files
-pull_prompts({ outputDir: "./prompts" })
-// Creates: ./prompts/my-prompt.promptl, ./prompts/other-prompt.promptl, etc.
+All write operations (`add_prompt`, `push_prompts`) validate prompts **before** making API calls using the official `promptl-ai` library.
 
-// 2. Edit files locally in your IDE
+**Benefits:**
+- ⚡ **Fast feedback** - No wasted API calls
+- 🎯 **Precise errors** - Exact line and column numbers
+- 📝 **Code frames** - See surrounding context with `^~~~` pointer
+- 🤖 **LLM-actionable** - Errors include root cause and fix suggestions
 
-// 3. Push single file back (name auto-detected from filename)
-replace_prompt({ filePath: "./prompts/my-prompt.promptl" })
+### Atomic Operations
 
-// 4. Or push multiple files
-append_prompts({ 
-  filePaths: ["./prompts/prompt-a.promptl", "./prompts/prompt-b.promptl"],
-  overwrite: true 
+**Validate ALL, push ALL or NOTHING:**
+
+```javascript
+// Trying to push 10 prompts, but 1 has an error
+add_prompt({
+  filePaths: [
+    "./prompts/valid-1.promptl",
+    "./prompts/valid-2.promptl",
+    "./prompts/BROKEN.promptl",  // Has nested tags
+    // ... 7 more valid prompts
+  ]
 })
+
+// Result: NOTHING is pushed
+// Error shows exactly what's wrong in BROKEN.promptl
+// Fix the error, retry → all 10 push successfully
 ```
 
-### Example 2: Create New Prompt
+### Error Message Example
 
-```javascript
-replace_prompt({
-  name: "sentiment-analyzer",
-  content: `---
-provider: OpenAI
-model: gpt-4o
-temperature: 0
-schema:
-  type: object
-  properties:
-    sentiment:
-      type: string
-      enum: [positive, negative, neutral]
-  required: [sentiment]
----
-<system>
-You are a sentiment analysis expert.
-</system>
+```
+❌ Validation Failed - No Changes Made
 
-<user>
-Analyze: {{ text }}
-</user>`
-})
+1 prompt(s) have errors.
+
+### my-prompt
+Error Code: `message-tag-inside-message`
+Error: Message tags cannot be inside of another message
+Root Cause: Message/role tags cannot be nested inside each other.
+Location: Line 107, Column 1
+Code Context:
 ```
+105: ## EXAMPLES
+106: 
+107: <assistant>
 
-### Example 3: Run with Parameters
+      ^~~~~~~~~~~~
+108: questions:
+109:   - id: q1
+```
+Fix: Move the nested tag outside its parent. Use code block (```yaml) instead.
+```
+
+### Supported Error Types
+
+- `message-tag-inside-message` - Nested role tags
+- `content-tag-inside-content` - Nested content tags
+- `config-not-found` - Missing YAML frontmatter
+- `invalid-config` - Malformed YAML
+- `unclosed-block` - Missing closing tag
+- `variable-not-defined` - Undefined variable
+- `invalid-tool-call-placement` - Tool call outside `<assistant>`
+- ...and more from official `promptl-ai` compiler
+
+---
 
+## 🔄 Migration Guide (v2 → v3)
+
+### Tool Changes
+
+| Old Tool (v2) | New Tool (v3) | Notes |
+|---------------|---------------|-------|
+| `append_prompts` | `add_prompt` | Always overwrites if exists (no `overwrite` param needed) |
+| `replace_prompt` | `add_prompt` | Same behavior, unified tool |
+
+**Migration:**
 ```javascript
-const result = await run_prompt({
-  name: "sentiment-analyzer",
-  parameters: { text: "I love this product!" }
-})
+// OLD (v2)
+append_prompts({ filePaths: [...], overwrite: true })
+replace_prompt({ filePath: "./prompt.promptl" })
 
-// Returns: { sentiment: "positive" }
+// NEW (v3)
+add_prompt({ filePaths: [...] })  // Always overwrites if exists
 ```
 
-### Example 4: Search Documentation
+---
 
-```javascript
-// Find topics about JSON
-docs({ action: "find", query: "json output" })
+## 🔧 Troubleshooting
 
-// Get specific topic
-docs({ action: "get", topic: "config-json-output" })
+### "Validation Failed" Errors
+
+**Problem:** Prompt fails with nested tag error
+
+**Solution:** The error shows exact location with code frame:
+```
+Error Code: `message-tag-inside-message`
+Location: Line 4, Column 7
+Code Context:
+4: <user><assistant>Nested!</assistant></user>
+          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Fix: Move the nested tag outside its parent.
 ```
 
+Follow the fix suggestion - errors are LLM-actionable!
+
+### "No Changes Made" After Push
+
+**Problem:** `push_prompts` reports no changes
+
+**Cause:** All prompts are already up to date (content matches LIVE)
+
+**Solution:** This is normal - no action needed
+
+### Version Naming Best Practices
+
+**Good:**
+- `feat/add-sentiment-analyzer`
+- `fix/typo-in-greeting`
+- `refactor/simplify-prompts`
+- `docs/update-examples`
+
+**Avoid:**
+- `test` (too vague)
+- `update` (what was updated?)
+- `v1.2.3` (use semantic versioning elsewhere)
+
+### Dynamic Descriptions Not Updating
+
+**Problem:** Tool descriptions show old prompt list
+
+**Cause:** Cache not refreshed (30s TTL)
+
+**Solution:** Wait 30 seconds or restart MCP server
+
 ---
 
 ## Contributing

package/dist/api.d.ts

@@ -11,7 +11,7 @@
  * - POST /projects/:id/versions/:uuid/documents/create-or-update - create/update document
  * - POST /projects/:id/versions/:uuid/documents/run - run document
  */
-import type { LatitudeError, Version, Document, DocumentChange, DeployResult, RunResult } from './types.js';
+import type { LatitudeError, Document, DocumentChange, DeployResult, RunResult } from './types.js';
 export declare class LatitudeApiError extends Error {
     readonly errorCode: string;
     readonly statusCode: number;
@@ -32,14 +32,8 @@ export declare class LatitudeApiError extends Error {
  * Get project ID from config
  */
 export declare function getProjectId(): string;
-export declare function listVersions(): Promise<Version[]>;
-export declare function getVersion(versionUuid: string): Promise<Version>;
-export declare function createVersion(name: string): Promise<Version>;
-export declare function publishVersion(versionUuid: string, title?: string): Promise<Version>;
 export declare function listDocuments(versionUuid?: string): Promise<Document[]>;
 export declare function getDocument(path: string, versionUuid?: string): Promise<Document>;
-export declare function createOrUpdateDocument(versionUuid: string, path: string, content: string, force?: boolean): Promise<Document>;
-export declare function deleteDocument(versionUuid: string, path: string): Promise<void>;
 /**
  * Push response from the API
  */
@@ -88,5 +82,4 @@ export declare function validatePromptLContent(content: string, path: string): P
  * This is the same workflow the CLI uses, ensuring proper validation.
  */
 export declare function deployToLive(changes: DocumentChange[], _versionName?: string): Promise<DeployResult>;
-export declare function getPromptNames(): Promise<string[]>;
 export {};

package/dist/api.js

@@ -15,20 +15,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LatitudeApiError = void 0;
 exports.getProjectId = getProjectId;
-exports.listVersions = listVersions;
-exports.getVersion = getVersion;
-exports.createVersion = createVersion;
-exports.publishVersion = publishVersion;
 exports.listDocuments = listDocuments;
 exports.getDocument = getDocument;
-exports.createOrUpdateDocument = createOrUpdateDocument;
-exports.deleteDocument = deleteDocument;
 exports.pushChanges = pushChanges;
 exports.computeDiff = computeDiff;
 exports.runDocument = runDocument;
 exports.validatePromptLContent = validatePromptLContent;
 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");
@@ -266,14 +259,6 @@ exports.LatitudeApiError = LatitudeApiError;
 function getProjectId() {
     return getConfig().projectId;
 }
-async function listVersions() {
-    const projectId = getProjectId();
-    return request(`/projects/${projectId}/versions`);
-}
-async function getVersion(versionUuid) {
-    const projectId = getProjectId();
-    return request(`/projects/${projectId}/versions/${versionUuid}`);
-}
 async function createVersion(name) {
     const projectId = getProjectId();
     return request(`/projects/${projectId}/versions`, {
@@ -298,19 +283,6 @@ async function getDocument(path, versionUuid = 'live') {
     const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
     return request(`/projects/${projectId}/versions/${versionUuid}/documents/${normalizedPath}`);
 }
-async function createOrUpdateDocument(versionUuid, path, content, force = false) {
-    const projectId = getProjectId();
-    logger.debug(`Creating/updating document: ${path} (${content.length} chars, force=${force})`);
-    return request(`/projects/${projectId}/versions/${versionUuid}/documents/create-or-update`, {
-        method: 'POST',
-        body: { path, prompt: content, force },
-    });
-}
-async function deleteDocument(versionUuid, path) {
-    const projectId = getProjectId();
-    const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
-    await request(`/projects/${projectId}/versions/${versionUuid}/documents/${normalizedPath}`, { method: 'DELETE' });
-}
 /**
  * Push changes to a version in a single batch
  * This is the CLI-style push that sends all changes at once
@@ -740,13 +712,3 @@ async function deployToLive(changes, _versionName) {
         throw publishError;
     }
 }
-async function getPromptNames() {
-    try {
-        const docs = await listDocuments('live');
-        return docs.map((doc) => doc.path);
-    }
-    catch (error) {
-        logger.warn('Failed to fetch prompt names', error);
-        return [];
-    }
-}

package/dist/index.js

@@ -20,7 +20,7 @@ async function main() {
     (0, server_js_1.setupGracefulShutdown)();
     // Log startup info
     logger.info('='.repeat(50));
-    logger.info('Latitude MCP Server v2.0.0');
+    logger.info('Latitude MCP Server v3.1.0');
     logger.info('='.repeat(50));
     // Validate required environment variables
     const apiKey = config_util_js_1.config.get('LATITUDE_API_KEY');

package/dist/server.js

@@ -17,7 +17,7 @@ const logger = logger_util_js_1.Logger.forContext('server.ts');
 // Server Configuration
 // ============================================================================
 const SERVER_NAME = 'latitude-mcp-server';
-const SERVER_VERSION = '2.0.0';
+const SERVER_VERSION = '3.1.0';
 // ============================================================================
 // Server Instance
 // ============================================================================

package/dist/tools.js

@@ -292,6 +292,10 @@ const PushPromptsSchema = zod_1.z.object({
         .array(zod_1.z.string())
         .optional()
         .describe('File paths to .promptl files - FULL SYNC: deletes remote prompts not in this list'),
+    versionName: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional version name (like git branch: feat/add-auth, fix/typo). If omitted, auto-generates timestamp.'),
 });
 async function handlePushPrompts(args) {
     try {
@@ -334,7 +338,7 @@ async function handlePushPrompts(args) {
         }
         // Push all changes in one batch
         try {
-            const result = await (0, api_js_1.deployToLive)(changes, 'push');
+            const result = await (0, api_js_1.deployToLive)(changes, args.versionName || 'push');
             // Force refresh cache after mutations
             const newNames = await forceRefreshAndGetNames();
             let content = `**Summary:**\n`;
@@ -381,6 +385,10 @@ const AddPromptSchema = zod_1.z.object({
         .array(zod_1.z.string())
         .optional()
         .describe('File paths to .promptl files - overwrites if exists, adds if new'),
+    versionName: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional version name (like git commit: feat/add-auth, fix/typo). Describes what changed.'),
 });
 async function handleAddPrompt(args) {
     try {
@@ -444,7 +452,7 @@ async function handleAddPrompt(args) {
         }
         // Push all changes in one batch
         try {
-            const result = await (0, api_js_1.deployToLive)(changes, 'add');
+            const result = await (0, api_js_1.deployToLive)(changes, args.versionName || 'add');
             // Force refresh cache after mutations
             const newNames = await forceRefreshAndGetNames();
             let content = `**Summary:**\n`;

package/package.json

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