chore: README MCP 章节 + CI 装 mcp 依赖 + 全仓 ruff 债务清零

- README/zh：修正过期「MCP 未发布」表行，新增镜像 MCP 章节（parity 5/5）
- skills-check.yml：unittest 前 pip install requirements.txt（MCP 测试不 skip）
- .gitignore：out/
- tasks.md：组 1-6 勾选 24/29，3.1 更正为根 requirements.txt + CI 安装
- 全仓 ruff 41 项清零（PLW1510 check=False / BLE001 fail-open noqa /
  EXE 位 / RUF059 改名 / SIM115-402 / TRY004 保型 noqa）——
  提交门禁跑全仓 ruff check .，债务不清则任何提交都过不了

Author: loong10k

.github/workflows/skills-check.yml

@@ -15,6 +15,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+      - name: Install requirements (mcp SDK so MCP server tests run, not skip)
+        run: python3 -m pip install --disable-pip-version-check -r requirements.txt
       - name: Verify vendored skills match the lockfile digests
         run: python3 scripts/vendor/skill_vendor.py check --offline
       - name: Verify lockfile pins still match upstream refs and content

.gitignore

@@ -19,3 +19,5 @@ build/
 dist/
 htmlcov/
 Thumbs.db
+# codeguard 失败日志落盘目录
+out/

README.md

@@ -70,7 +70,7 @@ AI code that passes lint on first try
 | Current version | `0.6.7` |
 | ZCode manifest | `.zcode-plugin/plugin.json` |
 | Codex manifest | `.codex-plugin/plugin.json` |
-| MCP server | Not published until the SDK-backed protocol implementation is ready; use the CLI and hooks |
+| MCP server | Published: stdio server via the official SDK (`check_code_style` / `auto_fix` / `list_languages`); see Quick start |
 | Primary language | Python 3.10+ (hooks), YAML/JSON (config) |
 | License | Apache-2.0 |
 
@@ -199,6 +199,25 @@ When this plugin is active, you do **not** need to do anything manually:
 - When the user says "commit", you will receive a final all-linters-must-pass gate check.
 - At session end, you will see a summary of which lints passed/failed.
 
+### MCP server
+
+`run_check.py --mcp` starts a stdio MCP server (official `mcp` SDK; install
+dependencies with `pip install -r requirements.txt`) exposing three tools:
+
+| Tool | Purpose |
+|---|---|
+| `check_code_style` | Run lint and return a per-language envelope with `stderr_path` and `log_path` |
+| `auto_fix` | Run the formatter chain, then re-run lint and embed the check envelope |
+| `list_languages` | List supported language ids and display names (no internal commands) |
+
+```bash
+python3 scripts/run_check.py --mcp .
+```
+
+Failed runs write the full combined output to `<project>/out/.codeguard-last.log`
+(the same path appears in the tool envelope and the CLI summary line; suppress
+with `--quiet`).
+
 ## Configuration
 
 User config in `~/.zcode/settings.local.yaml` (ZCode) or equivalent for other hosts:

README.zh-CN.md

@@ -70,7 +70,7 @@ AI 一次写出就过 lint 的代码
 | 当前版本 | `0.6.7` |
 | ZCode manifest | `.zcode-plugin/plugin.json` |
 | Codex manifest | `.codex-plugin/plugin.json` |
-| MCP 服务 | SDK 协议实现完成前不随清单发布；当前使用 CLI 与 Hooks |
+| MCP 服务 | 已发布：官方 SDK stdio 服务（`check_code_style` / `auto_fix` / `list_languages`）；见快速开始 |
 | 主要语言 | Python 3.10+（钩子）、YAML/JSON（配置） |
 | 协议 | Apache-2.0 |
 
@@ -184,6 +184,24 @@ ln -s $PWD ~/.kimi/plugins/partme-codeguard-plugin
 - 用户说「commit」时，你会受到「所有 linter 必须通过」的最后门禁
 - 会话结束时会看到本会话 lint 通过/失败的总结
 
+### MCP 服务器
+
+`run_check.py --mcp` 启动 stdio MCP 服务（官方 `mcp` SDK；先用
+`pip install -r requirements.txt` 安装依赖），暴露三个工具：
+
+| 工具 | 用途 |
+|---|---|
+| `check_code_style` | 跑 lint，返回逐语言信封与 `stderr_path`、`log_path` |
+| `auto_fix` | 先跑 formatter 链再复检 lint（嵌入 check 信封） |
+| `list_languages` | 列出语言 id 与显示名（不含内部命令） |
+
+```bash
+python3 scripts/run_check.py --mcp .
+```
+
+失败时完整输出落盘到 `<项目根>/out/.codeguard-last.log`（与工具信封及 CLI
+摘要行里的路径一致；`--quiet` 可关闭）。
+
 ## 配置
 
 `~/.zcode/settings.local.yaml`（ZCode）或各平台对应文件：

hooks/env_check.py

@@ -7,7 +7,6 @@
 3. 输出一段 AGENTS.md 风格的提示，让 AI 知道自己在一个被 codeguard 管理的项目里
 """
 import os
-import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -129,6 +128,6 @@ def main() -> int:
         sys.exit(main())
     except SystemExit:
         raise
-    except Exception as exc:  # 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
+    except Exception as exc:  # noqa: BLE001 — 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
         print(f"[codeguard] 内部错误已忽略（fail-open）: {exc!r}", file=sys.stderr)
         sys.exit(0)

hooks/gate_lib.py

@@ -17,11 +17,13 @@
 PLUGIN_ROOT = Path(__file__).resolve().parents[1]   # hooks/ 的上级 = 插件根
 sys.path.insert(0, str(PLUGIN_ROOT / "scripts"))
 
-from detect_lang import (  # noqa: E402
-    LANG_COMMANDS, detect_languages, load_user_config, project_uses_linter, probe_toolchain,
+from detect_lang import (
+    LANG_COMMANDS,
+    detect_languages,
+    probe_toolchain,
+    project_uses_linter,
 )
 
-
 # === git 提交内容安全检查：绝不该进版本库的文件 ===
 # 目录（路径任一段落匹配即违规）：依赖/虚拟环境/构建产物/IDE/缓存
 GUARD_EXCLUDE_DIRS = {
@@ -43,7 +45,7 @@ def _git(project_root: Path, *args: str) -> str | None:
     """跑只读 git 命令；失败（非 git 仓/无 upstream 等）返回 None，由调用方降级"""
     try:
         proc = subprocess.run(
-            ["git", *args], cwd=project_root, capture_output=True, text=True, timeout=15
+            ["git", *args], cwd=project_root, capture_output=True, check=False, text=True, timeout=15
         )
     except (subprocess.TimeoutExpired, OSError, FileNotFoundError):
         return None
@@ -101,7 +103,8 @@ def format_safety_report(violations: list[tuple[str, str, str]]) -> str:
 
 
 def _gate_cache_path(project_root: Path) -> Path:
-    import hashlib, tempfile
+    import hashlib
+    import tempfile
     key = hashlib.sha1(str(project_root.resolve()).encode()).hexdigest()[:12]
     return Path(tempfile.gettempdir()) / f"codeguard-gate-{os.getuid()}-{key}.json"
 
@@ -191,7 +194,7 @@ def check(lang: str):
             return (lang, None, f"{lang} 项目未接入（缺 linter 配置文件），本次未验证")
         try:
             proc = subprocess.run(
-                gate_cmd, cwd=project_root, capture_output=True, text=True, timeout=timeout
+                gate_cmd, cwd=project_root, capture_output=True, check=False, text=True, timeout=timeout
             )
         except subprocess.TimeoutExpired:
             return (lang, None, f"{lang} 检查超时（>{timeout}s），本次未验证")
@@ -217,7 +220,7 @@ def check(lang: str):
     for r in results:              # pool.map 保序，输出与语言表顺序一致
         if r is None:
             continue
-        lang, failure, skip = r
+        _, failure, skip = r
         if failure:
             failures.append(failure)
         if skip:

hooks/post_tool_lint.py

@@ -133,7 +133,7 @@ def is_ejs_template(file_path: str) -> bool:
 
 def run(cmd: list[str], cwd: Path, timeout: int = 300) -> tuple[int, str, str]:
     try:
-        proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+        proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout, check=False)
         return proc.returncode, proc.stdout, proc.stderr
     except subprocess.TimeoutExpired:
         return 124, "", f"timeout after {timeout}s"
@@ -293,6 +293,6 @@ def materialize(cmd: list[str]) -> list[str]:
         sys.exit(main())
     except SystemExit:
         raise
-    except Exception as exc:  # 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
+    except Exception as exc:  # noqa: BLE001 — 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
         print(f"[codeguard] 内部错误已忽略（fail-open）: {exc!r}", file=sys.stderr)
         sys.exit(0)

hooks/pre_tool_git_guard.py

@@ -11,17 +11,17 @@
 from __future__ import annotations
 
 import json
-import subprocess
 import os
+import subprocess
 import sys
 from pathlib import Path
 
 PLUGIN_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(PLUGIN_ROOT / "scripts"))
 sys.path.insert(0, str(PLUGIN_ROOT / "hooks"))
 
-from detect_lang import ensure_user_path, find_project_root, load_user_config  # noqa: E402
-from gate_lib import (  # noqa: E402
+from detect_lang import ensure_user_path, load_user_config
+from gate_lib import (
     check_commit_safety,
     format_safety_report,
     gate_directive,
@@ -51,7 +51,7 @@ def _is_git_repo(p: Path) -> bool:
     try:
         proc = subprocess.run(
             ["git", "-C", str(p), "rev-parse", "--git-dir"],
-            capture_output=True, text=True, timeout=10,
+            capture_output=True, check=False, text=True, timeout=10,
         )
     except (subprocess.TimeoutExpired, OSError):
         return False
@@ -113,7 +113,7 @@ def skip_gate_via_git_config(project_root: Path) -> bool:
     try:
         proc = subprocess.run(
             ["git", "config", "--get", "codeguard.skipGate"],
-            cwd=project_root, capture_output=True, text=True, timeout=10,
+            cwd=project_root, capture_output=True, check=False, text=True, timeout=10,
         )
     except (subprocess.TimeoutExpired, OSError):
         return False
@@ -165,6 +165,6 @@ def main() -> int:
         sys.exit(main())
     except SystemExit:
         raise
-    except Exception as exc:  # 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
+    except Exception as exc:  # noqa: BLE001 — 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
         print(f"[codeguard] 内部错误已忽略（fail-open）: {exc!r}", file=sys.stderr)
         sys.exit(0)

hooks/stop_summary.py

@@ -57,6 +57,6 @@ def main() -> int:
         sys.exit(main())
     except SystemExit:
         raise
-    except Exception as exc:  # 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
+    except Exception as exc:  # noqa: BLE001 — 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
         print(f"[codeguard] 内部错误已忽略（fail-open）: {exc!r}", file=sys.stderr)
         sys.exit(0)

hooks/user_prompt_validator.py

@@ -19,21 +19,26 @@
 sys.path.insert(0, str(PLUGIN_ROOT / "scripts"))
 sys.path.insert(0, str(PLUGIN_ROOT / "hooks"))
 
-from detect_lang import detect_languages, ensure_user_path, find_project_root, load_user_config  # noqa: E402
-from gate_lib import (  # noqa: E402
+# 触发此钩子的关键词（中英）
+# 英文按词边界匹配（防止 pushed/deployment 误命中），中文子串即可。
+# 2026-09-22 实测回归：`我刚才 pushed 了`、`关于 deployment 策略的讨论`
+# 必须静默（子串匹配曾把它们当提交意图跑全仓 lint）。
+import re as _re
+
+from detect_lang import (
+    detect_languages,
+    ensure_user_path,
+    find_project_root,
+    load_user_config,
+)
+from gate_lib import (
     check_commit_safety,
     format_safety_report,
     gate_directive,
     run_gate,
     summarize_failures,
 )
 
-# 触发此钩子的关键词（中英）
-# 英文按词边界匹配（防止 pushed/deployment 误命中），中文子串即可。
-# 2026-09-22 实测回归：`我刚才 pushed 了`、`关于 deployment 策略的讨论`
-# 必须静默（子串匹配曾把它们当提交意图跑全仓 lint）。
-import re as _re
-
 TRIGGER_PATTERNS = [
     "commit", "push", "deploy", "提交", "发布", "部署",
 ]
@@ -178,6 +183,6 @@ def main() -> int:
         sys.exit(main())
     except SystemExit:
         raise
-    except Exception as exc:  # 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
+    except Exception as exc:  # noqa: BLE001 — 内部错误 fail-open：traceback 绝不进 AI 上下文/阻断工作流
         print(f"[codeguard] 内部错误已忽略（fail-open）: {exc!r}", file=sys.stderr)
         sys.exit(0)