@hunyed15/codecgc 0.1.1 → 0.1.3

package/INSTALLATION.md

@@ -47,6 +47,24 @@ npm install -g @hunyed15/codecgc --registry=https://registry.npmjs.org/
 cgc-install --mode user
 ```
 
+这会写入：
+
+- `~/.claude/mcp.json`
+- `~/.claude/hooks/route-edit.ps1`
+- `~/.claude/commands/cgc.md`
+- `~/.claude/commands/cgc-install.md`
+- `~/.claude/commands/cgc-status.md`
+- `~/.claude/commands/cgc-doctor.md`
+
+写入完成后，可以在 Claude 中直接输入：
+
+```text
+/cgc
+/cgc-install
+/cgc-status
+/cgc-doctor
+```
+
 如果安装阶段因为 Python 未就绪而跳过了这一步，可以在装好 Python 后手动补执行该命令。
 
 安装后，以下命令将全局可用：

package/README.md

@@ -1,4 +1,4 @@
-# CodeCGC Release v0.1.1
+# CodeCGC Release v0.1.2
 
 ## 📦 发布内容
 
@@ -6,7 +6,7 @@
 
 ## 📋 版本信息
 
-- **版本号**: 0.1.1
+- **版本号**: 0.1.2
 - **发布日期**: 2026-05-04
 - **Python 要求**: >= 3.10
 - **Node.js 要求**: >= 20.0.0
@@ -46,7 +46,41 @@ pip install pyyaml
 cgc-install --mode user
 ```
 
-全局安装完成后，CodeCGC 会尝试自动写入 Claude 用户级集成到 `~/.claude`。
+全局安装完成后，CodeCGC 会尝试自动写入 Claude 用户级集成到 `~/.claude`，包括：
+
+- `~/.claude/mcp.json`
+- `~/.claude/hooks/route-edit.ps1`
+- `~/.claude/commands/cgc*.md` 自定义 slash commands
+
+当前安装链路还会注册 3 个 MCP server：
+
+- `codecgc`：CodeCGC 编排器 MCP
+- `codex`：后端执行器 MCP
+- `gemini`：前端执行器 MCP
+
+安装完成后，可以在 Claude 中直接使用：
+
+- `/cgc`
+- `/cgc-install`
+- `/cgc-status`
+- `/cgc-doctor`
+- `/cgc-plan`
+- `/cgc-build`
+- `/cgc-fix`
+- `/cgc-test`
+- `/cgc-review`
+- `/cgc-route`
+- `/cgc-history`
+- `/cgc-package-audit`
+- `/cgc-external-audit`
+- `/cgc-release-readiness`
+- `/cgc-lifecycle`
+
+当前这些 Claude commands 已调整为：
+
+- 优先走 `codecgc` MCP orchestrator
+- 只有在 MCP tool 路径不可用时，才回退到本地 CLI
+
 如果安装时 Python 尚未就绪，自动集成会跳过，此时可在安装 Python 后手动执行 `cgc-install --mode user`。
 
 ### 2. 初始化项目

package/codecgcmcp/README.md

@@ -0,0 +1,17 @@
+# CodeCGC MCP Server
+
+This package contains the first minimal CodeCGC orchestrator MCP server.
+
+Current scope:
+
+- install
+- status
+- doctor
+- entry
+- continue
+- explain
+- review
+- history
+- route
+
+This server currently reuses the existing CodeCGC runtime scripts rather than replacing them.

package/codecgcmcp/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codecgcmcp"
+version = "0.1.0"
+description = "FastMCP orchestrator server for CodeCGC."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp[cli]>=1.21.2",
+]
+
+[project.scripts]
+codecgcmcp = "codecgcmcp.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codecgcmcp"]

package/codecgcmcp/src/codecgcmcp/__init__.py

@@ -0,0 +1 @@
+"""CodeCGC MCP orchestrator package."""

package/codecgcmcp/src/codecgcmcp/cli.py

@@ -0,0 +1,12 @@
+"""Console entry point for the CodeCGC MCP server."""
+
+from codecgcmcp.server import run
+
+
+def main() -> None:
+    """Start the CodeCGC MCP server."""
+    run()
+
+
+if __name__ == "__main__":
+    main()

package/codecgcmcp/src/codecgcmcp/server.py

@@ -0,0 +1,525 @@
+"""FastMCP server implementation for the CodeCGC orchestrator."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult
+from mcp.types import TextContent
+from pydantic import Field
+
+from codecgc_workflow_runtime import run_json_script
+
+mcp = FastMCP("CodeCGC MCP Server")
+
+
+def _append_repeated_flag(args: list[str], flag: str, values: list[str]) -> None:
+    for value in values:
+        text = str(value).strip()
+        if text:
+            args.extend([flag, text])
+
+
+def _normalize_workspace(workspace: str) -> str:
+    return str(Path(workspace).expanduser().resolve()) if str(workspace).strip() else ""
+
+
+def _as_tool_result(payload: dict[str, Any]) -> CallToolResult:
+    return CallToolResult(
+        content=[
+            TextContent(
+                type="text",
+                text=json.dumps(payload, ensure_ascii=True, indent=2),
+            )
+        ],
+        isError=not bool(payload.get("success", True)),
+    )
+
+
+@mcp.tool(
+    name="codecgc.install",
+    description="Install or sync CodeCGC integration for the current project or Claude user profile.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_install(
+    mode: Annotated[
+        Literal["local", "user-dry-run", "user", "status", "doctor"],
+        Field(description="Install mode for CodeCGC integration."),
+    ] = "local",
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Output format. Use summary for normal product-facing replies."),
+    ] = "summary",
+    workspace: Annotated[
+        str,
+        Field(description="Optional target workspace root for local/status/doctor modes."),
+    ] = "",
+    user_root: Annotated[
+        str,
+        Field(description="Optional explicit Claude user root for user/user-dry-run modes."),
+    ] = "",
+) -> CallToolResult:
+    args = ["--mode", mode, "--format", format]
+    normalized_workspace = _normalize_workspace(workspace)
+    if normalized_workspace:
+        args.extend(["--workspace", normalized_workspace])
+    if str(user_root).strip():
+        args.extend(["--user-root", str(user_root).strip()])
+    return _as_tool_result(run_json_script("install_codecgc.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.status",
+    description="Check CodeCGC integration readiness for the current or specified workspace.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_status(
+    workspace: Annotated[
+        str,
+        Field(description="Optional target workspace root."),
+    ] = "",
+) -> CallToolResult:
+    args = ["--mode", "status", "--format", "json"]
+    normalized_workspace = _normalize_workspace(workspace)
+    if normalized_workspace:
+        args.extend(["--workspace", normalized_workspace])
+    return _as_tool_result(run_json_script("install_codecgc.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.doctor",
+    description="Run CodeCGC runtime and integration health checks.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_doctor(
+    workspace: Annotated[
+        str,
+        Field(description="Optional target workspace root."),
+    ] = "",
+) -> CallToolResult:
+    args = ["--mode", "doctor", "--format", "json"]
+    normalized_workspace = _normalize_workspace(workspace)
+    if normalized_workspace:
+        args.extend(["--workspace", normalized_workspace])
+    return _as_tool_result(run_json_script("install_codecgc.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.entry",
+    description="Primary CodeCGC orchestration entry for new requests, continue, explain, and auto-dispatch decisions.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_entry(
+    request: Annotated[str, "Natural-language request for CodeCGC."] = "",
+    mode: Annotated[
+        Literal["auto", "new", "continue", "explain"],
+        Field(description="Entry mode."),
+    ] = "auto",
+    flow: Annotated[
+        Literal["", "feature", "issue"],
+        Field(description="Optional explicit workflow flow."),
+    ] = "",
+    slug: Annotated[str, "Optional workflow slug."] = "",
+    latest: Annotated[bool, "Use the latest matching workflow."] = False,
+    include_fixtures: Annotated[bool, "Allow fixture workflows to be considered."] = False,
+    auto_dispatch: Annotated[bool, "Allow entry to dispatch when the route permits it."] = False,
+    dry_run: Annotated[bool, "Avoid real executor dispatch."] = False,
+    audit_file: Annotated[str, "Optional audit file for review dispatch."] = "",
+    decision: Annotated[
+        Literal["", "accepted", "changes-requested"],
+        Field(description="Optional review decision when the request is review-like."),
+    ] = "",
+) -> CallToolResult:
+    args = ["--mode", mode]
+    if str(request).strip():
+        args.extend(["--request", str(request).strip()])
+    if flow:
+        args.extend(["--flow", flow])
+    if str(slug).strip():
+        args.extend(["--slug", str(slug).strip()])
+    if latest:
+        args.append("--latest")
+    if include_fixtures:
+        args.append("--include-fixtures")
+    if auto_dispatch:
+        args.append("--auto-dispatch")
+    if dry_run:
+        args.append("--dry-run")
+    if str(audit_file).strip():
+        args.extend(["--audit-file", str(audit_file).strip()])
+    if decision:
+        args.extend(["--decision", decision])
+    return _as_tool_result(run_json_script("entry_codecgc_workflow.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.continue",
+    description="Continue the current or latest CodeCGC workflow using the existing runtime state.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_continue(
+    request: Annotated[str, "Optional continue request text. Defaults to continuing the current work."] = "继续刚刚的工作",
+    flow: Annotated[
+        Literal["", "feature", "issue"],
+        Field(description="Optional explicit workflow flow."),
+    ] = "",
+    slug: Annotated[str, "Optional workflow slug."] = "",
+    latest: Annotated[bool, "Use the latest matching workflow."] = True,
+    include_fixtures: Annotated[bool, "Allow fixture workflows to be considered."] = False,
+    auto_dispatch: Annotated[bool, "Allow continue to dispatch when the route permits it."] = False,
+    dry_run: Annotated[bool, "Avoid real executor dispatch."] = False,
+) -> CallToolResult:
+    args = ["--mode", "continue", "--request", str(request).strip() or "继续刚刚的工作"]
+    if flow:
+        args.extend(["--flow", flow])
+    if str(slug).strip():
+        args.extend(["--slug", str(slug).strip()])
+    if latest:
+        args.append("--latest")
+    if include_fixtures:
+        args.append("--include-fixtures")
+    if auto_dispatch:
+        args.append("--auto-dispatch")
+    if dry_run:
+        args.append("--dry-run")
+    return _as_tool_result(run_json_script("entry_codecgc_workflow.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.explain",
+    description="Explain the current or latest CodeCGC workflow state and recommended next action.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_explain(
+    request: Annotated[str, "Optional explain request text."] = "现在下一步该做什么",
+    flow: Annotated[
+        Literal["", "feature", "issue"],
+        Field(description="Optional explicit workflow flow."),
+    ] = "",
+    slug: Annotated[str, "Optional workflow slug."] = "",
+    latest: Annotated[bool, "Use the latest matching workflow."] = True,
+    include_fixtures: Annotated[bool, "Allow fixture workflows to be considered."] = False,
+) -> CallToolResult:
+    args = ["--mode", "explain", "--request", str(request).strip() or "现在下一步该做什么"]
+    if flow:
+        args.extend(["--flow", flow])
+    if str(slug).strip():
+        args.extend(["--slug", str(slug).strip()])
+    if latest:
+        args.append("--latest")
+    if include_fixtures:
+        args.append("--include-fixtures")
+    return _as_tool_result(run_json_script("entry_codecgc_workflow.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.review",
+    description="Review a CodeCGC execution audit and write the decision back to workflow artifacts.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_review(
+    audit_file: Annotated[str, "Execution audit JSON file path."],
+    decision: Annotated[
+        Literal["accepted", "changes-requested"],
+        Field(description="Requested review decision."),
+    ],
+    risk: Annotated[list[str], Field(description="Optional remaining risks to record.")] = [],
+    next_step: Annotated[str, "Optional next-step text to record."] = "",
+    force: Annotated[bool, "Allow overwriting an existing review writeback."] = False,
+) -> CallToolResult:
+    args = ["--audit-file", str(audit_file).strip(), "--decision", decision]
+    _append_repeated_flag(args, "--risk", risk)
+    if str(next_step).strip():
+        args.extend(["--next-step", str(next_step).strip()])
+    if force:
+        args.append("--force")
+    return _as_tool_result(run_json_script("review_codecgc_workflow.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.history",
+    description="Read recent CodeCGC workflow history across feature and issue flows.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_history(
+    flow: Annotated[
+        Literal["all", "feature", "issue"],
+        Field(description="Workflow flow filter."),
+    ] = "all",
+    status: Annotated[str, "Workflow status filter."] = "all",
+    last: Annotated[int, "Maximum number of records to return."] = 10,
+    include_fixtures: Annotated[bool, "Include fixture workflows."] = False,
+) -> CallToolResult:
+    args = ["--flow", flow, "--status", str(status).strip() or "all", "--last", str(int(last)), "--format", "json"]
+    if include_fixtures:
+        args.append("--include-fixtures")
+    return _as_tool_result(run_json_script("audit_codecgc_workflow_history.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.route",
+    description="Route an existing CodeCGC workflow to the recommended next command.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_route(
+    flow: Annotated[
+        Literal["feature", "issue"],
+        Field(description="Workflow flow."),
+    ],
+    slug: Annotated[str, "Workflow slug."],
+) -> CallToolResult:
+    return _as_tool_result(run_json_script("route_codecgc_workflow.py", "--flow", flow, "--slug", str(slug).strip()))
+
+
+@mcp.tool(
+    name="codecgc.plan",
+    description="Plan or repair a CodeCGC feature or issue workflow scaffold.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_plan(
+    flow: Annotated[
+        Literal["feature", "issue"],
+        Field(description="Workflow flow."),
+    ],
+    slug: Annotated[str, "Workflow slug."],
+    summary: Annotated[str, "Planning summary."],
+    date: Annotated[str, "Optional workflow date, defaults to current date in runtime."] = "",
+    target_paths: Annotated[list[str], Field(description="Target paths for this workflow.")] = [],
+    kind: Annotated[
+        Literal["auto", "frontend", "backend"],
+        Field(description="Routing kind."),
+    ] = "auto",
+    goal: Annotated[str, "Optional goal text."] = "",
+    context: Annotated[list[str], Field(description="Optional context notes.")] = [],
+    user_story: Annotated[str, "Optional user story."] = "",
+    in_scope: Annotated[list[str], Field(description="In-scope items.")] = [],
+    out_of_scope: Annotated[list[str], Field(description="Out-of-scope items.")] = [],
+    acceptance: Annotated[list[str], Field(description="Acceptance criteria.")] = [],
+    risk: Annotated[list[str], Field(description="Risk items.")] = [],
+    dependency: Annotated[list[str], Field(description="Dependencies.")] = [],
+    assumption: Annotated[list[str], Field(description="Assumptions.")] = [],
+    open_question: Annotated[list[str], Field(description="Open questions.")] = [],
+    validation: Annotated[list[str], Field(description="Validation steps.")] = [],
+    rollback: Annotated[list[str], Field(description="Rollback notes.")] = [],
+    symptom: Annotated[str, "Issue symptom."] = "",
+    reproduction: Annotated[str, "Issue reproduction."] = "",
+    expected: Annotated[str, "Expected behavior."] = "",
+    actual: Annotated[str, "Actual behavior."] = "",
+    root_cause: Annotated[str, "Root cause note."] = "",
+    preferred_fix: Annotated[str, "Preferred fix note."] = "",
+    rejected_fix: Annotated[str, "Rejected fix note."] = "",
+    artifact_class: Annotated[
+        Literal["product", "fixture"],
+        Field(description="Artifact class."),
+    ] = "product",
+    force: Annotated[bool, "Allow overwriting scaffold state when needed."] = False,
+) -> CallToolResult:
+    args = ["--flow", flow, "--slug", str(slug).strip(), "--summary", str(summary).strip()]
+    if str(date).strip():
+        args.extend(["--date", str(date).strip()])
+    _append_repeated_flag(args, "--target-path", target_paths)
+    if kind:
+        args.extend(["--kind", kind])
+    if str(goal).strip():
+        args.extend(["--goal", str(goal).strip()])
+    _append_repeated_flag(args, "--context", context)
+    if str(user_story).strip():
+        args.extend(["--user-story", str(user_story).strip()])
+    _append_repeated_flag(args, "--in-scope", in_scope)
+    _append_repeated_flag(args, "--out-of-scope", out_of_scope)
+    _append_repeated_flag(args, "--acceptance", acceptance)
+    _append_repeated_flag(args, "--risk", risk)
+    _append_repeated_flag(args, "--dependency", dependency)
+    _append_repeated_flag(args, "--assumption", assumption)
+    _append_repeated_flag(args, "--open-question", open_question)
+    _append_repeated_flag(args, "--validation", validation)
+    _append_repeated_flag(args, "--rollback", rollback)
+    if str(symptom).strip():
+        args.extend(["--symptom", str(symptom).strip()])
+    if str(reproduction).strip():
+        args.extend(["--reproduction", str(reproduction).strip()])
+    if str(expected).strip():
+        args.extend(["--expected", str(expected).strip()])
+    if str(actual).strip():
+        args.extend(["--actual", str(actual).strip()])
+    if str(root_cause).strip():
+        args.extend(["--root-cause", str(root_cause).strip()])
+    if str(preferred_fix).strip():
+        args.extend(["--preferred-fix", str(preferred_fix).strip()])
+    if str(rejected_fix).strip():
+        args.extend(["--rejected-fix", str(rejected_fix).strip()])
+    args.extend(["--artifact-class", artifact_class])
+    if force:
+        args.append("--force")
+    return _as_tool_result(run_json_script("plan_codecgc_workflow.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.build",
+    description="Execute a CodeCGC feature step through the existing runtime.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_build(
+    slug: Annotated[str, "Feature workflow slug."],
+    step_number: Annotated[int | None, "Optional explicit step number."] = None,
+    checklist_file: Annotated[str, "Optional checklist file path."] = "",
+    audit_root: Annotated[str, "Optional audit root path."] = "",
+    timeout_seconds: Annotated[int, "Execution timeout in seconds."] = 120,
+    session_id: Annotated[str, "Optional reusable executor session id."] = "",
+    dry_run: Annotated[bool, "Avoid real executor dispatch."] = False,
+    return_all_messages: Annotated[bool, "Return executor event logs when available."] = False,
+) -> CallToolResult:
+    args = ["--slug", str(slug).strip(), "--timeout-seconds", str(int(timeout_seconds))]
+    if step_number is not None:
+        args.extend(["--step-number", str(int(step_number))])
+    if str(checklist_file).strip():
+        args.extend(["--checklist-file", str(checklist_file).strip()])
+    if str(audit_root).strip():
+        args.extend(["--audit-root", str(audit_root).strip()])
+    if str(session_id).strip():
+        args.extend(["--session-id", str(session_id).strip()])
+    if dry_run:
+        args.append("--dry-run")
+    if return_all_messages:
+        args.append("--return-all-messages")
+    return _as_tool_result(run_json_script("run_codecgc_build.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.fix",
+    description="Execute a CodeCGC issue fix step through the existing runtime.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_fix(
+    slug: Annotated[str, "Issue workflow slug."],
+    step_number: Annotated[int | None, "Optional explicit step number."] = None,
+    checklist_file: Annotated[str, "Optional checklist file path."] = "",
+    audit_root: Annotated[str, "Optional audit root path."] = "",
+    timeout_seconds: Annotated[int, "Execution timeout in seconds."] = 120,
+    session_id: Annotated[str, "Optional reusable executor session id."] = "",
+    dry_run: Annotated[bool, "Avoid real executor dispatch."] = False,
+    return_all_messages: Annotated[bool, "Return executor event logs when available."] = False,
+) -> CallToolResult:
+    args = ["--slug", str(slug).strip(), "--timeout-seconds", str(int(timeout_seconds))]
+    if step_number is not None:
+        args.extend(["--step-number", str(int(step_number))])
+    if str(checklist_file).strip():
+        args.extend(["--checklist-file", str(checklist_file).strip()])
+    if str(audit_root).strip():
+        args.extend(["--audit-root", str(audit_root).strip()])
+    if str(session_id).strip():
+        args.extend(["--session-id", str(session_id).strip()])
+    if dry_run:
+        args.append("--dry-run")
+    if return_all_messages:
+        args.append("--return-all-messages")
+    return _as_tool_result(run_json_script("run_codecgc_fix.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.test",
+    description="Execute a CodeCGC test step through the existing runtime.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_test(
+    flow: Annotated[
+        Literal["feature", "issue"],
+        Field(description="Workflow flow."),
+    ],
+    slug: Annotated[str, "Workflow slug."],
+    step_number: Annotated[int | None, "Optional explicit step number."] = None,
+    checklist_file: Annotated[str, "Optional checklist file path."] = "",
+    audit_root: Annotated[str, "Optional audit root path."] = "",
+    timeout_seconds: Annotated[int, "Execution timeout in seconds."] = 120,
+    session_id: Annotated[str, "Optional reusable executor session id."] = "",
+    dry_run: Annotated[bool, "Avoid real executor dispatch."] = False,
+    return_all_messages: Annotated[bool, "Return executor event logs when available."] = False,
+) -> CallToolResult:
+    args = ["--flow", flow, "--slug", str(slug).strip(), "--timeout-seconds", str(int(timeout_seconds))]
+    if step_number is not None:
+        args.extend(["--step-number", str(int(step_number))])
+    if str(checklist_file).strip():
+        args.extend(["--checklist-file", str(checklist_file).strip()])
+    if str(audit_root).strip():
+        args.extend(["--audit-root", str(audit_root).strip()])
+    if str(session_id).strip():
+        args.extend(["--session-id", str(session_id).strip()])
+    if dry_run:
+        args.append("--dry-run")
+    if return_all_messages:
+        args.append("--return-all-messages")
+    return _as_tool_result(run_json_script("run_codecgc_test.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.package_audit",
+    description="Audit whether the published CodeCGC package contains all required runtime files.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_package_audit(
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Output format."),
+    ] = "json",
+) -> CallToolResult:
+    return _as_tool_result(run_json_script("audit_codecgc_package_runtime.py", "--format", format))
+
+
+@mcp.tool(
+    name="codecgc.external_audit",
+    description="Audit external capability registration policy and locally observed MCP servers.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_external_audit(
+    workspace: Annotated[str, "Optional target workspace root."] = "",
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Output format."),
+    ] = "json",
+) -> CallToolResult:
+    args = ["--format", format]
+    normalized_workspace = _normalize_workspace(workspace)
+    if normalized_workspace:
+        args.extend(["--workspace", normalized_workspace])
+    return _as_tool_result(run_json_script("audit_codecgc_external_capabilities.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.release_readiness",
+    description="Run the combined CodeCGC release, maintenance, and ops readiness audit.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_release_readiness(
+    workspace: Annotated[str, "Optional target workspace root."] = "",
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Output format."),
+    ] = "json",
+) -> CallToolResult:
+    args = ["--format", format]
+    normalized_workspace = _normalize_workspace(workspace)
+    if normalized_workspace:
+        args.extend(["--workspace", normalized_workspace])
+    return _as_tool_result(run_json_script("audit_codecgc_release_readiness.py", *args))
+
+
+@mcp.tool(
+    name="codecgc.lifecycle",
+    description="Audit CodeCGC lifecycle coverage across roadmap, workflows, and execution artifacts.",
+    meta={"version": "0.1.0", "author": "CodeCGC"},
+)
+async def codecgc_lifecycle(
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Output format."),
+    ] = "json",
+) -> CallToolResult:
+    return _as_tool_result(run_json_script("audit_codecgc_lifecycle.py", "--format", format))
+
+
+def run() -> None:
+    """Start the MCP server over stdio transport."""
+    mcp.run(transport="stdio")

package/model-routing.yaml

@@ -9,6 +9,8 @@ frontend_paths:
   - "web/**"
   - "frontend/**"
 
+custom_frontend_paths:
+
 backend_paths:
   - "apps/api/**"
   - "server/**"
@@ -17,6 +19,8 @@ backend_paths:
   - "src/repositories/**"
   - "backend/**"
 
+custom_backend_paths:
+
 shared_paths:
   - "packages/shared/**"
   - "src/shared/**"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunyed15/codecgc",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Claude-hosted multi-model workflow product shell for CodeCGC.",
   "license": "MIT",
   "type": "commonjs",
@@ -57,6 +57,9 @@
     "codecgc/cgc-roadmap/",
     "codecgc/cgc-test/",
     "codecgc/reference/",
+    "codecgcmcp/pyproject.toml",
+    "codecgcmcp/README.md",
+    "codecgcmcp/src/codecgcmcp/",
     "codexmcp/pyproject.toml",
     "codexmcp/README.md",
     "codexmcp/LICENSE",

package/scripts/codecgc_workflow_runtime.py

@@ -28,6 +28,7 @@ def run_json_script(script_name: str, *args: str) -> dict[str, Any]:
     completed = subprocess.run(
         command,
         cwd=PROJECT_WORKSPACE,
+        stdin=subprocess.DEVNULL,
         capture_output=True,
         text=True,
         encoding="utf-8",

package/scripts/install_codecgc.py

@@ -42,6 +42,11 @@ DEFAULT_HOOKS = {
 
 SENSITIVE_KEYWORDS = ("token", "secret", "key", "password", "auth")
 MCP_RUNTIME_REQUIREMENT = 'mcp[cli]>=1.21.2'
+DEFAULT_ALLOWED_TOOLS = [
+    "mcp__codecgc__*",
+    "mcp__codex__*",
+    "mcp__gemini__*",
+]
 
 
 def get_user_claude_root(override_root: str = "") -> Path:
@@ -64,6 +69,7 @@ def get_user_claude_paths(override_root: str = "") -> dict[str, Path]:
         "mcp": root / "mcp.json",
         "hooks_dir": root / "hooks",
         "hook_script": root / "hooks" / "route-edit.ps1",
+        "commands_dir": root / "commands",
     }
 
 
@@ -78,6 +84,7 @@ def get_workspace_paths(override_workspace: str = "") -> dict[str, Path]:
         "settings": claude_dir / "settings.json",
         "mcp": root / ".mcp.json",
         "hook_script": hooks_dir / "route-edit.ps1",
+        "commands_dir": claude_dir / "commands",
         "routing_file": root / "model-routing.yaml",
     }
 
@@ -110,6 +117,249 @@ def build_hook_payload(command_text: str) -> dict[str, Any]:
     }
 
 
+def _normalize_command_path_for_markdown(path: Path) -> str:
+    return str(path).replace("\\", "\\\\")
+
+
+def build_mcp_first_command_template(
+    *,
+    filename: str,
+    description: str,
+    argument_hint: str,
+    primary_tool: str,
+    direct_rules: list[str],
+    missing_rules: list[str] | None = None,
+    fallback_command: str,
+) -> tuple[str, str]:
+    lines = [
+        "---",
+        f"description: {description}",
+        f"argument-hint: \"{argument_hint}\"",
+        "---",
+        f"Prefer the `{primary_tool}` MCP tool as the primary execution path.",
+        "",
+        "Execution rules:",
+    ]
+    lines.extend(f"- {item}" for item in direct_rules)
+    if missing_rules:
+        lines.append("")
+        lines.append("Missing parameter rules:")
+        lines.extend(f"- {item}" for item in missing_rules)
+    lines.append("")
+    lines.append("Fallback rule:")
+    lines.append(f"- Only fall back to Bash + `{fallback_command}` CLI when the MCP tool path is unavailable or the user explicitly wants CLI behavior.")
+    lines.append("- Summarize the result briefly for the user.")
+    return filename, "\n".join(lines) + "\n"
+
+
+def build_custom_command_templates(bin_dir: Path) -> dict[str, str]:
+    templates = dict(
+        [
+            build_mcp_first_command_template(
+                filename="cgc.md",
+                description="Run CodeCGC in the current project",
+                argument_hint="[request or flags]",
+                primary_tool="codecgc.entry",
+                direct_rules=[
+                    "If the user supplied a natural-language request, pass it to `codecgc.entry`.",
+                    "If the user is asking to continue recent work, use `codecgc.continue`.",
+                    "If the user is asking what to do next, use `codecgc.explain`.",
+                ],
+                fallback_command="cgc",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-install.md",
+                description="Install or sync CodeCGC integration for the current project or user Claude profile",
+                argument_hint="[flags]",
+                primary_tool="codecgc.install",
+                direct_rules=[
+                    "Map install flags to `codecgc.install` fields such as `mode`, `workspace`, and `user_root`.",
+                    "If the user did not supply flags, use the default install mode.",
+                ],
+                fallback_command="cgc-install",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-status.md",
+                description="Check CodeCGC integration status",
+                argument_hint="[flags]",
+                primary_tool="codecgc.status",
+                direct_rules=[
+                    "Use `codecgc.status` for installation readiness checks.",
+                    "Map `workspace` when the user explicitly provides a target project directory.",
+                ],
+                fallback_command="cgc-status",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-doctor.md",
+                description="Run CodeCGC doctor checks",
+                argument_hint="[flags]",
+                primary_tool="codecgc.doctor",
+                direct_rules=[
+                    "Use `codecgc.doctor` for runtime and integration health checks.",
+                    "Map `workspace` when the user explicitly provides a target project directory.",
+                ],
+                fallback_command="cgc-doctor",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-plan.md",
+                description="Plan or repair a CodeCGC workflow",
+                argument_hint="[structured planning flags]",
+                primary_tool="codecgc.plan",
+                direct_rules=[
+                    "Extract `flow`, `slug`, and `summary` before calling the tool.",
+                    "Map any provided `target_paths`, `kind`, and planning fields such as `goal`, `acceptance`, `risk`, and issue-specific fields.",
+                ],
+                missing_rules=[
+                    "If `flow` is missing, ask whether this is a `feature` or `issue` workflow.",
+                    "If `slug` is missing, ask for a stable workflow slug.",
+                    "If `summary` is missing, ask for a short planning summary.",
+                ],
+                fallback_command="cgc-plan",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-build.md",
+                description="Execute a CodeCGC feature build step",
+                argument_hint="[flags]",
+                primary_tool="codecgc.build",
+                direct_rules=[
+                    "Extract `slug` before calling the tool.",
+                    "Map optional execution fields such as `step_number`, `checklist_file`, `audit_root`, `timeout_seconds`, `session_id`, and `dry_run`.",
+                ],
+                missing_rules=[
+                    "If `slug` is missing, ask for the target feature workflow slug.",
+                ],
+                fallback_command="cgc-build",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-fix.md",
+                description="Execute a CodeCGC issue fix step",
+                argument_hint="[flags]",
+                primary_tool="codecgc.fix",
+                direct_rules=[
+                    "Extract `slug` before calling the tool.",
+                    "Map optional execution fields such as `step_number`, `checklist_file`, `audit_root`, `timeout_seconds`, `session_id`, and `dry_run`.",
+                ],
+                missing_rules=[
+                    "If `slug` is missing, ask for the target issue workflow slug.",
+                ],
+                fallback_command="cgc-fix",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-test.md",
+                description="Execute a CodeCGC test step",
+                argument_hint="[flags]",
+                primary_tool="codecgc.test",
+                direct_rules=[
+                    "Extract `flow` and `slug` before calling the tool.",
+                    "Map optional execution fields such as `step_number`, `checklist_file`, `audit_root`, `timeout_seconds`, `session_id`, and `dry_run`.",
+                ],
+                missing_rules=[
+                    "If `flow` is missing, ask whether the test belongs to a `feature` or `issue` workflow.",
+                    "If `slug` is missing, ask for the target workflow slug.",
+                ],
+                fallback_command="cgc-test",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-review.md",
+                description="Review a CodeCGC execution audit",
+                argument_hint="[flags]",
+                primary_tool="codecgc.review",
+                direct_rules=[
+                    "Extract `audit_file` and `decision` before calling the tool.",
+                    "Map optional `risk`, `next_step`, and `force` fields when they are explicitly provided.",
+                ],
+                missing_rules=[
+                    "If `audit_file` is missing, ask for the audit JSON path.",
+                    "If `decision` is missing, ask whether the review is `accepted` or `changes-requested`.",
+                ],
+                fallback_command="cgc-review",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-route.md",
+                description="Route a CodeCGC workflow to the next recommended command",
+                argument_hint="[flags]",
+                primary_tool="codecgc.route",
+                direct_rules=[
+                    "Extract `flow` and `slug` before calling the tool.",
+                    "Use this command when the user already knows the target workflow and wants the next recommended action.",
+                ],
+                missing_rules=[
+                    "If `flow` is missing, ask whether the workflow is `feature` or `issue`.",
+                    "If `slug` is missing, ask for the workflow slug.",
+                ],
+                fallback_command="cgc-route",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-history.md",
+                description="Read recent CodeCGC workflow history",
+                argument_hint="[flags]",
+                primary_tool="codecgc.history",
+                direct_rules=[
+                    "Map optional history filters such as `flow`, `status`, `last`, and `include_fixtures`.",
+                    "If no filters are provided, use the default history query.",
+                ],
+                fallback_command="cgc-history",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-package-audit.md",
+                description="Audit the CodeCGC package runtime contents",
+                argument_hint="[flags]",
+                primary_tool="codecgc.package_audit",
+                direct_rules=[
+                    "Map `format` when the user explicitly requests `summary` or `json`.",
+                    "Use this command for publish/runtime completeness checks.",
+                ],
+                fallback_command="cgc-package-audit",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-external-audit.md",
+                description="Audit external MCP capability registration and observation",
+                argument_hint="[flags]",
+                primary_tool="codecgc.external_audit",
+                direct_rules=[
+                    "Map optional `workspace` and `format` fields.",
+                    "Use this command for external capability policy and registration checks.",
+                ],
+                fallback_command="cgc-external-audit",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-release-readiness.md",
+                description="Run CodeCGC release readiness checks",
+                argument_hint="[flags]",
+                primary_tool="codecgc.release_readiness",
+                direct_rules=[
+                    "Map optional `workspace` and `format` fields.",
+                    "Use this command for combined release, maintenance, and ops checks.",
+                ],
+                fallback_command="cgc-release-readiness",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-lifecycle.md",
+                description="Audit CodeCGC lifecycle coverage",
+                argument_hint="[flags]",
+                primary_tool="codecgc.lifecycle",
+                direct_rules=[
+                    "Map `format` when the user explicitly requests `summary` or `json`.",
+                    "Use this command to inspect roadmap/workflow/execution lifecycle coverage.",
+                ],
+                fallback_command="cgc-lifecycle",
+            ),
+        ]
+    )
+    return templates
+
+
+def write_custom_command_files(target_dir: Path, bin_dir: Path) -> list[str]:
+    target_dir.mkdir(parents=True, exist_ok=True)
+    templates = build_custom_command_templates(bin_dir)
+    written: list[str] = []
+    for filename, content in templates.items():
+        path = target_dir / filename
+        path.write_text(content, encoding="utf-8")
+        written.append(str(path))
+    return written
+
+
 def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dict[str, Any], bool]:
     hooks = current.get("hooks")
     expected_hooks = build_hook_payload(command_text)
@@ -144,6 +394,33 @@ def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dic
     return current, True
 
 
+def merge_permission_settings(current: dict[str, Any], allow_rules: list[str]) -> tuple[dict[str, Any], bool]:
+    permissions = current.get("permissions")
+    changed = False
+
+    if not isinstance(permissions, dict):
+        permissions = {}
+        current["permissions"] = permissions
+        changed = True
+
+    allow = permissions.get("allow")
+    if not isinstance(allow, list):
+        allow = []
+        permissions["allow"] = allow
+        changed = True
+
+    existing = {str(item).strip() for item in allow if str(item).strip()}
+    for rule in allow_rules:
+        normalized = str(rule).strip()
+        if not normalized or normalized in existing:
+            continue
+        allow.append(normalized)
+        existing.add(normalized)
+        changed = True
+
+    return current, changed
+
+
 def write_json_file(path: Path, payload: dict[str, Any]) -> Path:
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
@@ -201,6 +478,17 @@ def settings_have_hook_command(settings: dict[str, Any], command_text: str) -> b
     return False
 
 
+def settings_have_allowed_tools(settings: dict[str, Any], allow_rules: list[str]) -> bool:
+    permissions = settings.get("permissions")
+    if not isinstance(permissions, dict):
+        return False
+    allow = permissions.get("allow")
+    if not isinstance(allow, list):
+        return False
+    existing = {str(item).strip() for item in allow if str(item).strip()}
+    return all(str(rule).strip() in existing for rule in allow_rules)
+
+
 def build_workspace_hook_command(workspace_paths: dict[str, Path]) -> str:
     return "powershell -ExecutionPolicy Bypass -File .claude/hooks/route-edit.ps1"
 
@@ -235,11 +523,15 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
         settings,
         build_workspace_hook_command(workspace_paths),
     )
+    merged_settings, permissions_changed = merge_permission_settings(merged_settings, DEFAULT_ALLOWED_TOOLS)
     if settings_changed or not workspace_paths["settings"].exists():
         write_json_file(workspace_paths["settings"], merged_settings)
+    elif permissions_changed:
+        write_json_file(workspace_paths["settings"], merged_settings)
 
     if PROJECT_HOOK_PATH.resolve() != workspace_paths["hook_script"].resolve():
         shutil.copyfile(PROJECT_HOOK_PATH, workspace_paths["hook_script"])
+    written_commands = write_custom_command_files(workspace_paths["commands_dir"], WORKSPACE / "bin")
 
     summary = build_mode_summary_payload(
         scope="项目级 Claude 与 MCP 集成面",
@@ -255,10 +547,14 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
         "routing_file": str(routing_path),
         "claude_settings": str(workspace_paths["settings"]),
         "hook_script": str(workspace_paths["hook_script"]),
+        "commands_dir": str(workspace_paths["commands_dir"]),
+        "command_files": written_commands,
         "notes": [
             "Repository-local MCP config was synced from the executor registry.",
             "Project-local model-routing.yaml was synchronized and preserves custom path blocks.",
             "Claude pre-edit guardrail hook was synchronized into the target workspace.",
+            "Claude MCP tool permissions were merged into project .claude/settings.json.",
+            "Project-local Claude slash commands were synchronized into .claude/commands.",
             "This mode prepares project-level integration surfaces for the selected workspace.",
         ],
         "summary": summary,
@@ -273,6 +569,7 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
     user_paths = get_user_claude_paths(override_root)
     user_settings = load_json_file(user_paths["settings"])
     merged_settings, settings_changed = merge_hook_settings(user_settings, build_user_hook_command(user_paths))
+    merged_settings, permissions_changed = merge_permission_settings(merged_settings, DEFAULT_ALLOWED_TOOLS)
     mcp_config = build_mcp_config()
     recommended_next_action = f"cgc-install --mode user --user-root {shell_quote(str(user_paths['root']))}"
     summary = build_mode_summary_payload(
@@ -290,11 +587,13 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
             "settings_json": str(user_paths["settings"]),
             "mcp_json": str(user_paths["mcp"]),
             "hook_script": str(user_paths["hook_script"]),
+            "commands_dir": str(user_paths["commands_dir"]),
         },
         "would_write": {
-            "settings_changed": settings_changed or not user_paths["settings"].exists(),
+            "settings_changed": settings_changed or permissions_changed or not user_paths["settings"].exists(),
             "mcp_changed": True,
             "hook_changed": True,
+            "commands_changed": True,
         },
         "preview": {
             "settings": sanitize_for_preview(merged_settings),
@@ -303,6 +602,7 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
         "notes": [
             "This mode does not modify user-level Claude files.",
             "Use this preview to inspect the future user-level integration surface.",
+            "The preview includes MCP tool allow rules for codecgc, codex, and gemini servers.",
             "Current CodeCGC product policy still defaults to project-local installation.",
         ],
         "summary": summary,
@@ -313,12 +613,15 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
     user_paths = get_user_claude_paths(override_root)
     user_paths["root"].mkdir(parents=True, exist_ok=True)
     user_paths["hooks_dir"].mkdir(parents=True, exist_ok=True)
+    user_paths["commands_dir"].mkdir(parents=True, exist_ok=True)
 
     settings = load_json_file(user_paths["settings"])
     merged_settings, settings_changed = merge_hook_settings(settings, build_user_hook_command(user_paths))
+    merged_settings, permissions_changed = merge_permission_settings(merged_settings, DEFAULT_ALLOWED_TOOLS)
     write_json_file(user_paths["settings"], merged_settings)
     write_json_file(user_paths["mcp"], build_mcp_config())
     shutil.copyfile(PROJECT_HOOK_PATH, user_paths["hook_script"])
+    written_commands = write_custom_command_files(user_paths["commands_dir"], WORKSPACE / "bin")
     summary = build_mode_summary_payload(
         scope="用户级 Claude 集成面",
         human_summary="用户级 Claude 集成文件已写入。",
@@ -334,15 +637,20 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
             "settings_json": str(user_paths["settings"]),
             "mcp_json": str(user_paths["mcp"]),
             "hook_script": str(user_paths["hook_script"]),
+            "commands_dir": str(user_paths["commands_dir"]),
         },
         "changes": {
-            "settings_changed": settings_changed or not user_paths["settings"].exists(),
+            "settings_changed": settings_changed or permissions_changed or not user_paths["settings"].exists(),
             "mcp_changed": True,
             "hook_changed": True,
+            "commands_changed": True,
         },
+        "command_files": written_commands,
         "notes": [
             "User-level Claude integration files were written to the selected root.",
             "The user-level hook script was copied from the project hook source.",
+            "MCP tool allow rules were merged into ~/.claude/settings.json.",
+            "User-level Claude slash commands were written to ~/.claude/commands.",
             "This mode is explicit and should be used only when a broader Claude integration surface is intended.",
         ],
         "summary": summary,
@@ -373,6 +681,7 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
             f"- Routing 文件: {result.get('routing_file', '')}",
             f"- Claude 设置: {result.get('claude_settings', '')}",
             f"- Hook 脚本: {result.get('hook_script', '')}",
+            f"- Slash Commands: {result.get('commands_dir', '')}",
             "- 说明: 可选外部能力如 MemOS 不由 cgc-install 自动写入；如需启用，请在 Claude 中单独配置官方 MCP。",
         ]
         next_actions = [
@@ -391,6 +700,7 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
             f"- 预演 Settings: {planned.get('settings_json', '')}",
             f"- 预演 MCP: {planned.get('mcp_json', '')}",
             f"- 预演 Hook: {planned.get('hook_script', '')}",
+            f"- 预演 Slash Commands: {planned.get('commands_dir', '')}",
             "- 说明: 该预演只覆盖 CodeCGC 必需执行器；MemOS 等可选外部能力仍建议在 Claude 中独立配置。",
         ]
         next_actions = []
@@ -410,6 +720,7 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
             f"- Settings: {written.get('settings_json', '')}",
             f"- MCP: {written.get('mcp_json', '')}",
             f"- Hook 脚本: {written.get('hook_script', '')}",
+            f"- Slash Commands: {written.get('commands_dir', '')}",
             "- 说明: 该安装只写入 CodeCGC 必需执行器；MemOS 等可选外部能力仍需在 Claude 中单独配置。",
         ]
         next_actions = [
@@ -431,6 +742,7 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
     routing_exists = workspace_paths["routing_file"].exists()
 
     hook_registered = settings_have_hook_command(current_settings, expected_hook_command)
+    permissions_registered = settings_have_allowed_tools(current_settings, DEFAULT_ALLOWED_TOOLS)
     mcp_matches = current_mcp == expected_mcp if workspace_paths["mcp"].exists() else False
     hook_file_matches = current_hook_text == expected_hook_text if workspace_paths["hook_script"].exists() else False
 
@@ -441,6 +753,8 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
         missing.append("mcp_json")
     if not hook_registered:
         missing.append("claude_settings_hook")
+    if not permissions_registered:
+        missing.append("claude_settings_permissions")
     if not hook_file_matches:
         missing.append("hook_script")
 
@@ -456,11 +770,13 @@ def collect_project_status(workspace_paths: dict[str, Path]) -> dict[str, Any]:
         "hook_exists": workspace_paths["hook_script"].exists(),
         "mcp_matches_expected": mcp_matches,
         "hook_registered": hook_registered,
+        "permissions_registered": permissions_registered,
         "hook_file_matches_expected": hook_file_matches,
         "ready": ready,
         "missing_or_outdated": missing,
         "recommended_command": "" if ready else build_workspace_install_command(workspace_paths["root"]),
         "hook_expected": {"hooks": build_hook_payload(expected_hook_command)},
+        "permissions_expected": {"permissions": {"allow": DEFAULT_ALLOWED_TOOLS}},
     }
 
 
@@ -473,6 +789,7 @@ def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
     current_hook_text = load_text_file(user_paths["hook_script"])
 
     hook_registered = settings_have_hook_command(current_settings, expected_hook_command)
+    permissions_registered = settings_have_allowed_tools(current_settings, DEFAULT_ALLOWED_TOOLS)
     mcp_matches = current_mcp == expected_mcp if user_paths["mcp"].exists() else False
     hook_file_matches = current_hook_text == expected_hook_text if user_paths["hook_script"].exists() else False
 
@@ -481,6 +798,8 @@ def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
         missing.append("mcp_json")
     if not hook_registered:
         missing.append("claude_settings_hook")
+    if not permissions_registered:
+        missing.append("claude_settings_permissions")
     if not hook_file_matches:
         missing.append("hook_script")
 
@@ -495,6 +814,7 @@ def collect_user_status(user_paths: dict[str, Path]) -> dict[str, Any]:
         "hook_exists": user_paths["hook_script"].exists(),
         "mcp_matches_expected": mcp_matches,
         "hook_registered": hook_registered,
+        "permissions_registered": permissions_registered,
         "hook_file_matches_expected": hook_file_matches,
         "ready": ready,
         "missing_or_outdated": missing,
@@ -583,14 +903,18 @@ def build_pip_install_command(python_command: str, requirement: str) -> str:
 
 def build_local_editable_install_command(python_command: str) -> str:
     runtime_command = python_command.strip() or sys.executable
+    codecgcmcp_path = WORKSPACE / "codecgcmcp"
     codexmcp_path = WORKSPACE / "codexmcp"
     geminimcp_path = WORKSPACE / "geminimcp"
+    if not (codecgcmcp_path / "pyproject.toml").exists():
+        return ""
     if not (codexmcp_path / "pyproject.toml").exists():
         return ""
     if not (geminimcp_path / "pyproject.toml").exists():
         return ""
     return (
-        f"{shell_quote(runtime_command)} -m pip install -e {shell_quote(str(codexmcp_path))} "
+        f"{shell_quote(runtime_command)} -m pip install -e {shell_quote(str(codecgcmcp_path))} "
+        f"-e {shell_quote(str(codexmcp_path))} "
         f"-e {shell_quote(str(geminimcp_path))}"
     )
 
@@ -663,6 +987,25 @@ def classify_doctor_failures(
             )
             continue
 
+        if name == "python_runtime_import_probe_codecgcmcp":
+            if configured_python_missing:
+                continue
+            if "No module named 'codecgcmcp'" in detail or 'No module named "codecgcmcp"' in detail:
+                add_failure(
+                    "codecgcmcp-package-missing",
+                    "当前解释器无法导入本地 `codecgcmcp` 包。",
+                    "确认当前安装包已包含 `codecgcmcp/src`；仓库开发环境可执行本地 editable install，安装产物则应重新安装 CodeCGC 包。",
+                    editable_install_command,
+                )
+            else:
+                add_failure(
+                    "codecgcmcp-runtime-broken",
+                    "`codecgcmcp` 启动入口存在，但当前运行时仍无法导入。",
+                    "仓库开发环境可先重装本地编排器包；若你使用的是已安装产物，则优先重新安装 CodeCGC，再检查编排器源码是否缺失或损坏。",
+                    editable_install_command,
+                )
+            continue
+
         if name == "python_runtime_import_probe_codexmcp":
             if configured_python_missing:
                 continue
@@ -776,11 +1119,18 @@ def collect_doctor_status(override_workspace: str = "") -> dict[str, Any]:
 
     runtime_probe_command = configured_python_command if configured_python_command else (python_command or sys.executable)
     runtime_env = dict(os.environ)
-    combined_pythonpath = os.pathsep.join([str(WORKSPACE / "codexmcp" / "src"), str(WORKSPACE / "geminimcp" / "src")])
+    combined_pythonpath = os.pathsep.join(
+        [
+            str(WORKSPACE / "scripts"),
+            str(WORKSPACE / "codecgcmcp" / "src"),
+            str(WORKSPACE / "codexmcp" / "src"),
+            str(WORKSPACE / "geminimcp" / "src"),
+        ]
+    )
     existing_pythonpath = runtime_env.get("PYTHONPATH", "").strip()
     runtime_env["PYTHONPATH"] = f"{combined_pythonpath}{os.pathsep}{existing_pythonpath}" if existing_pythonpath else combined_pythonpath
 
-    for module_name in ("mcp", "codexmcp.cli", "geminimcp.cli"):
+    for module_name in ("mcp", "codecgcmcp.cli", "codexmcp.cli", "geminimcp.cli"):
         probe = probe_python_import(runtime_probe_command, module_name, runtime_env)
         checks.append(
             {

package/scripts/sync_codecgc_mcp_config.py

@@ -1,3 +1,4 @@
+import os
 import json
 from pathlib import Path
 
@@ -8,16 +9,32 @@ WORKSPACE = Path(__file__).resolve().parents[1]
 MCP_CONFIG_PATH = WORKSPACE / ".mcp.json"
 
 
+def build_runtime_pythonpath(*extra_paths: Path) -> str:
+    paths = [str(WORKSPACE / "scripts"), *(str(path) for path in extra_paths)]
+    return os.pathsep.join(paths)
+
+
 def build_mcp_config() -> dict:
     registry = build_executor_registry()
     servers: dict[str, dict] = {}
 
+    servers["codecgc"] = {
+        "command": str(next(iter(registry.values()))["python_command"]),
+        "args": ["-m", "codecgcmcp.cli"],
+        "env": {
+            "PYTHONPATH": build_runtime_pythonpath(WORKSPACE / "codecgcmcp" / "src"),
+        },
+    }
+
     for config in registry.values():
         servers[str(config["mcp_server_name"])] = {
             "command": str(config["python_command"]),
             "args": ["-m", str(config["python_module"])],
             "env": {
-                "PYTHONPATH": str(config["pythonpath"]),
+                "PYTHONPATH": build_runtime_pythonpath(
+                    WORKSPACE / "codecgcmcp" / "src",
+                    Path(str(config["pythonpath"])),
+                ),
             },
         }