MCP Grok

mcp grok

基于FastMCP构建的安全、面向项目的持久shell管理服务器。通过快速、无状态的JSON-RPC API实现强健、可审核的远程shell执行和项目环境管理。

特性

• 持久的沙盒项目shell：每个项目都有自己的登录shell子进程，以特定用户身份运行（默认值： michi).
• 无状态、基于JSON的API：所有操作（创建项目、切换、运行shell命令、列出项目、查询活动项目）都通过FastMCP工具公开。
• 线程安全、健壮的shell管理：每个项目只有一个会话外壳，具有强大的锁定和管道安全性。
• 自动记录：所有会话事件和输出都记录到 server_audit.log 以及stdout。
• 可通过CLI配置：启动时设置端口、项目目录和默认项目名称。
• 已测试并准备生产：通过广泛而现实的端到端测试。

需求

• Python 3.12+
• 尼克斯 （对于可重复的开发环境，请通过 nix-shell)
• 或者：在中安装Python依赖项 pyproject.toml (mcp[cli], prompt-toolkit, pytest等）

快速入门

# Clone the repository
$ git clone https://github.com/MBanucu/mcp-grok.git
$ cd mcp-grok

# Start the MCP-Grok server using flakes (recommended)
$ nix develop .#
# an interactive project management menu will pop up
# start the MCP Server and the SuperAssistant Proxy

# Start the MCP-Grok server manually
$ nix develop .#menuSuppressed --command python -m mcp_grok.mcp_grok_server

# Or with options using mcp-grok-server:
$ nix develop .#menuSuppressed --command python -m mcp_grok.mcp_grok_server --port 8099 --projects-dir ~/dev/my-projects --default-project testproject

# Start the SuperAssistant Proxy manually
$ nix develop .#menuSuppressed --command superassistant-proxy

高级： 对于要抑制交互式菜单的环境（如CI、脚本或自动化），请使用 menuSuppressed 镍片外壳： ``sh nix develop .#menuSuppressed ` 对于直接命令行使用，请始终将shell命令包装在 sh -c '...': `sh nix develop .#menuSuppressed --command sh -c 'python -m pytest tests' `` 这保证了shell的设置与开发完全相同，没有交互式菜单，可以完全访问所有CLI工具。

默认情况下，服务器在本地运行，监听配置的端口，并在以下位置公开与FastMCP兼容的HTTP+JSON端点 /mcp （通常，例如。http://localhost:8000/mcp).

用法/API

您通过JSON-RPC POST请求与服务器通信。示例工具及其用途：

• execute_shell（命令：str）： 在当前活动的持久shell中执行shell命令。
• create_new_project（项目名称：str）： 创建新的持久项目目录并启动一个干净的shell。
• change_active_project（项目名称：str）： 切换到另一个项目（如果存在）并运行其shell。
• list_all_projects（）： 列出所有可用的项目目录。
• get_active_project（）： 返回当前活动项目的结构化信息（名称、绝对路径）。

示例：运行命令

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_shell",
    "arguments": {"command": "whoami"}
  }
}

示例：创建新项目

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_new_project",
    "arguments": {"project_name": "myproject"}
  }
}

看 tests/test_mcp.py 了解更多编程使用模式和预期输出。

代码质量：Linting和类型检查

此项目使用linter和静态类型检查器，就像在CI中一样。您可以按如下方式在本地运行它们（使用推荐的Nix环境）：

用高脚片打毛8

薄片8 检查代码中常见的样式、错误和复杂性问题。

nix develop .#menuSuppressed --command sh -c 'flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics && flake8 src tests --count --max-complexity=10 --max-line-length=127 --statistics'

• 第一次运行强制执行严格的错误；第二种提供具有宽松规则（如行长度和复杂性）的统计数据，与CI匹配。

使用pyright进行类型检查

火葬场 为Python执行静态类型检查。

nix develop .#menuSuppressed --command pyright .

• 这将检查整个项目中的类型错误，如CI。

运行测试

nix develop .#menuSuppressed --command python -m pytest tests

测试在子流程中启动服务器，模拟真实的工具API请求，然后自行清理。涵盖了所有主要功能，包括项目管理、外壳执行、API错误处理和会话管理。

项目结构

• src/mcp_grok/mcp_grok_server.py ：主服务器入口；所有的逻辑。
• tests/ ：基于Pytest的功能和集成测试。
• pyproject.toml ：依赖关系和构建配置。

安全说明

警告：切勿将此服务器暴露于公共互联网，因为它允许shell访问，尽管每个项目/用户都严格沙盒。

NixOS系统集成和高级使用

在NixOS中用作系统包

如果你想提供 mcp-grok-server 作为NixOS上使用flake的系统包，将此flake作为输入添加到NixOS配置中：

# In your flakes-enabled NixOS configuration (flake.nix):
{
  inputs.mcp-grok.url = "github:MBanucu/mcp-grok";

  outputs = { self, nixpkgs, mcp-grok, ... }@inputs: {
    nixosConfigurations.mymachine = nixpkgs.lib.nixosSystem {
      # ...
      environment.systemPackages = [ mcp-grok.packages.${inputs.nixpkgs.system}.default ];
      # ...
    };
  };
}

如果不使用薄片，请参阅下面的叠加/传统用法以了解兼容性。

用作另一个flake项目的输入

您可以将此项目作为输入添加到您自己的基于flake的Python/Nix项目中：

# In your flake.nix
{
  inputs.mcp-grok.url = "github:MBanucu/mcp-grok";

  outputs = { self, nixpkgs, mcp-grok, ... }@inputs: {
    # ...
    packages.${self.system}.mcp-grok = mcp-grok.packages.${self.system}.default;
    devShells.${self.system}.with-mcp-grok = nixpkgs.legacyPackages.${self.system}.mkShell {
      buildInputs = [ mcp-grok.packages.${self.system}.default ];
    };
  };
}

叠加/遗留使用

如果不使用薄片，您仍然可以使用此项目的 default.nix 作为覆盖层。 配置示例。ix：

重要提示： 首次启用实验特征/薄片时： 你必须 注释掉 这 environment.systemPackages = with pkgs; [ mcp-grok ]; 下面是您的初始重建，因为Nix在薄片形成之前不会知道mcp-grok。只有在第一次成功后才取消承诺 nixos-rebuild 启用flakes后，否则将出现构建错误。

{ config, pkgs, ... }:

{
  nix.settings.experimental-features = [
    "nix-command"
    "flakes"
  ];

  nixpkgs.overlays = [
    (
      self: super:
      {
        mcp-grok = import (builtins.fetchGit {
          url = "https://github.com/MBanucu/mcp-grok.git";
        });
      }
    )
  ];

  # Comment out the lines below for your initial rebuild before enabling flakes
  environment.systemPackages = with pkgs; [
    mcp-grok
  ];
  # Uncomment them after the first successful nixos-rebuild with flakes enabled
}

提供的 default.nix 透明地转发到薄片包，以实现作为覆盖层或与传统产品的最大兼容性 nix-build.

贡献

为该项目做出贡献：

• 分支机构和PR：避免直接推到 main 支。为您的更改创建一个功能分支，并提交Pull Request（PR）以供审查和集成。
• 代码质量：遵循上述“代码质量”部分中的linting和类型检查指南。
• 测试：在提交PR之前，确保所有测试都通过。

______________________________________________________________________

快乐地探索，并随时贡献或提交问题！