Metadata-Version: 2.4
Name: mcp-workspace-guardian
Version: 0.5.27
Summary: A workspace guardian MCP server with an easy installer CLI.
Author-email: Antigravity <antigravity@google.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: server
Requires-Dist: mcp>=0.1.0; extra == "server"

# MCP Guard 使用说明书 (Workspace Guardian Manual)

MCP Guard 是一个标准的 Model Context Protocol (MCP) 静态合规守卫与交互式依赖图谱工具，原生支持 Python, C++, Java, Go, Rust, JavaScript, TypeScript 等多语言软件开发。

---

## 🚀 最佳开发流程操作顺序 (Recommended Workflow)

为了获得最佳的软件开发合规与拓扑导航体验，建议您和 AI 智能体按照以下顺序执行指令：

### ➔ 步骤一：工作空间初始化与自举环境就绪 (Initialize & Bootstrap)
在您的项目工作区根目录下运行初始化指令：
```bash
mcp-guard init
```
*   **自适应指纹识别**：系统会自动极速扫描您的项目。如果探测到 `package.xml` 或 ROS 构建关键字，会**自适应额外拷出 ROS 专项规则库 (ros_rules.md)**，否则只拷贝通用规则。
*   **释放软件开发全生命周期规范模板**：初始化时会自动在当前工作区的 `.agents/templates/` 目录中释出四大核心流程骨架文件，引导并强制 AI 智能体规范工作：
    - `RESEARCH_REPORT.md` (系统调研与分析报告模板)
    - `IMPLEMENTATION_PLAN.md` (编码方案与实施设计模板)
    - `TEST_GUIDE.md` (测试自检、通用/ROS 调试打印与一键清理规范)
    - `WALKTHROUGH.md` (交付总结与验收报告模板)
*   **国内极速自举**：若当前系统 Python 版本低于 3.10（如 Ubuntu 20.04 的默认 Python 3.8），系统会在初始化阶段自动安装 `uv` 并下载构建独立的 Python 3.11 虚拟环境。**本项目已默认配置中科大及清华大学高速镜像源**，自动绕过 GitHub 下载超时卡死问题，实现秒级部署。

### ➔ 步骤二：安装集成注册 (Install)
将 MCP 服务器一键注册至您当前使用的 IDE 或 AI 客户端：
```bash
# 注册至 Antigravity IDE (推荐)
mcp-guard install ide

# 注册至 Claude Code CLI 终端工具
mcp-guard install claude

# 注册至 VS Code Cline / Roo-Cline 插件
mcp-guard install cline
```

### ➔ 步骤三：构建代码图谱的三种模式 (Build Modes)
扫描当前工作区所有源文件，根据您的项目架构规模选择以下三种模式之一：

*   **模式一：扁平全景拓扑模式**（适合中小型项目，将所有文件调用画在单张大图里）
    ```bash
    mcp-guard build
    ```
*   **模式二：ROS 轴心下钻模式**（针对 ROS 结构，自动以 `src` 目录为边界划分并生成多子图网页）
    ```bash
    mcp-guard build -src
    ```
*   **模式三：自定义轴心下钻模式**（针对多包或自定义多模块项目，将指定目录如 `packages`、`lib` 等作为划分大节点）
    ```bash
    mcp-guard build --pivot <目录名>
    ```

*   **其他构建参数说明**：
    *   **自适应增量**：比对文件修改时间 `mtime`，未修改的文件 1 毫秒跳过，仅解析变化文件。
    *   **强制全量重建**：若需忽略缓存强行重新扫描并覆盖图谱，请追加 `-f` 或 `--force` 参数，例如：
        ```bash
        mcp-guard build -src -f
        ```

### ➔ 步骤四：渲染交互式图谱 (View)
在系统默认浏览器中打开层级大纲与可视化图谱网络：
```bash
mcp-guard view
```
*   **大纲树折叠**：左侧提供 📁文件夹 ➔ 文件（含语言原生图标）➔ <span style="background:#EE9D28;color:#111;border-radius:3px;padding:0 3px;">C</span> 类 / <span style="background:#7C5BBF;color:#fff;border-radius:3px;padding:0 3px;">ƒ</span> 函数 的 IDE 级折叠大纲，点击自动对齐并平滑 focus 聚焦到拓扑图，右侧面板展示入度与出度依赖详情。
*   **多层级双击下钻**：若您使用了下钻模式（模式二/三），主图网页中展示的是模块级文件夹大节点。您只需在浏览器中**【双击】**这些文件夹节点，页面即可自动深入下钻到该包内部的精细依赖调用子图网页中。
*   **目录拓扑聚焦**：点击目录旁的 🎯 按钮，主图谱自动过滤仅显示该目录内的节点与调用关系，支持跨目录调用边保留。
*   **智能节点唤醒**：即使节点被「隐藏无调用符号」过滤，主动点击大纲中的符号后仍可在图谱中临时显示并聚焦该节点。

### ➔ 步骤五：代码编写与增量强审计 (Audit)
*   **静默看守**：代码编写过程中，AI 智能体会自动调用 MCP 接口校验您修改的文件，防止引入系统命令注入、空捕获、或缺失中文注释。
*   **手动强审计**：您可以在终端随时手动对当前的改动执行强制自检审计：
```bash
mcp-guard audit
```

---

## 🛠️ CLI 命令行参数速查 (--help)

运行 `mcp-guard --help` 可以随时获取最新的中文参数速查表：

*   `mcp-guard init`：在当前工作区初始化助手守则、ROS及通用规则库、生命周期流程规范模板以及使用说明书文件。
*   `mcp-guard build`：扫描并更新图谱。支持 `-src` 轴模式，支持 `--pivot <dir>` 自定义轴模式，支持 `-f / --force` 强制全量重构。
*   `mcp-guard view`：在默认浏览器中渲染并打开层级交互式依赖图谱网页（支持双击节点下钻）。
*   `mcp-guard audit`：手动审计工作区变更文件并提供缺失注释的自愈修复代码。
*   `mcp-guard install <target>`：一键将本 MCP 服务器注册至对应的客户端（如 `ide`、`claude`、`cline` 等）。
*   `mcp-guard uninstall`：一键卸载清理 mcp-guard 在当前工作区内的配置文件、自举虚拟环境并从所有 IDE 绑定中反注册注销服务。
