@samik081/mcp-komodo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Komodo MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+[![npm version](https://img.shields.io/npm/v/@samik081/mcp-komodo)](https://www.npmjs.com/package/@samik081/mcp-komodo)
+[![License: MIT](https://img.shields.io/npm/l/@samik081/mcp-komodo)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@samik081/mcp-komodo)](https://nodejs.org)
+
+# MCP Komodo
+
+MCP server for the [Komodo](https://komo.do) DevOps platform. Manage servers, stacks, deployments, builds, and more through natural language in Cursor, Claude Code, and Claude Desktop.
+
+## Features
+
+- **40 tools** across **12 resource categories** covering the complete Komodo DevOps API
+- **Three access tiers** (`read-only`, `read-execute`, `full`) for granular control
+- **Category filtering** via `KOMODO_CATEGORIES` to expose only the tools you need
+- **Zero HTTP dependencies** -- uses the official `komodo_client` SDK
+- **TypeScript/ESM** with full type safety
+
+## Quick Start
+
+Run the server directly with npx:
+
+```bash
+KOMODO_URL="https://komodo.example.com" \
+KOMODO_API_KEY="your-api-key" \
+KOMODO_API_SECRET="your-api-secret" \
+npx @samik081/mcp-komodo
+```
+
+The server validates your Komodo connection on startup and fails immediately with a clear error if credentials are missing or invalid.
+
+## Configuration
+
+**Claude Code CLI (recommended):**
+
+```bash
+claude mcp add --transport stdio komodo \
+  --env KOMODO_URL=https://komodo.example.com \
+  --env KOMODO_API_KEY=your-api-key \
+  --env KOMODO_API_SECRET=your-api-secret \
+  -- npx @samik081/mcp-komodo
+```
+
+**JSON config** (works with Claude Code `.mcp.json`, Claude Desktop `claude_desktop_config.json`, Cursor `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "komodo": {
+      "command": "npx",
+      "args": ["@samik081/mcp-komodo"],
+      "env": {
+        "KOMODO_URL": "https://komodo.example.com",
+        "KOMODO_API_KEY": "your-api-key",
+        "KOMODO_API_SECRET": "your-api-secret"
+      }
+    }
+  }
+}
+```
+
+## Access Tiers
+
+Control which tools are available using the `KOMODO_ACCESS_TIER` environment variable:
+
+| Tier | Tools | Description |
+|------|-------|-------------|
+| `full` (default) | 40 | Read, execute, and write -- full control |
+| `read-execute` | 39 | Read and execute -- no resource creation/deletion via write tool |
+| `read-only` | 25 | Read only -- safe for exploration, no state changes |
+
+**Tier details:**
+
+- **full**: All 40 tools. Includes `komodo_write_resource` for creating, updating, and deleting Komodo resources.
+- **read-execute**: 39 tools. All read tools plus execute tools (deploy, lifecycle, run, etc.). The `komodo_write_resource` tool is hidden.
+- **read-only**: 25 tools. List, get, logs, and stats only. All execute and write tools are hidden.
+
+Tools that are not available in your tier are not registered with the MCP server. They will not appear in your AI tool's tool list, keeping the context clean.
+
+Set `KOMODO_ACCESS_TIER` to `read-only`, `read-execute`, or `full` (default: `full`).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KOMODO_URL` | Yes | URL of your Komodo Core instance |
+| `KOMODO_API_KEY` | Yes | API key for authentication |
+| `KOMODO_API_SECRET` | Yes | API secret for authentication |
+| `KOMODO_ACCESS_TIER` | No | Access tier: `read-only`, `read-execute`, or `full` (default: `full`) |
+| `KOMODO_CATEGORIES` | No | Comma-separated category allowlist (e.g., `servers,stacks,builds`) |
+| `DEBUG` | No | Set to any value to enable debug logging to stderr |
+
+Generate API keys in the Komodo UI under **Settings > API Keys**.
+
+### Available Categories
+
+`servers`, `stacks`, `deployments`, `containers`, `builds`, `repos`, `procedures`, `actions`, `builders`, `alerters`, `resource-syncs`, `write`
+
+## Tools
+
+mcp-komodo provides 40 tools organized by category. Each tool's Access column shows the minimum tier required: `read-only` (available in all tiers), `read-execute` (requires `read-execute` or `full`), or `full` (requires `full` tier only).
+
+<details>
+<summary>Servers (6 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_servers` | List all servers with status and region | read-only |
+| `komodo_get_server` | Get server configuration, status, and action state | read-only |
+| `komodo_get_server_stats` | Get CPU, memory, disk usage, and load averages | read-only |
+| `komodo_get_server_info` | Get OS details, hardware info, and running processes | read-only |
+| `komodo_prune_docker` | Prune unused Docker resources on a server | read-execute |
+| `komodo_delete_docker_resource` | Delete a specific Docker image, volume, or network | read-execute |
+
+</details>
+
+<details>
+<summary>Stacks (6 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_stacks` | List all stacks with state, server, and service count | read-only |
+| `komodo_get_stack` | Get stack configuration, services, and action state | read-only |
+| `komodo_get_stack_log` | Get logs from stack services, with optional search | read-only |
+| `komodo_deploy_stack` | Deploy or redeploy a stack | read-execute |
+| `komodo_stack_lifecycle` | Start, stop, restart, pause, or unpause a stack | read-execute |
+| `komodo_destroy_stack` | Permanently destroy a stack | read-execute |
+
+</details>
+
+<details>
+<summary>Deployments (6 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_deployments` | List all deployments with state, image, and server | read-only |
+| `komodo_get_deployment` | Get deployment configuration, container status, and action state | read-only |
+| `komodo_get_deployment_log` | Get container logs, with optional search | read-only |
+| `komodo_deploy_deployment` | Deploy with latest image and configuration | read-execute |
+| `komodo_deployment_lifecycle` | Start, stop, restart, pause, or unpause a deployment | read-execute |
+| `komodo_destroy_deployment` | Permanently destroy a deployment | read-execute |
+
+</details>
+
+<details>
+<summary>Containers (1 tool)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_get_container_log` | Get logs from any Docker container on a server | read-only |
+
+</details>
+
+<details>
+<summary>Builds (4 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_builds` | List all build configurations with version info | read-only |
+| `komodo_get_build` | Get build configuration, builder, and action state | read-only |
+| `komodo_run_build` | Run a build to create a Docker image | read-execute |
+| `komodo_cancel_build` | Cancel a running build | read-execute |
+
+</details>
+
+<details>
+<summary>Repos (3 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_repos` | List all repos with URL, server, and state | read-only |
+| `komodo_get_repo` | Get repo configuration, branch, and action state | read-only |
+| `komodo_repo_clone_pull` | Clone or pull a repo on its target server | read-execute |
+
+</details>
+
+<details>
+<summary>Procedures (3 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_procedures` | List all procedures with state | read-only |
+| `komodo_get_procedure` | Get procedure stages, operations, and action state | read-only |
+| `komodo_run_procedure` | Run a procedure (executes all stages) | read-execute |
+
+</details>
+
+<details>
+<summary>Actions (3 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_actions` | List all actions with state | read-only |
+| `komodo_get_action` | Get action configuration and action state | read-only |
+| `komodo_run_action` | Run a custom TypeScript/Deno action | read-execute |
+
+</details>
+
+<details>
+<summary>Builders (2 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_builders` | List all builders with type | read-only |
+| `komodo_get_builder` | Get builder type, server configuration, and state | read-only |
+
+</details>
+
+<details>
+<summary>Alerters (2 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_alerters` | List all alerters with type | read-only |
+| `komodo_get_alerter` | Get alerter endpoint type, configuration, and status | read-only |
+
+</details>
+
+<details>
+<summary>Resource Syncs (3 tools)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_list_resource_syncs` | List all resource syncs with state and repo info | read-only |
+| `komodo_get_resource_sync` | Get sync configuration, managed resources, and state | read-only |
+| `komodo_trigger_sync` | Trigger a GitOps sync from the Git repo | read-execute |
+
+</details>
+
+<details>
+<summary>Write (1 tool)</summary>
+
+| Tool | Description | Access |
+|------|-------------|--------|
+| `komodo_write_resource` | Create, update, or delete any Komodo resource | full |
+
+</details>
+
+## Verify It Works
+
+After configuring your MCP client, ask your AI assistant:
+
+> "What servers are connected to Komodo?"
+
+If the connection is working, the assistant will call `komodo_list_servers` and return your servers with their current state and region.
+
+## Usage Examples
+
+Once configured, ask your AI tool questions in natural language:
+
+- **"List all my servers and their status"** -- calls `komodo_list_servers` to show every server with its current state and region.
+
+- **"What's the CPU and memory usage on server prod-01?"** -- calls `komodo_get_server_stats` to show real-time resource utilization.
+
+- **"Show me the logs from the production stack"** -- calls `komodo_get_stack_log` to retrieve recent log output from all services in the stack.
+
+- **"Deploy the frontend stack"** -- calls `komodo_deploy_stack` to redeploy the stack with its current configuration.
+
+- **"Create a new deployment called api-staging with image myapp:latest"** -- calls `komodo_write_resource` to create a new Deployment resource in Komodo.
+
+## Troubleshooting
+
+**Connection refused**
+Check that `KOMODO_URL` is correct and that Komodo Core is reachable from where the MCP server is running. The server validates the connection on startup, so if it started successfully, the URL was valid at that time.
+
+**Invalid credentials / 401 Unauthorized**
+Verify your API key and secret are correct. Check that the key has not been revoked or expired in the Komodo UI under Settings > API Keys.
+
+**Tools not showing up in your AI tool**
+Check your access tier setting. In `read-only` mode, only 25 tools are registered. In `read-execute` mode, 39 tools are registered. Use `full` (or omit `KOMODO_ACCESS_TIER`) for all 40 tools. Check `KOMODO_CATEGORIES` -- only tools in listed categories are registered. Also verify the server started without errors by checking stderr output.
+
+**Node.js version errors**
+mcp-komodo requires Node.js >= 18.0.0. Check your version with `node --version`.
+
+**Parse errors or "invalid JSON" in MCP client**
+This typically means something is writing to stdout besides the MCP server. Ensure no other tools, shell profiles, or startup scripts print to stdout when launching the server. The MCP protocol uses stdout for JSON-RPC communication. All mcp-komodo logging goes to stderr.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run in development mode (auto-reload)
+npm run dev
+
+# Open the MCP Inspector for interactive testing
+npm run inspect
+```
+
+## License
+
+MIT

package/dist/core/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Komodo API client factory with startup validation.
+ *
+ * CRITICAL: KomodoClient is a FACTORY FUNCTION -- do NOT use `new`.
+ * Sensitive patterns are registered BEFORE the client is created
+ * so that any error during initialization is also sanitized.
+ */
+import type { AppConfig } from "./config.js";
+/**
+ * Create a Komodo API client from config.
+ * Registers credentials as sensitive patterns before creating the client.
+ */
+export declare function createClient(config: AppConfig): {
+    auth: <T extends import("komodo_client/dist/types.js").AuthRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").AuthRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/responses.js").AuthResponses[Req["type"]]>;
+    user: <T extends import("komodo_client/dist/types.js").UserRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").UserRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/responses.js").UserResponses[Req["type"]]>;
+    read: <T extends import("komodo_client/dist/types.js").ReadRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").ReadRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/responses.js").ReadResponses[Req["type"]]>;
+    write: <T extends import("komodo_client/dist/types.js").WriteRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").WriteRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/responses.js").WriteResponses[Req["type"]]>;
+    execute: <T extends import("komodo_client/dist/types.js").ExecuteRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").ExecuteRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/responses.js").ExecuteResponses[Req["type"]]>;
+    execute_and_poll: <T extends import("komodo_client/dist/types.js").ExecuteRequest["type"], Req extends Extract<import("komodo_client/dist/types.js").ExecuteRequest, {
+        type: T;
+    }>>(type: T, params: Req["params"]) => Promise<import("komodo_client/dist/types.js").Update | (import("komodo_client/dist/types.js").Update | {
+        status: "Err";
+        data: import("komodo_client/dist/types.js").BatchExecutionResponseItemErr;
+    })[]>;
+    poll_update_until_complete: (update_id: string) => Promise<import("komodo_client/dist/types.js").Update>;
+    core_version: () => Promise<string>;
+    get_update_websocket: ({ on_update, on_login, on_open, on_close, }: {
+        on_update: (update: import("komodo_client/dist/types.js").UpdateListItem) => void;
+        on_login?: () => void;
+        on_open?: () => void;
+        on_close?: () => void;
+    }) => WebSocket;
+    subscribe_to_update_websocket: ({ on_update, on_open, on_login, on_close, retry, retry_timeout_ms, cancel, on_cancel, }: {
+        on_update: (update: import("komodo_client/dist/types.js").UpdateListItem) => void;
+        on_login?: () => void;
+        on_open?: () => void;
+        on_close?: () => void;
+        retry?: boolean;
+        retry_timeout_ms?: number;
+        cancel?: import("komodo_client").CancelToken;
+        on_cancel?: () => void;
+    }) => Promise<void>;
+    connect_terminal: ({ query, on_message, on_login, on_open, on_close, }: {
+        query: import("komodo_client/dist/types.js").ConnectTerminalQuery;
+    } & import("komodo_client").TerminalCallbacks) => WebSocket;
+    execute_terminal: (request: import("komodo_client/dist/types.js").ExecuteTerminalBody, callbacks?: import("komodo_client/dist/terminal.js").ExecuteCallbacks) => Promise<void>;
+    execute_terminal_stream: (request: import("komodo_client/dist/types.js").ExecuteTerminalBody) => Promise<AsyncIterable<string>>;
+    connect_exec: ({ query: { type, query }, on_message, on_login, on_open, on_close, }: {
+        query: import("komodo_client").ConnectExecQuery;
+    } & import("komodo_client").TerminalCallbacks) => WebSocket;
+    connect_container_exec: ({ query, ...callbacks }: {
+        query: import("komodo_client/dist/types.js").ConnectContainerExecQuery;
+    } & import("komodo_client").TerminalCallbacks) => WebSocket;
+    execute_container_exec: (body: import("komodo_client/dist/types.js").ExecuteContainerExecBody, callbacks?: import("komodo_client/dist/terminal.js").ExecuteCallbacks) => Promise<void>;
+    execute_container_exec_stream: (body: import("komodo_client/dist/types.js").ExecuteContainerExecBody) => Promise<AsyncIterable<string>>;
+    connect_deployment_exec: ({ query, ...callbacks }: {
+        query: import("komodo_client/dist/types.js").ConnectDeploymentExecQuery;
+    } & import("komodo_client").TerminalCallbacks) => WebSocket;
+    execute_deployment_exec: (body: import("komodo_client/dist/types.js").ExecuteDeploymentExecBody, callbacks?: import("komodo_client/dist/terminal.js").ExecuteCallbacks) => Promise<void>;
+    execute_deployment_exec_stream: (body: import("komodo_client/dist/types.js").ExecuteDeploymentExecBody) => Promise<AsyncIterable<string>>;
+    connect_stack_exec: ({ query, ...callbacks }: {
+        query: import("komodo_client/dist/types.js").ConnectStackExecQuery;
+    } & import("komodo_client").TerminalCallbacks) => WebSocket;
+    execute_stack_exec: (body: import("komodo_client/dist/types.js").ExecuteStackExecBody, callbacks?: import("komodo_client/dist/terminal.js").ExecuteCallbacks) => Promise<void>;
+    execute_stack_exec_stream: (body: import("komodo_client/dist/types.js").ExecuteStackExecBody) => Promise<AsyncIterable<string>>;
+};
+/**
+ * Validate connectivity to Komodo by calling GetVersion.
+ * Must be called during startup before accepting MCP connections.
+ * Exits the process with code 1 if validation fails.
+ */
+export declare function validateConnection(client: ReturnType<typeof createClient>, config: AppConfig): Promise<void>;

package/dist/core/client.js

@@ -0,0 +1,41 @@
+/**
+ * Komodo API client factory with startup validation.
+ *
+ * CRITICAL: KomodoClient is a FACTORY FUNCTION -- do NOT use `new`.
+ * Sensitive patterns are registered BEFORE the client is created
+ * so that any error during initialization is also sanitized.
+ */
+import { KomodoClient } from "komodo_client";
+import { logger } from "./logger.js";
+import { registerSensitivePattern, sanitizeMessage } from "./errors.js";
+/**
+ * Create a Komodo API client from config.
+ * Registers credentials as sensitive patterns before creating the client.
+ */
+export function createClient(config) {
+    registerSensitivePattern(config.apiKey);
+    registerSensitivePattern(config.apiSecret);
+    return KomodoClient(config.url, {
+        type: "api-key",
+        params: { key: config.apiKey, secret: config.apiSecret },
+    });
+}
+/**
+ * Validate connectivity to Komodo by calling GetVersion.
+ * Must be called during startup before accepting MCP connections.
+ * Exits the process with code 1 if validation fails.
+ */
+export async function validateConnection(client, config) {
+    try {
+        const version = await client.read("GetVersion", {});
+        logger.info(`Connected to Komodo at ${config.url} (version: ${version.version})`);
+    }
+    catch (error) {
+        logger.error(`Failed to connect to Komodo at ${config.url}`);
+        logger.error("Check that KOMODO_URL is correct and Komodo Core is running.");
+        if (error instanceof Error) {
+            logger.error(`Details: ${sanitizeMessage(error.message)}`);
+        }
+        process.exit(1);
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Environment variable parsing and validation.
+ * Reads required and optional config from process.env.
+ */
+import type { AccessTier } from '../types/index.js';
+export interface AppConfig {
+    url: string;
+    apiKey: string;
+    apiSecret: string;
+    accessTier: AccessTier;
+    categories: string[] | null;
+    debug: boolean;
+}
+/**
+ * Load and validate application config from environment variables.
+ *
+ * Required: KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET
+ * Optional: KOMODO_ACCESS_TIER (default: 'full'), KOMODO_CATEGORIES, DEBUG
+ *
+ * Throws clear error (no credentials in message) if required vars are missing.
+ */
+export declare function loadConfig(): AppConfig;

package/dist/core/config.js

@@ -0,0 +1,57 @@
+/**
+ * Environment variable parsing and validation.
+ * Reads required and optional config from process.env.
+ */
+/**
+ * Determine the access tier from KOMODO_ACCESS_TIER.
+ *
+ * Valid values: "read-only", "read-execute", "full" (default).
+ */
+function parseAccessTier() {
+    const tier = process.env.KOMODO_ACCESS_TIER;
+    if (tier === "read-only" || tier === "read-execute") {
+        return tier;
+    }
+    return "full";
+}
+function parseCategories(value) {
+    if (value === undefined || value === '') {
+        return null;
+    }
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Load and validate application config from environment variables.
+ *
+ * Required: KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET
+ * Optional: KOMODO_ACCESS_TIER (default: 'full'), KOMODO_CATEGORIES, DEBUG
+ *
+ * Throws clear error (no credentials in message) if required vars are missing.
+ */
+export function loadConfig() {
+    const url = process.env.KOMODO_URL;
+    const apiKey = process.env.KOMODO_API_KEY;
+    const apiSecret = process.env.KOMODO_API_SECRET;
+    const missing = [];
+    if (!url)
+        missing.push('KOMODO_URL');
+    if (!apiKey)
+        missing.push('KOMODO_API_KEY');
+    if (!apiSecret)
+        missing.push('KOMODO_API_SECRET');
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(', ')}. ` +
+            'Set these variables to connect to your Komodo instance.');
+    }
+    return {
+        url: url.replace(/\/+$/, ''),
+        apiKey: apiKey,
+        apiSecret: apiSecret,
+        accessTier: parseAccessTier(),
+        categories: parseCategories(process.env.KOMODO_CATEGORIES),
+        debug: Boolean(process.env.DEBUG),
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Error sanitization layer.
+ *
+ * Strips sensitive credentials from error messages before they reach
+ * the LLM context. All Komodo API errors should go through
+ * handleKomodoError() to produce MCP-compliant error responses
+ * with isError: true.
+ */
+/**
+ * Register a string that should be redacted from all error messages.
+ * Called at startup with API key and secret before any API calls.
+ */
+export declare function registerSensitivePattern(pattern: string): void;
+/**
+ * Replace all registered sensitive patterns and common auth header
+ * patterns with [REDACTED].
+ */
+export declare function sanitizeMessage(message: string): string;
+/** MCP-compliant error response type with isError flag. */
+export type McpErrorResponse = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+/**
+ * Wrap a Komodo API error into an MCP-compliant error response.
+ * Sanitizes the error message to strip any leaked credentials.
+ */
+export declare function handleKomodoError(context: string, error: unknown): McpErrorResponse;

package/dist/core/errors.js

@@ -0,0 +1,46 @@
+/**
+ * Error sanitization layer.
+ *
+ * Strips sensitive credentials from error messages before they reach
+ * the LLM context. All Komodo API errors should go through
+ * handleKomodoError() to produce MCP-compliant error responses
+ * with isError: true.
+ */
+/** Mutable array of sensitive strings to redact from error messages. */
+const SENSITIVE_PATTERNS = [];
+/**
+ * Register a string that should be redacted from all error messages.
+ * Called at startup with API key and secret before any API calls.
+ */
+export function registerSensitivePattern(pattern) {
+    if (pattern && pattern.length > 0) {
+        SENSITIVE_PATTERNS.push(pattern);
+    }
+}
+/**
+ * Replace all registered sensitive patterns and common auth header
+ * patterns with [REDACTED].
+ */
+export function sanitizeMessage(message) {
+    let sanitized = message;
+    for (const pattern of SENSITIVE_PATTERNS) {
+        sanitized = sanitized.replaceAll(pattern, "[REDACTED]");
+    }
+    // Strip common auth header patterns
+    sanitized = sanitized.replace(/x-api-key:\s*\S+/gi, "x-api-key: [REDACTED]");
+    sanitized = sanitized.replace(/x-api-secret:\s*\S+/gi, "x-api-secret: [REDACTED]");
+    sanitized = sanitized.replace(/authorization:\s*\S+/gi, "authorization: [REDACTED]");
+    return sanitized;
+}
+/**
+ * Wrap a Komodo API error into an MCP-compliant error response.
+ * Sanitizes the error message to strip any leaked credentials.
+ */
+export function handleKomodoError(context, error) {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const safeMessage = sanitizeMessage(rawMessage);
+    return {
+        content: [{ type: "text", text: `Error ${context}: ${safeMessage}` }],
+        isError: true,
+    };
+}

package/dist/core/formatters.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared response formatting functions for all Komodo resource types.
+ *
+ * Every formatter converts typed API responses into concise, LLM-friendly
+ * plain text. No raw JSON is ever returned. Lists use one line per resource.
+ * Details show key fields only, not every config option.
+ */
+import { Types } from "komodo_client";
+export declare function formatServerList(servers: Types.ServerListItem[]): string;
+export declare function formatServerDetail(server: Types.Server, actionState?: Types.ServerActionState): string;
+export declare function formatSystemStats(stats: Types.SystemStats): string;
+export declare function formatSystemInfo(info: Types.SystemInformation): string;
+export declare function formatProcessList(processes: Types.SystemProcess[]): string;
+export declare function formatStackList(stacks: Types.StackListItem[]): string;
+export declare function formatStackDetail(stack: Types.Stack, actionState?: Types.StackActionState): string;
+export declare function formatDeploymentList(deployments: Types.DeploymentListItem[]): string;
+export declare function formatDeploymentDetail(deployment: Types.Deployment, actionState?: Types.DeploymentActionState): string;
+export declare function formatBuildList(builds: Types.BuildListItem[]): string;
+export declare function formatBuildDetail(build: Types.Build, actionState?: Types.BuildActionState): string;
+export declare function formatRepoList(repos: Types.RepoListItem[]): string;
+export declare function formatRepoDetail(repo: Types.Repo, actionState?: Types.RepoActionState): string;
+export declare function formatProcedureList(procedures: Types.ProcedureListItem[]): string;
+export declare function formatProcedureDetail(procedure: Types.Procedure, actionState?: Types.ProcedureActionState): string;
+export declare function formatActionList(actions: Types.ActionListItem[]): string;
+export declare function formatActionDetail(action: Types.Action, actionState?: Types.ActionActionState): string;
+export declare function formatBuilderList(builders: Types.BuilderListItem[]): string;
+export declare function formatBuilderDetail(builder: Types.Builder, actionState?: Record<string, boolean>): string;
+export declare function formatAlerterList(alerters: Types.AlerterListItem[]): string;
+export declare function formatAlerterDetail(alerter: Types.Alerter): string;
+export declare function formatResourceSyncList(syncs: Types.ResourceSyncListItem[]): string;
+export declare function formatResourceSyncDetail(sync: Types.ResourceSync, actionState?: Types.ResourceSyncActionState): string;
+export declare function formatLog(log: Types.Log): string;
+export declare function formatResourceCreated(resourceType: string, resource: any): string;
+export declare function formatResourceUpdated(resourceType: string, resource: any): string;
+export declare function formatResourceDeleted(resourceType: string, resource: any): string;
+export declare function formatUpdateCreated(update: Types.Update, description: string): string;