内容
# LM工作室MCP服务器
一个用于LM工作室集成的强大的模型上下文协议（MCP）服务器，具有安全第一的文件操作、持久内存管理和全面的工具。
## 🌟 功能特点
- **安全优先操作**
- 在所有破坏性操作（删除/移动/重命名/备份）之前强制执行`dry_run`
- `读前写`策略防止意外数据丢失
- 具有结构化响应模式的自动错误处理
- **全面的工具集** （5个路由器，30+工具）
- `文件操作`：移动、复制、读取、打开、列表、比较、查找项目
- `目录操作`：创建文件夹、删除文件/文件夹、重命名、备份、安全删除、复制文件夹
- `实用操作`：压缩、解压、文件哈希（SHA256）、清理临时文件
- `数据操作`：读写JSON、写文件、CSV预览/统计/按日期筛选、搜索文本
- `系统操作`：获取时间、解析日期时间
- **代码执行工具**
- `python_eval()`：带有捕获输出和变量的安全单行Python表达式
- `python_exec()`：带有序列化结果过滤的多行代码块
- `shell()`：用于快速查询的系统shell命令执行
- **持久内存协议**
- 通过`memory.json`知识库跨会话学习
- 新任务前`列表`（检查过去的课程）
- 解决方案/错误修复后`添加`（<20字摘要限制）
- **便携设计**
- 所有路径相对于脚本位置（`BASE_DIR`）
- 没有硬编码的绝对路径
- 跨操作系统环境工作
- **错误恢复**
- 清晰的错误消息和重试指导
- 操作前路径验证
- 故障时优雅降级
## 📁 项目结构
```
lm-studio-mcp-server/
├── mcp_server.py # 主要基于路由器的MCP服务器（文件操作、目录操作等）
├── git_mcp_server.py # Git集成工具
├── mcp_file_organizer.py # 文件组织实用程序
├── mcp_webscraper.py # 通过SearXNG进行网络搜索和当前时间
├── config/
│ ├── mcp.json # LM工作室MCP服务器配置
│ └── AgentTools.preset.json # 基于路由器的工具系统提示
├── MIT-LICENSE.txt # 许可证和署名
├── README.md # 此文件
├── .gitignore # Git忽略模式
├── requirements.txt # Python依赖项
└── pyproject.toml # 项目配置/包
```
## 🚀 安装
### 1. 克隆仓库
```bash
cd D:\Scripts\lm-studio-mcp-server
python -m venv venv
venv\Scripts\activate
# 选项1：requirements.txt
pip install -r requirements.txt
# 选项2：pyproject.toml（不要同时使用选项1和选项2）
pip install .
```
### 2. 配置LM工作室MCP服务器
将所有服务器添加到`.user/.lmstudio/mcp.json`：
```json
{
"mcpServers": {
// 主要基于路由器的服务器（必需）
"本地实用程序MCP": {
"command": "D:\Scripts\lm-studio-mcp-server\venv\Scripts\python.exe",
"args": [
"D:\Scripts\lm-studio-mcp-server\mcp_server.py"
],
"env": {"PYTHONUNBUFFERED": "1"},
"timeout": 180000
},
// 可选：通过SearXNG进行网络搜索和当前时间（需要SearXNG在localhost:8080）
"网络浏览器MCP": {
"command": "D:\Scripts\lm-studio-mcp-server\venv\Scripts\python.exe",
"args": ["D:\Scripts\lm-studio-mcp-server\mcp_webscraper.py"],
"env": {"PYTHONUNBUFFERED": "1"}
},
// 可选：Git集成工具
"Git MCP": {
"command": "D:\Scripts\lm-studio-mcp-server\venv\Scripts\python.exe",
"args": ["D:\Scripts\lm-studio-mcp-server\git_mcp_server.py"],
"env": {"PYTHONUNBUFFERED": "1"}
}
}
}
```
### 3. 设置系统提示
复制`config/AgentTools.preset.json`内容到LM工作室的系统提示字段，或手动粘贴基于路由器的工具文档。
## ⚙️ 配置
### 内存路径（默认）
默认情况下，内存存储在脚本位置的相对路径：
```
{project_root}/memory.json → D:\Scripts\lm-studio-mcp-server\memory.json
```
不需要环境变量 - 路径始终是相对的！
### 备份根目录（可选）
对于`dir_op`备份操作，备份默认存储在此：
```
{project_root}/backups/ → D:\Scripts\lm-studio-mcp-server\backups
```
## 🛠️ 使用示例
### 示例1：具有安全性的文件操作
```python
# 递归查找所有Python文件
universal_router(
router="文件操作",
action="查找项目",
params={
"路径": ["D:\Projects"],
"模式": "*.py",
"最大结果": 10,
"递归": True,
"包含文件": True,
"包含文件夹": False
}
)
# 移动文件（建议先使用dry_run=True）
universal_router(
router="文件操作",
action="移动",
params={
"源": ["D:\Projects\old_file.py"],
"目标": "D:\Archived"
}
)
```
### 示例2：内存协议（跨会话学习）
**在开始新任务前检查现有课程：**
```python
manage_memory(action="列表")
# 输出显示所有已学习的类似任务的课程
```
**在完成复杂操作后保存课程：**
```python
manage_memory(
action="添加",
topic="csv-date-filtering-2025",
summary="使用ISO日期格式进行csv_filter_by_date，并使用正确的列名"
)
```
### 示例3：CSV数据处理
```python
# 预览CSV的前10行
universal_router(
router="数据操作",
action="读取CSV预览",
params={
"路径": ["D:\Data\sales.csv"],
"n": 10
}
)
# 按日期范围筛选（ISO格式：YYYY-MM-DD）
universal_router(
router="数据操作",
action="按日期筛选CSV",
params={
"路径": ["D:\Data\sales.csv"],
"日期列": "sale_date",
"开始": "2024-01-01",
"结束": "2024-12-31"
}
)
```
### 示例4：文件比较和备份
```python
# 比较文件的两个版本
universal_router(
router="文件操作",
action="比较",
params={
"文件1": ["D:\Projects\code.py"],
"文件2": ["D:\Backups\code_backup.py"]
}
)
# 备份重要文件并进行SHA256哈希验证
universal_router(
router="目录操作",
action="备份",
params={
"名称": "*.py",
"备份根目录": "D:\Backups"
}
)
```
### 示例5：写入文件操作
```python
# 写入单个文件
universal_router(
router="数据操作",
action="写入文件",
params={
"路径": ["D:\Projects\output.txt"],
"内容": "Hello, World! 这是写入的内容。"
}
)
# 写入多个文件并匹配内容列表
universal_router(
router="数据操作",
action="写入文件",
params={
"路径": ["file1.txt", "file2.txt"],
"内容": ["文件1的内容", "文件2的内容"]
}
)
# 直接Python用法（在适当的管理上下文中安全）
with open("D:\Projects\output.txt", "w") as f:
f.write("直接写入示例")
```
## 🌐 网络搜索工具（独立）
网络搜索工具是一个独立的服务器，独立于主路由器系统运行。它需要SearXNG在`http://localhost:8080/search`运行。
**用法：**
```python
# 直接调用独立服务器
search_web(
查询="最新的AI新闻",
详细程度="简要",
最大结果=5,
语言="zh"
)
current_time() # 返回ISO日期时间字符串
```
**注意：** 不要为网络搜索使用`universal_router()` - 它作为单独的FastMCP实例运行。在LM工作室中配置时，请直接使用工具名称。
## 📋 核心规则（始终遵循）
1. **先阅读**：在修改任何文件之前，使用`文件操作：读取`验证内容
2. **规范名称**：使用确切的路由器/操作名称 - 变化会导致错误
3. **安全第一**：在所有破坏性操作之前设置`dry_run=True`
4. **不重新格式化**：工具输出是权威数据 - 除非请求，否则不要重新格式化
5. **增量更改**：进行小的、专注的更新，保留现有的逻辑
## ⚠️ 常见错误和解决方案
| 错误 | 解决方案 |
|---------|----------|
| `文件操作:删除文件(路径="*.py")` | 在删除单个路径之前，先使用`查找项目` |
| 在删除前缺少`dry_run=True` | 始终先使用`列表()`或预览结果 |
| CSV日期格式不匹配 | 检查`csv_stats()`列名；使用ISO日期（YYYY-MM-DD） |
| 硬编码绝对路径 | 使用脚本位置的相对路径（`BASE_DIR`） |
## 🔐 错误处理策略
- **路由器错误**：验证路由器名称是以下之一：`文件操作`、`目录操作`、`实用操作`、`数据操作`、`系统操作`
- **文件未找到**：在尝试读取/写入之前，使用`列表()`确认路径存在
- **权限错误**：检查目录权限并尝试使用`dry_run`进行验证
## 🧠 内存协议（管理课程）
### 何时调用`manage_memory: list`
- 新任务启动
- 在复杂的多步骤操作之前
- 引用技术设置/偏好时
### 何时调用`manage_memory: add`
- 解决错误或棘手的问题后
- 发现用户偏好/工作流程后
- 完成重要的功能实现后
### 摘要限制
每篇课程摘要最多20个字。关注可行的要点，而不是对话细节。
## 📄 许可证
该项目在[MIT License](MIT-LICENSE.txt)下获得许可。
### 署名
安全优先的MCP工具设计模式（读前写、dry_run强制执行、内存协议）由[@Pazran](https://github.com/Pazran)开发。如果您在自己的项目中重用或改编任何工具，请务必注明此作品。
## 🤝 贡献
这是生产就绪的参考实现。潜在的增强领域：
- 根据操作过程中发现的用例添加路由器操作
- 增强的错误恢复模式
- 扩展的内存协议功能
---
**注意**：该项目使用Python 3.9+开发。始终先使用`dry_run=True`测试破坏性操作。网络搜索工具需要localhost:8080上的SearXNG。
