内容
# 本地 LLM 委托 MCP
优化的模型上下文协议（MCP）服务器，旨在通过智能地将低复杂度任务委托给高性能的本地 LLM（大型语言模型），显著降低优质令牌成本。
该服务器允许您利用巨大的本地上下文窗口进行“手术”式开发任务（重构、单元测试、文档），同时保持您的主要 LLM 专注于复杂的架构和推理。
## 🚀 主要功能
- **LiteLLM 集成：** 与 Ollama、vLLM、LM Studio、Anthropic 或任何 OpenAI 兼容的提供商无缝连接。
- **外部化配置：** 通过 `config.yaml` 微调模型参数（温度、top_p、max_tokens）。
- **可自定义的提示：** 在 `prompts.yaml` 中定义您自己的任务模板和系统消息。
- **令牌优化：** 自动将简单任务卸载到本地模型，如 Qwen 2.5/3.5 Coder。
- **使用跟踪：** 通过内置的使用日志和统计数据监控您的节省。
## 🛠️ 要求
- **本地 LLM 运行器**（例如 Ollama、vLLM、LM Studio）
- **Python 3.13+**
## 📦 安装
1. **克隆仓库：**
```bash
git clone https://github.com/mrrodriguez/local-llm-delegation-mcp.git
cd local-llm-delegation-mcp
```
2. **设置环境变量：**
```bash
cp .env.example .env
# 编辑 .env 以匹配您的本地设置
```
3. **选择您的安装方法：**
**选项 A：全局 CLI（推荐简单安装）**
安装为全局工具。这将 `local-llm-delegator` 命令添加到您的 PATH 中。
```bash
pip install .
# 或使用 pipx（推荐）
pipx install .
```
**选项 B：本地环境（推荐开发）**
使用虚拟环境，并直接将您的 MCP 客户端指向启动脚本。
```bash
python -m venv .venv
source .venv/bin/activate
pip install .
```
## ⚙️ 配置
服务器使用灵活的配置系统。设置从项目根目录中的 `config.yaml` 和 `prompts.yaml` 加载，具有通过环境变量（或 `.env` 文件）可用的关键覆盖。
### 配置层次结构
1. **基本默认值：** 在 `config.py` 中硬编码。
2. **YAML 文件：** `config.yaml`（模型设置）和 `prompts.yaml`（任务模板）。
3. **环境变量：** 覆盖特定设置，如 `LOCAL_MODEL_NAME` 和 `OPENAI_BASE_URL`。
### 1. 快速入门：环境变量
切换模型的最快方式，无需编辑文件：
```bash
# 在您的 .env 文件或 shell 环境中
LOCAL_MODEL_NAME=ollama/llama3:8b # 覆盖 config.yaml
OPENAI_BASE_URL=http://localhost:11434/v1
```
### 2. 模型调整（`config.yaml`）
更新 `name` 以匹配您的本地提供商的格式（例如 `ollama/qwen2.5-coder`）。提供的模板针对高端硬件（例如 Apple M 系列 Max）进行了优化。
```yaml
model:
name: "openai/Qwen3-Coder-30B-A3B-Instruct-MLX-8bit" # 示例：OMLX/MLX
temperature: 0.1
max_tokens: 32768
extra_params:
num_ctx: 65536
num_predict: 32768
top_p: 0.80
```
*注意：`name` 必须遵循 [LiteLLM 提供商格式](https://docs.litellm.ai/docs/providers)。*
### 3. 自定义任务（`prompts.yaml`）
通过在 `prompts.yaml` 中添加条目来定义您自己的工具。每个顶级键成为 `query_local_llm_with_context` 工具的子任务。
## 🔌 集成
您可以通过全局命令或直接指向项目的路径将此服务器添加到您首选的客户端。
### 1. Gemini Code CLI
**如果全局安装（选项 A）：**
```bash
gemini mcp add local-llm-delegator local-llm-delegator --trust
```
**如果使用直接脚本或路径（选项 B）：**
```bash
gemini mcp add local-llm-delegator /path/to/your/start-script.sh --trust
```
### 2. Claude Code
添加到您的 `~/.claude.json`：
```json
"mcpServers": {
"local-llm-delegator": {
"command": "local-llm-delegator" // 如果全局安装；否则为启动它的任何包装脚本
}
}
```
*注意：如果使用自定义启动脚本（例如 OMLX），请将 `command` 设置为脚本的绝对路径。*
## 📊 使用跟踪
服务器将使用情况记录到 `mcp_usage.jsonl`。通过以下方式查看统计信息：
- `get_local_llm_usage_stats`（MCP 工具）
- `show-stats`（CLI 命令 - 即将推出）或 `python show_stats.py`
## 📜 许可证
MIT
