STARWARCLOUD STARWAR.AI
返回市场
字节视界-MCP

字节视界-MCP

作者：kbrisso8 星标更新：2025-07-19
安装使用来源：spider==github.com

项目介绍

Byte Vision MCP

一个使用本地LLama.cpp模型提供文本补全功能的Model Context Protocol (MCP)服务器。该服务器暴露了一个单一的MCP工具，接受文本提示并返回使用本地托管语言模型生成的文本补全。

这个项目是什么？

Byte Vision MCP是MCP兼容客户端（如Claude Desktop、IDE或其他AI工具）与本地LLama.cpp语言模型之间的桥梁。它允许您：

  • 通过MCP协议使用本地语言模型
  • 通过环境文件配置所有模型参数
  • 使用自定义提示生成文本补全
  • 通过保持一切本地来维护隐私
  • 集成到MCP兼容的应用程序中

特性

  • 支持MCP协议：标准的MCP服务器实现
  • 本地模型执行：使用LLama.cpp进行模型推理
  • 可配置参数：所有设置通过环境文件控制
  • GPU加速：支持CUDA、ROCm和Metal
  • 提示缓存：内置缓存以提高性能
  • 详细日志记录：详细的调试和监控日志
  • 优雅关闭：适当的资源清理和错误处理

构建于

核心依赖

间接依赖

Web框架及HTTP

运行时需求

  • Go SDK 1.23+ - 具有最新特性的现代Go运行时
  • LLama.cpp - 本地语言模型推理引擎
  • GGUF模型 - GGUF格式的量化语言模型

前提条件

  • Go 1.23+ 用于构建服务器
  • LLama.cpp二进制文件（参见/llamacpp/README.md安装）
  • GGUF格式模型（参见/models/README.md获取来源）

快速开始

1. 克隆并构建

git clone <repository-url>
cd byte-vision-mcp
go mod tidy
go build -o byte-vision-mcp

2. 设置LLama.cpp

遵循以下说明：/llamacpp/README.md

  • 下载预编译的二进制文件，或
  • 从源代码构建

3. 下载模型

查看：/models/README.md

  • 推荐的模型来源
  • 如何下载GGUF模型
  • 模型放置说明

4. 配置环境

复制示例配置：

cp example-byte-vision-cfg.env byte-vision-cfg.env

编辑以匹配您的设置：byte-vision-cfg.env

更新路径以匹配您的安装

LLamaCliPath=/path/to/your/llama-cli ModelFullPathVal=/path/to/your/model.gguf AppLogPath=/path/to/logs/

5. 运行服务器

./byte-vision-mcp

默认情况下，服务器将在http://localhost:8080/mcp-completion启动。

项目结构

byte-vision-mcp/
├── llamacpp/ # LLama.cpp二进制文件和安装指南
├── logs/ # 应用程序和模型日志
├── models/ # GGUF模型文件
├── prompt-cache/ # 性能缓存提示
├── main.go # 主MCP服务器实现
├── model.go # 模型执行逻辑
├── types.go # 配置结构
├── byte-vision-cfg.env # 您的配置（从示例创建）
└── example-byte-vision-cfg.env # 示例配置

配置

该文件控制服务器的所有方面：byte-vision-cfg.env

应用程序设置

  • : 日志文件目录 AppLogPath
  • : 日志文件名 AppLogFileName
  • : 服务器端口（默认:8080） HttpPort
  • : MCP端点路径（默认） EndPoint``/mcp-completion
  • : 请求超时（默认300） TimeOutSeconds

LLama.cpp设置

  • : llama-cli可执行文件路径 LLamaCliPath
  • : 您的GGUF模型文件路径 ModelFullPathVal
  • : 上下文窗口大小 CtxSizeVal
  • : 分配给GPU的层数 GPULayersVal
  • : 生成温度 TemperatureVal
  • : 最大生成标记数 PredictVal
  • 和许多其他LLama.cpp参数...

使用

MCP工具：generate_completion

服务器暴露了一个单一的MCP工具，接受基本和高级参数以微调LLama.cpp执行。

基本使用

**输入:**
{
"prompt": "写一篇关于机器人学习绘画的短故事"
}
**输出:**
{
"content": [
{
"type": "text",
"text": "生成的补全文本..."
}
]
}

高级使用带参数

完整参数输入:

{
"prompt": "用简单的话解释量子计算",
"temperature": 0.7,
"predict": 500,
"top_k": 40,
"top_p":  0.9,
"ctx_size": 4096,
"threads": 8,
"gpu_layers": 35
}

可用参数

核心模型及性能参数
参数类型描述示例默认来源
model字符串覆盖模型路径"/path/to/model.gguf"ModelFullPathVal
threads整数生成CPU线程数8ThreadsVal
gpu_layers整数GPU加速层数35GPULayersVal
ctx_size整数上下文窗口大小4096CtxSizeVal
batch_size整数批处理大小512BatchCmdVal
生成控制参数
参数类型描述范围默认来源
predict整数生成标记数1-8192PredictVal
temperature浮点数创造性/随机性控制0.0-2.0TemperatureVal
top_k整数Top-K采样1-100TopKVal
top_p浮点数Top-P（核心）采样0.0-1.0TopPVal
repeat_penalty浮点数重复惩罚0.5-2.0RepeatPenaltyVal
输入/输出参数
参数类型描述示例默认来源
prompt_file字符串从文件加载提示"/path/to/prompt.txt"PromptFileVal
log_file字符串自定义日志文件路径"/path/to/custom.log"ModelLogFileNameVal

参数使用示例

1. 创意写作（高温度）
{
"prompt": "写一篇关于时间旅行的创意故事",
"temperature": 1.2,
"top_p": 0.95,
"predict": 1000,
"repeat_penalty": 1.1
}
2. 技术文档（低温度）
{
"prompt": "解释TCP/IP协议栈",
"temperature": 0.3,
"top_k": 10,
"predict": 800,
"ctx_size": 8192
}
3. 代码生成（平衡）
{
"prompt": "编写一个Python函数来排序列表",
"temperature": 0.6,
"top_k": 30,
"top_p": 0.8,
"predict": 400
}
4. 长上下文处理
{
"prompt": "总结这份文档...",
"ctx_size": 32768,
"gpu_layers": 40,
"batch_size": 1024,
"predict": 500
}
5. 性能优化
{
"prompt": "关于Go语法的快速问题",
"threads": 12,
"gpu_layers": 45,
"batch_size": 2048,
"predict": 200,
"temperature": 0.4
}
6. 使用外部提示文件
{
"prompt_file": "/path/to/complex_prompt.txt",
"temperature": 0.8,
"predict": 1500,
"log_file": "/path/to/custom_generation.log"
}

参数指南

温度设置
- **0.0-0.3**: 高度确定性，事实性响应
- **0.4-0.7**: 平衡创造力和连贯性
- **0.8-1.2**: 创造性，多样化响应
- **1.3-2.0**: 高度创造性，潜在混乱
上下文大小指南
- **2048-4096**: 短对话，简单任务
- **8192-16384**: 中等文档，复杂推理
- **32768+**: 长文档，广泛上下文
GPU层优化
- **0**: 仅CPU处理
- **25-35**: 平衡CPU/GPU（8GB VRAM）
- **40+**: 完整GPU加速（12GB+ VRAM）
预测长度
- **50-200**: 短回答，代码片段
- **300-800**: 中等解释，文档
- **1000+**: 长篇内容，故事

性能考虑

内存使用
{
"ctx_size": 4096, // 对于有限RAM降低
"batch_size": 512, // 较小批次以稳定
"gpu_layers": 25 // 如果GPU内存有限则减少
}
速度优化
{
"threads": 8, // 匹配CPU核心
"gpu_layers": 45, // 最大化GPU使用
"batch_size": 2048, // 较大批次以提高吞吐量
"predict": 200 // 较短以快速响应
}
质量优化
{
"temperature": 0.7, // 平衡创造力
"top_k": 40, // 多样化采样
"top_p": 0.9, // 核心采样
"repeat_penalty": 1.1, // 减少重复
"ctx_size": 8192 // 较大上下文以增强连贯性
}

错误处理

该工具为无效参数提供特定的错误消息：

{
"content": [
{
"type": "text",
"text": "错误：无效的温度值。必须在0.0和2.0之间"
}
]
}

默认行为

  • 所有参数都是可选的，除了prompt
  • 环境配置当未指定参数时使用
  • 零值被忽略（例如，temperature: 0使用配置默认值）
  • 无效值回退到配置默认值

集成示例

JavaScript/Node.js
const result = await mcpClient.callTool("generate_completion", {
prompt: "解释JavaScript中的async/await",
temperature: 0.5,
predict: 600,
top_k: 25
});
console.log(result.content[0].text);
Python
response = mcp_client.call_tool("generate_completion", {
"prompt": "编写一个Python类用于二叉树",
"temperature": 0.6,
"predict": 800,
"top_p": 0.8
})
print(response["content"][0]["text"])
curl（直接HTTP）
curl -X POST http://localhost:8080/mcp-completion \
-H "Content-Type: application/json" \
-d '{
"prompt": "解释Docker容器",
"temperature": 0.4,
"predict": 500,
"ctx_size": 4096
}'

这个全面的参数系统允许对LLama.cpp的行为进行细粒度控制，同时保持向后兼容性和易用性。

GPU加速

NVIDIA GPU（CUDA）

  • 下载CUDA启用的LLama.cpp二进制文件
  • 设置GPULayersVal=33（或根据您的GPU内存调整）
  • 设置MainGPUVal=0（或您首选的GPU索引）

AMD GPU（ROCm - 仅限Linux）

  • 下载ROCm启用的LLama.cpp二进制文件
  • 配置类似于CUDA设置

Apple Silicon（Metal - macOS）

  • Metal支持已内置
  • 不需要额外配置

日志

日志写入控制台和文件：

  • 应用程序日志：logs/byte-vision-mcp.log
  • 模型日志：logs/[model-name].log
  • 可配置的日志级别和详细程度

查看日志管理详情。/logs/README.md

故障排除

常见问题

  1. “找不到llama-cli”

    • 检查您的文件LLamaCliPath``.env
    • 确保二进制文件具有执行权限

  2. “找不到模型文件”

    • 验证指向有效的.gguf文件ModelFullPathVal
    • 检查文件权限

  3. 内存不足错误

    • 减少CtxSizeVal
    • 使用较小的模型
    • 增加GPULayersVal以卸载到GPU

  4. 生成缓慢

    • 启用GPU加速
    • 增加GPULayersVal
    • 使用量化模型（Q4，Q5，Q8）

  5. 服务器无法启动

    • 检查端口是否已被占用
    • 验证配置中的所有路径是否存在
    • 查看日志以获取详细错误信息

开发

从源代码构建

go mod tidy go build -o byte-vision-mcp

运行测试

go test ./...

依赖项

    • 环境文件加载 github.com/joho/godotenv
    • MCP协议实现 github.com/metoro-io/mcp-golang

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 如适用添加测试
  5. 提交拉取请求

许可

此项目根据MIT许可条款授权。

支持

  • 检查每个子目录中的README文件以获取特定的设置说明
  • 查看日志以获取详细的错误信息
  • 确保配置中的所有路径都是绝对路径且可访问

作者: Kevin Brisson

邮箱: kbrisso@gmail.com

LinkedIn: Kevin Brisson

项目链接: https://github.com/kbrisso/byte-vision-mcp