Skip to content

Commit 390d1aa

Browse files
StuMasonclaude
StuMason
and
claude
authored
feat!: v2.0.0 Token Diet - 85% token reduction (#57)
* feat!: v2.0.0 Token Diet - 85% token reduction BREAKING CHANGE: Major rewrite of MCP tool layer for token efficiency. Token reduction: ~43,000 → ~6,600 tokens (85% reduction) Tool count: 77 → 33 tools (57% reduction) Consolidated tools with action parameters: - projects: list|get|create|update|delete - environments: list|get|create|delete - application: create_github|create_key|update|delete - database: create (8 types)|delete - service: create|update|delete - control: start|stop|restart for apps/dbs/services - env_vars: CRUD for app/service env vars - private_keys: list|get|create|update|delete - database_backups: list|get|list_executions|get_execution - deployment: get|cancel|list_for_app Removed: All 7 MCP prompts (unused) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: address review feedback - add validate_server tool and remove @ts-nocheck - Add missing validate_server tool to mcp-server.ts (was documented but not implemented) - Remove @ts-nocheck and fix type issues properly - McpServer constructor: remove unsupported capabilities option - createPrivateKey: add default value for optional name parameter - Update tool count to 34 across all documentation (was 33) - All tests passing, build clean, lint clean 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 5c86231 commit 390d1aa

File tree

7 files changed

+850
-1572
lines changed

7 files changed

+850
-1572
lines changed

‎CHANGELOG.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,59 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [2.0.0] - 2026-01-06
9+
10+
### Breaking Changes - Token Diet Release 🏋️
11+
12+
**v2.0.0 is a complete rewrite of the MCP tool layer focused on drastically reducing token usage.**
13+
14+
- **Token reduction: ~43,000 → ~6,600 tokens** (85% reduction)
15+
- **Tool count: 77 → 34 tools** (56% reduction)
16+
- All prompts removed (7 prompts were unused)
17+
18+
### Changed
19+
20+
- **Consolidated tools** - Related operations now share a single tool with action parameters:
21+
- Server: `server_resources`, `server_domains`, `validate_server` (separate focused tools)
22+
- Projects: `projects` tool with `action: list|get|create|update|delete`
23+
- Environments: `environments` tool with `action: list|get|create|delete`
24+
- Applications: `application` tool with `action: create_github|create_key|update|delete`
25+
- Databases: `database` tool with `action: create|delete` and `type: postgresql|mysql|mariadb|mongodb|redis|keydb|clickhouse|dragonfly`
26+
- Services: `service` tool with `action: create|update|delete`
27+
- Control: `control` tool for start/stop/restart across applications, databases, services
28+
- Env vars: `env_vars` tool for CRUD across applications and services
29+
- Private keys: `private_keys` tool with `action: list|get|create|update|delete`
30+
- Backups: `database_backups` tool with `action: list|get|list_executions|get_execution`
31+
- Deployments: `deployment` tool with `action: get|cancel|list_for_app`
32+
33+
- **Terse descriptions** - All tool descriptions minimized for token efficiency
34+
35+
### Removed
36+
37+
- All 7 MCP prompts (`debug-app`, `health-check`, `deploy-app`, `troubleshoot-ssl`, `restart-project`, `env-audit`, `backup-status`)
38+
- `get_infrastructure_overview` moved to inline implementation in `get_infrastructure_overview` tool (simpler)
39+
40+
### Migration Guide
41+
42+
Most v1.x tool names still exist unchanged:
43+
44+
- `get_version`, `get_mcp_version` - unchanged
45+
- `list_servers`, `get_server` - unchanged
46+
- `list_applications`, `get_application`, `get_application_logs` - unchanged
47+
- `list_databases`, `get_database` - unchanged
48+
- `list_services`, `get_service` - unchanged
49+
- `list_deployments`, `deploy` - unchanged
50+
- `diagnose_app`, `diagnose_server`, `find_issues` - unchanged
51+
- `restart_project_apps`, `bulk_env_update`, `stop_all_apps`, `redeploy_project` - unchanged
52+
53+
Consolidated tools (use action parameter):
54+
55+
- `create_project` → `projects` with `action: 'create'`
56+
- `delete_project` → `projects` with `action: 'delete'`
57+
- `create_postgresql` → `database` with `action: 'create', type: 'postgresql'`
58+
- `start_application` → `control` with `resource: 'application', action: 'start'`
59+
- `create_application_env` → `env_vars` with `resource: 'application', action: 'create'`
60+
861
## [1.6.0] - 2026-01-06
962

1063
### Added

‎CLAUDE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
MCP (Model Context Protocol) server for Coolify that provides 75 tools and 7 workflow prompts for AI assistants to manage infrastructure through natural language. Tools cover servers, projects, environments, applications, databases, services, deployments, private keys, smart diagnostics, and batch operations. Prompts provide guided workflows for debugging, deployment, health checks, and more.
7+
MCP (Model Context Protocol) server for Coolify that provides 34 token-optimized tools for AI assistants to manage infrastructure through natural language. Tools cover servers, projects, environments, applications, databases, services, deployments, private keys, smart diagnostics, and batch operations. v2.0.0 reduced token usage by 85% (from ~43,000 to ~6,600 tokens) by consolidating related operations into single tools with action parameters.
88

99
## Commands
1010

@@ -101,11 +101,11 @@ When making changes to the codebase, ensure documentation is updated:
101101
- Follow [Keep a Changelog](https://keepachangelog.com/) format
102102
103103
2. **README.md** - Update if:
104-
- Tool count changes (update "75 tools" in Features section)
104+
- Tool count changes (update "34 tools" in Features section)
105105
- New tools added (add to appropriate category in Available Tools)
106106
- New example prompts needed
107107
- Response size improvements made (update comparison table)
108108
109-
3. **This file (CLAUDE.md)** - Update tool count if changed
109+
3. **This file (CLAUDE.md)** - Update tool count if changed (currently 34 tools)
110110
111111
Always work on a feature branch and include documentation updates in the same PR as code changes.

‎README.md‎

Lines changed: 22 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -9,41 +9,33 @@
99
[![codecov](https://codecov.io/gh/StuMason/coolify-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/StuMason/coolify-mcp)
1010
[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stumason-coolify-mcp-badge.png)](https://mseep.ai/app/stumason-coolify-mcp)
1111

12-
> **The most comprehensive MCP server for Coolify** - 75 tools, 7 workflow prompts, smart diagnostics, and batch operations for managing your self-hosted PaaS through AI assistants.
12+
> **The most comprehensive MCP server for Coolify** - 34 optimized tools, smart diagnostics, and batch operations for managing your self-hosted PaaS through AI assistants.
1313
1414
A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabling AI assistants to manage and debug your Coolify instances through natural language.
1515

1616
## Features
1717

18-
This MCP server provides **75 tools** and **7 workflow prompts** for **debugging, management, and deployment**:
19-
20-
| Category | Tools |
21-
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
22-
| **Infrastructure** | overview, mcp_version (all resources at once) |
23-
| **Diagnostics** | diagnose_app, diagnose_server, find_issues (smart lookup by name/domain/IP) |
24-
| **Batch Operations** | restart_project_apps, bulk_env_update, stop_all_apps, redeploy_project |
25-
| **Servers** | list, get, validate, resources, domains |
26-
| **Projects** | list, get, create, update, delete |
27-
| **Environments** | list, get, create, delete |
28-
| **Applications** | list, get, update, delete, start, stop, restart, logs, env vars (CRUD), create (private-gh, private-key) |
29-
| **Databases** | list, get, create (8 types), delete, start, stop, restart, backups (list, get), backup executions (list, get) |
30-
| **Services** | list, get, create, update, delete, start, stop, restart, env vars (list, create, delete) |
31-
| **Deployments** | list, get, deploy, cancel, list by application |
32-
| **Private Keys** | list, get, create, update, delete |
33-
34-
### Workflow Prompts
35-
36-
Pre-built guided workflows that walk you through common tasks:
37-
38-
| Prompt | Description |
39-
| ------------------ | ----------------------------------------------------------- |
40-
| `debug-app` | Debug an application - gathers logs, status, env vars |
41-
| `health-check` | Full infrastructure health analysis |
42-
| `deploy-app` | Step-by-step deployment wizard from Git repository |
43-
| `troubleshoot-ssl` | SSL/TLS certificate diagnosis workflow |
44-
| `restart-project` | Safely restart all apps in a project with status monitoring |
45-
| `env-audit` | Audit and compare environment variables across applications |
46-
| `backup-status` | Check database backup status and history |
18+
This MCP server provides **34 token-optimized tools** for **debugging, management, and deployment**:
19+
20+
| Category | Tools |
21+
| -------------------- | ----------------------------------------------------------------------------------------- |
22+
| **Infrastructure** | `get_infrastructure_overview`, `get_mcp_version`, `get_version` |
23+
| **Diagnostics** | `diagnose_app`, `diagnose_server`, `find_issues` |
24+
| **Batch Operations** | `restart_project_apps`, `bulk_env_update`, `stop_all_apps`, `redeploy_project` |
25+
| **Servers** | `list_servers`, `get_server`, `validate_server`, `server_resources`, `server_domains` |
26+
| **Projects** | `projects` (list, get, create, update, delete via action param) |
27+
| **Environments** | `environments` (list, get, create, delete via action param) |
28+
| **Applications** | `list_applications`, `get_application`, `application` (CRUD), `application_logs` |
29+
| **Databases** | `list_databases`, `get_database`, `database` (create 8 types, delete), `database_backups` |
30+
| **Services** | `list_services`, `get_service`, `service` (create, update, delete) |
31+
| **Control** | `control` (start/stop/restart for apps, databases, services) |
32+
| **Env Vars** | `env_vars` (CRUD for application and service env vars) |
33+
| **Deployments** | `list_deployments`, `deploy`, `deployment` (get, cancel, list_for_app) |
34+
| **Private Keys** | `private_keys` (list, get, create, update, delete via action param) |
35+
36+
### v2.0.0 Token Diet
37+
38+
v2.0.0 reduced token usage by **85%** (from ~43,000 to ~6,600 tokens) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.
4739

4840
## Installation
4941

‎V2_PLAN.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# v2.0.0 Token Diet Implementation Plan
2+
3+
## Goal
4+
5+
Reduce MCP token usage from ~43,000 to <15,000 tokens while preserving all functionality.
6+
7+
## ✅ COMPLETED - Results
8+
9+
- **Token reduction: ~43,000 → ~6,600 tokens** (85% reduction, well under 15k target!)
10+
- **Tool count: 77 → 33 tools** (57% reduction)
11+
- **All 179 tests passing**
12+
- **Build and lint clean**
13+
14+
## Progress Tracker
15+
16+
### Phase 1: Core Rewrite
17+
18+
- [x] Create feature branch `v2-token-diet`
19+
- [x] Rewrite mcp-server.ts with consolidated tools (77 → 33 tools)
20+
- [x] Build and verify no TypeScript errors
21+
- [x] coolify-client.ts unchanged (not needed)
22+
23+
### Phase 2: Tests
24+
25+
- [x] Rewrite mcp-server.test.ts for new tool structure
26+
- [x] Verify all tests pass (179 tests)
27+
- [x] Maintain good coverage (98%+)
28+
29+
### Phase 3: Documentation
30+
31+
- [x] Update package.json version to 2.0.0
32+
- [x] Update CHANGELOG.md with migration guide
33+
- [ ] Update README.md (tool count, examples)
34+
- [ ] Update CLAUDE.md (tool count)
35+
36+
### Phase 4: Verification
37+
38+
- [x] `npm run build` - clean
39+
- [x] `npm run lint` - clean (warnings only)
40+
- [x] `npm test` - all pass
41+
- [ ] Manual test key flows against live Coolify
42+
- [x] Verify token count < 15,000 (~6,600 actual)
43+
44+
### Phase 5: Release
45+
46+
- [ ] Create PR
47+
- [ ] Merge and tag v2.0.0
48+
49+
## New Tool Structure (34 tools)
50+
51+
| Tool | Description | Consolidates |
52+
| ----------------------------- | ------------------------ | --------------------------------------------- |
53+
| `get_version` | Coolify API version | - |
54+
| `get_mcp_version` | MCP server version | - |
55+
| `get_infrastructure_overview` | Overview with counts | - |
56+
| `diagnose_app` | App diagnostics | - |
57+
| `diagnose_server` | Server diagnostics | - |
58+
| `find_issues` | Scan for problems | - |
59+
| `list_servers` | List servers | - |
60+
| `get_server` | Server details | - |
61+
| `server_resources` | Resources on server | get_server_resources |
62+
| `server_domains` | Domains on server | get_server_domains |
63+
| `validate_server` | Validate server | - |
64+
| `projects` | CRUD projects | list/get/create/update/delete_project (5→1) |
65+
| `environments` | CRUD environments | list/get/create/delete_environment (4→1) |
66+
| `list_applications` | List apps | - |
67+
| `get_application` | App details | - |
68+
| `application` | Create/update/delete app | create*application*\* + update + delete (4→1) |
69+
| `application_logs` | Get logs | get_application_logs |
70+
| `list_databases` | List databases | - |
71+
| `get_database` | Database details | - |
72+
| `database` | Create/delete database | 8 create\_\* + delete (9→1) |
73+
| `list_services` | List services | - |
74+
| `get_service` | Service details | - |
75+
| `service` | Create/update/delete svc | 3→1 |
76+
| `control` | Start/stop/restart | 9 tools → 1 |
77+
| `env_vars` | Manage env vars | 7 tools → 1 |
78+
| `list_deployments` | List deployments | - |
79+
| `deploy` | Deploy by tag/UUID | - |
80+
| `deployment` | Get/cancel/list_for_app | 3→1 |
81+
| `private_keys` | CRUD SSH keys | 5→1 |
82+
| `database_backups` | Backup operations | 4→1 |
83+
| `restart_project_apps` | Batch restart | - |
84+
| `bulk_env_update` | Batch env update | - |
85+
| `stop_all_apps` | Emergency stop | - |
86+
| `redeploy_project` | Batch redeploy | - |
87+
88+
**Total: 34 tools** (down from 77)
89+
90+
## Removed
91+
92+
- All 7 prompts (debug-app, health-check, deploy-app, troubleshoot-ssl, restart-project, env-audit, backup-status)
93+
94+
## Breaking Changes
95+
96+
- Tool names changed (e.g., `create_postgresql` → `database` with `action: 'create', type: 'postgresql'`)
97+
- `start_application` → `control` with `resource: 'application', action: 'start'`
98+
- All prompts removed
99+
- Parameter structures changed for consolidated tools
100+
101+
## Notes
102+
103+
- coolify-client.ts unchanged - all client methods still exist
104+
- Types unchanged - all request/response types still exist
105+
- Only MCP tool layer consolidated

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@masonator/coolify-mcp",
33
"scope": "@masonator",
4-
"version": "1.6.0",
4+
"version": "2.0.0",
55
"description": "MCP server implementation for Coolify",
66
"type": "module",
77
"main": "./dist/index.js",

0 commit comments

Comments
 (0)