Cursor Local LLM MCP Proxy

增强型本地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 取而代之的是块。这是意料之中的。

🔄 架构和工作流程

%%{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 -使用代理功能生成文本
2. chat_completion -通过工具集成完成聊天
3. rag_query -使用RAG查询索引文档
4. index_document -RAG查询的索引文档
5. save_rag_storage -手动将RAG文档保存到磁盘
6. clear_rag_storage -清除所有持久RAG存储
7. rag_storage_status -获取RAG存储状态和持久性信息
8. sonar_query -困惑声纳API实时信息采集
9. delegate_to_local_llm -将请求委托给本地LLM编排器
10. orchestrator_status -获取编排器状态和连接的工具
11. list_orchestrated_tools -列出所有可用的编排工具
12. 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. 克隆存储库：

git clone https://github.com/Davz33/Cursor-Local-llm-MCP-proxy
cd local-llm-proxy

1. 安装依赖项：

npm install

1. 构建TypeScript项目：

npm run build

1. （可选）引导Pixi环境进行DeepEval测试：

# install Pixi if you don't already have it: https://pixi.sh/latest/
pixi install

⚠️ 重要提示： 您必须先构建项目，然后才能将其与Cursor等MCP客户端一起使用。

🚀 用法

1.启动LM Studio

1. 下载并安装 LM 工作室
2. 加载您喜欢的型号（例如Qwen3、Llama等）
3. 启动服务器 http://localhost:1234/v1

2.配置环境（可选）

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):

{
  "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 并复制其内容。
2. 在LM Studio中：

- 通过UI将提示粘贴到活动预设中，或 - 编辑 ~/.lmstudio/config-presets/.json 并更新 operation.fields.value 使用提示文本。

1. 在LM Studio中重新启动预设，以便在运行评估之前拾取提示。

5.启动MCP服务器

生产：

npm start

开发（带热重新加载）：

npm run dev

构建TypeScript：

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

规则组合

编排器会自动组合两个规则集：

1. 从存储库加载一般规则
2. 从用户目录（如果存在）加载个人规则
3. 将它们结合起来以实现全面的编排行为
4. 如果任一文件丢失，则优雅地回退

📋 API示例

基本文本生成

{
  "name": "generate_text_v2",
  "arguments": {
    "prompt": "Explain quantum computing in simple terms",
    "use_agentic": true,
    "max_tokens": 500,
    "temperature": 0.7
  }
}

聊天补全

{
  "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文档索引

{
  "name": "index_document",
  "arguments": {
    "file_path": "/path/to/document.txt"
  }
}

或者直接索引文本内容：

{
  "name": "index_document",
  "arguments": {
    "text_content": "Your text content to index for RAG queries"
  }
}

RAG查询

{
  "name": "rag_query",
  "arguments": {
    "query": "What are the main concepts discussed?",
    "max_tokens": 300
  }
}

RAG存储管理

{
  "name": "save_rag_storage",
  "arguments": {}
}

{
  "name": "rag_storage_status",
  "arguments": {}
}

{
  "name": "clear_rag_storage",
  "arguments": {}
}

🧪 测试

服务器包括全面的测试功能：

# 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检查以确保工具调用行为保持稳定：

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客户端中配置后，您可以测试这些工具：

1. 生成文本： 使用 mcp_local-llm-proxy_generate_text_v2 在IDE中
2. 聊天完成： 使用 mcp_local-llm-proxy_chat_completion
3. RAG查询： 使用 mcp_local-llm-proxy_rag_query
4. 索引文件： 使用 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交互
• 模块化工具：具有完全类型安全的可扩展工具架构

工具架构

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工作流程

1. 文献检索：文档被处理并存储在矢量索引中
2. 自动持久化：文档在索引后会自动保存到磁盘
3. 查询处理：自然语言查询转换为向量搜索
4. 上下文检索：检索相关文档块
5. 响应生成：LLM使用检索到的上下文生成响应
6. 消息来源：响应包括源文档信息
7. 跨会话持久性：文档在Cursor重新启动和服务器重新启动时仍然存在

🚨 故障排除

常见问题

1. 连接被拒绝：确保LM Studio服务器正在上运行 http://localhost:1234/v1
2. 未找到型号：验证LM Studio中的模型名称是否与您的配置匹配
3. 端口冲突：如果需要，更改LM Studio端口并更新配置
4. 内存问题：减小模型大小或增加系统内存
5. 未找到工具：确保您已使用以下工具构建了项目 npm run build
6. MCP客户端问题：配置更改后重新启动MCP客户端（游标）

调试模式

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. 克隆和设置：

   git clone https://github.com/Davz33/Cursor-Local-llm-MCP-proxy
   cd local-llm-proxy
   npm install
   npm run build

1. 启动LM工作室：

- 下载并安装 LM 工作室 - 加载模型（例如Qwen3、Llama） - 启动服务器 http://localhost:1234/v1

1. 配置光标：

- 将MCP配置添加到您的 mcp.json - 更新路径以指向您的 dist/index.js - 重新启动游标

1. 测试：

- 使用 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，然后再次查询-您的文档将保留！