Jarvis MCP

🚀 JARVIS MCP Project Documentation

JARVIS MCP is a system implemented based on the MCP Go framework, adopting the Model-Code-Proxy pattern. It offers functions such as executing commands and performing file operations, and runs on the local system.

🚀 Quick Start

Example Usage

# Execute a system command: Display help information
curl -X POST http://localhost:8090/api/v1/tool/execute_command --data '{"command":"help","arg":"/"}'

# Read file content
curl -X POST http://localhost:8090/api/v1/tool/read_file --data '{"file":"/path/to/file.txt"}'

# Write to a new file
curl -X POST http://localhost:8090/api/v1/tool/write_file --data '{"file":"newfile.txt","content":"Hello, World!"}'

✨ Features

• Command Execution: Execute system commands in a controlled manner.
• File Operations: Perform file operations such as reading and writing.

📦 Installation

Install from Source Code

1. Clone the repository:

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

2. Build the project:

   go mod tidy
   ./build.sh
   

3. Run the program:

   ./out/jarvis-mcp --port=8090
   

Install Binary Files

Download the binary file for your platform from the Releases page, then extract and run it.

💻 Usage Examples

Basic Usage

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

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

Advanced Usage

To add a new tool (e.g., create_directory), follow these steps:

1. Create a new Go file (e.g., directory.go) and define the tool interface.
2. Register the tool in the main function:

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

📚 Documentation

Tool Explanation

Execute Command Tool

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
}

File Operation Tool

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
}

Project Architecture

Module Division

• shell: Handles the execution of system commands.
• files: Responsible for file operations such as reading and writing.

Core Components

• Tool Registration: All tools are registered and managed through the mcp framework.
• Context Handling: Uses Go's context to pass request-related information.

Security Considerations

1. Permission Control:
   • Only allow authenticated users to execute sensitive commands or perform file operations.
   • Set appropriate file access permissions to prevent unauthorized read and write operations.
2. Input Validation:
   • Conduct strict input validation on user-provided commands and file paths to prevent injection attacks.
   • Ensure that all external inputs are sanitized.
3. Logging:
   • Log all executed operations, including command content and detailed information about file operations.
   • Configure the log level and output format for subsequent auditing and problem troubleshooting.
4. Exception Handling:
   • Capture errors for all operations that may fail and provide meaningful error messages.
   • Implement a rollback mechanism to prevent data inconsistency caused by partial operation success and other operation failures.
5. Resource Cleanup:
   • Release unused system resources in a timely manner, such as file handles and network connections.
   • Regularly clean up temporarily generated files to avoid disk space exhaustion.

Configuration Management

Manage runtime parameters through configuration files or environment variables, such as setting the default file storage path or command timeout.

Project Structure

javis-mcp/
├── api/                  # Interface definitions and route handling
│   └── routes.go         # Define interface endpoints for each tool
├── build.sh              # Build script
├── cmd/                  # Executable file entry point
│   └── main.go           # Project main function, responsible for initialization and starting the service
├── files/                # File operation module
│   ├── file.go           # File read and write logic
│   └── directory.go      # Directory creation and deletion functions
├── shell/                # System command execution module
│   └── command.go        # Command execution logic
└── go.mod                # Dependency management file

Error Handling and Debugging

Common Error Scenarios

1. Insufficient Permissions:

   {
       "error": "permission denied"
   }
   

2. File Not Found:

   {
       "error": "file not found"
   }
   

3. Command Syntax Error:

   {
       "error": "invalid command syntax"
   }
   

Debugging Steps

1. Check the log output to obtain detailed error information.
2. Ensure that the service has sufficient permissions to perform related operations.
3. Verify that the input parameters conform to the expected format.

Best Practices

• Principle of Least Privilege: Limit the functionality scope of each tool and only grant necessary permissions.
• Log Auditing: Regularly review operation logs to identify abnormal behavior and potential security vulnerabilities.
• Performance Optimization: Monitor the running status of the service and optimize critical paths to improve response speed.

Project Maintenance

1. Version Control:
   • Use Git for code management and regularly commit change records.
   • Follow the semantic versioning strategy to ensure compatibility and traceability.
2. Dependency Management:
   • Regularly update Go dependency libraries to maintain the security and stability of the project.
   • Monitor changes in dependencies and evaluate their impact on the project.
3. Test Coverage:
   • Write unit tests and integration test cases to ensure the normal operation of each functional module.
   • Use automated testing tools to accelerate the development process and improve code quality.

Appendix

Environment Variable Configuration

# Set the port for the service to run on
export PORT=8090

# Configure the log output directory
export LOG_PATH=./logs

Log Format Example

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

By following the above structure and best practices, you can effectively build a secure, reliable, and easily maintainable command-line tool and service framework.