ccc-mcp 0.1.0__tar.gz

ccc_mcp-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# Set in the OS environment; this file is not loaded automatically.
+# Register a project, then grant access once in the local terminal:
+# ccc-mcp project add "D:/Projects/my-app" --id my-app
+# ccc-mcp project authorize my-app
+# CCC_MCP_HOME=C:\Users\YOUR_NAME\.ccc-mcp
+# Real agents are opt-in; Fake requires no login or model credits.
+CCC_MCP_ENABLE_REAL_AGENTS=0

ccc_mcp-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,154 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Release version without the v prefix (for example 0.1.1)
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install "ruff>=0.13,<1"
+      - run: ruff check src tests
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux covers every supported Python version. macOS and Windows run the
+          # same suite once to catch OS-specific path, process and locking behavior.
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: macos-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Configure Git identity
+        run: |
+          git config --global user.name "ci"
+          git config --global user.email "ci@example.invalid"
+          git config --global init.defaultBranch main
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Version must match the package
+        id: version
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/ccc_mcp/__init__.py)
+          if [ "${RELEASE_VERSION}" != "${version}" ]; then
+            echo "Requested version ${RELEASE_VERSION} does not match package version ${version}" >&2
+            exit 1
+          fi
+          echo "version=${version}" >> "${GITHUB_OUTPUT}"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - name: Require one universal wheel
+        run: python -c "from pathlib import Path; wheels = list(Path('dist').glob('*.whl')); assert len(wheels) == 1 and wheels[0].name.endswith('-py3-none-any.whl'), wheels"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  smoke-install:
+    name: install wheel (${{ matrix.os }})
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Install the exact built wheel
+        run: python -c "from pathlib import Path; import subprocess, sys; wheels = list(Path('dist').glob('*.whl')); assert len(wheels) == 1, wheels; subprocess.check_call([sys.executable, '-m', 'pip', 'install', str(wheels[0])])"
+      - name: Smoke-test the installed CLI
+        run: |
+          python -m ccc_mcp --help
+          python -c "import ccc_mcp, importlib.metadata as m; assert ccc_mcp.__version__ == m.version('ccc-mcp'); print(ccc_mcp.__version__)"
+      - name: Verify the Windows runtime dependency
+        if: runner.os == 'Windows'
+        run: python -c "import win32job"
+
+  github-release:
+    name: attach build to GitHub Release
+    needs: [lint, test, build, smoke-install]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Create release with the sdist and wheel
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ needs.build.outputs.version }}
+        run: gh release create "v${RELEASE_VERSION}" dist/* --repo "${GITHUB_REPOSITORY}" --target "${GITHUB_SHA}" --title "v${RELEASE_VERSION}" --generate-notes
+
+  publish:
+    name: publish
+    needs: [build, smoke-install, github-release]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ccc-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

ccc_mcp-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.ccc-mcp/
+.agentbridge/
+.demo/
+.tools/
+.tunnel/
+npm

ccc_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bruce601080102
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ccc_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: ccc-mcp
+Version: 0.1.0
+Summary: Persistent context and governed agent orchestration over MCP
+Project-URL: Homepage, https://github.com/bruce601080102/ccc-mcp
+Project-URL: Repository, https://github.com/bruce601080102/ccc-mcp
+Project-URL: Issues, https://github.com/bruce601080102/ccc-mcp/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,chatgpt,claude-code,codex,mcp,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: portalocker<4,>=3
+Requires-Dist: psutil<8,>=7
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Requires-Dist: pywin32>=311; sys_platform == 'win32'
+Requires-Dist: typer<1,>=0.16
+Provides-Extra: dev
+Requires-Dist: httpx<1,>=0.28; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.13; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ccc-mcp
+
+**Let the right coding agent do the right job—and keep the handoff verifiable.**
+
+[![CI](https://img.shields.io/github/actions/workflow/status/bruce601080102/ccc-mcp/release.yaml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/bruce601080102/ccc-mcp/actions/workflows/release.yaml)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Platforms](https://img.shields.io/badge/Platforms-macOS%20%7C%20Linux%20%7C%20Windows-555555?style=flat-square)](docs/en/1-install-and-sign-in.md)
+[![MCP](https://img.shields.io/badge/Protocol-MCP-6E56CF?style=flat-square)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[![ChatGPT](https://img.shields.io/badge/ChatGPT-PM-10A37F?style=flat-square)](docs/en/2-connect-chatgpt.md)
+[![Codex](https://img.shields.io/badge/Codex-SA%20%C2%B7%20REVIEW-000000?style=flat-square)](docs/en/4-workflow.md)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-SD%2FRD-D97757?style=flat-square)](docs/en/4-workflow.md)
+
+ccc-mcp is a local MCP workflow for software projects. ChatGPT manages the request and shared context; Codex can analyse and review; Claude Code can implement. Or, when that is the better fit, ChatGPT can run every workflow role itself. Each handoff retains the evidence needed to continue, review, or recover the work.
+
+It is designed for people who use more than one AI coding tool and do not want a quota limit, lost chat history, or an unverified "tests passed" claim to end a project.
+
+> [Traditional Chinese README](README_ZH.md) · [English documentation](docs/en/1-install-and-sign-in.md)
+
+## What it does
+
+- Routes work through configurable `PM → SA → SD/RD → REVIEW → PM` roles.
+- Preserves versioned shared context, raw agent reports, diffs, and host-observed test evidence.
+- Uses Codex and Claude Code through their native CLIs, or assigns every role to ChatGPT for a ChatGPT-only workflow.
+- Falls back only for recognised quota exhaustion, never for a normal install, login, or execution error.
+- Shares operator-installed `SKILL.md` guidance across all roles.
+
+## Choose your mode
+
+**Best-model workflow** uses ChatGPT as PM, Codex for analysis/review, and Claude Code for implementation. It is the default when you have all three tools.
+
+**ChatGPT-only workflow** sets all five role slots (`SA`, `SD`, `RD`, `SD/RD`, and `REVIEW`) to ChatGPT via `config profile chatgpt-only` — including the standalone `SD`/`RD` slots, so neither `config show` nor a manual dispatch is left showing a leftover Codex/Claude provider. The automatic workflow itself still only ever dispatches `SA → SD/RD → REVIEW`. It needs no Codex or Claude Code CLI, so it does not consume their CLI allowances. Available models, quotas, and tool access always follow your connected ChatGPT account and plan — never assume unlimited usage.
+
+## Quick start
+
+Prerequisites: Git, Python 3.11+, and an OpenAI Platform Tunnel. The best-model workflow also needs signed-in Codex and/or Claude Code accounts.
+
+```bash
+git clone https://github.com/bruce601080102/ccc-mcp.git
+cd ccc-mcp
+source scripts/setup-real-agents.sh
+# Run this only when using Codex and/or Claude Code:
+ccc-mcp setup all
+
+ccc-mcp project create hello-demo
+ccc-mcp project authorize hello-demo
+```
+
+For a ChatGPT-only workflow, omit `ccc-mcp setup all`, then apply the `chatgpt-only` profile after creating the project:
+
+```bash
+ccc-mcp --project hello-demo config profile chatgpt-only
+```
+
+Connect the local server to ChatGPT with the Tunnel instructions in [Chinese](docs/ch/2-connect-chatgpt.md) or [English](docs/en/2-connect-chatgpt.md). Then ask ChatGPT, with the ccc-mcp connection selected:
+
+> Create `hello.py` in `hello-demo`; it should print `Hello, World!`, with a test that verifies the output.
+
+Verify the work on the machine that owns the project:
+
+```bash
+ccc-mcp --project hello-demo task status
+ccc-mcp --project hello-demo task usage
+ccc-mcp --project hello-demo context show
+```
+
+For a native role, `task usage` is the source of truth for whether its CLI was actually invoked. A ChatGPT role is intentionally interactive and has no native CLI invocation: `task usage` marks it `"interactive": true` with `invocation.source: "chatgpt_web"`, so `cli_invoked: false` there reads as "by design," never as an ambiguous CLI failure. In either mode, a reported success is not sufficient: the configured host test command is recorded before review can complete the task.
+
+`ccc-mcp --project hello-demo config show` (or `config providers`) also reports a read-only `profile` field — `chatgpt-only`, `best-model`, or `custom` — derived live from every role's current provider. Switch back at any time with `ccc-mcp --project hello-demo config profile best-model`, which resolves dynamically from whichever native CLIs are actually installed (both → the Codex/Claude split; only one → every role on it; neither → rejected).
+
+## How the workflow works
+
+```text
+ChatGPT (PM) → Codex (SA) → Claude Code (SD/RD) → Codex (REVIEW)
+       ↑                                                    │
+       └──────── shared context + evidence + next task ─────┘
+```
+
+The defaults are deliberately opinionated, not mandatory. Assign any supported provider to a role:
+
+```bash
+ccc-mcp --project hello-demo config role REVIEW codex --effort high --quota-fallback chatgpt
+ccc-mcp --project hello-demo config role SD/RD claude
+ccc-mcp --project hello-demo config show
+```
+
+For the complete role and workflow model, see [the workflow guide](docs/en/4-workflow.md) or the [Traditional Chinese guide](docs/ch/4-workflow.md).
+
+## Documentation
+
+Read the numbered documents in order for a full setup. The two language trees use the same filenames and sequence.
+
+| Step | Topic |
+| --- | --- |
+| 1 | Install and sign in |
+| 2 | Connect ChatGPT |
+| 3 | Create and authorize a first project |
+| 4 | Run and resume the workflow |
+| 5 | Configure providers, roles, context, and tests |
+| 6 | Install and use skills |
+| 7 | Understand reliability and security boundaries |
+| 8–11 | CLI reference, public protocol, technical reference, and architecture |
+
+- [Traditional Chinese README](README_ZH.md)
+- [English documentation index](docs/en/README.md)
+
+## Important boundary
+
+`project authorize` permits ccc-mcp to modify that project and run its configured test command. Dependency installation can execute package scripts, so review dependency changes as part of the diff. Codex runs in its configured sandbox. Claude Code has a restricted tool policy, but does **not** yet have an equivalent OS-enforced sandbox; use a least-privileged OS account for it.
+
+Done with a project? `ccc-mcp project revoke <id>` (if still authorized) then `ccc-mcp project delete <id>` permanently removes it from `project list` and blocks the ID from ever being used or re-registered again. It never deletes files on disk or any historical Context/task/evidence — delete the project directory yourself once you've confirmed its path. See [reliability and security](docs/en/7-reliability-and-security.md) for the full guarantee.
+
+## Development
+
+```bash
+python3.11 -m pytest -q
+```
+
+The repository requires Python 3.11 or newer. Real-agent tests are opt-in because they need locally installed, authenticated CLIs; see [Chinese](docs/ch/1-install-and-sign-in.md) or [English](docs/en/1-install-and-sign-in.md).

ccc_mcp-0.1.0/README.md

@@ -0,0 +1,120 @@
+# ccc-mcp
+
+**Let the right coding agent do the right job—and keep the handoff verifiable.**
+
+[![CI](https://img.shields.io/github/actions/workflow/status/bruce601080102/ccc-mcp/release.yaml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/bruce601080102/ccc-mcp/actions/workflows/release.yaml)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Platforms](https://img.shields.io/badge/Platforms-macOS%20%7C%20Linux%20%7C%20Windows-555555?style=flat-square)](docs/en/1-install-and-sign-in.md)
+[![MCP](https://img.shields.io/badge/Protocol-MCP-6E56CF?style=flat-square)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[![ChatGPT](https://img.shields.io/badge/ChatGPT-PM-10A37F?style=flat-square)](docs/en/2-connect-chatgpt.md)
+[![Codex](https://img.shields.io/badge/Codex-SA%20%C2%B7%20REVIEW-000000?style=flat-square)](docs/en/4-workflow.md)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-SD%2FRD-D97757?style=flat-square)](docs/en/4-workflow.md)
+
+ccc-mcp is a local MCP workflow for software projects. ChatGPT manages the request and shared context; Codex can analyse and review; Claude Code can implement. Or, when that is the better fit, ChatGPT can run every workflow role itself. Each handoff retains the evidence needed to continue, review, or recover the work.
+
+It is designed for people who use more than one AI coding tool and do not want a quota limit, lost chat history, or an unverified "tests passed" claim to end a project.
+
+> [Traditional Chinese README](README_ZH.md) · [English documentation](docs/en/1-install-and-sign-in.md)
+
+## What it does
+
+- Routes work through configurable `PM → SA → SD/RD → REVIEW → PM` roles.
+- Preserves versioned shared context, raw agent reports, diffs, and host-observed test evidence.
+- Uses Codex and Claude Code through their native CLIs, or assigns every role to ChatGPT for a ChatGPT-only workflow.
+- Falls back only for recognised quota exhaustion, never for a normal install, login, or execution error.
+- Shares operator-installed `SKILL.md` guidance across all roles.
+
+## Choose your mode
+
+**Best-model workflow** uses ChatGPT as PM, Codex for analysis/review, and Claude Code for implementation. It is the default when you have all three tools.
+
+**ChatGPT-only workflow** sets all five role slots (`SA`, `SD`, `RD`, `SD/RD`, and `REVIEW`) to ChatGPT via `config profile chatgpt-only` — including the standalone `SD`/`RD` slots, so neither `config show` nor a manual dispatch is left showing a leftover Codex/Claude provider. The automatic workflow itself still only ever dispatches `SA → SD/RD → REVIEW`. It needs no Codex or Claude Code CLI, so it does not consume their CLI allowances. Available models, quotas, and tool access always follow your connected ChatGPT account and plan — never assume unlimited usage.
+
+## Quick start
+
+Prerequisites: Git, Python 3.11+, and an OpenAI Platform Tunnel. The best-model workflow also needs signed-in Codex and/or Claude Code accounts.
+
+```bash
+git clone https://github.com/bruce601080102/ccc-mcp.git
+cd ccc-mcp
+source scripts/setup-real-agents.sh
+# Run this only when using Codex and/or Claude Code:
+ccc-mcp setup all
+
+ccc-mcp project create hello-demo
+ccc-mcp project authorize hello-demo
+```
+
+For a ChatGPT-only workflow, omit `ccc-mcp setup all`, then apply the `chatgpt-only` profile after creating the project:
+
+```bash
+ccc-mcp --project hello-demo config profile chatgpt-only
+```
+
+Connect the local server to ChatGPT with the Tunnel instructions in [Chinese](docs/ch/2-connect-chatgpt.md) or [English](docs/en/2-connect-chatgpt.md). Then ask ChatGPT, with the ccc-mcp connection selected:
+
+> Create `hello.py` in `hello-demo`; it should print `Hello, World!`, with a test that verifies the output.
+
+Verify the work on the machine that owns the project:
+
+```bash
+ccc-mcp --project hello-demo task status
+ccc-mcp --project hello-demo task usage
+ccc-mcp --project hello-demo context show
+```
+
+For a native role, `task usage` is the source of truth for whether its CLI was actually invoked. A ChatGPT role is intentionally interactive and has no native CLI invocation: `task usage` marks it `"interactive": true` with `invocation.source: "chatgpt_web"`, so `cli_invoked: false` there reads as "by design," never as an ambiguous CLI failure. In either mode, a reported success is not sufficient: the configured host test command is recorded before review can complete the task.
+
+`ccc-mcp --project hello-demo config show` (or `config providers`) also reports a read-only `profile` field — `chatgpt-only`, `best-model`, or `custom` — derived live from every role's current provider. Switch back at any time with `ccc-mcp --project hello-demo config profile best-model`, which resolves dynamically from whichever native CLIs are actually installed (both → the Codex/Claude split; only one → every role on it; neither → rejected).
+
+## How the workflow works
+
+```text
+ChatGPT (PM) → Codex (SA) → Claude Code (SD/RD) → Codex (REVIEW)
+       ↑                                                    │
+       └──────── shared context + evidence + next task ─────┘
+```
+
+The defaults are deliberately opinionated, not mandatory. Assign any supported provider to a role:
+
+```bash
+ccc-mcp --project hello-demo config role REVIEW codex --effort high --quota-fallback chatgpt
+ccc-mcp --project hello-demo config role SD/RD claude
+ccc-mcp --project hello-demo config show
+```
+
+For the complete role and workflow model, see [the workflow guide](docs/en/4-workflow.md) or the [Traditional Chinese guide](docs/ch/4-workflow.md).
+
+## Documentation
+
+Read the numbered documents in order for a full setup. The two language trees use the same filenames and sequence.
+
+| Step | Topic |
+| --- | --- |
+| 1 | Install and sign in |
+| 2 | Connect ChatGPT |
+| 3 | Create and authorize a first project |
+| 4 | Run and resume the workflow |
+| 5 | Configure providers, roles, context, and tests |
+| 6 | Install and use skills |
+| 7 | Understand reliability and security boundaries |
+| 8–11 | CLI reference, public protocol, technical reference, and architecture |
+
+- [Traditional Chinese README](README_ZH.md)
+- [English documentation index](docs/en/README.md)
+
+## Important boundary
+
+`project authorize` permits ccc-mcp to modify that project and run its configured test command. Dependency installation can execute package scripts, so review dependency changes as part of the diff. Codex runs in its configured sandbox. Claude Code has a restricted tool policy, but does **not** yet have an equivalent OS-enforced sandbox; use a least-privileged OS account for it.
+
+Done with a project? `ccc-mcp project revoke <id>` (if still authorized) then `ccc-mcp project delete <id>` permanently removes it from `project list` and blocks the ID from ever being used or re-registered again. It never deletes files on disk or any historical Context/task/evidence — delete the project directory yourself once you've confirmed its path. See [reliability and security](docs/en/7-reliability-and-security.md) for the full guarantee.
+
+## Development
+
+```bash
+python3.11 -m pytest -q
+```
+
+The repository requires Python 3.11 or newer. Real-agent tests are opt-in because they need locally installed, authenticated CLIs; see [Chinese](docs/ch/1-install-and-sign-in.md) or [English](docs/en/1-install-and-sign-in.md).

ccc_mcp-0.1.0/README_ZH.md

@@ -0,0 +1,121 @@
+# ccc-mcp
+
+**讓最適合的 coding agent 負責最適合的工作，並讓每一次交接都能驗證。**
+
+[![CI](https://img.shields.io/github/actions/workflow/status/bruce601080102/ccc-mcp/release.yaml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/bruce601080102/ccc-mcp/actions/workflows/release.yaml)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Platforms](https://img.shields.io/badge/Platforms-macOS%20%7C%20Linux%20%7C%20Windows-555555?style=flat-square)](docs/ch/1-install-and-sign-in.md)
+[![MCP](https://img.shields.io/badge/Protocol-MCP-6E56CF?style=flat-square)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+[![ChatGPT](https://img.shields.io/badge/ChatGPT-PM-10A37F?style=flat-square)](docs/ch/2-connect-chatgpt.md)
+[![Codex](https://img.shields.io/badge/Codex-SA%20%C2%B7%20REVIEW-000000?style=flat-square)](docs/ch/4-workflow.md)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-SD%2FRD-D97757?style=flat-square)](docs/ch/4-workflow.md)
+
+ccc-mcp 是給軟體專案使用的本機 MCP 工作流程。ChatGPT 管理需求與共用 Context；Codex 可以負責分析與審查；Claude Code 可以負責實作。若那才是合適選擇，也能讓 ChatGPT 單獨完成所有工作流角色。每一次交接都會保留繼續工作、審查或恢復任務需要的證據。
+
+它適合同時使用多種 AI coding 工具的人：不讓額度耗盡、對話遺失，或模型一句「測試通過」就中止專案。
+
+> [English README](README.md) · [繁體中文文件](docs/ch/1-install-and-sign-in.md)
+
+## 它能做什麼
+
+- 以可設定的 `PM → SA → SD/RD → REVIEW → PM` 角色接力處理工作。
+- 保存版本化共用 Context、原始 agent 報告、diff 與主機實際觀察到的測試證據。
+- 透過原生 CLI 使用 Codex 和 Claude Code，也可將所有角色指定給 ChatGPT，走 ChatGPT-only workflow。
+- 只在辨識為額度耗盡時才啟用 fallback，不會把安裝、登入或一般執行錯誤誤當成額度問題。
+- 讓操作者安裝的 `SKILL.md` 指引可供所有角色使用。
+
+## 選擇模式
+
+**最佳模型工作流**：ChatGPT 擔任 PM、Codex 負責分析與審查、Claude Code 負責實作。若你三種工具都有，這是預設模式。
+
+**ChatGPT-only workflow**：用 `config profile chatgpt-only` 把全部五個角色（`SA`、`SD`、`RD`、`SD/RD`、`REVIEW`）都設為 ChatGPT——包含獨立的 `SD`、`RD`，`config show` 或手動派工都不會殘留 Codex／Claude。自動工作流本身實際上仍只會接力派發 `SA → SD/RD → REVIEW`。不需要 Codex 或 Claude Code CLI，也不會消耗它們的 CLI 額度；但可用模型、額度與功能一律依你連接的 ChatGPT 帳戶與方案而定，不要假設額度是無限的。
+
+## 快速開始
+
+需求：Git、Python 3.11 以上、OpenAI Platform Tunnel。最佳模型工作流另需已登入的 Codex 和／或 Claude Code 帳戶。
+
+```bash
+git clone https://github.com/bruce601080102/ccc-mcp.git
+cd ccc-mcp
+source scripts/setup-real-agents.sh
+# 只有要使用 Codex 和／或 Claude Code 時才執行：
+ccc-mcp setup all
+
+ccc-mcp project create hello-demo
+ccc-mcp project authorize hello-demo
+```
+
+若要全程使用 ChatGPT，略過 `ccc-mcp setup all`，建立專案後套用 `chatgpt-only` profile：
+
+```bash
+ccc-mcp --project hello-demo config profile chatgpt-only
+```
+
+依照[連接 ChatGPT](docs/ch/2-connect-chatgpt.md)建立 Tunnel 並選取 ccc-mcp 連線後，在 ChatGPT 提出：
+
+> 請在 `hello-demo` 建立 `hello.py`，執行時輸出 `Hello, World!`，並加入驗證輸出的測試。
+
+在擁有專案的本機驗證結果：
+
+```bash
+ccc-mcp --project hello-demo task status
+ccc-mcp --project hello-demo task usage
+ccc-mcp --project hello-demo context show
+```
+
+對原生角色而言，`task usage` 才是 CLI 是否真的被呼叫的依據；ChatGPT 角色本來就是互動式執行，沒有原生 CLI 呼叫：`task usage` 會標示 `"interactive": true` 與 `invocation.source: "chatgpt_web"`，所以這裡的 `cli_invoked: false` 代表「設計上本來就不呼叫」，不是模糊的 CLI 失敗訊號。不論哪種模式，聊天回覆自稱成功都不夠；設定的主機測試命令會在 REVIEW 完成前留下紀錄。
+
+`ccc-mcp --project hello-demo config show`（或 `config providers`）也會顯示唯讀的 `profile` 欄位——`chatgpt-only`、`best-model` 或 `custom`——由目前所有角色的 provider 即時推算。隨時可用 `ccc-mcp --project hello-demo config profile best-model` 切回，這會依本機實際安裝的 CLI 動態決定（兩個都裝＝Codex/Claude 分工；只裝一個＝全部角色用那一個；一個都沒裝則拒絕）。
+
+## 工作流程
+
+```text
+ChatGPT（PM）→ Codex（SA）→ Claude Code（SD/RD）→ Codex（REVIEW）
+       ↑                                                    │
+       └──────── 共用 Context、證據與下一個任務 ────────────┘
+```
+
+預設角色是有意見的預設值，不是硬性規定。你可以替角色指定支援的 provider：
+
+```bash
+ccc-mcp --project hello-demo config role REVIEW codex --effort high --quota-fallback chatgpt
+ccc-mcp --project hello-demo config role SD/RD claude
+ccc-mcp --project hello-demo config show
+```
+
+完整說明請看[協作工作流程](docs/ch/4-workflow.md)。
+
+## 文件
+
+完整設定建議依序閱讀編號文件；英文與繁中的檔名和順序一致。
+
+| 步驟 | 主題 |
+| --- | --- |
+| 1 | 安裝與登入 |
+| 2 | 連接 ChatGPT |
+| 3 | 建立並授權第一個專案 |
+| 4 | 執行與恢復工作流程 |
+| 5 | 設定 provider、角色、Context 與測試 |
+| 6 | 安裝與使用 Skill |
+| 7 | 了解可靠性與安全邊界 |
+| 8–11 | CLI 參考、公開協議、技術參考與架構 |
+
+- [繁體中文文件目錄](docs/ch/README.md)
+- [English README](README.md)
+- [English documentation index](docs/en/README.md)
+
+## 重要邊界
+
+`project authorize` 允許 ccc-mcp 修改該專案並執行設定的測試命令。相依套件安裝可能執行 package script，因此相依變更也必須納入 diff 審閱。Codex 依設定的 sandbox 執行；Claude Code 雖有限制工具政策，但尚未有同等的 OS 強制 sandbox，應以最低權限的 OS 帳戶執行。
+
+不想再用某個專案了？先 `ccc-mcp project revoke <id>`（若目前仍是持續授權狀態），再執行 `ccc-mcp project delete <id>` 永久從 `project list` 移除，之後這個 ID 不能再被使用或重新註冊。它不會刪除磁碟上的檔案，也不會刪除任何歷史 Context／task／證據——確認路徑後請自行刪除專案目錄。完整說明見[可靠性與安全邊界](docs/ch/7-reliability-and-security.md)。
+
+## 開發
+
+```bash
+python3.11 -m pytest -q
+```
+
+本專案要求 Python 3.11 以上。真實 agent 測試需要本機已安裝且登入的 CLI，預設不會執行；詳見[安裝與登入](docs/ch/1-install-and-sign-in.md)。