LocaLama MCP服务器（测试分支）

使用Roo Code或Cline的MCP服务器。Bot（目前未使用Claude Desktop或CoPilot MCP VS代码扩展进行测试）通过在本地LLM和付费API之间智能路由编码任务来优化成本。这里面有很多坏的实现。

概述

LocalLama MCP服务器旨在通过动态决定是否将编码任务卸载到本地能力较差的指令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服务器中提供以下工具：

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服务器中提供了以下资源：

静态资源：

locallama://status：LocalLama MCP服务器的当前状态。
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密钥时可用）。

安装

# Clone the repository
git clone https://github.com/yourusername/locallama-mcp.git
cd locallama-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Install retriv dependencies (if you want to use retriv)
pip install retriv>=0.3.1 numpy>=1.22.0 scikit-learn>=1.0.2 scipy>=1.8.0

Retriv的Python设置（代码搜索）

代码搜索功能使用Retriv，一个基于Python的语义搜索库。要使用此功能，请执行以下操作：

安装Python确保您的系统上安装了Python 3.8+。

创建虚拟环境 （推荐）：

   # For Linux/macOS:
   python3 -m venv venv
   source venv/bin/activate

   # For Windows:
   python -m venv venv
   venv\Scripts\activate

安装Retriv和依赖项:

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

配置服务器以使用您的虚拟环境:

将这些行添加到您的 .env 文件：

   # Python Configuration
   PYTHON_PATH=./venv/bin/python  # For Linux/macOS
   # PYTHON_PATH=./venv/Scripts/python.exe  # For Windows
   PYTHON_DETECT_VENV=true

备注：您还可以使用以下命令让服务器自动安装Retriv retriv_init 工具与 install_dependencies 着手 true.

配置

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

cp .env.example .env

然后编辑 .env 使用您的特定配置文件：

# Local LLM Endpoints
LM_STUDIO_ENDPOINT=http://localhost:1234/v1
OLLAMA_ENDPOINT=http://localhost:11434/api

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

# Code Search Configuration
CODE_SEARCH_ENABLED=true
CODE_SEARCH_EXCLUDE_PATTERNS=["node_modules/**","dist/**",".git/**"]
CODE_SEARCH_INDEX_ON_START=true
CODE_SEARCH_REINDEX_INTERVAL=3600

# Code Task Analysis Configuration
TASK_DECOMPOSITION_ENABLED=true
DEPENDENCY_ANALYSIS_ENABLED=true
MAX_SUBTASKS=8
SUBTASK_GRANULARITY=medium

# Benchmark Configuration
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

# Server Lock Configuration
LOCK_FILE_CHECK_ACTIVE_PROCESS=true
REMOVE_STALE_LOCK_FILES=true

# API Keys (replace with your actual keys)
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Logging
LOG_LEVEL=debug

# Python Configuration
PYTHON_PATH=./venv/bin/python  # For Linux/macOS
# PYTHON_PATH=./venv/Scripts/python.exe  # For 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：用于访问各种LLM服务的OpenRouter API密钥

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代码

与Cline整合时。Bot或Roo Code，您可以直接传递这些环境变量：

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

用法

启动服务器

npm start

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

如果之前的服务器进程在没有正确清理的情况下崩溃，增强的锁文件机制将自动检测并删除过时的锁文件，从而允许新的服务器实例正确启动。

OpenRouter集成

该服务器与OpenRouter集成，可以访问来自不同提供商的各种免费和付费模式。主要特征包括：

免费模型访问：自动检索和跟踪OpenRouter提供的免费型号
模型跟踪：维护可用模型的本地缓存，以减少API调用
强制更新工具：包括a clear_openrouter_tracking 强制更新模型的工具
提高了可靠性：具有强大的目录处理和增强的错误记录功能

要使用OpenRouter集成，请执行以下操作：

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

当前的OpenRouter集成提供了对大约240种型号的访问，其中包括来自谷歌、Meta、Mistral和微软等提供商的30多种免费型号。

代码任务分析

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

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

通过MCP接口进行代码任务分析的示例：

/use_mcp_tool locallama analyze_code_task {"task": "Create a React component that fetches data from an API and displays it in a paginated table with sorting capabilities"}

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

子任务及其依赖关系
复杂性评估
建议执行顺序
关键路径识别
建议的优化

用户首选项和作业跟踪

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

用户选项

用户偏好存储在 user-preferences.json 文件并包括：

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

- Fully automated selection：让决策引擎选择最佳选项 - Local model only：始终使用本地模型 - Free API only：首选可用的免费API型号 - Paid API only：始终使用付费API模型

成本确认阈值：设置在使用付费API之前何时请求确认的阈值

检索优先级：启用或禁用对现有代码解决方案的Retriv搜索进行优先级排序

默认文件目录：配置Retriv索引的默认目录

排除图案：指定要从Retriv索引中排除的模式

作业跟踪

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

活动作业：通过查看所有当前活动的作业 locallama://jobs/active
工作进度：通过以下方式跟踪特定作业的进度 locallama://jobs/progress/{jobId}
工作取消：使用取消正在运行的作业 cancel_job 工具

与Cline一起使用。机器人

将此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": "0.07",
        "TASK_DECOMPOSITION_ENABLED": "true",
        "DEPENDENCY_ANALYSIS_ENABLED": "true",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here"
      },
      "disabled": false
    }
  }
}

配置后，您可以使用Cline中的MCP工具。机器人程序：

get_free_models：从OpenRouter检索免费型号列表
clear_openrouter_tracking：如果遇到问题，强制更新OpenRouter模型
benchmark_free_models：对OpenRouter免费型号的性能进行基准测试
analyze_code_task：分析复杂的编码任务并制定分解计划
visualize_dependencies：生成任务依赖关系的可视化表示
retriv_init：初始化并配置Retriv以进行代码搜索和索引
cancel_job：取消正在运行的作业以防止成本失控

Cline中的示例用法。机器人程序：

/use_mcp_tool locallama clear_openrouter_tracking {}

这将清除跟踪数据并强制更新模型，如果您没有看到任何免费模型，或者您想确保拥有最新的模型信息，这将非常有用。

增强的路线任务工作流

这 route_task 该工具现在遵循结构化的工作流程：

加载用户首选项：从配置文件加载存储的用户首选项
成本估算：评估执行成本，如果成本超过阈值，则提示确认
任务分解分析：确定是否需要任务分段
检索：在生成任何新代码之前，检查Retriv中的现有代码解决方案
决策引擎路由：确定执行任务的最具成本效益的方法
工作机会：创建新作业并将其登录 locallama://jobs/active
进度跟踪：用途 locallama://jobs/progress/{jobId} 跟踪作业进度
结果存储：将结果存储在Retriv中以供将来重用

示例用法：

/use_mcp_tool locallama route_task {
  "task": "Create a function to calculate the Fibonacci sequence",
  "context_length": 1000,
  "expected_output_length": 500,
  "complexity": 0.3,
  "priority": "cost"
}

“回报优先”战略

服务器现在实现了“Retriv First”策略来优先处理现有代码：

设置Python环境：按照上面的Python设置说明进行操作
编码索引：使用 retriv_init 为代码存储库建立索引
语义搜索：提交任务时，Retriv会搜索类似的代码
代码重用：如果发现类似的代码，则立即返回，不生成新代码
后备方案：如果没有找到合适的代码，则将任务路由到相应的模型

示例用法：

/use_mcp_tool locallama retriv_init {
  "directories": ["/path/to/your/code/repo"],
  "exclude_patterns": ["node_modules/**", "dist/**"],
  "install_dependencies": true,
  "force_reindex": true
}

了解使用情况

MCP服务器提供了几种监视和了解其使用情况的方法：

API使用和成本：使用以下工具跟踪不同API（如OpenRouter）的令牌使用情况和估计成本 locallama://usage/{api} 资源。替换 {api} 使用API的名称（例如。， openrouter).此信息由成本监控模块收集。
作业跟踪：监视提交到服务器的任务的状态和进度：

- locallama://jobs/active：列出当前正在运行的所有作业。 - locallama://jobs/progress/{jobId}：显示特定作业ID的详细进度百分比和状态。

模型执行日志：服务器日志(locallama.log 默认情况下）包含有关哪些模型用于特定任务的详细信息，包括决策引擎做出的决策。
高级本地模型功能（LM Studio和Ollama）:

- 自动提示策略改进：The lmStudioModule （并可能 ollamaModule 如果以类似的方式实现）可以随着时间的推移自动对模型的不同提示策略进行基准测试。如果基于质量启发式方法找到了更好的策略，它将被保存并用于未来的请求。该过程基于配置定期发生（例如。， promptImprovementConfig 在……里面 lm-studio/index.ts).检查日志中指示策略更新的消息。 - 推测推理/解码：The lmStudioModules callWithSpeculativeInference 函数（可能还有Ollama的等效函数）试图通过推测性地生成一些令牌，然后验证它们来加速响应。这由配置控制（例如。， speculativeInferenceConfig 在……里面 lm-studio/index.ts)并且需要模型支持。日志将指示何时尝试、接受或拒绝推测推理，并可能显示生成/接受的令牌的统计数据。 - 配置：虽然不通过工具/资源直接控制，但这些功能的行为（启用状态、阈值、冷却）在相应的模块文件中进行管理(lm-studio/index.ts, ollama/index.ts)以及它们关联的配置对象（如 DEFAULT_PROMPT_IMPROVEMENT_CONFIG, DEFAULT_SPECULATIVE_INFERENCE_CONFIG).

推测推断统计：当为LM Studio或Ollama模型启用推测推断时，日志还可能包含有关生成、接受的令牌数量和可能节省的时间的统计信息。
资源状态：检查服务器和集成的一般状态：

- locallama://status：一般服务器状态。 - locallama://models：检测到的本地模型列表（LM Studio，Ollama）。 - locallama://openrouter/status：OpenRouter集成的状态。

通过利用这些资源并检查日志，与服务器交互的用户和LLM可以深入了解其操作、成本和性能，包括本地模型模块中发生的高级优化。

运行基准

该项目包括一个全面的基准测试系统，用于将本地LLM模型与付费API模型进行比较：

# Run a simple benchmark
node run-benchmarks.js

# Run a comprehensive benchmark across multiple models
node run-benchmarks.js comprehensive

基准结果存储在 benchmark-results 目录，包括：

JSON格式的单个任务性能指标
JSON和Markdown格式的摘要报告
模型性能综合分析

基准结果

该存储库包括基准测试结果，这些结果为不同模型的性能提供了有价值的见解。这些结果：

不包含任何敏感的API密钥或个人信息
提供有助于为决策引擎提供信息的性能指标
包括响应时间、成功率、质量分数和令牌使用统计数据
对于任何想了解本地LLM和付费API之间权衡的人来说都很有用

发展

以开发模式运行

npm run dev

运行测试

npm test

中的所有测试文件 /test 目录使用适当的模拟来防止在测试运行期间启动多个实际的服务器实例。如果您创建了自定义测试脚本，请确保它们正确清理服务器进程，并在完成后删除锁文件。

故障排除

由于锁定文件，服务器无法启动

如果服务器因检测到另一个实例已在运行而无法启动：

检查是否有另一个实例正在运行 ps 或任务管理器
如果没有其他实例正在运行，则锁文件可能由于之前的崩溃而过时
增强的锁机制应自动检测并删除过时的锁文件
如果需要，您可以手动删除 locallama.lock 项目根目录中的文件

安全说明

这 .gitignore 文件被配置为防止敏感数据被提交到存储库
API密钥和其他机密应存储在 .env 文件，已从版本控制中排除
存储库中包含的基准结果不包含敏感信息

许可证

国际协调委员会

阶段

第一阶段：代码任务分析

状态：已完成
完成率：100%
功能：任务分解、复杂性分析、依赖映射、令牌估计

第二阶段：代币优化

状态：已完成
完成率：100%
特点：基于模式的缓存、相似性匹配、缓存失效、重用优化

第3阶段：模型选择增强

状态：已完成
完成率：100%
特点：动态模型评分、性能历史跟踪、资源优化

阶段4：代码质量集成

状态：已完成
完成率：100%
功能：代码验证、质量评估、特定任务分析、基于模型的评估

第五阶段：性能优化

状态：已完成
完成率：100%
特点：缓存优化、检索效率、资源使用优化

第6阶段：新模块集成

状态：进行中
完成率：60%
功能：模块系统架构、组件框架、可扩展性改进、用户偏好、作业跟踪、Retriv集成
当前重点：实施“回报优先”战略和岗位管理制度

LocaLLama MCP Server

快速接入

详细介绍