JARVIS MCP

只是一个相当聪明的系统 - 机器命令代理

JARVIS MCP 是一个轻量级服务器，它通过标准化的 API 接口提供对本地机器命令和文件操作的安全访问。受到托尼·斯塔克的人工智能助手 JARVIS 的启发，JARVIS MCP 充当应用程序和本地系统之间的桥梁。

概述

JARVIS MCP 实现了模型-代码-代理 (MCP) 架构，为应用程序提供了一种安全、标准化的方式来执行命令和在本地机器上执行文件操作。它充当一个中间层，通过定义良好的 API 接受请求，在受控环境中执行操作，并返回格式化的结果。

特性

• 命令执行: 在本地系统上运行 shell 命令，并进行适当的错误处理
• 文件操作: 在本地系统上读取、写入和管理文件
• 目录可视化: 生成文件系统的递归树状视图作为 JSON 结构
• 工作目录支持: 在特定目录中执行命令
• 强大的错误处理: 详细的错误消息和验证
• 全面的输出: 捕获并返回 stdout 和 stderr
• 简单集成: 标准 I/O 接口，易于与各种客户端集成

安装

前提条件

• Go 1.24.1 或更高版本
• Git（用于克隆存储库）

从源代码构建

1. 克隆存储库：

   git clone <repository-url>
   cd jarvis-mcp
   

2. 使用提供的脚本构建应用程序：

   ./build.sh
   

   可执行文件将在 out 目录中创建。

跨平台构建说明

Linux

# 为 Linux 构建（当前架构）
GOOS=linux GOARCH=amd64 go build -o out/jarvis-mcp-linux-amd64 ./cmd/jarvis
chmod +x ./out/jarvis-mcp-linux-amd64

# 对于 ARM64（如 Raspberry Pi）
GOOS=linux GOARCH=arm64 go build -o out/jarvis-mcp-linux-arm64 ./cmd/jarvis
chmod +x ./out/jarvis-mcp-linux-arm64

macOS

# 为 macOS 构建（Intel）
GOOS=darwin GOARCH=amd64 go build -o out/jarvis-mcp-macos-intel ./cmd/jarvis
chmod +x ./out/jarvis-mcp-macos-intel

# 为 macOS 构建（Apple Silicon）
GOOS=darwin GOARCH=arm64 go build -o out/jarvis-mcp-macos-arm64 ./cmd/jarvis
chmod +x ./out/jarvis-mcp-macos-arm64

Windows

# 为 Windows 构建
GOOS=windows GOARCH=amd64 go build -o out/jarvis-mcp-windows-amd64.exe ./cmd/jarvis

用法

运行服务器

执行二进制文件：

# Linux/macOS
./out/jarvis-mcp

# Windows
.\out\jarvis-mcp-windows-amd64.exe

服务器通过标准输入/输出进行通信，使其易于与各种客户端集成。

使用 Claude Desktop 进行配置

JARVIS MCP 旨在通过其工具界面与 Claude Desktop 无缝协作。以下是如何设置它：

设置过程

1. 使用上面的说明为您的平台构建 JARVIS MCP
2. 打开 Claude Desktop 应用程序
3. 访问首选项:
   • macOS：单击菜单栏中的“Claude”，然后选择“首选项”
   • Windows：单击右上角的设置齿轮图标
4. 导航到左侧边栏中的“工具”部分
5. **单击“添加工具”**以创建新的工具配置

配置命令执行工具

1. 配置 execute_command 工具：

   • 名称: 执行命令
   • 描述: 在您的本地机器上执行 shell 命令
   • 路径: jarvis-mcp 二进制文件的完整路径（例如，/Users/username/jarvis-mcp/out/jarvis-mcp）
   • 参数: 留空（服务器使用 stdin/stdout）
   • 工作目录: 可选；指定默认工作目录

2. 保存配置

配置文件操作工具

您可以为特定的文件操作配置其他工具。例如：

1. 配置 read_file 工具：

   • 名称: 读取文件
   • 描述: 读取系统上文件的内容
   • 路径: 与您的 jarvis-mcp 二进制文件相同的路径
   • 参数: 留空

2. 配置 write_file 工具：

   • 名称: 写入文件
   • 描述: 将内容写入系统上的文件
   • 路径: 与您的 jarvis-mcp 二进制文件相同的路径
   • 参数: 留空

3. 按照相同的模式配置以下其他工具：

   • list_directory: 列出目录内容
   • create_directory: 创建新目录
   • move_file: 移动或重命名文件
   • search_files: 搜索文件
   • get_file_info: 获取文件元数据
   • directory_tree: 生成文件和目录的递归树状视图

在对话中使用工具

配置完成后，您可以在与 Claude 的对话中调用这些工具：

1. 键入类似“请显示我的 .bashrc 文件的内容”的请求
2. Claude 将显示一个工具选择界面
3. 选择适当的工具（例如，“读取文件”）
4. Claude 将使用 JARVIS MCP 执行操作
5. 结果将显示在您的对话中

平台特定的路径格式

macOS/Linux

/Users/username/path/to/jarvis-mcp/out/jarvis-mcp

Windows

C:\Users\username\path\to\jarvis-mcp\out\jarvis-mcp-windows-amd64.exe

故障排除

• 工具未响应: 确保二进制文件路径正确且文件可执行
• 权限错误: 检查 Claude Desktop 是否有权执行二进制文件
• 路径问题: 使用绝对路径以避免工作目录问题
• 执行错误: 确保该工具具有访问请求的文件/目录的适当权限

API 参考

JARVIS MCP 通过其 API 公开以下工具：

命令工具

execute_command

在本地系统上执行 shell 命令。

参数：

• command（字符串，必需）：要执行的 shell 命令
• working directory（字符串，可选）：应在其中执行命令的目录

返回：

• 成功时：命令输出 (stdout)
• 失败时：错误消息和任何命令输出 (stderr)

文件系统工具

read_file

读取文件的内容。

参数：

• path（字符串，必需）：要读取的文件的路径

返回：

• 成功时：文件内容
• 失败时：错误消息

write_file

将内容写入文件。

参数：

• path（字符串，必需）：将写入文件的路径
• content（字符串，必需）：要写入文件的内容

返回：

• 成功时：成功消息
• 失败时：错误消息

create_directory

创建一个新目录。

参数：

• path（字符串，必需）：要创建的目录的路径

返回：

• 成功时：成功消息
• 失败时：错误消息

list_directory

列出目录的内容。

参数：

• path（字符串，必需）：要列出的目录的路径

返回：

• 成功时：文件和目录的列表，带有 [FILE] 和 [DIR] 指示符
• 失败时：错误消息

move_file

移动或重命名文件和目录。

参数：

• source（字符串，必需）：要移动的文件或目录的源路径
• destination（字符串，必需）：文件或目录将移动到的目标路径

返回：

• 成功时：成功消息
• 失败时：错误消息

search_files

搜索与模式匹配的文件。

参数：

• path（字符串，必需）：搜索的起始路径
• pattern（字符串，必需）：用于匹配文件和目录名称的搜索模式

返回：

• 成功时：匹配文件的列表
• 失败时：错误消息

get_file_info

检索有关文件或目录的详细元数据。

参数：

• path（字符串，必需）：要获取信息的文件或目录的路径

返回：

• 成功时：带有文件元数据（名称、大小、模式、修改时间等）的 JSON
• 失败时：错误消息

directory_tree

生成文件和目录的递归树状视图。

参数：

• path（字符串，必需）：从中生成树的目录的路径

返回：

• 成功时：表示目录树的 JSON 结构
• 失败时：错误消息

架构

JARVIS MCP 构建在 MCP Go 框架 之上，该框架实现了模型-代码-代理模式。该架构包括：

1. 请求处理: 解析和验证传入的请求
2. 命令执行: 以受控方式运行系统命令
3. 文件操作: 从本地系统上的文件读取和写入
4. 响应格式化: 提供结构化、信息丰富的响应

项目结构

jarvis-mcp/
├── build.sh                    # 构建脚本
├── cmd/                        # 应用程序入口点
│   └── jarvis/                 # 主要 JARVIS MCP 应用程序
│       └── main.go             # 应用程序入口点
├── pkg/                        # 库包
│   ├── shell/                  # Shell 命令执行包
│   │   ├── execute_command.go  # 命令执行功能
│   │   └── shell.go            # 核心 shell 操作函数
│   ├── utils/                  # 实用程序函数
│   │   └── utils.go            # 实用程序辅助函数
│   └── files/                  # 文件操作包
│       ├── files.go            # 核心文件操作函数
│       ├── files_test.go       # 文件操作测试
│       ├── read_file.go        # 读取文件工具实现
│       ├── write_file.go        # 写入文件工具实现
│       ├── create_directory.go # 创建目录工具实现
│       ├── list_directory.go   # 列出目录工具实现
│       ├── move_file.go        # 移动文件工具实现
│       ├── search_files.go     # 搜索文件工具实现
│       ├── file_info.go        # 获取文件信息工具实现
│       └── directory_tree.go   # 目录树工具实现
├── go.mod                      # Go 模块定义
├── go.sum                      # Go 模块校验和
├── go.work                     # Go 工作区文件
├── go.work.sum                 # Go 工作区校验和
└── out/                        # 构建输出
    └── jarvis-mcp              # 编译后的二进制文件

安全注意事项

JARVIS MCP 提供对本地系统上执行命令和文件操作的直接访问。请考虑以下安全实践：

• 以适当的权限运行（避免以 root/管理员身份运行）
• 仅在受信任的环境中使用
• 考虑为生产用途实施额外的授权机制
• 谨慎选择允许命令执行和文件操作的目录
• 实施路径验证以防止未经授权访问系统文件

平台特定的安全说明

Linux/macOS

• 使用具有有限权限的专用用户运行
• 考虑使用 chroot 环境来限制文件系统访问
• 使用 chmod 限制可执行权限：chmod 700 jarvis-mcp

Windows

• 以标准用户身份运行，而不是管理员
• 考虑使用 Windows 安全功能来限制访问
• 使用文件夹/文件权限来限制对敏感目录的访问

开发

添加新工具

要使用其他功能扩展 JARVIS MCP，请按照以下模式在适当的包中创建一个新文件：

package mypackage

import (
    "context"
    "errors"

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

func GetMyTool() (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("my_tool",
        mcp.WithDescription("工具的描述"),
        mcp.WithString("param_name",
            mcp.Required(),
            mcp.Description("参数描述"),
        ),
    ), myToolHandler
}

func myToolHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // 参数验证
    param, ok := request.Params.Arguments["param_name"].(string)
    if !ok {
        return nil, errors.New("parameter is required")
    }

    // 工具实现
    result, err := doSomething(param)
    if err != nil {
        return nil, err
    }

    return mcp.NewToolResultText(result), nil
}

然后在 cmd/jarvis/main.go 中注册该工具：

mcpServer.AddTool(mypackage.GetMyTool())

许可证

[在此处指定您的许可证]

致谢

• 使用 MCP Go 框架 构建
• 灵感来自漫威电影宇宙中托尼·斯塔克的 JARVIS