Feature: Add Lock Manager Integration with ai-dev-kit

[ViperJuice]

Feature: Add Lock Manager Integration with ai-dev-kit

Context

The ai-dev-kit project uses ai_dev_kit/mcp/lock_manager.py to coordinate MCP gateway access, specifically referencing .mcp-gateway/gateway.lock for file-based locking.

This integration pattern suggests that lock management could be a first-class feature in mcp-gateway itself, rather than being implemented externally by each client.

Current Implementation

In ai-dev-kit:

• ai_dev_kit/mcp/lock_manager.py:101 - DEFAULT_LOCK_DIR = ".mcp-gateway"
• ai_dev_kit/cli.py:1062 - References .mcp-gateway/gateway.lock

Lock file purpose:

• Prevent concurrent access to MCP gateway
• Coordinate multiple ai-dev-kit processes
• Ensure safe MCP server lifecycle management

Proposed Enhancement

1. Native Lock Manager in mcp-gateway

Add a built-in lock manager that:

• Provides file-based locking with the same .mcp-gateway/gateway.lock convention
• Handles lock acquisition, release, and timeout
• Exposes lock status via health check endpoint

2. Documentation

Document the lock file format and contract:

• Lock file structure (JSON schema)
• Lock acquisition protocol
• Timeout and cleanup behavior
• Multi-process coordination guarantees

3. Health Check Endpoint

Add endpoint to query lock status:

curl http://localhost:8000/health/locks

Response:

{
  "locks": [
    {
      "resource": "gateway",
      "holder": "ai-dev-kit-process-12345",
      "acquired_at": "2026-01-09T14:30:00Z",
      "ttl": 300
    }
  ]
}

Benefits

1. Centralized coordination: Single source of truth for lock state
2. Simplified clients: ai-dev-kit and other clients can rely on gateway's lock manager
3. Better observability: Health endpoint shows current lock holders
4. Consistent behavior: All clients use same locking protocol

Related

• ai-dev-kit issue: (reference when creating)
• Sister repos also affected: mcp-gateway clients may benefit

Priority

Medium - Current file-based locking works, but native support would improve reliability.

---

Generated from ai-dev-kit reflection wishlist (2026-01-09)
Source: specs/wishlists/REFLECT-2026-01-09/REFLECT-wishlist.md#wish-001