latitudesh 0.0.2 → 0.1.0

package/README.md

@@ -1,49 +1,22 @@
-# latitudesh
-
-Model Context Protocol (MCP) Server for the *latitudesh* API.
-
-<div align="left" style="margin-bottom: 0;">
-    <a href="https://www.speakeasy.com/?utm_source=latitudesh&utm_campaign=mcp-typescript" class="badge-link">
-        <span class="badge-container">
-            <span class="badge-icon-section">
-                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 30 30" fill="none" style="vertical-align: middle;"><title>Speakeasy Logo</title><path fill="currentColor" d="m20.639 27.548-19.17-2.724L0 26.1l20.639 2.931 8.456-7.336-1.468-.208-6.988 6.062Z"></path><path fill="currentColor" d="m20.639 23.1 8.456-7.336-1.468-.207-6.988 6.06-6.84-.972-9.394-1.333-2.936-.417L0 20.169l2.937.416L0 23.132l20.639 2.931 8.456-7.334-1.468-.208-6.986 6.062-9.78-1.39 1.468-1.273 8.31 1.18Z"></path><path fill="currentColor" d="m20.639 18.65-19.17-2.724L0 17.201l20.639 2.931 8.456-7.334-1.468-.208-6.988 6.06Z"></path><path fill="currentColor" d="M27.627 6.658 24.69 9.205 20.64 12.72l-7.923-1.126L1.469 9.996 0 11.271l11.246 1.596-1.467 1.275-8.311-1.181L0 14.235l20.639 2.932 8.456-7.334-2.937-.418 2.937-2.549-1.468-.208Z"></path><path fill="currentColor" d="M29.095 3.902 8.456.971 0 8.305l20.639 2.934 8.456-7.337Z"></path></svg>
-            </span>
-            <span class="badge-text badge-text-section">BUILT BY SPEAKEASY</span>
-        </span>
-    </a>
-    <a href="https://opensource.org/licenses/MIT" class="badge-link">
-        <span class="badge-container blue">
-            <span class="badge-text badge-text-section">LICENSE // MIT</span>
-        </span>
-    </a>
-</div>
-
-
-<br /><br />
-> [!IMPORTANT]
-> This MCP Server is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/latitude/latitude). Delete this notice before publishing to a package manager.
+# Latitude.sh MCP Server
 
-<!-- Start Summary [summary] -->
-## Summary
+> Model Context Protocol (MCP) server for the [Latitude.sh API](https://www.latitude.sh/docs/api-reference)
 
-Latitude.sh API: The Latitude.sh API is a RESTful API to manage your Latitude.sh account. It allows you to perform the same actions as the Latitude.sh dashboard.
-<!-- End Summary [summary] -->
+## Overview
 
-<!-- Start Table of Contents [toc] -->
-## Table of Contents
-<!-- $toc-max-depth=2 -->
-* [latitudesh](#latitudesh)
-  * [Installation](#installation)
-  * [Development](#development)
-  * [Contributions](#contributions)
+The Latitude.sh MCP Server exposes your Latitude.sh REST API as an AI-ready interface, allowing developer tools and assistants to list, create, and manage your infrastructure resources programmatically.
+
+Use natural language to:
+
+- 🔎 List and inspect servers, projects, and SSH keys
+- ⚙️ Create or delete bare-metal instances
+- 📡 Manage networking and automation directly from chat-based IDEs
 
-<!-- End Table of Contents [toc] -->
 
-<!-- Start Installation [installation] -->
 ## Installation
 
-> [!TIP]
-> To finish publishing your MCP Server to npm and others you must [run your first generation action](https://www.speakeasy.com/docs/github-setup#step-by-step-guide).
+> 🪶 Prerequisite: You’ll need a [Latitude.sh API Key](https://www.latitude.sh/dashboard/api-keys).
+
 <details>
 <summary>DXT (Desktop Extension)</summary>
 
@@ -61,14 +34,10 @@ The DXT package includes the MCP server and all necessary configuration. Once in
 <details>
 <summary>Cursor</summary>
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=Latitudesh&config=eyJtY3BTZXJ2ZXJzIjp7IkxhdGl0dWRlc2giOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsibGF0aXR1ZGVzaCIsInN0YXJ0IiwiLS1zZXJ2ZXItaW5kZXgiLCIuLi4iLCItLWxhdGl0dWRlLWFwaS1rZXkiLCIuLi4iLCItLWJlYXJlciIsIi4uLiJdfX19)
-
-Or manually:
-
 1. Open Cursor Settings
 2. Select Tools and Integrations
 3. Select New MCP Server
-4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:
+4. Paste the following JSON into the MCP Server Configuration:
 
 ```json
 {
@@ -78,27 +47,27 @@ Or manually:
       "args": [
         "latitudesh",
         "start",
-        "--server-index",
-        "...",
-        "--latitude-api-key",
-        "...",
         "--bearer",
-        "..."
+        "<YOUR_API_KEY>"
       ]
     }
   }
 }
 ```
 
+**Note:** Replace `YOUR_LATITUDE_API_TOKEN` with your actual Latitude.sh bearer token.
+
 </details>
 
 <details>
 <summary>Claude Code CLI</summary>
 
 ```bash
-claude mcp add latitudesh npx latitudesh start -- --server-index ... --latitude-api-key ... --bearer ...
+claude mcp add latitudesh npx latitudesh start -- --bearer YOUR_LATITUDE_API_TOKEN
 ```
 
+**Note:** Replace `YOUR_LATITUDE_API_TOKEN` with your actual Latitude.sh bearer token.
+
 </details>
 <details>
 <summary>Windsurf</summary>
@@ -110,7 +79,7 @@ Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/ca
 3. Click on `Manage MCPs`. (To Manage MCPs you should be signed in with a Windsurf Account)
 4. Click on `View raw config` to open up the mcp configuration file.
 5. If the configuration file is empty paste the full json
-```
+```json
 {
   "mcpServers": {
     "Latitudesh": {
@@ -118,12 +87,8 @@ Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/ca
       "args": [
         "latitudesh",
         "start",
-        "--server-index",
-        "...",
-        "--latitude-api-key",
-        "...",
         "--bearer",
-        "..."
+        "<YOUR_API_KEY>"
       ]
     }
   }
@@ -138,7 +103,7 @@ Refer to [Official VS Code documentation](https://code.visualstudio.com/api/exte
 1. Open [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
 1. Search and open `MCP: Open User Configuration`. This should open mcp.json file
 2. If the configuration file is empty paste the full json
-```
+```json
 {
   "mcpServers": {
     "Latitudesh": {
@@ -146,12 +111,8 @@ Refer to [Official VS Code documentation](https://code.visualstudio.com/api/exte
       "args": [
         "latitudesh",
         "start",
-        "--server-index",
-        "...",
-        "--latitude-api-key",
-        "...",
         "--bearer",
-        "..."
+        "<YOUR_API_KEY>"
       ]
     }
   }
@@ -179,48 +140,117 @@ Paste the following config in the configuration
       "args": [
         "latitudesh",
         "start",
-        "--server-index",
-        "...",
-        "--latitude-api-key",
-        "...",
         "--bearer",
-        "..."
+        "<YOUR_API_KEY>"
       ]
     }
   }
 }
 ```
 
+**Note:** Replace `YOUR_LATITUDE_API_TOKEN` with your actual Latitude.sh bearer token.
+
 </details>
+<details>
+<summary>VS Code</summary>
+
+Refer to [Official VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for latest information
+
+1. Open [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (`Cmd+Shift+P` / `Ctrl+Shift+P`)
+2. Search and open `MCP: Open User Configuration` to open the mcp.json file
+3. Add the configuration:
+
+```json
+{
+  "servers": {
+    "Latitudesh": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "latitudesh",
+        "start",
+        "--bearer",
+        "YOUR_LATITUDE_API_TOKEN"
+      ]
+    }
+  }
+}
+```
 
+4. Save the file and restart VS Code
+5. Open Copilot Chat (`Cmd+Alt+I` / `Ctrl+Alt+I`) and enable **Agent mode**
+6. The Latitudesh tools will be available automatically
 
+**Note:** Replace `YOUR_LATITUDE_API_TOKEN` with your actual Latitude.sh bearer token.
+
+**Tips for using with VS Code:**
+- Be explicit in your prompts: "List my servers from Latitude.sh" instead of just "list servers"
+- Mention "Latitude.sh" or "MCP" to avoid Copilot searching local files
+
+</details>
 <details>
-<summary> Stdio installation via npm </summary>
-To start the MCP server, run:
+<summary>Claude Desktop</summary>
 
-```bash
-npx latitudesh start --server-index ... --latitude-api-key ... --bearer ...
+1. Open Claude Desktop
+2. Click on your Username in the left sidebar
+3. Go to `Settings` → `Developer` tab
+4. Click `Edit Config`
+5. Add the configuration:
+
+```json
+{
+  "mcpServers": {
+    "Latitudesh": {
+      "command": "npx",
+      "args": [
+        "latitudesh",
+        "start",
+        "--bearer",
+        "YOUR_LATITUDE_API_TOKEN"
+      ]
+    }
+  }
+}
 ```
 
-For a full list of server arguments, run:
+6. Save and restart Claude Desktop
 
+**Note:** Replace `YOUR_LATITUDE_API_TOKEN` with your actual Latitude.sh bearer token.
+
+</details>
+
+<details>
+<summary>Standalone CLI Usage</summary>
+
+To start the MCP server directly:
+
+```bash
+npx latitudesh start --bearer YOUR_LATITUDE_API_TOKEN
 ```
+
+**Optional flags:**
+- `--server-index <0|1>` - Select server (0=https://api.latitude.sh, 1=http://api.latitude.sh) [default: 0]
+- `--latitude-api-key <key>` - API key for URL templating
+- `--log-level <level>` - Log level (debug|warning|info|error) [default: info]
+
+For a full list of server arguments:
+
+```bash
 npx latitudesh --help
 ```
 
 </details>
-<!-- End Installation [installation] -->
-
-<!-- Placeholder for Future Speakeasy SDK Sections -->
 
 ## Development
 
 Run locally without a published npm package:
+
 1. Clone this repository
 2. Run `npm install`
 3. Run `npm run build`
-4. Run `node ./bin/mcp-server.js start --server-index ... --latitude-api-key ... --bearer ...`
-To use this local version with Cursor, Claude or other MCP Clients, you'll need to add the following config:
+4. Run `node ./bin/mcp-server.js start --bearer <YOUR_API_KEY>`
+
+To use this local version with MCP Clients, you'll need to add the following config:
 
 ```json
 {
@@ -228,31 +258,217 @@ To use this local version with Cursor, Claude or other MCP Clients, you'll need
     "Latitudesh": {
       "command": "node",
       "args": [
-        "./bin/mcp-server.js",
+        "/absolute/path/to/latitudesh-mcp/bin/mcp-server.js",
         "start",
-        "--server-index",
-        "...",
-        "--latitude-api-key",
-        "...",
         "--bearer",
-        "..."
+        "<YOUR_API_KEY>"
       ]
     }
   }
 }
 ```
 
-Or to debug the MCP server locally, use the official MCP Inspector: 
+### Debug locally
+
+Use the official [MCP Inspector](https://www.npmjs.com/package/@modelcontextprotocol/inspector):
 
 ```bash
-npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-index ... --latitude-api-key ... --bearer ...
+npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --bearer <YOUR_API_KEY>
 ```
 
+This opens an interactive UI at http://localhost:6274.
+
+## 🤝 Contributions
+
+While we welcome contributions, most of this code is auto-generated. Manual edits to generated files will be overwritten on regeneration.
+
+If you'd like to suggest improvements:
+
+- Open an Issue or PR with your proof of concept
+- We'll review and include it in future releases when possible
+
+<!-- Start Summary [summary] -->
+## Summary
+
+Latitude.sh API: The Latitude.sh API is a RESTful API to manage your Latitude.sh account. It allows you to perform the same actions as the Latitude.sh dashboard.
+<!-- End Summary [summary] -->
+
+<!-- Start Table of Contents [toc] -->
+## Table of Contents
+<!-- $toc-max-depth=2 -->
+* [Latitude.sh MCP Server](#latitudesh-mcp-server)
+  * [Overview](#overview)
+  * [Installation](#installation)
+  * [Development](#development)
+  * [🤝 Contributions](#contributions)
+  * [Installation](#installation-1)
+  * [Progressive Discovery](#progressive-discovery)
 
+<!-- End Table of Contents [toc] -->
+
+<!-- Start Installation [installation] -->
+## Installation
 
-## Contributions
+<details>
+<summary>Claude Desktop</summary>
 
-While we value contributions to this MCP Server, the code is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. 
-We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release. 
+Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](https://github.com/latitudesh/latitudesh-mcp/releases/download/v0.1.0/mcp-server.mcpb) file:
 
-### MCP Server Created by [Speakeasy](https://www.speakeasy.com/?utm_source=latitudesh&utm_campaign=mcp-typescript)
+Simply drag and drop the [`mcp-server.mcpb`](https://github.com/latitudesh/latitudesh-mcp/releases/download/v0.1.0/mcp-server.mcpb) file onto Claude Desktop to install the extension.
+
+The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.
+
+> [!NOTE]
+> MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Latitudesh&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJsYXRpdHVkZXNoIiwic3RhcnQiLCItLXNlcnZlci1pbmRleCIsIjAiLCItLWxhdGl0dWRlLWFwaS1rZXkiLCI8aW5zZXJ0IHlvdXIgYXBpIGtleSBoZXJlPiIsIi0tYmVhcmVyIiwiIl19)
+
+Or manually:
+
+1. Open Cursor Settings
+2. Select Tools and Integrations
+3. Select New MCP Server
+4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "latitudesh",
+    "start",
+    "--server-index",
+    "0",
+    "--latitude-api-key",
+    "<insert your api key here>",
+    "--bearer",
+    ""
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code CLI</summary>
+
+```bash
+claude mcp add Latitudesh -- npx -y latitudesh start --server-index 0 --latitude-api-key <insert your api key here> --bearer 
+```
+
+</details>
+<details>
+<summary>Gemini</summary>
+
+```bash
+gemini mcp add Latitudesh -- npx -y latitudesh start --server-index 0 --latitude-api-key <insert your api key here> --bearer 
+```
+
+</details>
+<details>
+<summary>Windsurf</summary>
+
+Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin) for latest information
+
+1. Open Windsurf Settings
+2. Select Cascade on left side menu
+3. Click on `Manage MCPs`. (To Manage MCPs you should be signed in with a Windsurf Account)
+4. Click on `View raw config` to open up the mcp configuration file.
+5. If the configuration file is empty paste the full json
+
+```bash
+{
+  "command": "npx",
+  "args": [
+    "latitudesh",
+    "start",
+    "--server-index",
+    "0",
+    "--latitude-api-key",
+    "<insert your api key here>",
+    "--bearer",
+    ""
+  ]
+}
+```
+</details>
+<details>
+<summary>VS Code</summary>
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Latitudesh%20MCP&color=0098FF)](vscode://ms-vscode.vscode-mcp/install?name=Latitudesh&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJsYXRpdHVkZXNoIiwic3RhcnQiLCItLXNlcnZlci1pbmRleCIsIjAiLCItLWxhdGl0dWRlLWFwaS1rZXkiLCI8aW5zZXJ0IHlvdXIgYXBpIGtleSBoZXJlPiIsIi0tYmVhcmVyIiwiIl19)
+
+Or manually:
+
+Refer to [Official VS Code documentation](https://code.visualstudio.com/api/extension-guides/ai/mcp) for latest information
+
+1. Open [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
+1. Search and open `MCP: Open User Configuration`. This should open mcp.json file
+2. If the configuration file is empty paste the full json
+
+```bash
+{
+  "command": "npx",
+  "args": [
+    "latitudesh",
+    "start",
+    "--server-index",
+    "0",
+    "--latitude-api-key",
+    "<insert your api key here>",
+    "--bearer",
+    ""
+  ]
+}
+```
+
+</details>
+<details>
+<summary> Stdio installation via npm </summary>
+To start the MCP server, run:
+
+```bash
+npx latitudesh start --server-index 0 --latitude-api-key <insert your api key here> --bearer 
+```
+
+For a full list of server arguments, run:
+
+```
+npx latitudesh --help
+```
+
+</details>
+<!-- End Installation [installation] -->
+
+<!-- Start Progressive Discovery [dynamic-mode] -->
+## Progressive Discovery
+
+MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.
+
+To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:
+
+```jsonc
+{
+  "mcpServers": {
+    "Latitudesh": {
+      "command": "npx",
+      "args": ["latitudesh", "start", "--mode", "dynamic"],
+      // ... other server arguments
+    }
+  }
+}
+```
+
+In dynamic mode, the server registers only the following meta-tools instead of every individual tool:
+
+- **`list_tools`**: Lists all available tools with their names and descriptions.
+- **`describe_tool`**: Returns the input schema for one or more tools by name.
+- **`execute_tool`**: Executes a tool by name with the provided input parameters.
+
+This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.
+<!-- End Progressive Discovery [dynamic-mode] -->
+
+<!-- Placeholder for Future Speakeasy SDK Sections -->