Byte Vision MCP

字节视觉MCP

一种模型上下文协议（MCP）服务器，使用本地LLama.cpp模型提供文本完成功能。这 服务器公开了一个MCP工具，该工具接受文本提示，并使用本地托管返回AI生成的补全 语言模型。

这个项目是什么？

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

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

特性

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

构建于

核心依赖关系

• v1.5.1 -从加载环境变量 .env

文件

• v0.12.0 -模型上下文协议（MCP）

Go的实现

间接依赖关系

Web框架和HTTP

• v1.8.1 -HTTP web框架
• v0.1.0 -服务器发送事件支持

运行时间要求

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

先决条件

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

快速开始

1.克隆和构建

git clone 
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 binaries and installation guide
├── logs/ # Application and model logs
├── models/ # GGUF model files
├── prompt-cache/ # Cached prompts for performance
├── main.go # Main MCP server implementation
├── model.go # Model execution logic
├── types.go # Configuration structures
├── byte-vision-cfg.env # Your configuration (create from example)
└── example-byte-vision-cfg.env # Example configuration

配置

该文件控制服务器的所有方面： 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 执行。

基本用法

**Input:**
{
"prompt": "Write a short story about a robot learning to paint"
}
**Output:**
{
"content": [
{
"type": "text",
"text": "Generated completion text..."
}
]
}

参数的高级用法

完整参数输入：

{
"prompt": "Explain quantum computing in simple terms",
"temperature": 0.7,
"predict": 500,
"top_k": 40,
"top_p": 0.9,
"ctx_size": 4096,
"threads": 8,
"gpu_layers": 35
}

可用参数

核心模型和性能参数

发电控制参数

输入/输出参数

参数使用示例

1.创意写作（高温）

{
"prompt": "Write a creative story about time travel",
"temperature": 1.2,
"top_p": 0.95,
"predict": 1000,
"repeat_penalty": 1.1
}

2.技术文件（低温）

{
"prompt": "Explain the TCP/IP protocol stack",
"temperature": 0.3,
"top_k": 10,
"predict": 800,
"ctx_size": 8192
}

3.代码生成（平衡）

{
"prompt": "Write a Python function to sort a list",
"temperature": 0.6,
"top_k": 30,
"top_p": 0.8,
"predict": 400
}

4.长上下文处理

{
"prompt": "Summarize this document...",
"ctx_size": 32768,
"gpu_layers": 40,
"batch_size": 1024,
"predict": 500
}

5.性能优化

{
"prompt": "Quick question about Go syntax",
"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**: Highly deterministic, factual responses
- **0.4-0.7**: Balanced creativity and coherence
- **0.8-1.2**: Creative, varied responses
- **1.3-2.0**: Highly creative, potentially chaotic

上下文大小指南

- **2048-4096**: Short conversations, simple tasks
- **8192-16384**: Medium documents, complex reasoning
- **32768+**: Long documents, extensive context

GPU层优化

- **0**: CPU-only processing
- **25-35**: Balanced CPU/GPU (8GB VRAM)
- **40+**: Full GPU acceleration (12GB+ VRAM)

预测长度

- **50-200**: Short answers, code snippets
- **300-800**: Medium explanations, documentation
- **1000+**: Long-form content, stories

性能注意事项

内存使用

{
"ctx_size": 4096, // Lower for limited RAM
"batch_size": 512, // Smaller batches for stability
"gpu_layers": 25 // Reduce if GPU memory limited
}

速度优化

{
"threads": 8, // Match CPU cores
"gpu_layers": 45, // Maximize GPU usage
"batch_size": 2048, // Larger batches for throughput
"predict": 200 // Shorter for quick responses
}

质量优化

{
"temperature": 0.7, // Balanced creativity
"top_k": 40, // Diverse sampling
"top_p": 0.9, // Nucleus sampling
"repeat_penalty": 1.1, // Reduce repetition
"ctx_size": 8192 // Larger context for coherence
}

错误处理

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

{
"content": [
{
"type": "text",
"text": "Error: Invalid temperature value. Must be between 0.0 and 2.0"
}
]
}

默认行为

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

集成示例

JavaScript/Node.js

const result = await mcpClient.callTool("generate_completion", {
prompt: "Explain async/await in JavaScript",
temperature: 0.5,
predict: 600,
top_k: 25
});
console.log(result.content[0].text);

python

response = mcp_client.call_tool("generate_completion", {
"prompt": "Write a Python class for a binary tree",
"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": "Explain Docker containers",
"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设置

苹果硅（金属-macOS）

• 内置金属支架
• 无需额外配置

日志记录

日志同时写入控制台和文件：

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

有关日志管理的详细信息，请参阅。 /logs/README.md

故障排除

常见问题

1. “找不到llama cli”

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

1. “找不到模型文件”

- 验证点是否有效 .gguf 文件 ModelFullPathVal - 检查文件权限

1. 内存不足错误

- 减少 CtxSizeVal - 使用较小的型号 - GPU卸载增加 GPULayersVal

1. 缓慢的一代

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

1. 服务器无法启动

- 检查端口是否已在使用中 - 验证配置中的所有路径是否存在 - 检查日志以获取详细的错误消息

发展

从源头构建

去模整洁 go build-o字节视觉mcp

运行测试

去测试。/...

依赖项

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

该项目根据麻省理工学院许可证条款获得许可。

支持

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

作者 凯文·布里森

电子邮件： kbrisso@gmail.com

领英： 凯文·布里森

项目链接：