增强型本地LLM代理MCP服务器
基于TypeScript的MCP(模型上下文协议)服务器,通过代理行为、检索增强响应和动态工具集成来增强本地LLM功能。
此服务器与Cursor和类似的IDE兼容,支持类似于Cursor的MCP客户端定义 mcp.json服务器的目标是减轻Cursor(和类似系统)中更强大的基于云的LLM的负载(和预算),并将其用于对本地提示的LLM进行验证和/或回退系统。
该项目的目标和当前的最小功能还旨在为您的LM studio本地代理配备RAG、内存图和工作区自动化等代理工具,从而进一步提高本地提供的答案的准确性,降低与更昂贵的云原生模型交互的可能性。
> 兼容性说明: 当前的工具调用堆栈已在LM Studio中使用 openai/gpt-oss-120b, qwen2.5-coder-32b-instruct,以及 qwen3-coder-32b-instruct其他型号可能需要提示或温度调整。
> LM Studio日志记录: 由于我们手动格式化工具调用,LM Studio JSON日志显示为空 tool_calls 阵列;序列化的工具请求嵌入到助手中 content 取而代之的是块。这是意料之中的。
🔄 架构和工作流程```mermaid
%%{init: {"flowchart": {"curve": "basis"}} }%%
flowchart TB
subgraph User_IDE_Layer [User & IDE Layer]
User([User]) --> Cursor([Cursor IDE])
Cursor --> MCPClient([MCP Client])
end
subgraph MCP_Layer [MCP Communication Layer]
MCPClient --> MCPServer([Local LLM Proxy MCP Server])
end
subgraph Services [Agentic & Retrieval Services]
MCPServer --> AgenticService([Agentic Service])
MCPServer --> RetrievalService([Retrieval Service])
AgenticService --> FileSystemTool([File System Tool])
AgenticService --> RetrievalTool([Retrieval Tool])
AgenticService --> SonarTool([Web Search Tool])
RetrievalService --> VectorIndex([Vector Store])
RetrievalService --> DocumentStorage([Document Storage])
DocumentStorage --> DiskStorage[(Persistent Storage)]
end
subgraph LM_Studio [LM Studio Integration]
AgenticService --> LLMConfig([LLM Configuration])
RetrievalService --> LLMConfig
LLMConfig --> LMStudio([LM Studio Server])
LMStudio --> LocalModel([Local LLM Model])
end
subgraph Embeddings [Embedding Integration]
RetrievalService --> EmbeddingModel([Embedding Model])
end
subgraph External_APIs [External API Integration]
SonarTool --> SonarAPI([Perplexity Sonar API])
SonarAPI --> RealTimeData([Real-time Information])
end
User -.->|"1. Query"| Cursor
Cursor -.->|"2. MCP Protocol"| MCPClient
MCPClient -.->|"3. Tool Call"| MCPServer
MCPServer -.->|"4a. Agentic Processing"| AgenticService
MCPServer -.->|"4b. Retrieval Query"| RetrievalService
AgenticService -.->|"5a. Tool Selection"| FileSystemTool
AgenticService -.->|"5b. Tool Selection"| RetrievalTool
AgenticService -.->|"5c. Web Search"| SonarTool
RetrievalService -.->|"6a. Document Indexing"| VectorIndex
RetrievalService -.->|"6b. Auto-Save"| DocumentStorage
DocumentStorage -.->|"7. Persist to Disk"| DiskStorage
VectorIndex -.->|"8. Query Processing"| EmbeddingModel
EmbeddingModel -.->|"9. Vector Search"| VectorIndex
SonarTool -.->|"10. API Request"| SonarAPI
SonarAPI -.->|"11. Real-time Search"| RealTimeData
RealTimeData -.->|"12. Search Results"| SonarAPI
SonarAPI -.->|"13. API Response"| SonarTool
AgenticService -.->|"14. LLM Generation"| LLMConfig
RetrievalService -.->|"15. LLM Generation"| LLMConfig
LLMConfig -.->|"16. API Call"| LMStudio
LMStudio -.->|"17. Model Inference"| LocalModel
LocalModel -.->|"18. Response"| LMStudio
LMStudio -.->|"19. API Response"| LLMConfig
LLMConfig -.->|"20. Processed Response"| AgenticService
LLMConfig -.->|"21. Processed Response"| RetrievalService
AgenticService -.->|"22. Final Response"| MCPServer
RetrievalService -.->|"23. Final Response"| MCPServer
SonarTool -.->|"24. Final Response"| MCPServer
MCPServer -.->|"25. MCP Response"| MCPClient
MCPClient -.->|"26. Display Result"| Cursor
Cursor -.->|"27. Show to User"| User
DiskStorage -.->|"28. Load on Startup"| DocumentStorage
DocumentStorage -.->|"29. Recreate Index"| VectorIndex
## 🚀 特性
### 🧠 代理能力
- **文件系统工具**:读取、写入和列出文件和目录
- **RAG系统**:使用自然语言进行文档索引和查询
### 🔍 RAG(检索增强生成)
- 从文件中索引文档或直接输入文本
- 使用自然语言查询索引文档
- 回复的来源归因
- 跨游标重新启动的持久文档存储
- 服务器启动时自动加载文档
- 具有可配置存储路径的基于文件的持久性
### 🎯 MCP编排器
- **工具发现**:自动发现并连接到其他MCP服务器
- **智能刀具选择**:使用基于规则的逻辑为查询选择合适的工具
- **Web搜索优先级**:自动将web搜索查询路由到Sonar API
- **双重规则体系**:将一般功能规则与个人偏好分开
- **回退通信**:为游标回退提供有针对性的错误报告
- **上下文感知处理**:在工具执行之前从多个MCP服务器收集上下文
- **验证和质量控制**:确保响应质量和准确性
### 🛠 可用的MCP工具
1. `generate_text_v2` -使用代理功能生成文本
1. `chat_completion` -通过工具集成完成聊天
1. `rag_query` -使用RAG查询索引文档
1. `index_document` -RAG查询的索引文档
1. `save_rag_storage` -手动将RAG文档保存到磁盘
1. `clear_rag_storage` -清除所有持久RAG存储
1. `rag_storage_status` -获取RAG存储状态和持久性信息
1. `sonar_query` -困惑声纳API实时信息采集
1. `delegate_to_local_llm` -将请求委托给本地LLM编排器
1. `orchestrator_status` -获取编排器状态和连接的工具
1. `list_orchestrated_tools` -列出所有可用的编排工具
1. `call_orchestrated_tool` -直接调用特定的编排工具
### 🌐 LM工作室集成
- 与OpenAI兼容的API集成
- 支持Quen3和其他本地型号
- 可配置的基本URL和型号选择
- 环境变量配置
### 🎯 MCP编排器
- **工具发现**:自动发现并连接到其他MCP服务器
- **智能路由**:根据内容分析将查询路由到适当的工具
- **Web搜索集成**:优先考虑使用Sonar API进行实时信息收集
- **后备系统**:需要时优雅地回退到Cursor
- **基于规则的选择**:工具选择和使用的可配置规则
### 🔄 智能验证与回退系统
- **基于启发式的验证** 用于响应质量评估
- **自动回退** 当本地响应不足时,将LLM云化
- **智能工具选择** 具有增强的顺序思维整合
- **实时验证** 检查错误、无法表达和响应完整性
- **可配置阈值** 用于信心评分和回退触发
### 📋 配置和规则
- **光标委派规则**:参见 CURSOR_DELEGATION_RULES.md IDE集成指南
- **委托实施指南**:参见 授权_实施\_ GIDE.md 完成系统设置
- **MCP编排器规则**:参见 mcp-orchestrator-rules.example.json 用于服务器端规则配置
- **可定制的规则引擎** 用于工具使用策略和验证行为
- **基于环境的配置** 存在合理的违约
## 📦 安装
### 先决条件
- Node.js 18+
- LM Studio已安装并正在运行
- Git(用于克隆存储库)
### 设置
1. **克隆存储库:**```bash
git clone https://github.com/Davz33/Cursor-Local-llm-MCP-proxy
cd local-llm-proxy
- 安装依赖项:```bash
npm install
3. **构建TypeScript项目:**```bash
npm run build
- (可选)引导Pixi环境进行DeepEval测试:```bash
install Pixi if you don't already have it: https://pixi.sh/latest/
pixi install
**⚠️ 重要提示:** 您必须先构建项目,然后才能将其与Cursor等MCP客户端一起使用。
## 🚀 用法
### 1.启动LM Studio
1. 下载并安装 LM 工作室
1. 加载您喜欢的型号(例如Qwen3、Llama等)
1. 启动服务器 `http://localhost:1234/v1`
### 2.配置环境(可选)```bash
export LM_STUDIO_BASE_URL="http://localhost:1234/v1"
export LM_STUDIO_MODEL="qwen3-coder-30b-a3b-instruct"
3.配置MCP客户端(游标/IDE)
将以下配置添加到MCP客户端(例如,Cursor的 mcp.json):```json
{
"mcpServers": {
"local-llm-proxy": {
"command": "node",
"args": ["/path/to/your/local-llm-proxy/dist/index.js"],
"env": {
"LM_STUDIO_BASE_URL": "http://localhost:1234/v1",
"LM_STUDIO_MODEL": "qwen3-coder-30b-a3b-instruct"
}
}
}
}
**替换 `/path/to/your/local-llm-proxy` 使用克隆存储库的实际路径。**
### 4.在LM Studio中安装系统提示
1. 打开文件 `prompts/agentic-system-prompt.md` 并复制其内容。
1. 在LM Studio中:
- 通过UI将提示粘贴到活动预设中,或
- 编辑 `~/.lmstudio/config-presets/.json` 并更新 `operation.fields.value` 使用提示文本。
1. 在LM Studio中重新启动预设,以便在运行评估之前拾取提示。
### 5.启动MCP服务器
**生产:**```bash
npm start
开发(带热重新加载):```bash
npm run dev
**构建TypeScript:**```bash
npm run build
注: 当您的MCP客户端(如Cursor)调用时,MCP服务器会自动运行。在大多数情况下,您不需要手动启动它。
🔧 配置
可以使用环境变量配置服务器:
LM_STUDIO_BASE_URL:LM Studio API终结点(默认值:http://localhost:1234/v1)LM_STUDIO_MODEL:LM Studio中的型号名称(默认值:qwen3)
使用Sonar API实时信息
对于实时信息收集功能,服务器包括困惑声纳API集成。看 SONAR_INTEGRAT_README.md 有关详细的设置说明,包括:
- API密钥配置
- 环境变量设置
- 使用示例
- 成本因素
编排规则系统
MCP编排器使用双重规则系统将一般功能与个人偏好分开:
一般规则(跟踪存储库)
- 位置:
src/orchestrator/general-orchestration-rules.txt - 目的:核心MCP服务器功能和工具编排逻辑
- 内容:工具选择、错误处理、网络搜索模式、记忆操作、思维操作
- 维护:版本控制并在所有用户之间共享
个人规则(用户特定)
- 位置:
$HOME/local-llm-proxy/personal-orchestration-rules.txt - 目的:主观偏好和个人工作流程规则
- 内容:Git偏好、编码风格、开发工作流程、个人上下文偏好
- 维护:用户特定和可定制
环境变量
MCP_PERSONAL_RULES_PATH:个人规则的自定义路径(可选)- 默认个人规则位置:
$HOME/local-llm-proxy/personal-orchestration-rules.txt
规则组合
编排器会自动组合两个规则集:
- 从存储库加载一般规则
- 从用户目录(如果存在)加载个人规则
- 将它们结合起来以实现全面的编排行为
- 如果任一文件丢失,则优雅地回退
📋 API示例
基本文本生成```json
{
"name": "generate_text_v2",
"arguments": {
"prompt": "Explain quantum computing in simple terms",
"use_agentic": true,
"max_tokens": 500,
"temperature": 0.7
}
}
### 聊天补全```json
{
"name": "chat_completion",
"arguments": {
"messages": [
{"role": "user", "content": "Can you help me calculate the area of a circle with radius 5?"}
],
"use_agentic": true,
"max_tokens": 300
}
}
RAG文档索引```json
{
"name": "index_document",
"arguments": {
"file_path": "/path/to/document.txt"
}
}
**或者直接索引文本内容:**```json
{
"name": "index_document",
"arguments": {
"text_content": "Your text content to index for RAG queries"
}
}
RAG查询```json
{
"name": "rag_query",
"arguments": {
"query": "What are the main concepts discussed?",
"max_tokens": 300
}
}
### RAG存储管理```json
{
"name": "save_rag_storage",
"arguments": {}
}
``````json
{
"name": "rag_storage_status",
"arguments": {}
}
``````json
{
"name": "clear_rag_storage",
"arguments": {}
}
🧪 测试
服务器包括全面的测试功能:```bash
Build the project first
npm run build
Test basic functionality
npm start
Test with validation enabled
npm run start:with-validation
Development mode with hot reload
npm run dev
### DeepEval工具调用回归
运行自动DeepEval检查以确保工具调用行为保持稳定:```bash
npm run build
pixi install # one-time environment bootstrap
pixi run evaluate-tool-calling
# alternatively, if you already activated Pixi:
python deepeval/evaluate_tool_calling.py
测试MCP工具
在MCP客户端中配置后,您可以测试这些工具:
- 生成文本: 使用
mcp_local-llm-proxy_generate_text_v2在IDE中 - 聊天完成: 使用
mcp_local-llm-proxy_chat_completion - RAG查询: 使用
mcp_local-llm-proxy_rag_query - 索引文件: 使用
mcp_local-llm-proxy_index_document
🏗 建筑
模块化结构```
src/
├── config/
│ └── llm-config.ts # LLM and embedding model configuration
├── rag/
│ └── rag-service.ts # RAG functionality and document indexing
├── agentic/
│ └── agentic-service.ts # Agentic LLM interactions with tools
├── tools/
│ └── agentic-tools.ts # Tool definitions (filesystem, RAG)
└── mcp/
└── mcp-server.ts # MCP server implementation
### 核心组件
- **MCP服务器**:基于TypeScript的模型上下文协议通信
- **检索引擎**:嵌入具有确定性存储的动态文档索引
- **LM工作室适配器**:与OpenAI兼容的API集成
- **RAG服务**:使用HuggingFace嵌入进行文档索引和查询
- **代理服务**:工具集成LLM交互
- **模块化工具**:具有完全类型安全的可扩展工具架构
### 工具架构```typescript
interface Tool {
name: string;
description: string;
execute: (params: any, context?: ToolExecutionContext) => Promise;
}
const tool: Tool = {
name: "tool_name",
description: "Tool description",
execute: async (params, context) => {
// Tool implementation with full type safety
}
};
🔍 RAG工作流程
- 文献检索:文档被处理并存储在矢量索引中
- 自动持久化:文档在索引后会自动保存到磁盘
- 查询处理:自然语言查询转换为向量搜索
- 上下文检索:检索相关文档块
- 响应生成:LLM使用检索到的上下文生成响应
- 消息来源:响应包括源文档信息
- 跨会话持久性:文档在Cursor重新启动和服务器重新启动时仍然存在
🚨 故障排除
常见问题
- 连接被拒绝:确保LM Studio服务器正在上运行
http://localhost:1234/v1 - 未找到型号:验证LM Studio中的模型名称是否与您的配置匹配
- 端口冲突:如果需要,更改LM Studio端口并更新配置
- 内存问题:减小模型大小或增加系统内存
- 未找到工具:确保您已使用以下工具构建了项目
npm run build - MCP客户端问题:配置更改后重新启动MCP客户端(游标)
调试模式```bash
DEBUG=* npm start
### MCP配置问题
- **工具磨坏了**:这通常表示缓存问题。尝试:
1. 在Cursor中禁用并重新启用MCP集成
1. 完全重新启动游标
1. 检查路径是否正确 `mcp.json` 指向 `dist/index.js`
## 📈 性能提示
- 使用量化模型以获得更好的性能
- 调整 `max_tokens` 根据您的需求
- 启用长响应的流媒体
- 使用RAG进行大量文档查询
- 监控大型文档的内存使用情况
## 🔮 未来的增强功能
- \[\]具有切换功能的多代理工作流
- \[\]具有实时更新功能的高级流媒体
- \[x\] **跨会话的持久文档存储** ✅
- \[\]自定义工具开发框架
- \[\]性能监控和指标
- \[\]与更多LLM提供商集成
## 📄 许可证
GPL 3.0许可证-详见复制文件
## 🤝 贡献
欢迎投稿!请随时提交问题和拉取请求。
## 📞 支持
有关支持和问题:
- 在存储库中创建问题
- 检查故障排除部分
- 查看LM Studio配置指南
## 📝 快速入门指南
1. **克隆和设置:**```bash
git clone https://github.com/Davz33/Cursor-Local-llm-MCP-proxy
cd local-llm-proxy
npm install
npm run build
- 启动LM工作室:
- 下载并安装 LM 工作室
- 加载模型(例如Qwen3、Llama)
- 启动服务器
http://localhost:1234/v1
- 配置光标:
- 将MCP配置添加到您的
mcp.json - 更新路径以指向您的
dist/index.js - 重新启动游标
- 测试:
- 使用
mcp_local-llm-proxy_generate_text_v2在游标中 - 尝试
mcp_local-llm-proxy_chat_completion具有代理能力 - 索引文档
mcp_local-llm-proxy_index_document - 查询方式
mcp_local-llm-proxy_rag_query - 测试持久性:索引文档,重新启动Cursor,然后再次查询-您的文档将保留!
