JARVIS MCP 项目文档

概述

JARVIS MCP 是一个基于 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":"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!"}'

工具说明

执行命令工具

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)
   

配置管理

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

项目结构

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

使用示例

执行系统命令

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"}'

错误处理与调试

常见错误场景

1. 权限不足:

   {
       "error": "permission denied"
   }
   

2. 文件不存在:

   {
       "error": "file not found"
   }
   

3. 命令语法错误:

   {
       "error": "invalid command syntax"
   }
   

调试步骤

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

最佳实践

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

项目维护

1. 版本控制:

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

2. 依赖管理:

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

3. 测试覆盖:

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

附录

环境变量配置

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

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

日志格式示例

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

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