feat!: v2.0.0 Token Diet - 85% token reduction

[StuMason]

Summary

v2.0.0 is a complete rewrite of the MCP tool layer focused on drastically reducing token usage.

Metric	Before	After	Reduction
Tokens	~43,000	~6,600	85%
Tools	77	33	57%
Prompts	7	0	100%

Why This Matters

The MCP tool definitions were consuming ~43,000 tokens in the AI context window just for tool schemas. This left limited room for actual conversation and responses. v2.0.0 consolidates related operations into single tools with action parameters, reducing token usage to ~6,600 (well under the 15,000 target).

Breaking Changes

• Tool consolidation (e.g., create_project, delete_project → projects with action param)
• All 7 prompts removed (were unused)
• Parameter structures changed for consolidated tools

Migration Guide

Most v1.x tool names still exist unchanged:

• get_version, get_mcp_version, list_servers, get_server, etc.
• diagnose_app, diagnose_server, find_issues
• restart_project_apps, bulk_env_update, stop_all_apps, redeploy_project

Consolidated tools now use action parameter:

• create_project → projects with action: 'create'
• start_application → control with resource: 'application', action: 'start'
• create_postgresql → database with action: 'create', type: 'postgresql'

See CHANGELOG.md for full migration guide.

Test plan

• All 179 tests passing
• Build clean
• Lint clean (warnings only)
• Token count verified < 15,000 (~6,600 actual)
• Manual testing against live Coolify

🤖 Generated with Claude Code

[claude]

PR Review: v2.0.0 Token Diet - 85% token reduction

This is an excellent major release that significantly improves the MCP server's token efficiency. The consolidation strategy is well-executed and the documentation is thorough. Here's my detailed review:

✅ Strengths

1. Impressive Token Reduction

• 85% reduction (43,000 → 6,600 tokens) is a substantial improvement
• Well under the 15,000 target, leaving headroom for future additions
• The consolidation approach (action parameters) is a clean pattern used by many APIs

2. Code Quality

• The wrap() helper function provides consistent error handling across all tools
• Good use of Promise.allSettled() in get_infrastructure_overview for resilient parallel fetching
• Clean, readable switch statements for action routing
• Proper parameter validation with clear error messages

3. Documentation

• Excellent CHANGELOG with migration guide for breaking changes
• V2_PLAN.md provides good context for the design decisions
• README and CLAUDE.md properly updated with new tool counts

4. Backward Compatibility Consideration

• Keeping frequently-used tools unchanged (list_servers, get_server, diagnose_app, etc.) minimizes migration pain
• Good strategic choice about what to consolidate vs. keep separate

---

⚠️ Issues to Address

1. Missing validate_server Tool (Bug)

The README and V2_PLAN.md both list validate_server as a tool, but it's not implemented in mcp-server.ts. The client method validateServer() exists and is tested, but the MCP tool is missing.

The Servers section comment says "4 tools" but only defines 4 tools without validate_server:

• list_servers
• get_server
• server_resources
• server_domains

Fix: Add the missing tool:

this.tool('validate_server', 'Validate server connection', { uuid: z.string() }, async ({ uuid }) =>
  wrap(() => this.client.validateServer(uuid)),
);

This would bring the actual tool count to 34, or you could update the documentation to remove the reference to validate_server if it's intentionally excluded.

2. @ts-nocheck Usage (Code Quality)

Line 6 has // @ts-nocheck which disables TypeScript checking for the entire file. This is concerning for a production codebase because:

• Type errors won't be caught at compile time
• The as any casts (lines 295, 313, 471) suggest there may be typing issues that should be properly addressed

Recommendation: Remove @ts-nocheck and properly type the tool handlers. The Zod schemas should provide type inference, and if there are mismatches with client method signatures, those should be fixed at the type level.

3. Test Coverage Reduction

The test file went from ~500 lines to ~153 lines. While the comment explains that "CoolifyClient methods are fully tested in coolify-client.test.ts", the MCP server tests no longer verify:

• That tool handlers correctly call client methods with proper arguments
• That consolidated action routing works correctly (the switch statements)
• Error cases for missing required parameters

Recommendation: Add integration-style tests that mock the client and verify tool handlers call the right methods. For example:

it('should route projects action=create to createProject', async () => {
  const spy = jest.spyOn(client, 'createProject').mockResolvedValue({ uuid: 'new' });
  // Call tool with action: 'create', name: 'test'
  expect(spy).toHaveBeenCalledWith({ name: 'test', description: undefined });
});

---

💡 Suggestions (Non-blocking)

1. Input Validation Consistency

Some tools return early with error messages for missing required params (good), but others rely on Zod validation. Consider making all required params non-optional in the Zod schema where possible, so validation is consistent.

For example, in environments tool, project_uuid is always required but marked as z.string() (required), which is correct. But name is optional even though it's required for get/create/delete actions.

2. Consider Adding Tool Descriptions for Action Parameters

The current descriptions like "Manage projects: list/get/create/update/delete" are token-efficient, but AI assistants might benefit from slightly more context about required params per action. This could be a future enhancement.

3. V2_PLAN.md in Production

Consider whether V2_PLAN.md should remain in the repo post-release or be archived/removed. It's useful context but might confuse future contributors.

---

🔒 Security

No security concerns identified. The PR:

• Doesn't change authentication/authorization logic
• Properly propagates the existing client's secure HTTP handling
• The stop_all_apps emergency tool appropriately requires explicit confirmation

---

Summary

This is a well-designed major release with an impressive 85% token reduction. The main issue is the missing validate_server tool which should be addressed before merge (either add the tool or update documentation). The @ts-nocheck and reduced test coverage are worth considering but are less critical.

Verdict: Approve with minor changes (add validate_server tool or fix documentation).

[StuMason]

@claude please re-review

[claude]

Claude finished @StuMason's task in 1m 17s —— View job

---

Re-review: v2.0.0 Token Diet

• Verify validate_server tool was added
• Verify @ts-nocheck was removed
• Check for any remaining issues
• Provide updated review feedback

---

✅ Review Feedback Addressed

Both issues from my initial review have been fixed in commit d09605e:

1. validate_server tool - Fixed ✓

• Tool is now properly defined at src/lib/mcp-server.ts:164-169
• Comment updated to show "Servers (5 tools)"
• All documentation now correctly references 34 tools

2. @ts-nocheck removed - Fixed ✓

• TypeScript checking is now enabled for the file
• Only @typescript-eslint/no-explicit-any is disabled (reasonable for MCP SDK types)

✅ CI Status

All checks passing - tests and build are green.

📊 Final Assessment

This is a well-executed major release:

• 85% token reduction (43,000 → 6,600 tokens)
• 57% tool reduction (77 → 34 tools)
• Clean consolidation pattern using action parameters
• Comprehensive migration guide in CHANGELOG
• All documentation properly updated

Verdict: Approve 👍

---