MCP Lmstudio Windows 11 Controller

MCP LMStudio Win11桌面控制器

一个完全模块化的MCP（模型上下文协议）服务器，使任何与OpenAI兼容的LLM都能完全控制Windows 11桌面。专为使用LM Studio等工具进行严格的本地/LAN操作而设计。处理两种发出本机信号的模型 `` XML标签 和 生成纯文本的模型，不需要任何配置来区分它们。

______________________________________________________________________

建筑一瞥

Local LLM (LM Studio)  ──►  MCP Server  ──►  Parser Router  ──►  Tool Registry  ──►  TSD Applier  ──►  Windows APIs
(e.g., Llama/GPT on LAN)     (stdio/http/sse)   (auto-detects        (78 tools          (retries, hooks,
                              with local models   tag vs text)         across 15          timeouts, rate
                                                   hybrid mode)        modules)           limits, elevation)

______________________________________________________________________

快速开始

# 1. Install dependencies
npm install

# 2. Build TypeScript → dist/, then start in stdio mode (default)
npm start

# Or start as an HTTP server on port 3000
npm run start:http

# Or start as an SSE server
npm run start:sse

# For active development (no build step — ts-node runs src/ directly)
npm run dev

测试工具

快速测试单个工具：

# List all available tools
node test_tools.js list

# Show tool schema and required arguments
node test_tools.js schema file.read

# Call a tool
node test_tools.js call system.info '{}'
node test_tools.js call file.list '{"path":"C:\\temp"}'

# Interactive mode
node test_tools.js interactive

______________________________________________________________________

LM Studio设置（本地LLM集成）

该项目专为严格的本地/LAN操作而设计，LM Studio作为MCP服务器后端。

1.安装LM Studio

• 下载并安装 LM工作室.
• 下载兼容的模型（例如GPT-2、Llama或任何与OpenAI兼容的模型）。

2.启动本地服务器

• 打开LM工作室。
• 加载您选择的模型。
• 在上启动本地服务器 http://localhost:11000 （默认端口）。
• 确保服务器正在运行且可访问。

3.配置环境变量（可选）

代理工具默认为本地操作，但您可以覆盖：

# Set the local LM Studio endpoint (default: http://localhost:11000/v1)
set OPENAI_BASE_URL=http://localhost:11000/v1

# Set the model name (default: local-model)
set AGENT_MODEL=your-local-model-name

# API key is not required for local LM Studio (defaults to dummy)

4.测试代理

在LM Studio运行的情况下，测试自主查询：

node test_tools.js call agent.execute_query '{"query": "List the files in the current directory"}'

这 agent.execute_query 该工具利用您的本地LLM，使用可用的工具集自主规划和执行多步骤任务。

Qwen集成

代理还可以通过OAuth身份验证使用阿里云的Qwen模型。要启用Qwen：

1. 运行安装脚本：

node setup_qwen.js

1. 或者手动设置环境变量：

export USE_QWEN=true
export QWEN_MODEL=qwen3  # or other available models
export QWEN_BASE_URL=https://portal.qwen.ai/v1  # optional, uses default if not set

1. 运行代理查询-它将在首次使用时自动处理OAuth登录：

node test_tools.js call agent.execute_query '{"query": "What is the capital of France?"}'

首次运行时，代理将：

• 打开浏览器https://chat.qwen.ai/
• 提示您输入设备代码
• 完成OAuth身份验证
• 将令牌安全地存储在 memories/ 目录
• 令牌过期时自动刷新令牌

可用的Qwen型号包括 qwen3, coder-model，以及 vision-model.

______________________________________________________________________

先决条件

• Node.js 20+
• Windows 11 （工具模块调用Win32 API和PowerShell cmdlet）
• PowerShell 5.1+ （随附Windows，无需安装）

对于可选的低延迟输入模拟路径，请安装本机插件：

npm install ffi-napi

如果跳过此步骤， input_handler 自动回退到基于PowerShell的实现。

______________________________________________________________________

配置

config/session.json

config/tsds/*.json --任务特定定义

每个文件都会在不接触代码的情况下调整一个工具的运行时行为：

{
  "toolName": "file.delete",
  "retryPolicy": {
    "maxRetries": 2,
    "backoff": "exponential",
    "baseDelayMs": 500,
    "retryableErrors": ["ACCESS_DENIED", "FILE_IN_USE"]
  },
  "timeoutMs": 10000,
  "requiresElevation": false,
  "preHook": "backup_target",
  "postHook": "verify_deleted"
}

TSD字段：

路径沙盒

设置 FILE_MANAGER_SANDBOX 将环境变量转换为分号分隔的允许路径前缀列表。任何 file.* 在任何I/O运行之前，针对此列表之外路径的操作都会被拒绝：

set FILE_MANAGER_SANDBOX=C:\Users\MyUser;C:\Projects

______________________________________________________________________

工具参考

窗口管理器(window_manager)

文件管理器(file_manager)

流程经理(process_manager)

输入处理程序(input_handler)

剪贴板管理器(clipboard_manager)

显示管理器(display_manager)

注册表管理器(registry_manager)

计划任务(scheduled_tasks)

系统信息(system_info)

______________________________________________________________________

内置挂钩

______________________________________________________________________

添加新工具（4个步骤）

1. 创建 src/tools/my_tool.ts 实施 ToolModule 接口
2. 定义架构 --LLM看到的OpenAI函数定义
3. 编写TSD — config/tsds/my_tool.json 具有重试/挂钩/超时策略
4. 注册 --添加 import './my_tool'; 到 src/tools/index.ts

无需更改核心代码。解析器、注册表和传输会自动获取它。

______________________________________________________________________

运输方式

______________________________________________________________________

安全说明

• 立面是封闭的。 设置的工具 requiresElevation: true 如果进程没有以管理员身份运行，则TSD中的请求将失败，除非会话预先批准了它们。
• 路径沙盒 防止在配置的目录之外进行文件操作。
• 速率限制 通过TSD对每个工具强制执行，以防止失控回路。
• 审核日志记录 通过 log_action 钩子提供了每次调用的完整轨迹。
• 销毁前的备份。 file.delete 和 registry.write/registry.delete 全部运行 backup_target 在触摸任何东西之前。

______________________________________________________________________

项目结构

mcp-win11-desktop/
├── src/
│   ├── core/
│   │   ├── server.ts            # Entry point & boot orchestrator
│   │   ├── types.ts             # All shared TypeScript types
│   │   ├── errors.ts            # Typed error taxonomy
│   │   ├── logger.ts            # Pino singleton + scoped loggers
│   │   ├── registry.ts          # Tool registry (singleton)
│   │   ├── hooks.ts             # Hook registry + built-in hooks
│   │   ├── parser/
│   │   │   ├── router.ts        # Decides embedding vs text parser
│   │   │   ├── embedding_parser.ts  #  tag extraction
│   │   │   └── text_parser.ts   # Plain-text strategy stack
│   │   └── tsd/
│   │       ├── loader.ts        # Reads config/tsds/*.json
│   │       └── applier.ts       # Wraps execute() with TSD policies
│   ├── tools/
│   │   ├── index.ts             # Barrel — imports all tool modules
│   │   ├── window_manager.ts
│   │   ├── file_manager.ts
│   │   ├── process_manager.ts
│   │   ├── input_handler.ts
│   │   ├── clipboard_manager.ts
│   │   ├── display_manager.ts
│   │   ├── registry_manager.ts
│   │   ├── scheduled_tasks.ts
│   │   ├── system_info.ts
│   │   ├── internet_tools.ts
│   │   ├── ui_inspector.ts
│   │   ├── memory_manager.ts
│   │   ├── agent_orchestrator.ts
│   │   ├── virtual_desktop_manager.ts
│   │   └── shell_executor.ts
│   └── transports/
│       ├── http.ts              # Express HTTP server
│       ├── sse.ts               # Server-Sent Events
│       └── stdio.ts             # JSON-RPC over stdin/stdout
├── config/
│   ├── session.json             # Session defaults
│   └── tsds/                    # Per-tool TSD configs (15 files)
├── package.json
├── tsconfig.json
└── README.md