Lmstudio Bridge Enhanced

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

[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://lmstudio.ai/) [](#testing) [](#testing)

---

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

1. 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, topp, topk, maxtokens, systemprompt, 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 [MCP Server] ──> [Autonomous Agent] ──> [LLM Client] ──HTTP──> LM Studio | +──> [MCP Client] ──MCP──> filesystem, memory, git... | [Format Translator] OpenAI Anthropic Responses

**API Surfaces** (4 simultaneous):
- OpenAI-compatible: `/v1/chat/completions`, `/v1/completions`, `/v1/models`, `/v1/embeddings`, `/v1/responses`
- Anthropic-compatible: `/v1/messages`
- Native LM Studio REST: `/api/v1/models`, `/api/v1/models/load`, `/api/v1/models/unload`, `/api/v1/diagnostics`
- Native LM Studio Chat: `/api/v1/chat` — 19-event SSE streaming with reasoning, tool calls, model loading progress

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LMSTUDIO_HOST` | `localhost` | LM Studio host |
| `LMSTUDIO_PORT` | `1234` | LM Studio API port |
| `MCP_JSON_PATH` | (auto-detect) | Custom `.mcp.json` path |
| `DEFAULT_MODEL` | (auto-detect) | Default model to use (e.g., `qwen/qwen3-coder-30b`) |
| `LMS_MAX_RETRIES` | `3` | Max retry attempts for LMS CLI operations |
| `LMS_RETRY_BASE_DELAY` | `1.0` | Base delay between retries (seconds) |
| `LMS_RETRY_MAX_DELAY` | `10.0` | Maximum delay cap (seconds) |
| `LMS_EXTRA_NUMERIC_PARAMS` | `""` | Additional numeric params for type coercion (comma-separated) |

### System Prompt (Recommended)

To give your local LLM proper identity and tool usage guidance, configure a system prompt in LM Studio:

**How to Configure**:
1. Open LM Studio
2. Go to Settings → System Prompt (or Chat Settings)
3. Paste the following prompt:

You are a local language model running via LM Studio on the user's machine.

Your Identity

• Model: Running locally (not a cloud service)
• Capabilities: You have access to MCP tools for extended functionality
• Purpose: Assist users with tasks requiring external data/tools

When to Use Tools

✅ Use tools ONLY when:

• Reading/writing files → use autonomouswithmcp(mcp_name="filesystem")
• Fetching web content → use autonomouswithmcp(mcp_name="fetch")
• Storing/retrieving knowledge → use autonomouswithmcp(mcp_name="memory")
• GitHub operations → use autonomouswithmcp(mcp_name="github")

❌ Do NOT use tools for:

• Conversational responses (greetings, small talk)
• Identity questions ("Who are you?" - answer: "I am a local LLM...")
• General knowledge ("What is X?" - answer from training)
• Explanations, definitions, tutorials

Decision Process

Before calling ANY tool, ask:

1. Do I need external data I don't have? → If NO, answer directly
2. Is this a conversational response? → If YES, answer directly
3. Am I delegating to another LLM when I should answer? → If YES, answer directly

When in doubt, answer directly without tools.

**Testing Your Configuration**:

User: "Hello, who are you?" Expected: LLM responds directly (no tools) - "I am a local language model..."

User: "Read my README file" Expected: LLM uses autonomouswithmcp(mcp_name="filesystem", ...)

### MCP Discovery Priority

1. `$MCP_JSON_PATH` (if set)
2. `~/.lmstudio/mcp.json`
3. `$(pwd)/.mcp.json`
4. `~/.mcp.json`

---

## Testing

Run comprehensive tests:

```bash
cd lmstudio-bridge-enhanced
python3 -m pytest tests/ -v

Test Results: ~1969 tests passing, 91% coverage

Test coverage includes:

• Format adapter 3-way translation (200+ tests)
• Autonomous agent loops — OpenAI and Anthropic formats (100+ tests)
• Streaming — SSE parser, native SSE parser, thinking parser (100+ tests)
• Structured output and JSON schema (51 tests)
• Vision/multimodal (50+ tests)
• Model registry, selection, discovery (150+ tests)
• Model lifecycle — load, unload, JIT, download, validation (120+ tests)
• Agent profiles — slots, roles, resolver, knowledge base (200+ tests)
• Native chat client — 19 event types, ephemeral MCP (80+ tests)
• Reasoning, logprobs, authentication (80+ tests)
• Conversation branching (50+ tests)
• Thread safety, resource cleanup, error handling (80+ tests)
• Architecture guards, constants split, version consistency (30+ tests)

---

Documentation

• [Quick Start](docs/QUICKSTART.md) - Step-by-step tutorial
• [API Reference](docs/API_REFERENCE.md) - Complete tool documentation
• [Architecture](docs/ARCHITECTURE.md) - How dynamic discovery works
• [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues
• [Multi-Model Guide](docs/MULTIMODELGUIDE.md) - Model selection guide
• [Contributing](CONTRIBUTING.md) - Development guidelines

---

Troubleshooting

Connection Issues

# Verify LM Studio is running
curl http://localhost:1234/v1/models

# Check MCP configuration
python3 -c "from mcp_client.discovery import get_mcp_discovery; \
            d = get_mcp_discovery(); print(d.mcp_json_path)"

MCP Not Discovered

# List available MCPs
python3 -c "from mcp_client.discovery import get_mcp_discovery; \
            d = get_mcp_discovery(); print(d.list_available_mcps())"

See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) for more.

---

Version History

v5.1.0 (March 2026) - Current

Round G — Reliability & Efficiency (11 OPPs from server log analysis):

• OPP-38: Fix "model: default" sentinel escape — eliminated 167 ERRORs/session
• OPP-39: Context window guard — prevents 94K token overflow (cumulative tracking)
• OPP-43: JIT poll rate limiter — 60s memoization, eliminates 11,613 redundant polls
• OPP-32: Schema-aware type coercion — fixes string→array/object for LM Studio mod

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahmedibrahim085
• Source: ahmedibrahim085/lmstudio-bridge-enhanced
• License: MIT

Install and usage instructions live in the source repository linked above.