LM Studio Bridge Enhanced v5.1.0

An autonomous middleware agent that lets any MCP client delegate tasks to local LLMs, which can then use any MCP tool — translating between all 4 API formats in real-time.

Based on: LMStudio-MCP by infinitimeless

---

The 5 Pillars

This project is not just a bridge — it's a 3-way autonomous middleware agent built on 5 pillars:

     Claude Code                         Other MCPs
     (any MCP client)                    (filesystem, memory, git, fetch...)
          |                                   ^
          | MCP Protocol                      | MCP Protocol
          v                                   |
    +---------------------------------------------+
    |          PILLAR 1: MCP SERVER                |
    |          (FastMCP, 37 tools)                 |
    |                                              |
    |    +--------------------------------------+  |
    |    |   PILLAR 4: AUTONOMOUS AGENT         |  |
    |    |   (self-correcting loops, parallel   |  |
    |    |    tool exec, metrics, branching)    |  |
    |    +--------+-----------------+-----------+  |
    |             |                 |               |
    |    +--------v------+  +------v-----------+   |
    |    | PILLAR 2:     |  | PILLAR 3:        |   |
    |    | LLM CLIENT    |  | MCP CLIENT       |   |
    |    | (Facade +     |  | (dynamic         |   |
    |    |  7 sub-clients|  |  discovery,      |   |
    |    |  4 API surfs) |  |  hot reload)     |   |
    |    +--------+------+  +------+-----------+   |
    |             |                 |               |
    |    +--------v-----------------v-----------+   |
    |    |     PILLAR 5: FORMAT TRANSLATOR      |   |
    |    |     (OpenAI <-> Anthropic <->        |   |
    |    |      Responses, bidirectional)       |   |
    |    +--------------------------------------+   |
    +---------------------------------------------+
          |                                   |
          | HTTP (3 API surfaces)             | stdio/SSE
          v                                   v
     LM Studio                           MCP Servers
     (local LLMs)                        (any from .mcp.json)

| Pillar | Role | What Sees It As | |--------|------|-----------------| | 1. MCP Server | Serves 37 tools via FastMCP | Claude Code sees an MCP with tools | | 2. LLM Client | Facade + 7 sub-clients across 4 API surfaces | LM Studio sees an HTTP client | | 3. MCP Client | Connects to other MCPs dynamically from .mcp.json | Other MCPs see an MCP client | | 4. Autonomous Agent | Runs LLM-tool loops independently — multi-round, self-correcting, parallel | The orchestrator that ties everything together | | 5. Format Translator | Bidirectional 3-way translation: OpenAI, Anthropic, Responses | The universal glue between competing standards |

What Makes It Different

| # | Differentiation | Description | |---|----------------|-------------| | D-1 | 3-way MCP topology | Acts as MCP Server AND MCP Client AND LLM Client simultaneously — a 3-way node in the MCP graph | | D-2 | Autonomous agent loops | Claude delegates a task, the bridge runs a full LLM-tool loop and returns only the result | | D-3 | Universal format translation | OpenAI, Anthropic, Responses, Native — all 4 formats, bidirectional, for tools + messages + streaming | | D-4 | Dynamic MCP discovery | Hot-reload from .mcp.json — add a new MCP, it's instantly available. Zero code changes | | D-5 | Smart model routing | Scores all loaded models by capability and picks the best one for each task | | D-6 | JIT model lifecycle | Model not loaded? Bridge loads it. Wrong model? Bridge swaps it. All transparent | | D-7 | Conversation branching | Fork conversations at any point, explore alternatives, merge results — tree-based history |

---

Quick Start

1. Prerequisites

• Python 3.9+
• LM Studio v0.4.4+ with a model loaded
• MCP-compatible client (e.g., Claude Code)

2. Install

git clone https://github.com/ahmedibrahim085/lmstudio-bridge-enhanced.git
cd lmstudio-bridge-enhanced
pip install -r requirements.txt

3. Configure

Option A: Automated Setup (Recommended)

Run the setup script to automatically configure the correct paths:

./setup-config.sh

The script will:

• Detect your project root automatically
• Create configuration for Claude Code and/or LM Studio
• Set correct PYTHONPATH for Python module imports
• Backup existing configurations

Option B: Manual Configuration

For Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "lmstudio-bridge": {
      "command": "python3",
      "args": [
        "/absolute/path/to/lmstudio-bridge-enhanced/main.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/lmstudio-bridge-enhanced",
        "LMSTUDIO_HOST": "localhost",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

For LM Studio

Add to ~/.lmstudio/mcp.json:

{
  "mcpServers": {
    "lmstudio-bridge-enhanced": {
      "command": "python3",
      "args": [
        "/absolute/path/to/lmstudio-bridge-enhanced/main.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/lmstudio-bridge-enhanced",
        "LMSTUDIO_HOST": "localhost",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

Required Setup:

1. Replace /absolute/path/to/lmstudio-bridge-enhanced with your actual installation path
   • Example (macOS/Linux): /Users/yourname/projects/lmstudio-bridge-enhanced
   • Example (Windows): C:\Users\yourname\projects\lmstudio-bridge-enhanced
2. Important: Set PYTHONPATH to the same directory as main.py (the project root)

Optional Environment Variables:

• DEFAULT_MODEL: Pin a specific model (e.g., "qwen/qwen3-coder-30b")
• LMSTUDIO_HOST: Change if LM Studio runs on different host (default: localhost)
• LMSTUDIO_PORT: Change if LM Studio uses different port (default: 1234)

Example Configuration: See .mcp.json.example for a template configuration file with placeholders.

4. Use

In Claude Code or your MCP client:

Use the autonomous_with_mcp tool with the filesystem MCP to list all Python files

---

Key Features

Agent Profiles & Model Slots (v5.0.0)

Define task-specific agent roles and assign models dynamically:

# Create a role template
create_role(
    name="coder",
    description="Code generation and refactoring",
    config={"temperature": 0.2, "max_tokens": 4096}
)

# Create an agent with a model assigned to a role
create_agent(
    name="my-coder",
    role="coder",
    model="qwen/qwen3-coder-30b"
)

# List active agents
list_agents()

# Remove when done
remove_agent(name="my-coder")

Features:

• User-defined roles via YAML templates — create, modify, delete
• Any model can play any role with auto-resolved configuration
• Multiple agent slots run concurrently (coder + tester + reviewer)
• 6-param config: temperature, top_p, top_k, max_tokens, system_prompt, context_length
• Model family knowledge base: 6 families x 6 task types with vendor-researched overlays
• Critical constraints auto-enforced per model family

Native Chat API (v5.0.0)

Direct access to LM Studio's native /api/v1/chat endpoint with 19-event SSE streaming:

19 Event Types: chat.start, model_load.start/progress/end, prompt_processing.start/progress/end, reasoning.start/delta/end, tool_call.start/arguments/success/failure, message.start/delta/end, error, chat.end

Features:

• Rich streaming with model loading progress, reasoning tokens, tool execution status
• Native reasoning parameter (reasoning_effort: low/medium/high) replacing thinking_budget
• Log-probabilities support for confidence scoring
• Ephemeral MCP servers via integrations parameter
• API authentication via Authorization header

Model Auto-Download (v5.0.0)

Download models directly via REST API without manual LM Studio interaction:

lms_download_model(model_key="qwen/qwen3-coder-30b")

Multi-Model Support (v3.1.0)

Choose different models for different tasks:

# Reasoning model for analysis
autonomous_with_mcp(
    mcp_name="filesystem",
    task="Analyze codebase architecture",
    model="mistralai/magistral-small-2509"
)

# Coding model for implementation
autonomous_with_mcp(
    mcp_name="filesystem",
    task="Generate unit tests",
    model="qwen/qwen3-coder-30b"
)

# Default model (omit parameter)
autonomous_with_mcp(
    mcp_name="filesystem",
    task="List files"
)

Features:

• Async model validation with caching
• Clear error messages listing available models
• Backward compatible (model parameter is optional)
• Handles IDLE state (models auto-activate)

Structured Output (v3.2.0) - JSON Schema

Force the LLM to output valid JSON conforming to a schema (LM Studio v0.3.32+):

# Get structured JSON output
chat_completion(
    prompt="List 3 programming languages with their use cases",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "languages",
            "schema": {
                "type": "object",
                "properties": {
                    "languages": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "use_case": {"type": "string"}
                            }
                        }
                    }
                },
                "required": ["languages"]
            }
        }
    }
)
# Returns: {"languages": [{"name": "Python", "use_case": "Data science"}, ...]}

Features:

• JSON schema validation with validate_json_schema tool
• Schema depth and complexity limits (max 10 levels, 100 properties)
• json_object mode for unstructured but valid JSON
• Backward compatible (response_format is optional)

Note: Models < 7B parameters may produce invalid JSON. Recommended: Qwen 7B+, Llama 3 8B+, or Mistral 7B+.

Vision/Image Analysis (v3.2.0)

Analyze images using multimodal models (LM Studio v0.3.30+):

# Analyze any image (auto-detects input format)
analyze_image(image="/path/to/photo.jpg")
analyze_image(image="https://example.com/image.png")
analyze_image(image="data:image/png;base64,...")

# Generate descriptions with different styles
describe_image(image="/path/to/image.jpg", style="detailed")  # or "brief", "creative", "technical"

# Compare multiple images
compare_images(
    images=["design_v1.png", "design_v2.png"],
    comparison_type="differences"  # or "similarities", "both"
)

# Extract text (OCR-like)
extract_text_from_image(image="/path/to/document.png")

# Ask specific questions
answer_about_image(
    image="/path/to/chart.png",
    question="What is the value shown for Q3 2024?"
)

Supported Input Formats (auto-detected):

• File paths: /path/to/image.png, ./relative/path.jpg
• URLs: https://example.com/image.jpg
• Base64: data:image/png;base64,... or raw base64 strings

Note: Requires a vision-capable model (LLaVA, Qwen-VL, GPT-4V compatible). Text-only models will return an error.

Model Capability Registry (v3.2.0)

Query model capabilities, VRAM requir