Jarvis MCP

🚀 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 模式。
• 提供执行系统命令和文件操作功能。
• 支持多工具扩展与集成。
• 具备完善的安全机制和错误处理能力。

📦 安装指南

从源码安装

1. 克隆仓库：

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

2. 构建项目：

   go mod tidy
   ./build.sh
   

3. 运行程序：

   ./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），可以按照以下步骤进行：

1. 创建新的 Go 文件（如 directory.go）并定义工具接口。
2. 在 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                # 依赖管理文件

错误处理与调试

常见错误场景

1. 权限不足：

   {
       "error": "permission denied"
   }
   

2. 文件不存在：

   {
       "error": "file not found"
   }
   

3. 命令语法错误：

   {
       "error": "invalid command syntax"
   }
   

调试步骤

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

最佳实践

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

项目维护

版本控制

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

依赖管理

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

测试覆盖

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

附录

环境变量配置

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

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

日志格式示例

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

🔧 技术细节

安全注意事项

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