sirkirby/unifi-mcp v0.2.0

Release v0.2.0

on GitHub

🎉 Big Release: Context Optimization & Lazy Loading

This release introduces massive context optimization features that reduce token usage by up to 96% while maintaining full functionality and improving user experience.

🚀 What's New

1. True Lazy Tool Loading ⭐⭐⭐

Tools now load automatically on-demand when first called!

Before (v0.1.x):

• All 67 tools registered immediately
• ~5,000 tokens consumed for tool schemas
• Heavy context load on every conversation

After (v0.2.0 with lazy mode):

• Only 3 meta-tools registered initially (~225 tokens)
• Other tools load transparently when first used
• 96% token reduction with zero UX compromise!

Example:

User: "Show me my UniFi devices"

v0.1.x: All 67 tools already in context (5,000 tokens)
v0.2.0: Only 3 meta-tools in context (225 tokens)
        → unifi_list_devices loads automatically on first call
        → Total: 225 tokens (96% savings!)

2. Three Registration Modes

Choose the mode that fits your use case:

Recommended: Use lazy mode for Claude Desktop and production deployments!

3. Async Job Management

Execute long-running operations in the background:

{
  "tool": "unifi_async_start",
  "arguments": {
    "tool": "unifi_upgrade_device",
    "arguments": {"mac_address": "aa:bb:cc:dd:ee:ff", "confirm": true}
  }
}

{
  "tool": "unifi_async_status",
  "arguments": {"jobId": "abc123"}
}

4. Tool Index API with Build-Time Codegen

Programmatic tool discovery powered by static manifest generation with full schema extraction:

{
  "tool": "unifi_tool_index",
  "arguments": {}
}

How it works:

• Tool manifest is pre-generated at build time (src/tools_manifest.json)
• Full schema extraction - captures complete parameter definitions from decorators
• In lazy mode, reads from static file (instant, no imports!)
• Provides full tool discovery with complete type information for LLMs
• Updates automatically when adding new tools via make manifest

Example schema from manifest:

{
  "name": "unifi_list_clients",
  "description": "List clients/devices connected to the Unifi Network",
  "schema": {
    "input": {
      "type": "object",
      "properties": {
        "filter_type": {"type": "string"},
        "include_offline": {"type": "boolean"},
        "limit": {"type": "integer"}
      }
    }
  }
}

5. MCP Server Identity

The server now advertises its capabilities via .well-known/mcp-server.json:

{
  "capabilities": {
    "tools": true,
    "tool_index": true,
    "async_operations": true
  }
}

🔧 Technical Changes

Dependencies

• Upgraded MCP SDK: 1.13.1 → 1.21.2 (latest stable)
• Reason: Enables true lazy loading via FastMCP's add_tool() method

Architecture: Build-Time Codegen

Pre-generated tool manifest for optimal lazy loading

The Problem:

• Lazy loading needs tool discovery without imports
• Runtime discovery would require importing all modules
• Defeats the purpose of lazy loading!

The Solution:

• Generate src/tools_manifest.json at build time with full schema extraction
• Forces eager tool registration during build to populate TOOL_REGISTRY
• Extracts complete parameter schemas from @server.tool decorators
• In lazy mode, unifi_tool_index reads pre-generated manifest
• Result: Full tool discovery with complete schemas and zero runtime imports!

🎯 Migration Guide

Existing Users (v0.1.x → v0.2.0)

Option 1: Use lazy mode (NEW Default)

1. Only three new meta tools register at runtime
2. Claude (or other tool calling LLMs) will automatically discover and load tools on demand
3. Enjoy 96% token savings

Option 2: To maintain v0.1.x behavior

• Set to eager mode
• Add to Claude Desktop config:

  "env": {
    "UNIFI_TOOL_REGISTRATION_MODE": "eager"
  }

• All 67 tools registered immediately (same as v0.1.x)
• Nothing breaks!

🐛 Bug Fixes

🔐 CRITICAL SECURITY FIX: Permission Enforcement

Issue: Tools were not consistently enforcing permissions from config.yaml

Fix: Added decorator-level permission enforcement

• All 31 create/update/delete tools now use permission_category and permission_action
• Tools are not registered with MCP server if permissions are disabled
• All tools remain in tool index for discovery (users control permissions)
• Enforced at runtime based on users ENV via new Environment variable support for easy permission control
• Conservative defaults protect against accidental network disruption

See docs/permissions.md for complete documentation.

Other Fixes

1. Fixed unclosed aiohttp session warnings

   • Added proper cleanup in dev_console.py
   • No more connection warnings on exit

2. Meta-tools now visible in dev console

   • Registered via shared meta_tools helper
   • Consistent across MCP server and dev console