Jarvis Mcp

开发官方认证 Go

🚀 JARVIS MCP 项目文档

JARVIS MCP 是一个基于 MCP Go 框架实现的系统，采用 Model-Code-Proxy（模型-代码-代理）模式。它提供了执行命令、进行文件操作等功能，并在本地系统上运行，为用户带来便捷的操作体验。

🚀 快速开始

JARVIS MCP 是基于 MCP Go 框架实现的系统，运用 Model-Code-Proxy（模型-代码-代理）模式，可在本地系统运行，提供执行命令、文件操作等功能。

示例用法

# 执行系统命令：显示帮助信息
curl -X POST http://localhost:8090/api/v1/tool/execute_command --data '{"command":"help","arg":"/"}'

# 读取文件内容
curl -X POST http://localhost:8090/api/v1/tool/read_file --data '{"file":"/path/to/file.txt"}'

# 写入新文件
curl -X POST http://localhost:8090/api/v1/tool/write_file --data '{"file":"newfile.txt","content":"Hello, World!"}'

✨ 主要特性

基于 MCP Go 框架，采用 Model-Code-Proxy 模式。
提供执行系统命令和文件操作功能。
支持多工具扩展与集成。
具备完善的安全机制和错误处理能力。

📦 安装指南

从源码安装

克隆仓库：

git clone https://github.com/yourusername/jarvis-mcp.git
cd jarvis-mcp

构建项目：
```
go mod tidy
./build.sh
```
运行程序：
```
./out/jarvis-mcp --port=8090
```

二进制文件安装

从发布页面下载对应平台的二进制文件，然后解压并运行。

💻 使用示例

基础用法

执行系统命令

curl -X POST http://localhost:8090/api/v1/tool/execute_command \
--data '{"command":"ls", "arg":"-a"}'

读取文件内容

curl -X POST http://localhost:8090/api/v1/tool/read_file \
--data '{"file":"./test.txt"}'

📚 详细文档

工具说明

执行命令工具

package shell

import (
"context"
"errors"

"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
)

func GetExecuteCommandTool() (tool mcp.Tool, handler server.ToolHandlerFunc) {
return mcp.NewTool("execute_command",
mcp.WithDescription("Execute system commands in a controlled manner"),
mcp.WithString("command",
mcp.Required(),
mcp.Description("The command to execute")),
mcp.WithString("arg",
mcp.Optional(),
mcp.Description("Optional argument for the command")),
), ExecuteCommandHandler
}

func ExecuteCommandHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
cmd := request.Params.Arguments["command"].(string)
arg, ok := request.Params.Arguments["arg"].(string)
if !ok {
arg = ""
}

output, err := execute.Command(cmd, arg)
if err != nil {
return nil, errors.New("failed to execute command")
}

return mcp.NewToolResultText(output), nil
}

文件操作工具

package files

import (
"context"
"errors"

"github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
)

func GetReadFileTool() (tool mcp.Tool, handler server.ToolHandlerFunc) {
return mcp.NewTool("read_file",
mcp.WithDescription("Read content from a file"),
mcp.WithString("file",
mcp.Required(),
mcp.Description("The path to the file")),
), ReadFileHandler
}

func ReadFileHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
filePath := request.Params.Arguments["file"].(string)
content, err := readFile(filePath)
if err != nil {
return nil, errors.New("failed to read file")
}

return mcp.NewToolResultText(content), nil
}

项目架构

模块划分

shell：处理系统命令的执行。
files：负责文件操作，如读取、写入等。

核心组件

工具注册：所有工具通过 mcp 框架进行注册和管理。
上下文处理：使用 Go 的 context 来传递请求相关信息。

扩展与集成

添加新工具

要添加新的工具（例如 create_directory），可以按照以下步骤进行：

创建新的 Go 文件（如 directory.go）并定义工具接口。

在 main 函数中注册该工具：

tool, handler := GetCreateDirectoryTool()
server.AddTool(tool, handler)

配置管理

通过配置文件或环境变量来管理运行时参数，例如设置默认的文件存储路径或命令超时时间。

项目结构

javis-mcp/
├── api/                  # 接口定义和路由处理
│   └── routes.go         # 定义各个工具的接口端点
├── build.sh              # 构建脚本
├── cmd/                  # 可执行文件入口
│   └── main.go           # 项目主函数，负责初始化和启动服务
├── files/                # 文件操作模块
│   ├── file.go           # 文件读写逻辑
│   └── directory.go      # 目录创建与删除功能
├── shell/                # 系统命令执行模块
│   └── command.go        # 命令执行逻辑
└── go.mod                # 依赖管理文件

错误处理与调试

常见错误场景

权限不足：
```
{
"error": "permission denied"
}
```
文件不存在：
```
{
"error": "file not found"
}
```
命令语法错误：
```
{
"error": "invalid command syntax"
}
```

调试步骤

检查日志输出，获取详细错误信息。
确保服务有足够的权限执行相关操作。
验证输入参数是否符合预期格式。

最佳实践

最小权限原则：限制每个工具的功能范围，仅授予必要的权限。
日志审计：定期审查操作日志，识别异常行为和潜在的安全漏洞。
性能优化：监控服务的运行状态，优化关键路径以提升响应速度。

项目维护

版本控制

使用 Git 进行代码管理，定期提交变更记录。
遵循语义化版本ing策略，确保兼容性和可追溯性。

依赖管理

定期更新 Go 依赖库，保持项目的安全性与稳定性。
监控依赖项的变更，评估其对项目的影响。

测试覆盖

编写单元测试和集成测试用例，确保各功能模块正常工作。
使用自动化测试工具，加速开发流程并提高代码质量。

附录

环境变量配置

# 设置服务运行的端口
export PORT=8090

# 配置日志输出目录
export LOG_PATH=./logs

日志格式示例

{
"timestamp": "2024-03-15T12:34:56Z",
"level": "INFO",
"message": "Command 'ls -a' executed successfully"
}

🔧 技术细节

安全注意事项

权限控制
- 仅允许经过身份验证的用户执行敏感命令或文件操作。
- 设置适当的文件访问权限，避免未经授权的读写操作。
输入验证
- 对用户提供的命令和文件路径进行严格的输入验证，防止注入攻击。
- 确保所有外部输入都经过消毒处理。
日志记录
- 记录所有执行的操作日志，包括命令内容和文件操作的详细信息。
- 配置日志级别和输出格式，便于后续审计和问题排查。
异常处理
- 对所有可能失败的操作进行错误捕捉，并提供有意义的错误信息。
- 实现回滚机制，防止部分操作成功而其他操作失败导致的数据不一致。
资源清理
- 及时释放不再使用的系统资源，如文件句柄和网络连接。
- 定期清理临时生成的文件，避免磁盘空间耗尽。

0 条评论
分类：开发