@hunyed15/codecgc 0.1.2 → 0.1.4

package/README.md

@@ -52,12 +52,34 @@ cgc-install --mode user
 - `~/.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`。
 

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.2",
+  "version": "0.1.4",
   "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:
@@ -116,62 +121,233 @@ def _normalize_command_path_for_markdown(path: Path) -> str:
     return str(path).replace("\\", "\\\\")
 
 
-def build_custom_command_templates(bin_dir: Path) -> dict[str, str]:
-    cgc_js = _normalize_command_path_for_markdown(bin_dir / "cgc.js")
-    install_js = _normalize_command_path_for_markdown(bin_dir / "cgc-install.js")
-    status_js = _normalize_command_path_for_markdown(bin_dir / "cgc-status.js")
-    doctor_js = _normalize_command_path_for_markdown(bin_dir / "cgc-doctor.js")
+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"优先使用 `{primary_tool}` MCP 工具作为主执行路径。",
+        "内部思考语言可自行选择，但面向用户的最终回复默认使用中文。",
+        "",
+        "执行规则：",
+    ]
+    lines.extend(f"- {item}" for item in direct_rules)
+    if missing_rules:
+        lines.append("")
+        lines.append("缺少参数时：")
+        lines.extend(f"- {item}" for item in missing_rules)
+    lines.append("")
+    lines.append("回退规则：")
+    lines.append(f"- 只有在 MCP 工具路径不可用，或用户明确要求走 CLI 时，才回退到 Bash + `{fallback_command}`。")
+    lines.append("- 向用户用中文简要总结结果。")
+    return filename, "\n".join(lines) + "\n"
 
-    return {
-        "cgc.md": f"""---
-description: Run CodeCGC in the current project
-argument-hint: "[request or flags]"
----
-Use the Bash tool to run CodeCGC in the current project directory.
-
-- If the user supplied arguments, run:
-  `node "{cgc_js}" $ARGUMENTS`
-- If the user did not supply arguments, run:
-  `node "{cgc_js}" --help`
-- Show the command you ran and summarize the result briefly.
-""",
-        "cgc-install.md": f"""---
-description: Install or sync CodeCGC integration for the current project or user Claude profile
-argument-hint: "[flags]"
----
-Use the Bash tool to run the CodeCGC install command.
-
-- If the user supplied arguments, run:
-  `node "{install_js}" $ARGUMENTS`
-- If the user did not supply arguments, run:
-  `node "{install_js}"`
-- Show the command you ran and summarize the result briefly.
-""",
-        "cgc-status.md": f"""---
-description: Check CodeCGC integration status
-argument-hint: "[flags]"
----
-Use the Bash tool to run the CodeCGC status command.
-
-- If the user supplied arguments, run:
-  `node "{status_js}" $ARGUMENTS`
-- If the user did not supply arguments, run:
-  `node "{status_js}"`
-- Show the command you ran and summarize the result briefly.
-""",
-        "cgc-doctor.md": f"""---
-description: Run CodeCGC doctor checks
-argument-hint: "[flags]"
----
-Use the Bash tool to run the CodeCGC doctor command.
-
-- If the user supplied arguments, run:
-  `node "{doctor_js}" $ARGUMENTS`
-- If the user did not supply arguments, run:
-  `node "{doctor_js}"`
-- Show the command you ran and summarize the result briefly.
-""",
-    }
+
+def build_custom_command_templates(bin_dir: Path) -> dict[str, str]:
+    templates = dict(
+        [
+            build_mcp_first_command_template(
+                filename="cgc.md",
+                description="在当前项目中运行 CodeCGC",
+                argument_hint="[需求或参数]",
+                primary_tool="codecgc.entry",
+                direct_rules=[
+                    "如果用户提供的是自然语言需求，传给 `codecgc.entry`。",
+                    "如果用户想继续最近的工作，使用 `codecgc.continue`。",
+                    "如果用户想知道下一步做什么，使用 `codecgc.explain`。",
+                ],
+                fallback_command="cgc",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-install.md",
+                description="为当前项目或 Claude 用户目录安装/同步 CodeCGC 集成",
+                argument_hint="[参数]",
+                primary_tool="codecgc.install",
+                direct_rules=[
+                    "把安装参数映射到 `codecgc.install` 的 `mode`、`workspace`、`user_root` 等字段。",
+                    "如果用户没有提供参数，就使用默认安装模式。",
+                ],
+                fallback_command="cgc-install",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-status.md",
+                description="检查 CodeCGC 集成状态",
+                argument_hint="[参数]",
+                primary_tool="codecgc.status",
+                direct_rules=[
+                    "使用 `codecgc.status` 检查安装与集成就绪状态。",
+                    "如果用户明确给出目标项目目录，映射 `workspace`。",
+                ],
+                fallback_command="cgc-status",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-doctor.md",
+                description="运行 CodeCGC 自检",
+                argument_hint="[参数]",
+                primary_tool="codecgc.doctor",
+                direct_rules=[
+                    "使用 `codecgc.doctor` 检查运行时与集成健康状态。",
+                    "如果用户明确给出目标项目目录，映射 `workspace`。",
+                ],
+                fallback_command="cgc-doctor",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-plan.md",
+                description="规划或修复一个 CodeCGC 工作流",
+                argument_hint="[结构化规划参数]",
+                primary_tool="codecgc.plan",
+                direct_rules=[
+                    "调用前提取 `flow`、`slug` 和 `summary`。",
+                    "映射用户提供的 `target_paths`、`kind`，以及 `goal`、`acceptance`、`risk` 等规划字段和 issue 专属字段。",
+                ],
+                missing_rules=[
+                    "如果缺少 `flow`，询问这是 `feature` 还是 `issue` 工作流。",
+                    "如果缺少 `slug`，询问稳定的工作流 slug。",
+                    "如果缺少 `summary`，询问一个简短规划摘要。",
+                ],
+                fallback_command="cgc-plan",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-build.md",
+                description="执行 CodeCGC 功能开发步骤",
+                argument_hint="[参数]",
+                primary_tool="codecgc.build",
+                direct_rules=[
+                    "调用前提取 `slug`。",
+                    "映射可选执行字段，如 `step_number`、`checklist_file`、`audit_root`、`timeout_seconds`、`session_id`、`dry_run`。",
+                ],
+                missing_rules=[
+                    "如果缺少 `slug`，询问目标功能工作流的 slug。",
+                ],
+                fallback_command="cgc-build",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-fix.md",
+                description="执行 CodeCGC 问题修复步骤",
+                argument_hint="[参数]",
+                primary_tool="codecgc.fix",
+                direct_rules=[
+                    "调用前提取 `slug`。",
+                    "映射可选执行字段，如 `step_number`、`checklist_file`、`audit_root`、`timeout_seconds`、`session_id`、`dry_run`。",
+                ],
+                missing_rules=[
+                    "如果缺少 `slug`，询问目标问题工作流的 slug。",
+                ],
+                fallback_command="cgc-fix",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-test.md",
+                description="执行 CodeCGC 测试步骤",
+                argument_hint="[参数]",
+                primary_tool="codecgc.test",
+                direct_rules=[
+                    "调用前提取 `flow` 和 `slug`。",
+                    "映射可选执行字段，如 `step_number`、`checklist_file`、`audit_root`、`timeout_seconds`、`session_id`、`dry_run`。",
+                ],
+                missing_rules=[
+                    "如果缺少 `flow`，询问该测试属于 `feature` 还是 `issue` 工作流。",
+                    "如果缺少 `slug`，询问目标工作流 slug。",
+                ],
+                fallback_command="cgc-test",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-review.md",
+                description="审核一份 CodeCGC 执行审计结果",
+                argument_hint="[参数]",
+                primary_tool="codecgc.review",
+                direct_rules=[
+                    "调用前提取 `audit_file` 和 `decision`。",
+                    "如果用户明确提供，映射可选字段 `risk`、`next_step`、`force`。",
+                ],
+                missing_rules=[
+                    "如果缺少 `audit_file`，询问审计 JSON 路径。",
+                    "如果缺少 `decision`，询问审核结论是 `accepted` 还是 `changes-requested`。",
+                ],
+                fallback_command="cgc-review",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-route.md",
+                description="为 CodeCGC 工作流推荐下一条命令",
+                argument_hint="[参数]",
+                primary_tool="codecgc.route",
+                direct_rules=[
+                    "调用前提取 `flow` 和 `slug`。",
+                    "当用户已经知道目标工作流，只想得到下一步推荐动作时，使用这个命令。",
+                ],
+                missing_rules=[
+                    "如果缺少 `flow`，询问工作流是 `feature` 还是 `issue`。",
+                    "如果缺少 `slug`，询问工作流 slug。",
+                ],
+                fallback_command="cgc-route",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-history.md",
+                description="查看最近的 CodeCGC 工作流历史",
+                argument_hint="[参数]",
+                primary_tool="codecgc.history",
+                direct_rules=[
+                    "映射可选历史筛选字段，如 `flow`、`status`、`last`、`include_fixtures`。",
+                    "如果没有提供筛选条件，就使用默认历史查询。",
+                ],
+                fallback_command="cgc-history",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-package-audit.md",
+                description="审计 CodeCGC 发布包运行时内容",
+                argument_hint="[参数]",
+                primary_tool="codecgc.package_audit",
+                direct_rules=[
+                    "当用户明确要求 `summary` 或 `json` 时，映射 `format`。",
+                    "该命令用于发布包和运行时完整性检查。",
+                ],
+                fallback_command="cgc-package-audit",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-external-audit.md",
+                description="审计外部 MCP 能力注册与接入状态",
+                argument_hint="[参数]",
+                primary_tool="codecgc.external_audit",
+                direct_rules=[
+                    "映射可选字段 `workspace` 和 `format`。",
+                    "该命令用于外部能力策略与注册检查。",
+                ],
+                fallback_command="cgc-external-audit",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-release-readiness.md",
+                description="运行 CodeCGC 发布就绪检查",
+                argument_hint="[参数]",
+                primary_tool="codecgc.release_readiness",
+                direct_rules=[
+                    "映射可选字段 `workspace` 和 `format`。",
+                    "该命令用于联合检查发布、维护和运维就绪状态。",
+                ],
+                fallback_command="cgc-release-readiness",
+            ),
+            build_mcp_first_command_template(
+                filename="cgc-lifecycle.md",
+                description="审计 CodeCGC 生命周期覆盖情况",
+                argument_hint="[参数]",
+                primary_tool="codecgc.lifecycle",
+                direct_rules=[
+                    "当用户明确要求 `summary` 或 `json` 时，映射 `format`。",
+                    "该命令用于检查 roadmap、workflow、execution 的生命周期覆盖情况。",
+                ],
+                fallback_command="cgc-lifecycle",
+            ),
+        ]
+    )
+    return templates
 
 
 def write_custom_command_files(target_dir: Path, bin_dir: Path) -> list[str]:
@@ -219,6 +395,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")
@@ -276,6 +479,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"
 
@@ -310,8 +524,11 @@ 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"])
@@ -337,6 +554,7 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
             "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.",
         ],
@@ -352,6 +570,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(
@@ -372,7 +591,7 @@ def preview_user_install(override_root: str = "") -> dict[str, Any]:
             "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,
@@ -384,6 +603,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,
@@ -398,6 +618,7 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
 
     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"])
@@ -420,7 +641,7 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
             "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,
@@ -429,6 +650,7 @@ def install_user_runtime(override_root: str = "") -> dict[str, Any]:
         "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.",
         ],
@@ -521,6 +743,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
 
@@ -531,6 +754,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")
 
@@ -546,11 +771,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}},
     }
 
 
@@ -563,6 +790,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
 
@@ -571,6 +799,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")
 
@@ -585,6 +815,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,
@@ -673,18 +904,33 @@ 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))}"
     )
 
 
+def format_bool_zh(value: Any) -> str:
+    return "是" if bool(value) else "否"
+
+
+def format_list_zh(items: Any, empty_text: str = "无") -> str:
+    if not isinstance(items, list):
+        return empty_text
+    values = [str(item).strip() for item in items if str(item).strip()]
+    return "、".join(values) if values else empty_text
+
+
 def classify_doctor_failures(
     checks: list[dict[str, Any]],
     configured_python_command: str,
@@ -753,6 +999,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
@@ -866,11 +1131,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(
             {
@@ -972,12 +1244,12 @@ def main() -> int:
         lines = [
             f"- 工作区: {result.get('workspace', '')}",
             f"- 范围: {summary.get('scope', '')}",
-            f"- 项目级就绪: {'是' if summary.get('project_ready') else '否'}",
-            f"- 用户级就绪: {'是' if summary.get('user_ready') else '否'}",
+            f"- 项目级就绪: {format_bool_zh(summary.get('project_ready'))}",
+            f"- 用户级就绪: {format_bool_zh(summary.get('user_ready'))}",
             f"- 策略: {summary.get('default_policy', '')}",
             f"- 摘要: {summary.get('human_summary', '')}",
-            f"- 项目缺失项: {', '.join(project.get('missing_or_outdated', [])) or '无'}",
-            f"- 用户缺失项: {', '.join(user.get('missing_or_outdated', [])) or '无'}",
+            f"- 项目级缺失项: {format_list_zh(project.get('missing_or_outdated', []))}",
+            f"- 用户级缺失项: {format_list_zh(user.get('missing_or_outdated', []))}",
         ]
         recommended_project = str(summary.get("recommended_project_command", "")).strip()
         recommended_user = str(summary.get("recommended_user_command", "")).strip()
@@ -992,11 +1264,11 @@ def main() -> int:
         lines = [
             f"- 工作区: {result.get('workspace', '')}",
             f"- 范围: {summary.get('scope', '')}",
-            f"- 就绪: {'是' if summary.get('ready') else '否'}",
+            f"- 就绪: {format_bool_zh(summary.get('ready'))}",
             f"- 摘要: {summary.get('human_summary', '')}",
         ]
         failed_checks = summary.get("failed_checks", [])
-        lines.append(f"- 失败检查项: {', '.join(str(item) for item in failed_checks) or '无'}")
+        lines.append(f"- 失败检查项: {format_list_zh(failed_checks)}")
         failure_categories = summary.get("failure_categories", [])
         for item in failure_categories:
             if not isinstance(item, dict):
@@ -1013,7 +1285,7 @@ def main() -> int:
         fix_command = str(summary.get("recommended_fix_command", "")).strip()
         runtime_fix_command = str(summary.get("recommended_runtime_fix_command", "")).strip()
         next_actions = [item for item in [runtime_fix_command, fix_command] if item]
-        print(render_summary_block("CodeCGC Doctor", lines, next_actions))
+        print(render_summary_block("CodeCGC 自检", lines, next_actions))
         return 0 if result.get("success") else 1
 
     if args.format == "summary" and args.mode in {"local", "user-dry-run", "user"}:

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"])),
+                ),
             },
         }