本地 llama-MCP

Name: 本地 llama-MCP
Author: Heratiki

作者：Heratiki40 星标更新：2025-07-25

安装使用来源：spider==github.com

项目介绍

技术文档摘要

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 的语义搜索引擎。要使用此功能：

安装 Python：确保系统上已安装 Python 3.8+。

创建虚拟环境（推荐）：

# 对于 Linux/macOS：
python3 -m venv venv
source venv/bin/activate

# 对于 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 配置
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 集成：

在环境变量中设置您的 OPENROUTER_API_KEY
服务器将在启动时自动检索可用模型
如果遇到免费模型未显示的问题，可以通过 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": "