latitude-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -18,8 +18,9 @@
 </p>
 
 <p align="center">
-  <img alt="tools" src="https://img.shields.io/badge/🛠️_16_MCP_tools-full_CRUD_operations-2ED573.svg?style=for-the-badge">
-  <img alt="resources" src="https://img.shields.io/badge/📚_4_resources-read_only_access-2ED573.svg?style=for-the-badge">
+  <img alt="tools" src="https://img.shields.io/badge/🛠️_19_MCP_tools-full_CRUD_+_docs-2ED573.svg?style=for-the-badge">
+  <img alt="resources" src="https://img.shields.io/badge/📚_6_resources-read_only_access-2ED573.svg?style=for-the-badge">
+  <img alt="docs" src="https://img.shields.io/badge/📖_38_doc_topics-self_learning-4D87E6.svg?style=for-the-badge">
 </p>
 
 <div align="center">
@@ -217,7 +218,7 @@ Add to `.cursor/mcp.json` or MCP settings:
 
 ## 🛠️ Tool Reference
 
-This server provides **16 MCP tools** covering the complete Latitude API.
+This server provides **19 MCP tools** covering the complete Latitude API plus built-in documentation with **38 topics**.
 
 <div align="center">
 <table>
@@ -227,6 +228,7 @@ This server provides **16 MCP tools** covering the complete Latitude API.
 <td align="center">📝<br/><b>Prompts</b></td>
 <td align="center">🤖<br/><b>Execution</b></td>
 <td align="center">📊<br/><b>Operations</b></td>
+<td align="center">📚<br/><b>Docs</b></td>
 </tr>
 <tr>
 <td valign="top">
@@ -255,12 +257,124 @@ This server provides **16 MCP tools** covering the complete Latitude API.
 <code>create_log</code><br/>
 <code>trigger_evaluation</code>
 </td>
+<td valign="top">
+<code>help</code><br/>
+<code>get_docs</code><br/>
+<code>find_docs</code>
+</td>
 </tr>
 </table>
 </div>
 
 ---
 
+### 📚 Documentation Tools (AI Self-Learning)
+
+The server includes **38 documentation topics** organized by category, enabling AI agents to learn PromptL syntax on-demand. Topics include enhanced metadata (`useWhen` triggers, `difficulty`, `prerequisites`) for intelligent discovery.
+
+#### `latitude_help`
+
+Get complete server overview — all tools, documentation topics, and quick start workflow.
+
+```json
+{}
+```
+
+**Returns:** Server overview with 19 tools, 38 doc topics by category, and suggested next actions.
+
+---
+
+#### `latitude_find_docs` ⭐ NEW
+
+**Semantic search for documentation.** Describe what you're trying to do, get matched topics. Uses `useWhen` triggers from topic metadata for intelligent matching.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | `string` | Yes | What are you trying to do? |
+| `maxResults` | `number` | No | Max topics to return (default: 5) |
+
+```json
+{
+  "query": "extract structured data from text"
+}
+```
+
+**How it works:** Scores topics based on:
+- Title/description match
+- `useWhen` trigger phrases (e.g., "json output", "extract", "chatbot")
+- Topic name relevance
+
+**Returns:** Ranked topics with relevance scores and `getDocsCommand` for each.
+
+---
+
+#### `latitude_get_docs`
+
+Get comprehensive PromptL documentation for a specific topic.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | `enum` | Yes | One of 38 topics (see below) |
+
+**Available Topics (38 total):**
+
+| Category | Topics |
+|----------|--------|
+| **Core Syntax** (11) | `overview`, `structure`, `variables`, `conditionals`, `loops`, `references`, `tools`, `chains`, `agents`, `techniques`, `agent-patterns` |
+| **Configuration** (7) | `config-basics`, `config-generation`, `config-json-output`, `config-advanced`, `providers-openai`, `providers-anthropic`, `providers-google` |
+| **Messages** (2) | `messages-roles`, `messages-multimodal` |
+| **Tools** (4) | `tools-builtin`, `tools-custom`, `tools-schema` |
+| **Techniques** (4) | `technique-role`, `technique-few-shot`, `technique-cot`, `technique-tot` |
+| **Recipes** (5) | `recipe-classification`, `recipe-extraction`, `recipe-generation`, `recipe-chatbot`, `recipe-rag` |
+| **Guides** (6) | `conversation-history`, `guide-debugging`, `guide-safety`, `guide-performance`, `guide-testing`, `guide-versioning` |
+
+```json
+{
+  "topic": "recipe-rag"
+}
+```
+
+**Returns:** Comprehensive documentation with syntax, examples, best practices, related topics, and suggested tools.
+
+---
+
+#### Writing PromptL-Compliant Prompts
+
+AI agents can use these tools to write valid PromptL prompts:
+
+```
+1. latitude_find_docs({ query: "build a chatbot" })  → Discover relevant topics
+2. latitude_get_docs({ topic: "recipe-chatbot" })    → Learn chatbot patterns
+3. latitude_get_docs({ topic: "conversation-history" }) → Learn context management
+4. latitude_push_prompt                              → Push your prompt
+5. latitude_run_prompt                               → Test execution
+```
+
+**Example: AI discovers how to extract structured data:**
+
+```
+AI: latitude_find_docs({ query: "extract JSON from text" })
+   → Returns: config-json-output (score: 24), recipe-extraction (score: 18)
+
+AI: latitude_get_docs({ topic: "config-json-output" })
+   → Learns: schema config, JSON Schema types, constraints
+
+AI: Now writes valid PromptL:
+   ---
+   provider: OpenAI
+   model: gpt-4o
+   schema:
+     type: object
+     properties:
+       name: { type: string }
+       email: { type: string }
+     required: [name, email]
+   ---
+   Extract contact info from: {{ text }}
+```
+
+---
+
 ### Project Tools
 
 #### `latitude_list_projects`
@@ -530,6 +644,8 @@ Access Latitude data via MCP resources (read-only):
 | `latitude://projects/{projectId}/versions` | List versions for project |
 | `latitude://projects/{projectId}/versions/{versionUuid}/prompts` | List prompts in version |
 | `latitude://projects/{projectId}/versions/{versionUuid}/prompts/{path}` | Get specific prompt |
+| `docs://latitude/help` | Server overview & quick start |
+| `docs://latitude/{topic}` | PromptL documentation by topic |
 
 ---
 
@@ -635,8 +751,30 @@ latitude-mcp chat <conversationUuid> -m "Follow up question"
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `LATITUDE_API_KEY` | Yes | — | Your Latitude API key |
+| `LATITUDE_PROJECT_ID` | No | — | Default project ID (skip `projectId` in all tools) |
 | `LATITUDE_BASE_URL` | No | `https://gateway.latitude.so` | API base URL |
 
+### Skip `projectId` with Default Project
+
+Set `LATITUDE_PROJECT_ID` to avoid specifying `projectId` in every tool call:
+
+```json
+{
+  "mcpServers": {
+    "latitude": {
+      "command": "npx",
+      "args": ["latitude-mcp-server"],
+      "env": {
+        "LATITUDE_API_KEY": "your-api-key",
+        "LATITUDE_PROJECT_ID": "27756"
+      }
+    }
+  }
+}
+```
+
+When set, all tools that require `projectId` will use this default. You can still override per-call.
+
 ---
 
 ## 🔥 Common Issues & Quick Fixes

package/dist/controllers/latitude.controller.js

@@ -191,7 +191,10 @@ async function runPrompt(args) {
             userMessage: args.userMessage,
         });
         // Handle streaming response
-        if (args.stream && result && typeof result === 'object' && Symbol.asyncIterator in result) {
+        if (args.stream &&
+            result &&
+            typeof result === 'object' &&
+            Symbol.asyncIterator in result) {
             const chunks = [];
             for await (const chunk of result) {
                 chunks.push(chunk);
@@ -236,7 +239,10 @@ async function chat(args) {
         const messages = [{ role: 'user', content: args.message }];
         const result = await vendor_latitude_service_js_1.default.chatConversation(args.conversationUuid, messages, args.stream);
         // Handle streaming response
-        if (args.stream && result && typeof result === 'object' && Symbol.asyncIterator in result) {
+        if (args.stream &&
+            result &&
+            typeof result === 'object' &&
+            Symbol.asyncIterator in result) {
             const chunks = [];
             for await (const chunk of result) {
                 chunks.push(chunk);

package/dist/docs/phase1.docs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Phase 1 - Tier 1 Documentation Topics
+ *
+ * New granular documentation for:
+ * - config-json-output
+ * - config-generation
+ * - tools-builtin
+ * - technique-role
+ * - recipe-classification
+ * - recipe-extraction
+ * - conversation-history
+ * - guide-debugging
+ */
+export declare const DOCS_CONFIG_JSON_OUTPUT = "# Enforcing JSON Output\n\n> Guarantee structured responses with JSON Schema\n\n## Overview\n\nUse the \\`schema\\` config to force the model to return valid JSON.\n\n\\`\\`\\`yaml\n---\nprovider: OpenAI\nmodel: gpt-4o\nschema:\n  type: object\n  properties:\n    sentiment:\n      type: string\n      enum: [positive, negative, neutral]\n    confidence:\n      type: number\n  required: [sentiment, confidence]\n---\nAnalyze: {{ text }}\n\\`\\`\\`\n\n## Data Types\n\n| Type | Example | Use Case |\n|------|---------|----------|\n| \\`string\\` | \\`\"hello\"\\` | Text |\n| \\`number\\` | \\`0.95\\` | Scores |\n| \\`integer\\` | \\`42\\` | Counts |\n| \\`boolean\\` | \\`true\\` | Flags |\n| \\`array\\` | \\`[\"a\"]\\` | Lists |\n| \\`object\\` | \\`{...}\\` | Nested |\n\n## Constraints\n\n| Constraint | Description |\n|------------|-------------|\n| \\`enum\\` | Limit to values |\n| \\`minimum/maximum\\` | Number range |\n| \\`minLength/maxLength\\` | String length |\n| \\`minItems/maxItems\\` | Array size |\n\n## Tips\n\n- Always add \\`required\\` - prevents missing fields\n- Use \\`enum\\` for categories\n- Keep schemas focused - smaller = reliable\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"recipe-extraction\" })\\`\n- \\`latitude_get_docs({ topic: \"tools-builtin\" })\\`\n";
+export declare const DOCS_CONFIG_GENERATION = "# Generation Parameters\n\n> Control randomness, length, and quality\n\n## temperature\n\nControls randomness. Lower = focused, higher = creative.\n\n| Value | Use Case |\n|-------|----------|\n| \\`0\\` | Factual (enables caching) |\n| \\`0.2-0.4\\` | Code, analysis |\n| \\`0.5-0.7\\` | Balanced |\n| \\`0.8-1.0\\` | Creative |\n\n## maxTokens\n\nMaximum response length (~4 chars/token).\n\n## topP\n\nNucleus sampling. Use temperature OR topP, not both.\n\n## Penalties\n\n- \\`presencePenalty\\`: Avoid repeating topics\n- \\`frequencyPenalty\\`: Avoid repeating words\n\n## Common Configs\n\n- **Factual:** temperature: 0, maxTokens: 500\n- **Creative:** temperature: 0.9, maxTokens: 2000\n- **Code:** temperature: 0.2, maxTokens: 1000\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| Too random | Lower temperature |\n| Too boring | Raise temperature |\n| Too long | Set maxTokens |\n| Repetitive | Add frequencyPenalty |\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"guide-debugging\" })\\`\n";
+export declare const DOCS_TOOLS_BUILTIN = "# Built-in Latitude Tools\n\n> Pre-built: search, code, extract\n\n## Overview\n\n| Tool | Capability |\n|------|------------|\n| \\`latitude/search\\` | Web search |\n| \\`latitude/code\\` | Execute code |\n| \\`latitude/extract\\` | Extract data |\n\n## latitude/search\n\n\\`\\`\\`yaml\ntools:\n  - latitude/search\n\\`\\`\\`\n\n**Use for:** Real-time info, fact verification, research.\n\n## latitude/code\n\n\\`\\`\\`yaml\ntools:\n  - latitude/code\n\\`\\`\\`\n\n**Use for:** Math, data transformations, algorithms.\n\n## latitude/extract\n\n\\`\\`\\`yaml\ntools:\n  - latitude/extract\n\\`\\`\\`\n\n**Use for:** Entity extraction, data parsing.\n\n## Combining Tools\n\n\\`\\`\\`yaml\ntools:\n  - latitude/search\n  - latitude/code\n  - latitude/extract\n\\`\\`\\`\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"tools\" })\\`\n- \\`latitude_get_docs({ topic: \"recipe-extraction\" })\\`\n";
+export declare const DOCS_TECHNIQUE_ROLE = "# Role Prompting\n\n> Assign personas for specialized responses\n\n## Overview\n\nRole prompting assigns a persona to improve response quality.\n\n\\`\\`\\`\nYou are a senior financial advisor with 20 years of experience.\nSpecialization: retirement planning.\nStyle: professional yet approachable.\n\\`\\`\\`\n\n## Role Template\n\n\\`\\`\\`\nYou are a [ROLE] with [EXPERIENCE].\n\n**Expertise:** [skills]\n**Style:** [tone]\n**Constraints:** [limitations]\n\\`\\`\\`\n\n## Dynamic Roles\n\n\\`\\`\\`\n{{ if domain == \"legal\" }}\nYou are a senior attorney in {{ specialty }}.\n{{ else if domain == \"medical\" }}\nYou are a physician in {{ specialty }}.\n{{ endif }}\n\\`\\`\\`\n\n## Constrained Roles\n\n\\`\\`\\`\nYou are a customer service rep.\n\n**You MUST:** Be polite, reference policies.\n**You MUST NOT:** Make promises, share internal info.\n\\`\\`\\`\n\n## Best Practices\n\n| Do | Don't |\n|----|-------|\n| Define specific expertise | Generic \"expert\" |\n| Set communication style | Let tone vary |\n| Add constraints | Allow unrestricted |\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"agents\" })\\`\n- \\`latitude_get_docs({ topic: \"techniques\" })\\`\n";
+export declare const DOCS_RECIPE_CLASSIFICATION = "# Classification Patterns\n\n> Sentiment, intent, category classification\n\n## Few-Shot Classification\n\n\\`\\`\\`yaml\nschema:\n  type: object\n  properties:\n    label:\n      type: string\n      enum: [positive, negative, neutral]\n  required: [label]\n\\`\\`\\`\n\n\\`\\`\\`\nText: \"I love this!\" \u2192 positive\nText: \"Terrible.\" \u2192 negative\nText: \"{{ input }}\" \u2192\n\\`\\`\\`\n\n## Dynamic Examples\n\n\\`\\`\\`\n{{ for ex in examples }}\nText: {{ ex.text }}\nLabel: {{ ex.label }}\n{{ endfor }}\nText: {{ input }}\nLabel:\n\\`\\`\\`\n\n## Intent Classification\n\n\\`\\`\\`yaml\nschema:\n  type: object\n  properties:\n    intent:\n      type: string\n      enum: [order_status, return, complaint, other]\n    urgency:\n      type: string\n      enum: [low, medium, high]\n\\`\\`\\`\n\n## Tips\n\n- Use 3-5 examples per class\n- Balance examples across categories\n- Use JSON schema for reliable output\n- Include \"other\" for edge cases\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"config-json-output\" })\\`\n- \\`latitude_get_docs({ topic: \"loops\" })\\`\n";
+export declare const DOCS_RECIPE_EXTRACTION = "# Data Extraction Patterns\n\n> Entity extraction, structured data parsing\n\n## Basic Extraction\n\n\\`\\`\\`yaml\nschema:\n  type: object\n  properties:\n    name: { type: string }\n    email: { type: string }\n    phone: { type: string }\n\\`\\`\\`\n\n## Named Entity Recognition\n\n\\`\\`\\`yaml\nschema:\n  type: object\n  properties:\n    people:\n      type: array\n      items: { type: string }\n    organizations:\n      type: array\n      items: { type: string }\n    locations:\n      type: array\n      items: { type: string }\n\\`\\`\\`\n\n## Financial Extraction\n\n\\`\\`\\`yaml\nschema:\n  type: object\n  properties:\n    company: { type: string }\n    revenue: { type: string }\n    profit: { type: string }\n\\`\\`\\`\n\n## Tips\n\n- Use specific schemas for accuracy\n- Handle missing fields gracefully\n- Test with varied inputs\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"config-json-output\" })\\`\n- \\`latitude_get_docs({ topic: \"tools-builtin\" })\\`\n";
+export declare const DOCS_CONVERSATION_HISTORY = "# Conversation History\n\n> Multi-turn conversations, context management\n\n## Basic History Injection\n\n\\`\\`\\`\n{{ for msg in history }}\n<{{ msg.role }}>\n{{ msg.content }}\n</{{ msg.role }}>\n{{ endfor }}\n\n<user>{{ new_message }}</user>\n\\`\\`\\`\n\n## With System Context\n\n\\`\\`\\`\n<system>\nYou are a helpful assistant for {{ company }}.\n</system>\n\n{{ for msg in history }}\n<{{ msg.role }}>{{ msg.content }}</{{ msg.role }}>\n{{ endfor }}\n\n<user>{{ input }}</user>\n\\`\\`\\`\n\n## Summarized History\n\nFor long conversations:\n\n\\`\\`\\`\n<system>\nSummary: {{ summary }}\n</system>\n\n{{ for msg in recent_messages }}\n<{{ msg.role }}>{{ msg.content }}</{{ msg.role }}>\n{{ endfor }}\n\\`\\`\\`\n\n## Using latitude_chat\n\n1. \\`latitude_run_prompt\\` \u2192 get conversationUuid\n2. \\`latitude_chat({ conversationUuid, message })\\` \u2192 continue\n3. \\`latitude_get_conversation\\` \u2192 retrieve history\n\n## Token Management\n\n| Length | Strategy |\n|--------|----------|\n| < 10 msgs | Include all |\n| 10-30 msgs | Last 10 + summary |\n| 30+ msgs | Summary + last 5 |\n\n## Next Steps\n\n- \\`latitude_chat\\`\n- \\`latitude_get_docs({ topic: \"loops\" })\\`\n";
+export declare const DOCS_GUIDE_DEBUGGING = "# Debugging & Troubleshooting\n\n> Common errors and fixes\n\n## Variables Not Rendering\n\n**Symptom:** {{ variable }} appears literally\n\n| Cause | Fix |\n|-------|-----|\n| Typo | Check spelling |\n| Not passed | Provide parameter |\n| Wrong syntax | Use {{ }} |\n\n**Debug:** {{ variable || \"NOT_PROVIDED\" }}\n\n## Conditionals Not Working\n\nWrong - Missing endif:\n\\`\\`\\`\n{{ if condition }}\n  content\n\\`\\`\\`\n\nCorrect:\n\\`\\`\\`\n{{ if condition }}\n  content\n{{ endif }}\n\\`\\`\\`\n\nWrong - Missing quotes:\n\\`\\`\\`\n{{ if role == admin }}\n\\`\\`\\`\n\nCorrect:\n\\`\\`\\`\n{{ if role == \"admin\" }}\n\\`\\`\\`\n\n## Loops Not Iterating\n\n| Cause | Fix |\n|-------|-----|\n| Empty array | Check array has items |\n| Wrong name | Verify spelling |\n\n## Model Behavior Issues\n\n| Problem | Solution |\n|---------|----------|\n| Ignores instructions | Move to beginning |\n| Wrong format | Use JSON schema |\n| Too verbose | Add length instruction |\n| Too creative | Lower temperature |\n| Repetitive | Add frequencyPenalty |\n\n## Debugging Checklist\n\n- Variables spelled correctly?\n- All if have endif?\n- All for have endfor?\n- Strings quoted in comparisons?\n- YAML indentation correct?\n- Parameters provided?\n\n## Next Steps\n\n- \\`latitude_get_docs({ topic: \"variables\" })\\`\n- \\`latitude_get_docs({ topic: \"conditionals\" })\\`\n";