使用 mcp-agent 与 LM Studio 搭建本地 LLM Agent从环境配置到结构化输出【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent本指南以 mcp-agent 仓库中的 LM Studio Basic Agent 示例 为核心完整讲解如何用本地运行的 LM Studio 作为推理后端配合 filesystem MCP Server 构建具备完整工具调用tool calling与结构化输出能力的 Agent。读完本文你将掌握 LM Studio 本地服务与 mcp-agent 的对接方式、配置文件中各参数的真实含义与默认值、三类典型调用文件读取、目录列举、多轮对话的写法以及底层LMStudioAugmentedLLM的实现原理与结构化输出的两步式处理机制。一、示例概览本地模型 MCP 工具 完整 Agent这个示例解决了一个很实际的工程问题很多 Agent 框架的推理后端依赖云 API而 LM Studio 提供了本地运行、OpenAI 兼容的 HTTP 服务可以让整个 Agent 完全离线运行数据不出本机。examples/lm_studio示例正是演示了这种组合——Agent 通过 filesystem MCP Server 读取和分析本地文件所有 LLM 推理包括工具调用决策与结构化输出都发生在本地 LM Studio 中。从源码角度看该示例由三个文件构成职责非常清晰main.py示例入口包含普通用法与结构化输出两个演示函数mcp_agent.config.yamlAgent 的完整配置声明 LM Studio 连接与 filesystem MCP Serverrequirements.txt依赖声明核心为本地 mcp-agent 项目本体加openai客户端库。整体架构原文档给出了架构图它准确描述了数据流向┌──────────────┐ ┌──────────────┐ │ LM Studio │──────▶│ Filesystem │ │ Agent │ │ MCP Server │ └──────────────┘ └──────────────┘ │ │ OpenAI-compatible API ▼ ┌──────────────┐ │ LM Studio │ │ Local │ │ http:// │ │ localhost │ │ :1234 │ └──────────────┘Agent即LM Studio Agent对应源码中的Agent实例挂载 filesystem MCP Server 获取文件操作工具同时通过http://localhost:1234/v1这一 OpenAI 兼容端点把推理请求发给本地 LM Studio。值得注意的是所有 LLM 推理都发生在本地不存在模型输出离开本机的环节。二、原理纵深LMStudioAugmentedLLM 如何工作要真正理解这个示例需要深入 augmented_llm_lm_studio.py。LMStudioAugmentedLLM类直接继承自OpenAIAugmentedLLM其类注释明确说明LM Studio 在http://localhost:1234/v1提供完整的 OpenAI API 兼容性包括 chat completions、工具调用和结构化输出。因此 mcp-agent 不需要为 LM Studio 单独实现一套协议直接复用 OpenAI 客户端即可。class LMStudioAugmentedLLM(OpenAIAugmentedLLM): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) # Override provider name for logging and telemetry self.provider LM Studio构造函数仅做一件事把provider覆盖为LM Studio用于日志与遥测标识。框架本身的加载逻辑会依据main.py中await file_agent.attach_llm(LMStudioAugmentedLLM)显式指定 LLM 实现类。模型选择的优先级select_model方法体现了模型解析的优先级链这与配置部分直接相关优先采用request_params.model每次请求可临时指定模型其次读取配置中lm_studio.default_model两者皆无时回退到父类OpenAIAugmentedLLM.select_model的基准benchmark选择逻辑。这一行为在 test_augmented_llm_lm_studio.py 中有三个对应测试分别验证配置默认模型生效、请求参数覆盖配置、无配置默认值时回退父类。因此实际运行中示例配置里的default_model: openai/gpt-oss-20b是决定调用哪个模型的关键。结构化输出的两步式实现示例 README 提到 LM Studio 支持结构化输出但源码实现更值得注意。generate_structured被重写为两步流程先用generate_str生成一次文本响应此时 Agent 可以正常调用工具获取真实数据再构造一个 Return ONLY valid JSON matching this exact structure 的格式化提示词调用父类的generate_structured把上一步文本结果转换为目标 Pydantic 模型。之所以这样做是因为 API 层面不支持带工具调用的结构化输出组合。理解这一点有助于把握结构化输出的适用边界并非所有模型都能稳定输出合法 JSON详见后文结构化输出的注意事项小节。配置读取的独立来源get_provider_config类方法返回context.config.lm_studio而不是 openai 配置块这就保证了 LM Studio 可以有完全独立的配置段与 OpenAI 云端配置互不干扰。三、环境准备安装 LM Studio 并启动本地服务按照原文档的步骤环境准备分三步1. 安装 LM Studio从 LM Studio 官网下载并安装对应操作系统的版本。这是本地推理的运行载体。2. 下载并加载模型打开 LM Studio进入 Search 标签页搜索并下载本文示例使用的模型openai/gpt-oss-20b下载完成后进入 Chat 标签页在下拉列表中选中该模型完成加载。需要说明的是openai/gpt-oss-20b只是示例的默认选择任意在 LM Studio 中已加载的模型都可以替换它替换方法见第六节只需确认模型本身具备工具调用能力即可。3. 启动 LM Studio Server在 LM Studio 中进入 Developer 标签页或 Local Server 区域点击 Start Server服务默认监听http://localhost:1234在浏览器访问http://localhost:1234/v1/models验证服务已就绪——该端点会返回当前已加载模型的列表是排查服务未启动问题的最直接手段。四、项目设置克隆仓库、安装依赖与配置文件1. 克隆仓库并进入示例目录将 mcp-agent 仓库克隆到本地后进入examples/lm_studio目录本文所有命令均在示例目录下执行。2. 安装依赖示例使用uv管理依赖。若尚未安装 uv先执行pip install uv然后安装依赖uv pip install -r requirements.txtrequirements.txt 的内容非常精简值得逐行解读# Core framework dependency mcp-agent file://../../ # Link to the local mcp-agent project root # Additional dependencies specific to this example openai第一行通过file://../../以可编辑方式链接到仓库根目录的 mcp-agent 项目本体确保你运行的是当前仓库的代码第二行openai是必需的因为LMStudioAugmentedLLM底层复用 OpenAI Python 客户端来对接 LM Studio 的 OpenAI 兼容端点。3. 配置无需任何 API Key示例运行不需要任何 API Key因为 LM Studio 运行在本地、不要求认证。完整配置文件如下mcp_agent.config.yaml$schema: ../../schema/mcp-agent.config.schema.json execution_engine: asyncio logger: transports: [console, file] level: info progress_display: true path_settings: path_pattern: logs/lmstudio-agent-{unique_id}.jsonl unique_id: timestamp timestamp_format: %Y%m%d_%H%M%S mcp: servers: filesystem: command: npx args: [-y, modelcontextprotocol/server-filesystem, .] lm_studio: # base_url defaults to http://localhost:1234/v1 default_model: openai/gpt-oss-20b配置块解析如下execution_engine: asyncio使用基于 asyncio 的执行引擎该示例未使用 Temporal 等持久化工作流logger同时向控制台与 JSONL 文件输出日志日志按时间戳命名存放于logs/目录便于回放排查仓库 scripts 目录中提供了 event_viewer 等日志工具mcp.servers.filesystem通过npx启动官方modelcontextprotocol/server-filesystemMCP Server参数中的.表示以当前目录为根。而在 main.py 中还会动态执行context.config.mcp.servers[filesystem].args.extend([os.getcwd()])把当前工作目录追加进文件系统服务可访问的路径列表lm_studioLM Studio 专属配置段base_url省略时默认http://localhost:1234/v1default_model指定本地模型标识。五、运行示例与预期输出前置条件满足LM Studio 正在运行、模型已加载后直接执行uv run main.py原文档给出了预期输出形态INFO - Starting LM Studio example... INFO - LM Studio config: {api_key: lm-studio, base_url: http://localhost:1234/v1, default_model: openai/gpt-oss-20b} INFO - Agent has 3 tools available: [read_file, read_multiple_files, list_directory] --- Example 1: Reading config file --- INFO - Agent response: The mcp_agent.config.yaml file configures one MCP server: filesystem... --- Example 2: Listing files --- INFO - Agent response: Found 1 Python file in the current directory: main.py... --- Example 3: Multi-turn conversation --- INFO - Turn 1 response: The main Python file is main.py INFO - Turn 2 response: This file demonstrates using LM Studio with mcp-agent... --- Example completed successfully! --- INFO - Token usage summary: {...}注意日志首行的api_key: lm-studio——它并非真实凭据而是框架为兼容 OpenAI 客户端自动注入的占位值。这一点在 config.py 的LMStudioSettings中写死为默认值并由单测test_api_key_injection显式验证。示例一读取配置文件example_usage()首先创建名为file_explorer的 Agent绑定 filesystem 服务并挂载 LLM然后调用generate_str让模型读取并解释mcp_agent.config.yaml。该请求会触发工具调用链模型决策 → 调用read_file工具 → 依据工具结果组织自然语言回答。示例二列举目录第二个请求让模型列出当前目录下所有.py文件并解释其用途验证的是list_directory与read_multiple_files等工具的协作。示例三多轮对话第三个请求演示了上下文的连续性Turn 1 询问主 Python 文件叫什么模型回答main.pyTurn 2 紧接着让模型读取该文件并总结模型能正确理解该文件指代 Turn 1 中提到的main.py。这验证了 mcp-agent 的多轮对话会携带历史上下文而非每轮独立推理。结构化输出示例main.py的主函数会继续执行structured_output_example()演示generate_structured的用法class FileInfo(BaseModel): Information about files in a directory. file_names: List[str] file_count: int has_readme: bool它定义了一个 Pydantic 模型FileInfo然后调用llm.generate_structured(message..., response_modelFileInfo)要求模型把列出当前目录文件、判断是否存在 README的结果直接整理为结构化对象返回后可访问result.file_count、result.has_readme等字段。这正是第二节介绍的两步式实现先工具调用取数再二次请求格式化 JSON。六、切换模型与配置项的深度说明更换模型LM Studio 中加载的任何模型都可以替换示例模型只需修改 mcp_agent.config.yamllm_studio: default_model: your-model-identifier模型标识字符串需与 LM Studio 中显示的模型名一致如deepseek/deepseek-r1-distill-qwen-14b该模型名在仓库单测中作为示例出现过。若想更灵活也可以在每次请求时通过RequestParams(model...)临时指定模型——由源码可知它的优先级高于配置中的default_model。配置参数与环境变量从 config.py 的LMStudioSettings实现可以整理出完整的参数表参数默认值环境变量别名说明api_keylm-studioLM_STUDIO_API_KEY/lm_studio__api_key为兼容 OpenAI 客户端自动注入的占位值本地服务无需真实凭据base_urlhttp://localhost:1234/v1LM_STUDIO_BASE_URL/lm_studio__base_urlLM Studio 的 OpenAI 兼容端点default_modelNoneLM_STUDIO_DEFAULT_MODEL/lm_studio__default_model本地模型标识LMStudioSettings继承自OpenAISettings因此还顺带继承了reasoning_effort默认medium、user、default_headers等 OpenAI 字段但 API Key 与 base_url 的默认值都被覆写为本地场景。全部字段均可通过.env文件或环境变量覆盖配置解析遵循LM_STUDIO_前缀的SettingsConfigDict设置。结构化输出的注意事项原文档和源码都强调了一个重要限制并非所有模型都支持结构化输出尤其是参数规模低于 7B 的模型。如果你不确定所用模型是否支持应先查阅该模型卡片的 README。当 API 层面的结构化输出与工具调用无法同时满足时LMStudioAugmentedLLM会退化为第二节描述的两步式生成路径因此即使出现这种限制示例仍能产出 Pydantic 对象只是会多消耗一次推理。七、故障排查main.py的异常处理块给出了最常见的两类运行问题提示LM Studio 未启动确认服务运行在http://localhost:1234可通过浏览器访问http://localhost:1234/v1/models验证模型未加载确认已在 Chat 标签页加载openai/gpt-oss-20b或你替换的模型。对应到源码层级这两类问题通常表现为 OpenAI 客户端连接被拒ConnectionError或 404 找不到模型。此外若出现Agent 无工具可用请检查npx是否可用以及 filesystem MCP Server 是否能正常启动——示例日志中Agent has 3 tools available一行就是工具注册成功的标志。八、总结examples/lm_studio示例展示了 mcp-agent 对本地推理后端的完整支持路径通过 OpenAI 兼容协议对接 LM Studio、通过标准 MCP Server 接入工具、通过attach_llm(LMStudioAugmentedLLM)注入本地 LLM 实现并借助配置系统实现零 API Key、零云端依赖的本地 Agent。其价值不仅在于跑通流程更在于LMStudioAugmentedLLMaugmented_llm_lm_studio.py与LMStudioSettingsconfig.py所提供的模型选择优先级、两步式结构化输出等机制——这些同样是你在生产项目里集成 LM Studio 或其他 OpenAI 兼容本地服务时的可直接复用的模式。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考