🚀 JARVIS MCP 项目文档

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

🚀 快速开始

JARVIS MCP 可通过源码或二进制文件进行安装，安装完成后即可快速体验其功能。

示例用法

# 执行系统命令：显示帮助信息
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!"}'

✨ 主要特性

• 功能丰富：支持执行系统命令、文件读写等操作。
• 模块化设计：通过模块划分，将系统命令执行和文件操作分离，便于维护和扩展。
• 安全可靠：具备完善的安全机制，如权限控制、输入验证、日志记录等。
• 易于扩展：可方便地添加新工具，并通过配置文件或环境变量管理运行时参数。

📦 安装指南

从源码安装

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 来传递请求相关信息。

安全注意事项

⚠️ 重要提示

为确保系统安全稳定运行，请严格遵循以下安全注意事项：

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

扩展与集成

添加新工具

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

1. 创建新的 Go 文件（如 directory.go）并定义工具接口。
2. 在 main 函数中注册该工具：

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

配置管理

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

错误处理与调试

常见错误场景

1. 权限不足：

   {
       "error": "permission denied"
   }
   

2. 文件不存在：

   {
       "error": "file not found"
   }
   

3. 命令语法错误：

   {
       "error": "invalid command syntax"
   }
   

调试步骤

💡 使用建议

当遇到问题时，可按以下步骤进行调试：

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

最佳实践

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

项目维护

1. 版本控制：
   • 使用 Git 进行代码管理，定期提交变更记录。
   • 遵循语义化版本控制策略，确保兼容性和可追溯性。
2. 依赖管理：
   • 定期更新 Go 依赖库，保持项目的安全性与稳定性。
   • 监控依赖项的变更，评估其对项目的影响。
3. 测试覆盖：
   • 编写单元测试和集成测试用例，确保各功能模块正常工作。
   • 使用自动化测试工具，加速开发流程并提高代码质量。

附录

环境变量配置

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

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

日志格式示例

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

通过遵循上述结构和最佳实践，您可以有效地构建一个安全、可靠且易于维护的命令行工具和服务框架。