技术文档摘要

LocaLLama MCP Server (测试分支)

LocaLLama MCP Server 是一个与 Roo Code 或 Cline.Bot（目前尚未测试与 Claude Desktop 或 CoPilot MCP VS Code 扩展的兼容性）配合使用的服务器，通过智能地在本地大语言模型（LLM）和付费 API 之间分配编码任务来优化成本。此版本中存在许多实现问题。

概述

LocalLama MCP Server 设计用于通过动态决定是将编码任务卸载到本地能力较弱的指令 LLM（例如，LM Studio、Ollama）还是使用付费 API 来减少令牌使用量和成本。版本 1.7.0 引入了智能代码任务分析、高级依赖关系映射和智能任务分解功能。

关键组件

成本及令牌监控模块

• 查询当前 API 服务以获取上下文使用情况、累计成本、API 令牌价格和可用信用额度
• 收集实时数据以供决策引擎参考
• 实现智能代码模式识别和语义搜索以优化令牌使用
• 提供上下文感知的代码建议以减少冗余并提高效率
• 新增基于模式的缓存功能，可减少复杂任务中的令牌使用量约 30%

决策引擎

• 定义规则以比较使用付费 API 的成本与卸载到本地 LLM 的成本（以及潜在的质量权衡）
• 包含可配置的阈值，以确定何时进行卸载
• 使用基于基准数据的预判路由以更快地做出决策而无需调用 API
• 新增自适应模型选择系统，并带有性能历史跟踪
• 增强代码任务分解功能，带有复杂度分析
• 新功能：智能任务依赖关系映射，带有关键路径分析
• 新功能：代码复杂度评估系统，带有技术和领域知识评估
• 新功能：执行顺序优化，支持并行任务处理

API 集成及可配置性

• 提供配置界面，允许用户指定本地实例的端点（例如，LM Studio、Ollama）
• 使用标准化的 API 调用来与这些端点交互
• 集成 OpenRouter 以访问来自不同提供商的免费和付费模型
• 包含健壮的目录处理和缓存机制以确保可靠运行
• 新增基于 BM25 的语义代码搜索集成

备用方案及错误处理

• 在付费 API 数据不可用或本地服务失败时实施备用方案
• 包含健壮的日志记录和错误处理策略

基准测试系统

• 对比本地 LLM 模型与付费 API 模型的性能
• 测量响应时间、成功率、质量评分和令牌使用量
• 生成详细报告以供分析和决策
• 包含新的工具，用于基准测试免费模型并更新提示策略

服务器锁定机制

• 防止多个服务器实例同时运行
• 自动检测并清理因进程崩溃而遗留的锁文件
• 将连接信息存储在锁文件中以方便诊断
• 验证现有锁文件中的进程是否仍在运行
• 当尝试启动第二个实例时提供清晰的错误消息

工具

以下工具可在 LocalLama MCP Server 中使用：

• route_task：根据成本和复杂度将编码任务路由到本地 LLM 或付费 API。
  • 输入参数：task，context_length，expected_output_length，complexity，priority，preemptive
• retriv_init：初始化并配置 Retriv 以进行代码搜索和索引。
  • 输入参数：directories，exclude_patterns，chunk_size，force_reindex，bm25_options，install_dependencies
• cancel_job：取消正在运行的任务。
  • 输入参数：job_id
• preemptive_route_task：快速路由编码任务而不调用 API（更快但准确性较低）。
  • 输入参数：task，context_length，expected_output_length，complexity，priority
• get_cost_estimate：获取任务的成本估算。
  • 输入参数：context_length，expected_output_length，model
• benchmark_task：对特定任务进行本地 LLM 和付费 API 的性能基准测试。
  • 输入参数：task_id，task，context_length，expected_output_length，complexity，local_model，paid_model，runs_per_task
• benchmark_tasks：对多个任务进行本地 LLM 和付费 API 的性能基准测试。
  • 输入参数：tasks，runs_per_task，parallel，max_parallel_tasks

以下工具仅在安装了 Python 和 retriv 模块时可用：

• retriv_search：使用 Retriv 搜索引擎搜索代码。
  • 输入参数：query，limit

以下工具仅在配置了 OpenRouter API 密钥时可用：

• get_free_models：获取 OpenRouter 可用的免费模型列表。
  • 输入参数：无
• clear_openrouter_tracking：清除 OpenRouter 跟踪数据并强制更新。
  • 输入参数：无
• benchmark_free_models：对 OpenRouter 的免费模型进行性能基准测试。
  • 输入参数：tasks，runs_per_task，parallel，max_parallel_tasks
• set_model_prompting_strategy：更新 OpenRouter 模型的提示策略。
  • 输入参数：task，context_length，expected_output_length，priority，complexity，preemptive

资源

以下资源可在 LocalLama MCP Server 中使用：

静态资源：

• locallama://status：LocalLama MCP Server 的当前状态。
• locallama://models：可用的本地 LLM 模型列表。
• locallama://jobs/active：当前活跃的任务列表。
• locallama://memory-bank：内存银行目录中的文件列表（仅在存在 memory-bank 目录时可用）。
• locallama://openrouter/models：OpenRouter 可用的模型列表（仅在配置了 OpenRouter API 密钥时可用）。
• locallama://openrouter/free-models：OpenRouter 可用的免费模型列表（仅在配置了 OpenRouter API 密钥时可用）。
• locallama://openrouter/status：OpenRouter 集成的状态（仅在配置了 OpenRouter API 密钥时可用）。

资源模板：

• locallama://usage/{api}：特定 API 的令牌使用量和成本统计。
• locallama://jobs/progress/{jobId}：特定任务的进度信息。
• locallama://openrouter/model/{modelId}：特定 OpenRouter 模型的详细信息（仅在配置了 OpenRouter API 密钥时可用）。
• locallama://openrouter/prompting-strategy/{modelId}：特定 OpenRouter 模型的提示策略（仅在配置了 OpenRouter API 密钥时可用）。

安装

# 克隆仓库
git clone https://github.com/yourusername/locallama-mcp.git
cd locallama-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 安装 Retriv 依赖（如果要使用 Retriv）
pip install retriv>=0.3.1 numpy>=1.22.0 scikit-learn>=1.0.2 scipy>=1.8.0

Python 环境设置（代码搜索）

代码搜索功能使用 Retriv，这是一个基于 Python 的语义搜索引擎。要使用此功能：

1. 安装 Python：确保系统上已安装 Python 3.8+。
2. 创建虚拟环境（推荐）：

   # 对于 Linux/macOS：
   python3 -m venv venv
   source venv/bin/activate
   
   # 对于 Windows：
   python -m venv venv
   venv\Scripts\activate
   

3. 安装 Retriv 和依赖项：

   pip install retriv>=0.3.1 numpy>=1.22.0 scikit-learn>=1.0.2 scipy>=1.8.0
   

4. 配置服务器以使用您的虚拟环境： 在 .env 文件中添加以下内容：

   # Python 配置
   PYTHON_PATH=./venv/bin/python  # 对于 Linux/macOS
   # PYTHON_PATH=./venv/Scripts/python.exe  # 对于 Windows
   PYTHON_DETECT_VENV=true
   

注意：您也可以让服务器自动安装 Retriv，方法是在使用 retriv_init 工具时将 install_dependencies 设置为 true。

配置

复制 .env.example 文件以创建自己的 .env 文件：

cp .env.example .env

然后编辑 .env 文件以包含您的特定配置：

# 本地 LLM 端点
LM_STUDIO_ENDPOINT=http://localhost:1234/v1
OLLAMA_ENDPOINT=http://localhost:11434/api

# 配置
DEFAULT_LOCAL_MODEL=qwen2.5-coder-3b-instruct
TOKEN_THRESHOLD=1500
COST_THRESHOLD=0.02
QUALITY_THRESHOLD=0.7

# 代码搜索配置
CODE_SEARCH_ENABLED=true
CODE_SEARCH_EXCLUDE_PATTERNS=["node_modules/**","dist/**",".git/**"]
CODE_SEARCH_INDEX_ON_START=true
CODE_SEARCH_REINDEX_INTERVAL=3600

# 代码任务分析配置
TASK_DECOMPOSITION_ENABLED=true
DEPENDENCY_ANALYSIS_ENABLED=true
MAX_SUBTASKS=8
SUBTASK_GRANULARITY=medium

# 基准测试配置
BENCHMARK_RUNS_PER_TASK=3
BENCHMARK_PARALLEL=false
BENCHMARK_MAX_PARALLEL_TASKS=2
BENCHMARK_TASK_TIMEOUT=60000
BENCHMARK_SAVE_RESULTS=true
BENCHMARK_RESULTS_PATH=./benchmark-results

# 服务器锁定配置
LOCK_FILE_CHECK_ACTIVE_PROCESS=true
REMOVE_STALE_LOCK_FILES=true

# API 密钥（替换为您实际的密钥）
OPENROUTER_API_KEY=your_openrouter_api_key_here

# 日志
LOG_LEVEL=debug

# Python 配置
PYTHON_PATH=./venv/bin/python  # 对于 Linux/macOS
# PYTHON_PATH=./venv/Scripts/python.exe  # 对于 Windows
PYTHON_DETECT_VENV=true

环境变量解释

• 本地 LLM 端点

  • LM_STUDIO_ENDPOINT：LM Studio 实例运行的 URL
  • OLLAMA_ENDPOINT：Ollama 实例运行的 URL

• 配置

  • DEFAULT_LOCAL_MODEL：当卸载任务时使用的本地 LLM 模型
  • TOKEN_THRESHOLD：考虑卸载到本地 LLM 之前的最大令牌数
  • COST_THRESHOLD：触发本地 LLM 使用的成本阈值（以美元为单位）
  • QUALITY_THRESHOLD：低于该质量分数时，无论成本如何都使用付费 API

• 代码搜索配置

  • CODE_SEARCH_ENABLED：启用或禁用语义代码搜索功能
  • CODE_SEARCH_EXCLUDE_PATTERNS：从代码索引中排除的模式（JSON 数组）
  • CODE_SEARCH_INDEX_ON_START：服务器启动时是否索引代码文件
  • CODE_SEARCH_REINDEX_INTERVAL：重新索引之间的间隔（秒），0 表示禁用

• 代码任务分析配置（新增）

  • TASK_DECOMPOSITION_ENABLED：启用智能任务分解
  • DEPENDENCY_ANALYSIS_ENABLED：启用依赖关系映射和关键路径分析
  • MAX_SUBTASKS：分解任务时创建的最大子任务数
  • SUBTASK_GRANULARITY：子任务的详细程度（细、中、粗）

• API 密钥

  • OPENROUTER_API_KEY：您的 OpenRouter API 密钥，用于访问各种 LLM 服务

• Python 配置（新增）

  • PYTHON_PATH：Python 可执行文件的路径（如果有虚拟环境，则设置为虚拟环境中的 Python）
  • PYTHON_VENV_PATH：Python 虚拟环境的路径
  • PYTHON_DETECT_VENV：启用自动检测 Python 虚拟环境

• 新增工具

  • clear_openrouter_tracking：清除 OpenRouter 跟踪数据并强制更新
  • benchmark_free_models：对 OpenRouter 的免费模型进行性能基准测试
  • analyze_code_task：分析代码任务并建议分解策略
  • visualize_dependencies：创建任务依赖关系的可视化表示
  • retriv_init：初始化并配置 Retriv 以进行代码搜索和索引
  • cancel_job：取消正在运行的任务以防止成本失控
  • 增强的 route_task：实现结构化的流程，包括用户偏好、成本确认、Retriv 搜索和任务跟踪

• 服务器锁定配置（新增）

  • LOCK_FILE_CHECK_ACTIVE_PROCESS：验证锁文件中的进程是否仍在运行
  • REMOVE_STALE_LOCK_FILES：自动清理因进程崩溃而遗留的锁文件

Cline.Bot 和 Roo Code 的环境变量

当与 Cline.Bot 或 Roo Code 集成时，您可以直接传递这些环境变量：

• 对于简单配置：在 MCP 设置中使用基本的环境变量
• 对于高级路由：配置阈值以微调何时使用本地模型与云模型
• 对于模型选择：指定哪些本地模型应处理不同类型的需求
• 对于任务分解：配置如何分解和处理复杂任务

使用

启动服务器

npm start

服务器使用锁文件机制以防止多个实例同时运行。如果您尝试启动服务器时已有其他实例在运行，您将看到有关现有实例的信息，进程将退出。

如果先前的服务器进程崩溃且未正确清理，增强的锁文件机制将自动检测并删除过期的锁文件，允许新的服务器实例正确启动。

OpenRouter 集成

服务器集成了 OpenRouter 以访问来自不同提供商的各种免费和付费模型。主要功能包括：

• 免费模型访问：自动检索并跟踪 OpenRouter 提供的免费模型
• 模型跟踪：维护可用模型的本地缓存以减少 API 调用
• 强制更新工具：包含 clear_openrouter_tracking 工具以强制刷新模型
• 改进的可靠性：具有健壮的目录处理和增强的错误日志记录

要使用 OpenRouter 集成：

1. 在环境变量中设置您的 OPENROUTER_API_KEY
2. 服务器将在启动时自动检索可用模型
3. 如果遇到免费模型未显示的问题，可以通过 MCP 接口使用 clear_openrouter_tracking 工具

当前 OpenRouter 集成提供了大约 240 种模型的访问权限，包括来自 Google、Meta、Mistral 和 Microsoft 等提供商的 30 多种免费模型。

代码任务分析

新的任务分析系统智能地分解复杂的编码任务以实现最佳处理：

• 任务分解：将复杂任务分解为可管理的子任务
• 依赖关系映射：识别代码组件之间的关系
• 复杂度分析：评估算法、集成、领域知识和技术要求
• 关键路径分析：识别瓶颈和优化机会
• 执行顺序优化：安排任务以实现最佳并行执行

通过 MCP 接口使用代码任务分析的示例：

/use_mcp_tool locallama analyze_code_task {"task": "创建一个 React 组件，从 API 获取数据并在分页表格中显示，具有排序功能"}

这将返回一个结构化的分析结果，包括：

• 子任务及其依赖关系
• 复杂度评估
• 推荐的执行顺序
• 关键路径识别
• 建议的优化措施

用户偏好和任务跟踪

服务器现在包括用户偏好和任务跟踪功能：

用户偏好

用户偏好存储在一个 user-preferences.json 文件中，包括：

• 执行模式：控制任务的路由方式：

  • 全自动选择：让决策引擎选择最佳选项
  • 仅本地模型：始终使用本地模型
  • 仅免费 API：优先使用免费 API 模型
  • 仅付费 API：始终使用付费 API 模型

• 成本确认阈值：设置在使用付费 API 之前需要确认的成本阈值

• Retriv 搜索优先级：启用或禁用优先使用 Retriv 搜索现有代码解决方案

• 默认目录：配置 Retriv 索引的默认目录

• 排除模式：指定从 Retriv 索引中排除的模式

任务跟踪

服务器现在提供任务跟踪资源：

• 活跃任务：通过 locallama://jobs/active 查看所有当前活跃的任务
• 任务进度：通过 locallama://jobs/progress/{jobId} 跟踪特定任务的进度
• 任务取消：使用 cancel_job 工具取消正在运行的任务

与 Cline.Bot 结合使用

要将此 MCP 服务器与 Cline.Bot 结合使用，请将其添加到 Cline MCP 设置中：

{
  "mcpServers": {
    "locallama": {
      "command": "node",
      "args": ["/path/to/locallama-mcp"],
      "env": {
        "LM_STUDIO_ENDPOINT": "http://localhost:1234/v1",
        "OLLAMA_ENDPOINT": "http://localhost:11434/api",
        "DEFAULT_LOCAL_MODEL": "qwen2.5-coder-3b-instruct",
        "TOKEN_THRESHOLD": "1500",
        "COST_THRESHOLD": "0.02",
        "QUALITY_THRESHOLD": "