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之前，确保所有测试都通过。
______________________________________________________________________
快乐地探索，并随时贡献或提交问题！