LM Studio Bridge增强版v5.1.0
一个自主的中间件代理,允许任何MCP客户端将任务委派给本地LLM,然后LLM可以使用任何MCP工具实时在所有4种API格式之间进行转换。
基于: LMStudio MCP 无限无限
    
______________________________________________________________________
五大支柱
这个项目不仅仅是一座桥,它是一个 三向自治中间件代理 建立在5个支柱之上:
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)| 支柱 | 角色 | 如何看待它 |
|---|---|---|
| 1.MCP服务器 | 通过FastMCP提供37个工具 | Claude Code看到一个带有工具的MCP |
| 2.LLM客户端 | 立面+4个API表面上的7个子客户端 | LM Studio看到一个HTTP客户端 |
| 3.MCP客户端 | 从动态连接到其他MCP .mcp.json | 其他MCP看到MCP客户端 |
| 4.自主代理 | 独立运行LLM工具循环——多轮、自校正、并行 | 将所有内容联系在一起的编排器 |
| 5.格式转换器 | 双向三向翻译:OpenAI、Anthropic、Responses | 相互竞争的标准之间的通用粘合剂 |
是什么让它与众不同
| # | 区别 | 描述 |
|---|---|---|
| D-1 | 三向MCP拓扑 | 同时充当MCP服务器、MCP客户端和LLM客户端——MCP图中的三向节点 |
| D-2型 | 自治代理循环 | Claude委托一个任务,网桥运行一个完整的LLM工具循环,只返回结果 |
| D-3 | 通用格式转换 | OpenAI、Anthropic、Response、Native——所有4种格式,双向,用于工具+消息+流媒体 |
| D-4 | 动态MCP发现 | 从热重新加载 .mcp.json --添加一个新的MCP,它立即可用。零代码更改 |
| D-5 | 智能模型路由 | 按能力对所有加载的模型进行评分,并为每个任务选择最佳模型 |
| D-6 | JIT模型生命周期 | 模型未加载?桥载它。型号不对?桥交换它。一切都是透明的 |
| D-7 | 对话分支 | 在任何时候分叉对话,探索替代方案,合并结果——基于树的历史 |
______________________________________________________________________
快速开始
1.先决条件
- Python 3.9+
- LM 工作室 v0.4.4+,模型已加载
- MCP兼容客户端(如Claude Code)
2.安装
git clone https://github.com/ahmedibrahim085/lmstudio-bridge-enhanced.git
cd lmstudio-bridge-enhanced
pip install -r requirements.txt3.配置
选项A:自动设置(推荐)
运行安装脚本以自动配置正确的路径:
./setup-config.sh脚本将:
- 自动检测项目根目录
- 为Claude Code和/或LM Studio创建配置
- 设置正确
PYTHONPATH用于Python模块导入 - 备份现有配置
选项B:手动配置
克劳德代码
添加到您的项目 .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"
}
}
}
}LM工作室
添加 ~/.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"
}
}
}
}所需设置:
- 替换
/absolute/path/to/lmstudio-bridge-enhanced使用您的实际安装路径
- 示例(macOS/Linux): /Users/yourname/projects/lmstudio-bridge-enhanced - 示例(Windows): C:\Users\yourname\projects\lmstudio-bridge-enhanced
- 重要:设置
PYTHONPATH到与相同的目录main.py(项目根)
可选环境变量:
DEFAULT_MODEL:固定特定模型(例如。,"qwen/qwen3-coder-30b")LMSTUDIO_HOST:如果LM Studio在不同的主机上运行,则进行更改(默认值:localhost)LMSTUDIO_PORT:如果LM Studio使用不同的端口,则进行更改(默认值:1234)
配置示例: 看 .mcp.json.example 对于带有占位符的模板配置文件。
4.使用
在Claude Code或您的MCP客户端中:
Use the autonomous_with_mcp tool with the filesystem MCP to list all Python files______________________________________________________________________
主要特点
代理配置文件和型号插槽(v5.0.0)
定义特定任务的代理角色并动态分配模型:
# 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")特性:
- 通过YAML模板创建、修改、删除用户定义的角色
- 任何型号都可以通过自动解析配置发挥任何作用
- 多个代理槽同时运行(编码+测试+审核)
- 6-param配置:温度、top_p、top_k、max_tokens、system_prompt、context_length
- 模型族知识库:6个族x 6个任务类型,带有供应商研究的覆盖层
- 每个模型族自动执行关键约束
原生聊天API(v5.0.0)
直接访问LM Studio的本地 /api/v1/chat 具有19个事件SSE流的端点:
19事件类型: 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
特性:
- 丰富的流媒体,包括模型加载进度、推理令牌、工具执行状态
- 本地推理参数(
reasoning_effort:低/中/高)更换thinking_budget - 日志概率支持置信度评分
- 通过以下方式提供临时MCP服务器
integrations参数 - API认证通过
Authorization头球
模型自动下载(v5.0.0)
通过REST API直接下载模型,无需手动进行LM Studio交互:
lms_download_model(model_key="qwen/qwen3-coder-30b")多模型支持(v3.1.0)
为不同的任务选择不同的型号:
# 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"
)特性:
- 使用缓存进行异步模型验证
- 清除列出可用型号的错误消息
- 向后兼容(型号参数可选)
- 处理空闲状态(车型自动激活)
结构化输出(v3.2.0)-JSON模式
强制LLM输出符合模式的有效JSON(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"}, ...]}特性:
- JSON模式验证
validate_json_schema工具 - 模式深度和复杂性限制(最多10个级别,100个属性)
json_object非结构化但有效的JSON模式- 向后兼容(response_format是可选的)
备注:小于7B的模型参数可能会生成无效的JSON。推荐:Qwen 7B+、Llama 3 8B+或Mistral 7B+。
视觉/图像分析(v3.2.0)
使用多模态模型分析图像(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?"
)支持的输入格式 (自动检测):
- 文件路径:
/path/to/image.png,./relative/path.jpg - 网址:
https://example.com/image.jpg - Base64:
data:image/png;base64,...或原始base64字符串
备注:需要具有视觉功能的型号(兼容LLaVA、Qwen VL、GPT-4V)。纯文本模型将返回错误。
模型能力注册表(v3.2.0)
查询模型功能、VRAM要求,并为您的任务找到最佳模型:
# List all downloaded models with metadata
lms_list_downloaded_models()
# Returns: [{"model_key": "qwen/qwen3-coder-30b", "size_bytes": 19000000000, ...}]
# Get detailed capabilities with BFCL benchmark scores
get_model_capabilities(model="qwen/qwen3-coder-30b")
# Returns: {
# "model_key": "qwen/qwen3-coder-30b",
# "tool_use_score": 0.933, # BFCL benchmark
# "estimated_vram_gb": 18.5,
# "is_thinking_model": false,
# "max_context_length": 32768
# }
# Intelligent model resolution with fallback
lms_resolve_model(
requested_model="large-model-not-downloaded",
task_type="coding"
)
# Returns: Alternative model suggestion if requested not available
# Download a model
lms_download_model(model_key="huggingface/model-name")特性:
- VRAM估计(考虑量化、KV缓存、上下文长度)
- 思维模型检测(QwQ、DeepSeek-R1、o1模式)
- BFCL工具调用能力基准分数
- 智能回退建议
- 具有增量更新的持久缓存
VRAM估计公式:
VRAM = (file_size × quant_multiplier + kv_cache) × 1.1 overhead动态MCP发现
没有硬编码配置。适用于您的任何MCP .mcp.json:
autonomous_with_mcp("filesystem", "task")
autonomous_with_mcp("memory", "task")
autonomous_with_mcp("postgres", "task")
# Works with ANY MCP推理显示
对于具有推理能力的模型(DeepSeek R1、Magistral、Qwen3思维),请在最终答案之前查看模型的思维过程。
自主执行
LLM自主使用MCP工具:
# Single MCP
autonomous_with_mcp("filesystem", "Analyze codebase")
# Multiple MCPs
autonomous_with_multiple_mcps(
["filesystem", "memory"],
"Analyze code and build knowledge graph"
)
# Auto-discover all MCPs
autonomous_discover_and_execute("Complete this task")______________________________________________________________________
可用工具(共37个)
岩芯完井(5个工具)
chat_completion-聊天完成(包括推理_努力、日志问题、响应_格式)text_completion-文本/代码完成create_response-有状态的对话generate_embeddings-矢量嵌入validate_json_schema-在使用结构化输出之前验证JSON模式
健康与探索(5个工具)
health_check-检查LM Studio连接check_server_health-详细的服务器运行状况和诊断check_server_type-检测GUI与无头(llmster)get_current_model-获取加载的模型信息list_models-列出可用型号
视觉工具(6个工具)
analyze_image-全面的图像分析describe_image-生成描述(详细/简短/创意/技术)compare_images-比较多个图像extract_text_from_image-类似OCR的文本提取identify_objects-用位置标识对象answer_about_image-回答有关图像的具体问题
自主MCP(5个工具)
autonomous_with_mcp-按名称使用任何MCPautonomous_with_multiple_mcps-使用多个MCPautonomous_discover_and_execute-自动发现所有MCPautonomous_with_images-自主视觉输入list_available_mcps-列出发现的MCP
代理配置文件(5个工具)——v5.0.0中的新功能
create_agent-创建具有模型+角色的代理插槽list_agents-列出活动代理插槽remove_agent-删除代理插槽create_role-创建角色模板list_roles-列出可用的角色模板
智能模型选择(1个工具)
select_best_model-能力评分模型路由
LMS CLI工具(9个工具,可选)
lms_list_loaded_models-列出加载的模型及其详细信息lms_list_downloaded_models-列出所有下载的模型及其元数据lms_load_model-加载特定模型lms_unload_model-卸载模型以释放内存lms_ensure_model_loaded-临时模型预加载(推荐)lms_search_models-搜索型号目录lms_download_model-从Hugging Face下载模型lms_resolve_model-具有回退功能的智能模型解析lms_server_status-服务器运行状况和诊断
______________________________________________________________________
建筑
网桥在MCP生态系统中占据着独特的地位——它同时是服务器、客户端和自主代理:
Claude Code ──MCP──> [MCP Server] ──> [Autonomous Agent] ──> [LLM Client] ──HTTP──> LM Studio
|
+──> [MCP Client] ──MCP──> filesystem, memory, git...
|
[Format Translator]
OpenAI Anthropic ResponsesAPI表面 (4同时):
- OpenAI兼容:
/v1/chat/completions,/v1/completions,/v1/models,/v1/embeddings,/v1/responses - 人类相容性:
/v1/messages - 本地LM Studio REST:
/api/v1/models,/api/v1/models/load,/api/v1/models/unload,/api/v1/diagnostics - 本地LM工作室聊天:
/api/v1/chat--19个事件SSE流,包括推理、工具调用、模型加载进度
______________________________________________________________________
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
LMSTUDIO_HOST | localhost | LM工作室主持人 |
LMSTUDIO_PORT | 1234 | LM Studio API端口 |
MCP_JSON_PATH | (自动检测) | 自定义 .mcp.json 路径 |
DEFAULT_MODEL | (自动检测) | 要使用的默认模型(例如。, qwen/qwen3-coder-30b) |
LMS_MAX_RETRIES | 3 | LMS CLI操作的最大重试次数 |
LMS_RETRY_BASE_DELAY | 1.0 | 重试之间的基本延迟(秒) |
LMS_RETRY_MAX_DELAY | 10.0 | 最大延迟上限(秒) |
LMS_EXTRA_NUMERIC_PARAMS | "" | 用于类型强制转换的其他数字参数(逗号分隔) |
系统提示(推荐)
要为您的本地LLM提供正确的标识和工具使用指导,请在LM Studio中配置系统提示:
如何配置:
- 打开LM工作室
- 转到“设置”→ 系统提示(或聊天设置)
- 粘贴以下提示:
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 autonomous_with_mcp(mcp_name="filesystem")
- Fetching web content → use autonomous_with_mcp(mcp_name="fetch")
- Storing/retrieving knowledge → use autonomous_with_mcp(mcp_name="memory")
- GitHub operations → use autonomous_with_mcp(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.测试您的配置:
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 autonomous_with_mcp(mcp_name="filesystem", ...)MCP发现优先级
$MCP_JSON_PATH(如果设置)~/.lmstudio/mcp.json$(pwd)/.mcp.json~/.mcp.json
______________________________________________________________________
测试
运行全面测试:
cd lmstudio-bridge-enhanced
python3 -m pytest tests/ -v测试结果:~1969次测试通过,覆盖率91%
测试覆盖范围包括:
- 格式适配器三向转换(200+测试)
- 自主代理循环——OpenAI和Anthropic格式(100+测试)
- 流式传输——SSE解析器、原生SSE解析器和思维解析器(100+测试)
- 结构化输出和JSON模式(51个测试)
- 视觉/多模式(50+测试)
- 模型注册、选择、发现(150多项测试)
- 模型生命周期——加载、卸载、JIT、下载、验证(120多个测试)
- 代理配置文件——插槽、角色、解析器、知识库(200多个测试)
- 原生聊天客户端——19种事件类型,临时MCP(80+测试)
- 推理、logprobs、身份验证(80多项测试)
- 会话分支(50+测试)
- 线程安全、资源清理、错误处理(80多项测试)
- 架构保护、常量拆分、版本一致性(30+测试)
______________________________________________________________________
文档
______________________________________________________________________
故障排除
连接问题
# 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
# List available MCPs
python3 -c "from mcp_client.discovery import get_mcp_discovery; \
d = get_mcp_discovery(); print(d.list_available_mcps())"看 故障排除指南 更多。
______________________________________________________________________
版本历史
v5.1.0(2026年3月)-当前版本
G轮——可靠性和效率 (来自服务器日志分析的11个OPP):
- OPP-38:修复“model:default”哨兵转义--消除167个错误/会话
- OPP-39:上下文窗口保护--防止94K令牌溢出(累积跟踪)
- OPP-43:JIT轮询率限制器——60秒记忆,消除11613个冗余轮询
- OPP-32:模式感知类型强制--修复字符串→LM Studio模型的数组/对象
- OPP-33:预分派工具参数验证--捕获丢失的必需参数
- OPP-44:每个工具断路器——3状态模式(闭合/打开/半打开)
- OPP-37:工具调用孤立检测--跟踪已开始但未完成的调用
- OPP-40:工具结果缓存——基于TTL和命名空间规范化的allowlist
- OPP-45:每个模型的误差预算----具有退化状态的咨询性健康跟踪
- OPP-46:自适应超时——基于p95的自适应响应时间观察
- OPP-50:工具模式去重实验--设置previous_response_id时省略模式
新模块: tool_call_guard.py, tool_call_tracker.py, tool_result_cache.py, model_health.py, adaptive_timeout.py
6轮评审:修复了5个关键+6个高发现,经过架构师验证
统计:2167次测试,81%的覆盖率(CI),+5476/-131行,38个文件已更改
v5.0.0(2026年3月)
架构重构(A阶段):
- ARCH-1:LLMClient Facade模式——将1500行神类拆分为7个基于协议的子客户端(聊天、响应、人、流、思考、model_info、native_chat)
- ARCH-2:常量包——将854行平面文件拆分为15个域模块,并具有向后兼容的重新导出功能
- ARCH-3:指标辅助提取--重复数据消除4次复制粘贴15行块
- ARCH-4:异常层次结构--
core/exceptions.py具有适当的向上依赖修复 - ARCH-5:平台抽象npx生成——删除了85行仅限macOS的Homebrew路径
新功能(B阶段):
- OPP-21:本地推理参数(
reasoning_effort:低/中/高)--替换thinking_budget - OPP-28:API身份验证-
Authorization安全LM Studio实例的标头支持 - OPP-29:记录概率——每个令牌的置信度评分
- OPP-31:代理配置文件和模型槽——用户定义的角色、任何模型到任何角色、并发代理、6族知识库
- OPP-27:高级模型负载参数——GPU卸载、上下文长度、闪存注意力
- OPP-24:通过REST API建模自动下载
主要特征(C阶段):
- OPP-19:本地聊天API(
/api/v1/chat)--19个事件SSE解析器,具有模型加载、推理和工具调用功能 - OPP-25:临时MCP服务器--
integrations每个请求MCP配置的参数
统计:1969次测试,91%的覆盖率,57次提交,+9541/-2560行
v4.1.0(2026年3月)
- 弃用思考警告_预算 -迁移桥到v5.0.0推理API
- CI执行 --覆盖门(89%)、绒毛、建筑防护
- CI矩阵中的Python 3.12 --匹配pyproject.toml分类器
v4.0.0(2026年3月)
- 代码质量审核 --12个代理,3波深度审查,TDD修复
- 硬编码值提取 --所有神奇的数字都移动到config/constants.py
- 无声错误捕获消除 --所有16个捕获块都添加了日志记录
- 视觉助手重复数据删除 --合并6个重复的try/except块
- 未使用的导入清理 --ruff--修复所有工具模块
- 公共API测试覆盖范围 --register\_\*\_tools()函数现已测试
- 线程安全 --穿线。锁定共享缓存
- 错误合同 --标准化刀具错误返回格式
- 单音定时器 --TTL缓存的time.dononic()
- 1684次测试,覆盖率91%
v3.5.0(2026年2月)
- 已实施18个OPP 5轮(第1阶段至第C轮)
- 三路格式适配器 --OpenAI,拟人,响应(双向)
- 双格式自主循环 --OpenAI和Anthropic工具调用
- 流媒体基础设施 -适用于所有3个API曲面的SSE解析器
- 延伸思考 --思维模型的推理预算控制
- 多模态回路 --自主agent中的视觉支持
- 对话分支 --叉树/合并树导航
- 智能选型 --能力评分模型路由
- 通过API的本地MCP -API请求中配置的MCP服务器
- 测试基础设施大修 --1455次测试,覆盖率91%
- 10个服务器错误修复 --资源泄漏、线程安全、无声故障
v3.4.0(2026年2月)
- 流媒体(OPP-12)、扩展思维(OPP-14)、三向格式适配器(OPP-10)
- 智能选型(OPP-08)、无头部署(OPP-18)
- 约80%的覆盖率,约1100次测试
v3.2.0(2025年11月)
- 结构化JSON输出、视觉/多模式、模型能力注册表
- 331次测试,44次提交,10个新的MCP工具
v3.1.0(2025年11月)
- 多模型支持,模型验证,7个异常类
v3.0.0(2025年10月)
- 推理显示、循证安全、类型安全
看 文档/发行说明/ 了解完整细节。
______________________________________________________________________
许可证
MIT许可证-请参阅 许可证
______________________________________________________________________
积分
原创: LMStudio MCP 无限无限 增强通过:艾哈迈德·马吉德
开发团队:
- Ahmed Maged-首席开发人员
- Claude(Anthropic)-建筑、文档、最佳实践
- Qwen3编码器30B-代码生成和实现
- Qwen3 Think-深度分析和战略规划
看 贡献.md 有关开发协作的详细信息。
______________________________________________________________________
支持
- 问题:
- 文档: docs/
有关快速帮助,请参阅 QUICKSTART.md.
