@masonator/coolify-mcp 2.6.5 → 2.7.0

package/README.md

@@ -15,7 +15,7 @@ A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabli
 
 ## Features
 
-This MCP server provides **35 token-optimized tools** for **debugging, management, and deployment**:
+This MCP server provides **38 token-optimized tools** for **debugging, management, and deployment**:
 
 | Category             | Tools                                                                                                                       |
 | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -33,6 +33,9 @@ This MCP server provides **35 token-optimized tools** for **debugging, managemen
 | **Deployments**      | `list_deployments`, `deploy`, `deployment` (get, cancel, list_for_app)                                                      |
 | **Private Keys**     | `private_keys` (list, get, create, update, delete via action param)                                                         |
 | **GitHub Apps**      | `github_apps` (list, get, create, update, delete via action param)                                                          |
+| **Teams**            | `teams` (list, get, get_members, get_current, get_current_members)                                                          |
+| **Cloud Tokens**     | `cloud_tokens` (Hetzner/DigitalOcean: list, get, create, update, delete, validate)                                          |
+| **Documentation**    | `search_docs` (full-text search across Coolify docs)                                                                        |
 
 ### Token-Optimized Design
 

package/dist/__tests__/coolify-client.test.js

@@ -1577,6 +1577,47 @@ describe('CoolifyClient', () => {
             const result = await client.getVersion();
             expect(result).toEqual({ version: 'v4.0.0-beta.123' });
         });
+        it('should cache version after first call', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: async () => 'v4.0.0-beta.462',
+            });
+            const first = await client.getVersion();
+            const second = await client.getVersion();
+            expect(first).toEqual({ version: 'v4.0.0-beta.462' });
+            expect(second).toEqual({ version: 'v4.0.0-beta.462' });
+            // Only one fetch call — second was served from cache
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+        });
+        it('should return null from getCachedVersion before first call', () => {
+            expect(client.getCachedVersion()).toBeNull();
+        });
+        it('should return version from getCachedVersion after first call', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: async () => 'v4.0.0-beta.462',
+            });
+            await client.getVersion();
+            expect(client.getCachedVersion()).toBe('v4.0.0-beta.462');
+        });
+        it('should not cache version on error and retry on next call', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+                statusText: 'Internal Server Error',
+            });
+            await expect(client.getVersion()).rejects.toThrow();
+            expect(client.getCachedVersion()).toBeNull();
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: async () => 'v4.0.0-beta.462',
+            });
+            const result = await client.getVersion();
+            expect(result).toEqual({ version: 'v4.0.0-beta.462' });
+        });
         it('should handle version errors', async () => {
             mockFetch.mockResolvedValueOnce({
                 ok: false,

package/dist/__tests__/docs-search.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/docs-search.test.js

@@ -0,0 +1,220 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { DocsSearchEngine, parseDocs } from '../lib/docs-search.js';
+// Sample llms-full.txt content for testing
+const SAMPLE_DOCS = `---
+url: /docs/get-started/installation.md
+description: >-
+  Install Coolify self-hosted PaaS on Linux servers with automated Docker setup
+  script and SSH access.
+---
+
+# Installation
+
+Coolify can be installed on any Linux server.
+
+## Requirements
+
+You need a server with at least 2GB RAM and 2 CPU cores.
+SSH access is required for the installation process.
+
+## Quick Install
+
+Run the following command to install Coolify:
+
+\`\`\`bash
+curl -fsSL https://cdn.coolify.io/install.sh | bash
+\`\`\`
+
+---
+
+---
+url: /docs/applications/docker-compose.md
+description: >-
+  Deploy Docker Compose applications on Coolify with environment variables,
+  build packs, and custom domains.
+---
+
+# Docker Compose
+
+You can deploy any Docker Compose based application with Coolify.
+
+## Environment Variables
+
+Define environment variables in your docker-compose.yml or through the Coolify UI.
+Variables defined in the UI take precedence over those in the compose file.
+
+## Custom Domains
+
+Set custom domains for your Docker Compose services through the Coolify dashboard.
+Each service can have its own domain configuration.
+
+---
+
+---
+url: /docs/troubleshoot/applications/502-error.md
+description: >-
+  Fix 502 Bad Gateway errors in Coolify applications caused by health check
+  failures, port mismatches, and proxy configuration issues.
+---
+
+# 502 Bad Gateway Error
+
+A 502 error usually means your application is not responding to the reverse proxy.
+
+## Common Causes
+
+Check the following:
+- Your application is listening on the correct port
+- Health checks are configured properly
+- The container is actually running
+
+## Port Configuration
+
+Make sure your application listens on the port specified in the Coolify settings.
+The default exposed port is 3000 for most build packs.`;
+describe('parseDocs', () => {
+    it('should parse pages from llms-full.txt format', () => {
+        const chunks = parseDocs(SAMPLE_DOCS);
+        expect(chunks.length).toBeGreaterThan(0);
+    });
+    it('should extract title, url, and description from frontmatter', () => {
+        const chunks = parseDocs(SAMPLE_DOCS);
+        const installChunk = chunks.find((c) => c.title === 'Installation');
+        expect(installChunk).toBeDefined();
+        expect(installChunk.url).toBe('https://coolify.io/docs/get-started/installation');
+        expect(installChunk.description).toContain('Install Coolify');
+    });
+    it('should split pages into sub-chunks at ## headers', () => {
+        const chunks = parseDocs(SAMPLE_DOCS);
+        const subChunks = chunks.filter((c) => c.title.includes('>'));
+        expect(subChunks.length).toBeGreaterThan(0);
+        expect(subChunks.some((c) => c.title.includes('Requirements'))).toBe(true);
+    });
+    it('should strip .md extension from URLs', () => {
+        const chunks = parseDocs(SAMPLE_DOCS);
+        chunks.forEach((c) => {
+            expect(c.url).not.toContain('.md');
+        });
+    });
+    it('should handle empty input', () => {
+        const chunks = parseDocs('');
+        expect(chunks).toEqual([]);
+    });
+    it('should assign sequential IDs', () => {
+        const chunks = parseDocs(SAMPLE_DOCS);
+        chunks.forEach((chunk, index) => {
+            expect(chunk.id).toBe(index);
+        });
+    });
+});
+describe('DocsSearchEngine', () => {
+    let engine;
+    let mockFetch;
+    beforeEach(() => {
+        engine = new DocsSearchEngine();
+        mockFetch = jest.spyOn(global, 'fetch');
+    });
+    afterEach(() => {
+        mockFetch.mockRestore();
+    });
+    it('should fetch and index docs on first search', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('installation');
+        expect(results.length).toBeGreaterThan(0);
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+    it('should deduplicate concurrent loading', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const [results1, results2] = await Promise.all([
+            engine.search('installation'),
+            engine.search('docker'),
+        ]);
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+        expect(results1.length).toBeGreaterThan(0);
+        expect(results2.length).toBeGreaterThan(0);
+    });
+    it('should only fetch once across multiple searches', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        await engine.search('installation');
+        await engine.search('docker compose');
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+    it('should return results with title, url, description, snippet, score', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('502 error');
+        expect(results.length).toBeGreaterThan(0);
+        const r = results[0];
+        expect(r).toHaveProperty('title');
+        expect(r).toHaveProperty('url');
+        expect(r).toHaveProperty('description');
+        expect(r).toHaveProperty('snippet');
+        expect(r).toHaveProperty('score');
+        expect(typeof r.score).toBe('number');
+    });
+    it('should rank relevant results higher', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('docker compose environment variables');
+        expect(results[0].url).toContain('docker-compose');
+    });
+    it('should return empty array for no matches', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('xyznonexistent12345');
+        expect(results).toEqual([]);
+    });
+    it('should respect limit parameter', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('coolify', 2);
+        expect(results.length).toBeLessThanOrEqual(2);
+    });
+    it('should throw on fetch failure', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 500,
+        });
+        await expect(engine.search('test')).rejects.toThrow('Failed to fetch Coolify docs');
+    });
+    it('should retry after fetch failure', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 500,
+        });
+        await expect(engine.search('test')).rejects.toThrow();
+        // Second attempt should try fetching again (loading was reset)
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        const results = await engine.search('installation');
+        expect(results.length).toBeGreaterThan(0);
+    });
+    it('should report chunk count after loading', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            text: async () => SAMPLE_DOCS,
+        });
+        expect(engine.getChunkCount()).toBe(0);
+        await engine.search('test');
+        expect(engine.getChunkCount()).toBeGreaterThan(0);
+    });
+});

package/dist/__tests__/mcp-server.test.js

@@ -136,6 +136,21 @@ describe('CoolifyMcpServer v2', () => {
             expect(typeof client.bulkEnvUpdate).toBe('function');
             expect(typeof client.stopAllApps).toBe('function');
             expect(typeof client.redeployProjectApps).toBe('function');
+            // Team operations
+            expect(typeof client.listTeams).toBe('function');
+            expect(typeof client.getTeam).toBe('function');
+            expect(typeof client.getTeamMembers).toBe('function');
+            expect(typeof client.getCurrentTeam).toBe('function');
+            expect(typeof client.getCurrentTeamMembers).toBe('function');
+            // Cloud token operations
+            expect(typeof client.listCloudTokens).toBe('function');
+            expect(typeof client.getCloudToken).toBe('function');
+            expect(typeof client.createCloudToken).toBe('function');
+            expect(typeof client.updateCloudToken).toBe('function');
+            expect(typeof client.deleteCloudToken).toBe('function');
+            expect(typeof client.validateCloudToken).toBe('function');
+            // Version caching
+            expect(typeof client.getCachedVersion).toBe('function');
         });
     });
     describe('server configuration', () => {
@@ -148,41 +163,46 @@ describe('CoolifyMcpServer v2', () => {
     });
 });
 describe('truncateLogs', () => {
+    // Plain text log tests
     it('should return logs unchanged when within limits', () => {
         const logs = 'line1\nline2\nline3';
         const result = truncateLogs(logs, 200, 50000);
-        expect(result).toBe(logs);
+        expect(result.logs).toBe(logs);
+        expect(result.total).toBe(3);
     });
     it('should truncate to last N lines', () => {
         const logs = 'line1\nline2\nline3\nline4\nline5';
         const result = truncateLogs(logs, 3, 50000);
-        expect(result).toBe('line3\nline4\nline5');
+        expect(result.logs).toBe('line3\nline4\nline5');
+        expect(result.total).toBe(5);
+        expect(result.showing_start).toBe(3);
+        expect(result.showing_end).toBe(5);
     });
     it('should truncate by character limit when lines are huge', () => {
         const hugeLine = 'x'.repeat(100);
         const logs = `${hugeLine}\n${hugeLine}\n${hugeLine}`;
         const result = truncateLogs(logs, 200, 50);
-        expect(result.length).toBeLessThanOrEqual(50);
-        expect(result.startsWith('...[truncated]...')).toBe(true);
+        expect(result.logs.length).toBeLessThanOrEqual(50);
+        expect(result.logs.startsWith('...[truncated]...')).toBe(true);
     });
     it('should not add truncation prefix when under char limit', () => {
         const logs = 'line1\nline2\nline3';
         const result = truncateLogs(logs, 200, 50000);
-        expect(result.startsWith('...[truncated]...')).toBe(false);
+        expect(result.logs.startsWith('...[truncated]...')).toBe(false);
     });
     it('should handle empty logs', () => {
         const result = truncateLogs('', 200, 50000);
-        expect(result).toBe('');
+        expect(result.logs).toBe('');
     });
     it('should use default limits when not specified', () => {
         const logs = 'line1\nline2';
         const result = truncateLogs(logs);
-        expect(result).toBe(logs);
+        expect(result.logs).toBe(logs);
     });
     it('should respect custom line limit', () => {
         const lines = Array.from({ length: 300 }, (_, i) => `line${i + 1}`).join('\n');
         const result = truncateLogs(lines, 50, 50000);
-        const resultLines = result.split('\n');
+        const resultLines = result.logs.split('\n');
         expect(resultLines.length).toBe(50);
         expect(resultLines[0]).toBe('line251');
         expect(resultLines[49]).toBe('line300');
@@ -190,7 +210,90 @@ describe('truncateLogs', () => {
     it('should respect custom char limit', () => {
         const logs = 'x'.repeat(1000);
         const result = truncateLogs(logs, 200, 100);
-        expect(result.length).toBe(100);
+        expect(result.logs.length).toBe(100);
+    });
+    // Pagination tests (plain text)
+    it('should paginate plain text logs (page 2 = older entries)', () => {
+        const logs = Array.from({ length: 30 }, (_, i) => `line${i + 1}`).join('\n');
+        const page1 = truncateLogs(logs, 10, 50000, 1);
+        const page2 = truncateLogs(logs, 10, 50000, 2);
+        const page3 = truncateLogs(logs, 10, 50000, 3);
+        expect(page1.logs).toContain('line30');
+        expect(page1.logs).toContain('line21');
+        expect(page1.logs).not.toContain('line20');
+        expect(page2.logs).toContain('line20');
+        expect(page2.logs).toContain('line11');
+        expect(page2.logs).not.toContain('line10');
+        expect(page3.logs).toContain('line10');
+        expect(page3.logs).toContain('line1');
+        expect(page1.showing_start).toBe(21);
+        expect(page1.showing_end).toBe(30);
+    });
+    // JSON array format tests (Coolify deployment logs)
+    it('should parse JSON array logs and return last N visible entries', () => {
+        const entries = [
+            { output: 'Building...', timestamp: '2026-01-01T00:00:01Z', hidden: false },
+            { output: 'docker pull', timestamp: '2026-01-01T00:00:02Z', hidden: true },
+            { output: 'Compiling...', timestamp: '2026-01-01T00:00:03Z', hidden: false },
+            { output: 'Done.', timestamp: '2026-01-01T00:00:04Z', hidden: false },
+        ];
+        const result = truncateLogs(JSON.stringify(entries), 2, 50000);
+        expect(result.logs).toContain('Compiling...');
+        expect(result.logs).toContain('Done.');
+        expect(result.logs).not.toContain('Building...');
+        expect(result.logs).not.toContain('docker pull');
+        expect(result.total).toBe(3); // 3 visible entries
+    });
+    it('should filter hidden entries from JSON logs', () => {
+        const entries = [
+            { output: 'visible1', timestamp: '2026-01-01T00:00:01Z', hidden: false },
+            { output: 'hidden1', timestamp: '2026-01-01T00:00:02Z', hidden: true },
+            { output: 'hidden2', timestamp: '2026-01-01T00:00:03Z', hidden: true },
+            { output: 'visible2', timestamp: '2026-01-01T00:00:04Z', hidden: false },
+        ];
+        const result = truncateLogs(JSON.stringify(entries), 200, 50000);
+        expect(result.logs).toContain('visible1');
+        expect(result.logs).toContain('visible2');
+        expect(result.logs).not.toContain('hidden1');
+        expect(result.logs).not.toContain('hidden2');
+    });
+    it('should format JSON log entries with timestamp and output', () => {
+        const entries = [
+            { output: 'Starting deploy', timestamp: '2026-01-01T10:00:00Z', hidden: false },
+        ];
+        const result = truncateLogs(JSON.stringify(entries), 200, 50000);
+        expect(result.logs).toBe('[2026-01-01T10:00:00Z] Starting deploy');
+    });
+    it('should paginate JSON logs (page 2 = older entries)', () => {
+        const entries = Array.from({ length: 30 }, (_, i) => ({
+            output: `step ${i + 1}`,
+            timestamp: `2026-01-01T00:00:${String(i).padStart(2, '0')}Z`,
+            hidden: false,
+        }));
+        const page1 = truncateLogs(JSON.stringify(entries), 10, 50000, 1);
+        const page2 = truncateLogs(JSON.stringify(entries), 10, 50000, 2);
+        expect(page1.logs).toContain('step 30');
+        expect(page1.logs).toContain('step 21');
+        expect(page1.logs).not.toContain('step 20');
+        expect(page2.logs).toContain('step 20');
+        expect(page2.logs).toContain('step 11');
+        expect(page2.logs).not.toContain('step 10');
+        expect(page1.total).toBe(30);
+        expect(page1.showing_start).toBe(21);
+        expect(page1.showing_end).toBe(30);
+        expect(page2.showing_start).toBe(11);
+        expect(page2.showing_end).toBe(20);
+    });
+    it('should return metadata with total and showing range', () => {
+        const entries = Array.from({ length: 50 }, (_, i) => ({
+            output: `step ${i}`,
+            timestamp: `2026-01-01T00:00:${String(i).padStart(2, '0')}Z`,
+            hidden: false,
+        }));
+        const result = truncateLogs(JSON.stringify(entries), 10, 50000);
+        expect(result.total).toBe(50);
+        expect(result.showing_start).toBe(41);
+        expect(result.showing_end).toBe(50);
     });
 });
 // =============================================================================

package/dist/lib/coolify-client.d.ts

@@ -72,10 +72,12 @@ export interface GitHubAppSummary {
 export declare class CoolifyClient {
     private readonly baseUrl;
     private readonly accessToken;
+    private cachedVersion;
     constructor(config: CoolifyConfig);
     private request;
     private buildQueryString;
     getVersion(): Promise<Version>;
+    getCachedVersion(): string | null;
     validateConnection(): Promise<void>;
     listServers(options?: ListOptions): Promise<Server[] | ServerSummary[]>;
     getServer(uuid: string): Promise<Server>;

package/dist/lib/coolify-client.js

@@ -144,6 +144,7 @@ function toEnvVarSummary(envVar) {
  */
 export class CoolifyClient {
     constructor(config) {
+        this.cachedVersion = null;
         if (!config.baseUrl) {
             throw new Error('Coolify base URL is required');
         }
@@ -205,6 +206,9 @@ export class CoolifyClient {
     // Health & Version
     // ===========================================================================
     async getVersion() {
+        if (this.cachedVersion) {
+            return { version: this.cachedVersion };
+        }
         // The /version endpoint returns plain text, not JSON
         const url = `${this.baseUrl}/api/v1/version`;
         const response = await fetch(url, {
@@ -216,7 +220,11 @@ export class CoolifyClient {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
         const version = await response.text();
-        return { version: version.trim() };
+        this.cachedVersion = version.trim();
+        return { version: this.cachedVersion };
+    }
+    getCachedVersion() {
+        return this.cachedVersion;
     }
     async validateConnection() {
         try {

package/dist/lib/docs-search.d.ts

@@ -0,0 +1,32 @@
+interface DocChunk {
+    id: number;
+    title: string;
+    url: string;
+    description: string;
+    content: string;
+}
+export interface DocSearchResult {
+    title: string;
+    url: string;
+    description: string;
+    snippet: string;
+    score: number;
+}
+/**
+ * Lightweight full-text search over Coolify documentation.
+ * Fetches llms-full.txt on first search, parses into chunks, indexes with MiniSearch (BM25).
+ * The LLM calling this tool handles semantic understanding — we just need good ranking.
+ */
+export declare class DocsSearchEngine {
+    private index;
+    private chunks;
+    private loading;
+    ensureLoaded(): Promise<void>;
+    private loadAndIndex;
+    search(query: string, limit?: number): Promise<DocSearchResult[]>;
+    private getSnippet;
+    getChunkCount(): number;
+}
+/** Parse llms-full.txt into doc chunks. Exported for testing. */
+export declare function parseDocs(text: string): DocChunk[];
+export {};

package/dist/lib/docs-search.js

@@ -0,0 +1,152 @@
+import MiniSearch from 'minisearch';
+const DOCS_FULL_URL = 'https://coolify.io/docs/llms-full.txt';
+const DOCS_BASE_URL = 'https://coolify.io';
+/**
+ * Lightweight full-text search over Coolify documentation.
+ * Fetches llms-full.txt on first search, parses into chunks, indexes with MiniSearch (BM25).
+ * The LLM calling this tool handles semantic understanding — we just need good ranking.
+ */
+export class DocsSearchEngine {
+    constructor() {
+        this.index = null;
+        this.chunks = [];
+        this.loading = null;
+    }
+    async ensureLoaded() {
+        if (this.index)
+            return;
+        if (this.loading)
+            return this.loading;
+        this.loading = this.loadAndIndex();
+        return this.loading;
+    }
+    async loadAndIndex() {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 15000);
+            let response;
+            try {
+                response = await fetch(DOCS_FULL_URL, { signal: controller.signal });
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            if (!response.ok) {
+                throw new Error(`Failed to fetch Coolify docs: HTTP ${response.status}`);
+            }
+            const text = await response.text();
+            this.chunks = parseDocs(text);
+            this.index = new MiniSearch({
+                fields: ['title', 'description', 'content'],
+                storeFields: ['title', 'url', 'description'],
+                searchOptions: {
+                    boost: { title: 3, description: 2, content: 1 },
+                    prefix: true,
+                    fuzzy: 0.2,
+                },
+            });
+            this.index.addAll(this.chunks);
+        }
+        catch (error) {
+            this.loading = null;
+            this.index = null;
+            this.chunks = [];
+            throw error;
+        }
+    }
+    async search(query, limit = 5) {
+        await this.ensureLoaded();
+        if (!this.index) {
+            throw new Error('Documentation index failed to load');
+        }
+        const results = this.index.search(query).slice(0, limit);
+        return results.map((r) => ({
+            title: r.title,
+            url: r.url,
+            description: r.description,
+            snippet: this.getSnippet(r.id, query),
+            score: Math.round(r.score * 100) / 100,
+        }));
+    }
+    getSnippet(id, query) {
+        const chunk = this.chunks[id];
+        if (!chunk)
+            return '';
+        const content = chunk.content;
+        const queryTerms = query.toLowerCase().split(/\s+/);
+        // Find best position — where query terms appear
+        let bestPos = 0;
+        let bestScore = -1;
+        const lower = content.toLowerCase();
+        for (let i = 0; i < lower.length - 100; i += 50) {
+            const window = lower.slice(i, i + 300);
+            const score = queryTerms.reduce((s, t) => s + (window.includes(t) ? 1 : 0), 0);
+            if (score > bestScore) {
+                bestScore = score;
+                bestPos = i;
+            }
+        }
+        const start = Math.max(0, bestPos);
+        const end = Math.min(content.length, start + 300);
+        let snippet = content.slice(start, end).trim();
+        if (start > 0)
+            snippet = '...' + snippet;
+        if (end < content.length)
+            snippet = snippet + '...';
+        return snippet;
+    }
+    getChunkCount() {
+        return this.chunks.length;
+    }
+}
+/** Parse llms-full.txt into doc chunks. Exported for testing. */
+export function parseDocs(text) {
+    const chunks = [];
+    // Split on page boundaries: ---\n\n--- or end of frontmatter pairs
+    // Each page starts with ---\nurl: ...\ndescription: ...\n---\n then markdown
+    const pages = text.split(/\n---\n\n---\n/);
+    for (const page of pages) {
+        const parsed = parsePage(page);
+        if (!parsed)
+            continue;
+        // Split large pages into sub-chunks at ## headers
+        const sections = parsed.content.split(/\n(?=## )/);
+        for (const section of sections) {
+            const trimmed = section.trim();
+            if (!trimmed || trimmed.length < 20)
+                continue;
+            // Extract section title if present
+            const sectionTitle = trimmed.match(/^## (.+)/)?.[1];
+            const title = sectionTitle ? `${parsed.title} > ${sectionTitle}` : parsed.title;
+            chunks.push({
+                id: chunks.length,
+                title,
+                url: parsed.url,
+                description: parsed.description,
+                content: trimmed.replace(/^## .+\n/, '').trim(),
+            });
+        }
+    }
+    return chunks;
+}
+function parsePage(raw) {
+    // Handle frontmatter — may start with --- or just url:
+    const frontmatterMatch = raw.match(/(?:---\n)?url:\s*(.+)\ndescription:\s*>?-?\n?([\s\S]*?)\n---\n([\s\S]*)/);
+    if (!frontmatterMatch)
+        return null;
+    const urlPath = frontmatterMatch[1].trim();
+    const description = frontmatterMatch[2]
+        .split('\n')
+        .map((l) => l.trim())
+        .join(' ')
+        .trim();
+    const content = frontmatterMatch[3].trim();
+    // Extract H1 title from content
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    const title = titleMatch?.[1] || urlPath;
+    // Build full URL
+    const url = urlPath.endsWith('.md')
+        ? DOCS_BASE_URL + urlPath.replace(/\.md$/, '')
+        : DOCS_BASE_URL + urlPath;
+    return { url, description, title, content };
+}

package/dist/lib/mcp-server.d.ts

@@ -6,11 +6,19 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { CoolifyConfig, ResponseAction, ResponsePagination } from '../types/coolify.js';
 export declare const VERSION: string;
+export interface TruncatedLogsResult {
+    logs: string;
+    total: number;
+    showing_start: number;
+    showing_end: number;
+}
 /**
- * Truncate logs by line count and character count.
+ * Truncate logs by entry count with pagination support.
+ * Handles both JSON array format (Coolify deployment logs) and plain text.
+ * Page 1 = most recent entries, page 2 = next older batch, etc.
  * Exported for testing.
  */
-export declare function truncateLogs(logs: string, lineLimit?: number, charLimit?: number): string;
+export declare function truncateLogs(logs: string, lineLimit?: number, charLimit?: number, page?: number): TruncatedLogsResult;
 /** Generate contextual actions for an application based on its status */
 export declare function getApplicationActions(uuid: string, status?: string): ResponseAction[];
 /** Generate contextual actions for a deployment */
@@ -19,6 +27,7 @@ export declare function getDeploymentActions(uuid: string, status: string, appUu
 export declare function getPagination(tool: string, page?: number, perPage?: number, count?: number): ResponsePagination | undefined;
 export declare class CoolifyMcpServer extends McpServer {
     private readonly client;
+    private readonly docsSearch;
     constructor(config: CoolifyConfig);
     connect(transport: Transport): Promise<void>;
     private registerTools;

package/dist/lib/mcp-server.js

@@ -6,6 +6,7 @@ import { createRequire } from 'module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { CoolifyClient, } from './coolify-client.js';
+import { DocsSearchEngine } from './docs-search.js';
 const _require = createRequire(import.meta.url);
 export const VERSION = _require('../../package.json').version;
 /** Wrap handler with error handling */
@@ -25,21 +26,55 @@ function wrap(fn) {
 }
 const TRUNCATION_PREFIX = '...[truncated]...\n';
 /**
- * Truncate logs by line count and character count.
+ * Truncate logs by entry count with pagination support.
+ * Handles both JSON array format (Coolify deployment logs) and plain text.
+ * Page 1 = most recent entries, page 2 = next older batch, etc.
  * Exported for testing.
  */
-export function truncateLogs(logs, lineLimit = 200, charLimit = 50000) {
-    // First: limit by lines
-    const logLines = logs.split('\n');
-    const limitedLines = logLines.slice(-lineLimit);
-    let truncatedLogs = limitedLines.join('\n');
-    // Second: limit by characters (safety net for huge lines)
-    if (truncatedLogs.length > charLimit) {
-        // Account for prefix length to stay within limit
+export function truncateLogs(logs, lineLimit = 200, charLimit = 50000, page = 1) {
+    // Try parsing as JSON array (Coolify deployment log format)
+    let lines;
+    let total;
+    try {
+        const entries = JSON.parse(logs);
+        if (Array.isArray(entries)) {
+            const visible = entries.filter((e) => !e.hidden);
+            total = visible.length;
+            const end = total - (page - 1) * lineLimit;
+            const start = Math.max(0, end - lineLimit);
+            const slice = visible.slice(start, end);
+            lines = slice.map((e) => `[${e.timestamp ?? ''}] ${e.output ?? ''}`);
+        }
+        else {
+            const allLines = logs.split('\n');
+            total = allLines.length;
+            const end = total - (page - 1) * lineLimit;
+            const start = Math.max(0, end - lineLimit);
+            lines = allLines.slice(start, end);
+        }
+    }
+    catch {
+        // Plain text logs — split by newlines
+        const allLines = logs.split('\n');
+        total = allLines.length;
+        const end = total - (page - 1) * lineLimit;
+        const start = Math.max(0, end - lineLimit);
+        lines = allLines.slice(start, end);
+    }
+    const end = total - (page - 1) * lineLimit;
+    const start = Math.max(0, end - lineLimit);
+    let result = lines.join('\n');
+    // Safety net: limit by characters
+    if (result.length > charLimit) {
         const prefixLen = TRUNCATION_PREFIX.length;
-        truncatedLogs = TRUNCATION_PREFIX + truncatedLogs.slice(-(charLimit - prefixLen));
+        result = TRUNCATION_PREFIX + result.slice(-(charLimit - prefixLen));
     }
-    return truncatedLogs;
+    return {
+        logs: result,
+        total,
+        showing_start: start + 1,
+        showing_end: Math.min(end, total),
+    };
 }
 // =============================================================================
 // Action Generators for HATEOAS-style responses
@@ -120,6 +155,7 @@ function wrapWithActions(fn, getActions, getPaginationFn) {
 export class CoolifyMcpServer extends McpServer {
     constructor(config) {
         super({ name: 'coolify', version: VERSION });
+        this.docsSearch = new DocsSearchEngine();
         this.client = new CoolifyClient(config);
         this.registerTools();
     }
@@ -676,22 +712,48 @@ export class CoolifyMcpServer extends McpServer {
         this.tool('deployment', 'Manage deployment: get/cancel/list_for_app (logs excluded by default, use lines param to include)', {
             action: z.enum(['get', 'cancel', 'list_for_app']),
             uuid: z.string(),
-            lines: z.number().optional(), // Include logs truncated to last N lines (omit for no logs)
+            lines: z.number().optional(), // Include logs truncated to last N entries (omit for no logs)
+            page: z.number().optional(), // Log page (1=most recent, 2=older, etc.)
             max_chars: z.number().optional(), // Limit log output to last N chars (default: 50000)
-        }, async ({ action, uuid, lines, max_chars }) => {
+        }, async ({ action, uuid, lines, page, max_chars }) => {
             switch (action) {
                 case 'get':
                     // If lines param specified, include logs and truncate
                     if (lines !== undefined) {
+                        const p = page ?? 1;
+                        const ll = lines;
                         return wrapWithActions(async () => {
                             const deployment = (await this.client.getDeployment(uuid, {
                                 includeLogs: true,
                             }));
                             if (deployment.logs) {
-                                deployment.logs = truncateLogs(deployment.logs, lines, max_chars ?? 50000);
+                                const result = truncateLogs(deployment.logs, ll, max_chars ?? 50000, p);
+                                deployment.logs = result.logs;
+                                return {
+                                    ...deployment,
+                                    logs_meta: {
+                                        total_entries: result.total,
+                                        showing: `${result.showing_start}-${result.showing_end} of ${result.total}`,
+                                    },
+                                };
                             }
-                            return deployment;
-                        }, (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
+                            return { ...deployment, logs_meta: undefined };
+                        }, (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid), (dep) => {
+                            const total = dep.logs_meta?.total_entries ?? 0;
+                            const hasOlder = p * ll < total;
+                            const pagination = {};
+                            if (hasOlder)
+                                pagination.next = {
+                                    tool: 'deployment',
+                                    args: { action: 'get', uuid, lines: ll, page: p + 1 },
+                                };
+                            if (p > 1)
+                                pagination.prev = {
+                                    tool: 'deployment',
+                                    args: { action: 'get', uuid, lines: ll, page: p - 1 },
+                                };
+                            return Object.keys(pagination).length > 0 ? pagination : undefined;
+                        });
                     }
                     // Otherwise return essential info without logs
                     return wrapWithActions(() => this.client.getDeployment(uuid), (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
@@ -886,6 +948,80 @@ export class CoolifyMcpServer extends McpServer {
             }
         });
         // =========================================================================
+        // Teams (1 tool - consolidated)
+        // =========================================================================
+        this.tool('teams', 'Manage teams: list/get/get_members/get_current/get_current_members', {
+            action: z.enum(['list', 'get', 'get_members', 'get_current', 'get_current_members']),
+            id: z.number().optional(),
+        }, async ({ action, id }) => {
+            switch (action) {
+                case 'list':
+                    return wrap(() => this.client.listTeams());
+                case 'get':
+                    if (!id)
+                        return { content: [{ type: 'text', text: 'Error: id required' }] };
+                    return wrap(() => this.client.getTeam(id));
+                case 'get_members':
+                    if (!id)
+                        return { content: [{ type: 'text', text: 'Error: id required' }] };
+                    return wrap(() => this.client.getTeamMembers(id));
+                case 'get_current':
+                    return wrap(() => this.client.getCurrentTeam());
+                case 'get_current_members':
+                    return wrap(() => this.client.getCurrentTeamMembers());
+            }
+        });
+        // =========================================================================
+        // Cloud Tokens (1 tool - consolidated)
+        // =========================================================================
+        this.tool('cloud_tokens', 'Manage cloud provider tokens (Hetzner/DigitalOcean): list/get/create/update/delete/validate', {
+            action: z.enum(['list', 'get', 'create', 'update', 'delete', 'validate']),
+            uuid: z.string().optional(),
+            provider: z.enum(['hetzner', 'digitalocean']).optional(),
+            token: z.string().optional(),
+            name: z.string().optional(),
+        }, async ({ action, uuid, provider, token, name }) => {
+            switch (action) {
+                case 'list':
+                    return wrap(() => this.client.listCloudTokens());
+                case 'get':
+                    if (!uuid)
+                        return { content: [{ type: 'text', text: 'Error: uuid required' }] };
+                    return wrap(() => this.client.getCloudToken(uuid));
+                case 'create':
+                    if (!provider || !token || !name)
+                        return {
+                            content: [{ type: 'text', text: 'Error: provider, token, name required' }],
+                        };
+                    return wrap(() => this.client.createCloudToken({ provider, token, name }));
+                case 'update':
+                    if (!uuid)
+                        return { content: [{ type: 'text', text: 'Error: uuid required' }] };
+                    return wrap(() => this.client.updateCloudToken(uuid, { name }));
+                case 'delete':
+                    if (!uuid)
+                        return { content: [{ type: 'text', text: 'Error: uuid required' }] };
+                    return wrap(() => this.client.deleteCloudToken(uuid));
+                case 'validate':
+                    if (!uuid)
+                        return { content: [{ type: 'text', text: 'Error: uuid required' }] };
+                    return wrap(() => this.client.validateCloudToken(uuid));
+            }
+        });
+        // =========================================================================
+        // Documentation Search (1 tool)
+        // =========================================================================
+        this.tool('search_docs', 'Search Coolify documentation for how-to guides, configuration, troubleshooting', {
+            query: z.string().describe('Search query'),
+            limit: z.number().optional().describe('Max results (default 5)'),
+        }, async ({ query, limit }) => wrap(async () => {
+            const results = await this.docsSearch.search(query, limit ?? 5);
+            if (results.length === 0) {
+                return { results: [], hint: 'No matches. Try broader or different keywords.' };
+            }
+            return { results };
+        }));
+        // =========================================================================
         // Batch Operations (4 tools)
         // =========================================================================
         this.tool('restart_project_apps', 'Restart all apps in project', { project_uuid: z.string() }, async ({ project_uuid }) => wrap(() => this.client.restartProjectApps(project_uuid)));

package/dist/types/coolify.d.ts

@@ -907,11 +907,11 @@ export interface ResponseAction {
 export interface ResponsePagination {
     next?: {
         tool: string;
-        args: Record<string, number>;
+        args: Record<string, string | number>;
     };
     prev?: {
         tool: string;
-        args: Record<string, number>;
+        args: Record<string, string | number>;
     };
 }
 export interface DeploymentEssential {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.6.5",
+  "version": "2.7.0",
   "description": "MCP server implementation for Coolify",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.23.0",
+    "minisearch": "^7.2.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {