Skip to content
Merged
25 changes: 10 additions & 15 deletions docs/remote-scan.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Remote scan: `cdg scan` on a GitHub repository

Status: implemented in the Python build (`src/codigest/core/remote.py`); the Rust build and MCP
are not. Written against `c1c4d11` (0.12.2) as the plan for the pull requests that follow it, and
Status: implemented in the Python CLI and opt-in MCP `scan_github`; the Rust build is not. Written against `c1c4d11` (0.12.2) as the plan for the pull requests that follow it, and
corrected where the implementation turned out different.

## Goal
Expand Down Expand Up @@ -319,20 +318,16 @@ complete would be worse than none.

## MCP

The `scan` tool and the output of `tools/list` stay exactly as they are by default. Remote scan
is exposed only when the server is started with `cdg mcp --allow-remote`:
The local `scan` tool and the default `tools/list` remain unchanged. In the Python build,
`cdg mcp --allow-remote` adds a separate `scan_github` tool taking `repository`, optional
`ref`, `paths` and `format`. An unenabled call is refused. Authentication is controlled
only by the operator's additional `--auth` startup flag, not tool arguments. GitHub content
is untrusted input, not agent instructions. The CLI's download bounds and secret masking
apply unchanged, and each remote CLI process has a 110-second timeout.

- the `scan` tool then also takes `github` (`OWNER/REPO` or URL) and `ref`; `targets` names
paths inside the repository, as `--path` does;
- the tool description says that the content is from a third-party repository and may contain
instructions that are not the user's;
- the server passes `--auth` only when it was itself started with `--allow-remote --auth`; an
agent cannot ask for a token;
- `-y` is passed as for local scans, so the hard ceiling above is what bounds an agent's
request.

Without `--allow-remote`, a `scan` call with `github` set is refused with
`remote scan is off; start the server with cdg mcp --allow-remote`.
This source change is not in the Rust build. Tests cover tool discovery, denied remote
access, unchanged local path boundaries, argument validation, credential opt-in, and an
actual stdio-to-CLI-to-fake-GitHub scan. See `site/chatgpt-mcp.md` for private connectivity.

## Tests

Expand Down
60 changes: 60 additions & 0 deletions site/chatgpt-mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Private ChatGPT connection

Codigest runs on the machine that owns the project. Installing it in a different ChatGPT
execution environment does not grant access to your computer. Public directory submission is
not needed for a private custom MCP connection.

## 1. Install and test

Use a Python release containing `scan_github`, or install the reviewed source branch locally:

```powershell
uv tool install --python 3.15 --editable .
cd PATH_TO_A_SMALL_TEST_PROJECT
codigest mcp --allow-remote
```

The command waits for newline-delimited MCP requests; stop it with Ctrl+C after checking it
starts. Keep the test project small. This server also exposes local tools; remote mode does
not disable local access. Keep the same account, working directory and absolute executable
path when running it under a tunnel or scheduled task.

## 2. Create a private tunnel

Follow https://developers.openai.com/api/docs/guides/secure-mcp-tunnels . In
https://platform.openai.com/settings/organization/tunnels create a tunnel and associate the
intended ChatGPT workspace. Creating needs Tunnels Read + Manage; using needs Read + Use.
Custom MCP availability and tunnel permissions are separate. Check account availability and
billing; this guide does not promise a free service.

Download `tunnel-client` from that settings page. Set `CONTROL_PLANE_API_KEY` locally using
your secure environment or secret manager; never put its value in chat, a command argument,
this repository, or a saved profile. Then, from the test project:

```powershell
tunnel-client help quickstart
tunnel-client init --sample sample_mcp_stdio_local --profile codigest --tunnel-id YOUR_TUNNEL_ID --mcp-command "codigest mcp --allow-remote"
tunnel-client doctor --profile codigest --explain
tunnel-client run --profile codigest
```

If command lookup fails, use the absolute executable path reported by `Get-Command codigest`.
The run process must stay alive. Verify its working directory with the `tree` tool before
reading files; do not assume that the profile preserves your shell directory after restart.

## 3. Connect and verify

At https://chatgpt.com/plugins choose **+ → Add custom MCP server → Connection: Tunnel**,
select the same tunnel and create/install the private plugin. If unavailable, stop and check
account/workspace access rather than replacing this with an unauthenticated public endpoint.

Open a new chat and select the plugin. Check:

1. `tree` returns the intended test project, not a home directory or repository root by accident.
2. `scan` returns a harmless fixture file you created.
3. `scan_github` reads a small public repository/path and reports its resolved commit.
4. Private access is unavailable unless the operator restarted with `--allow-remote --auth`.

Only an observed successful tool call establishes end-to-end ChatGPT access. Local tests and
server startup alone do not. Refresh the plugin connection after changing tools or schemas.
The tunnel supplies connectivity, not autonomous background execution or access to Tailscale.
8 changes: 7 additions & 1 deletion site/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,13 @@ Serve these tools to AI agents over MCP (stdio).
cdg mcp
```

It takes no options and speaks newline-delimited JSON-RPC on stdin and stdout. See [MCP Integration](/mcp) for registering it and for the tools it offers.
It speaks newline-delimited JSON-RPC on stdin and stdout. See [MCP Integration](/mcp) for registering it and for the tools it offers.

#### Python-only: `--allow-remote`, `--auth`

The Python build can add `scan_github` with `--allow-remote`. Add `--auth` only to
allow the server to use existing GitHub credentials. The Rust build does not yet
support these options. See [MCP Integration](/mcp).

## `cdg status`

Expand Down
43 changes: 43 additions & 0 deletions site/ko/chatgpt-mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# ChatGPT 비공개 연결

Codigest는 프로젝트가 있는 컴퓨터에서 돕니다. 다른 ChatGPT 실행 환경에 설치해도 내 컴퓨터에 접근할 수는 없습니다. 비공개 사용자 지정 MCP 연결에는 공개 디렉터리 등록이 필요 없습니다.

## 1. 설치하고 시험하기

`scan_github`가 들어 있는 Python 릴리스를 쓰거나, 검토한 소스 브랜치를 로컬에 설치합니다.

```powershell
uv tool install --python 3.15 --editable .
cd PATH_TO_A_SMALL_TEST_PROJECT
codigest mcp --allow-remote
```

이 명령은 줄 단위 MCP 요청을 기다립니다. 시작되는 것을 확인했으면 Ctrl+C로 멈춥니다. 시험용 프로젝트는 작게 둡니다. 이 서버는 로컬 도구도 열어 두며, 원격 모드라고 로컬 접근이 꺼지지는 않습니다. 터널이나 예약 작업으로 돌릴 때도 같은 계정, 같은 작업 폴더, 같은 실행 파일 절대 경로를 씁니다.

## 2. 비공개 터널 만들기

https://developers.openai.com/api/docs/guides/secure-mcp-tunnels 를 따릅니다. https://platform.openai.com/settings/organization/tunnels 에서 터널을 만들고 쓸 ChatGPT 작업 공간을 연결합니다. 만들려면 Tunnels Read + Manage, 쓰려면 Read + Use 권한이 필요합니다. 사용자 지정 MCP를 쓸 수 있는지와 터널 권한은 따로입니다. 계정에서 쓸 수 있는지와 요금을 확인합니다. 이 안내는 무료를 약속하지 않습니다.

같은 설정 페이지에서 `tunnel-client`를 내려받습니다. `CONTROL_PLANE_API_KEY`는 안전한 환경 변수나 비밀값 관리 도구로 로컬에만 설정합니다. 그 값을 채팅, 명령 인자, 이 저장소, 저장된 프로필에 넣지 않습니다. 그다음 시험용 프로젝트에서 실행합니다.

```powershell
tunnel-client help quickstart
tunnel-client init --sample sample_mcp_stdio_local --profile codigest --tunnel-id YOUR_TUNNEL_ID --mcp-command "codigest mcp --allow-remote"
tunnel-client doctor --profile codigest --explain
tunnel-client run --profile codigest
```

명령을 찾지 못하면 `Get-Command codigest`가 알려 주는 실행 파일 절대 경로를 씁니다. run 프로세스는 계속 살아 있어야 합니다. 파일을 읽기 전에 `tree` 도구로 작업 폴더를 확인합니다. 다시 시작한 뒤에도 프로필이 셸의 폴더를 그대로 둔다고 가정하지 않습니다.

## 3. 연결하고 확인하기

https://chatgpt.com/plugins 에서 **+ → Add custom MCP server → Connection: Tunnel**을 고르고, 같은 터널을 골라 비공개 플러그인을 만들고 설치합니다. 이 항목이 없으면 인증 없는 공개 엔드포인트로 바꾸지 말고 멈춘 뒤 계정과 작업 공간 권한을 확인합니다.

새 채팅을 열고 플러그인을 고른 뒤 확인합니다.

1. `tree`가 홈 폴더나 저장소 루트가 아니라 의도한 시험용 프로젝트를 돌려줍니다.
2. `scan`이 직접 만든 무해한 시험 파일을 돌려줍니다.
3. `scan_github`가 작은 공개 저장소나 경로를 읽고 확정된 커밋을 알려 줍니다.
4. 운영자가 `--allow-remote --auth`로 다시 시작하지 않았다면 비공개 접근은 되지 않습니다.

ChatGPT까지 이어진 접근은 도구 호출이 실제로 성공하는 것을 봐야 확인됩니다. 로컬 시험과 서버 시작만으로는 확인되지 않습니다. 도구나 스키마를 바꾸면 플러그인 연결을 새로 고칩니다. 터널은 연결만 줍니다. 백그라운드 자율 실행이나 Tailscale 접근은 주지 않습니다.
8 changes: 7 additions & 1 deletion site/ko/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,13 @@ cdg term --context # PC 이름과 셸 정보 추가
cdg mcp
```

옵션은 없으며, stdin과 stdout으로 줄 단위 JSON-RPC를 주고받습니다. 등록 방법과 제공하는 도구는 [MCP 연동](/ko/mcp)을 참고하세요.
stdin과 stdout으로 줄 단위 JSON-RPC를 주고받습니다. 등록 방법과 제공하는 도구는 [MCP 연동](/ko/mcp)을 참고하세요.

#### Python-only: `--allow-remote`, `--auth`

The Python build can add `scan_github` with `--allow-remote`. Add `--auth` only to
allow the server to use existing GitHub credentials. The Rust build does not yet
support these options. See [MCP Integration](/mcp).

## `cdg status`

Expand Down
16 changes: 16 additions & 0 deletions site/ko/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,19 @@ printf '%s\n' \
```

두 번째 응답에는 `terminal_history`, `pack`, `scan`, `diff`, `semdiff`, `digest`, `tree`가 이 순서로 들어 있습니다.

## GitHub 저장소 (Python 빌드)

`scan_github`를 쓰려면 Python 서버를 원격 접근을 명시해 시작합니다.

```sh
uvx --python 3.15 codigest mcp --allow-remote
```

이 기능이 들어간 릴리스가 나오기 전까지는 소스에만 있는 기능입니다. 기본 `cdg mcp`의 도구 목록과 로컬 프로젝트 경계는 그대로입니다. Rust 빌드는 이 옵션을 아직 구현하지 않았습니다. GitHub 스캔은 저장소의 코드를 실행하지 않습니다.

`scan_github`는 `repository`(OWNER/REPO 또는 github.com URL), 선택 항목 `ref`, `paths`(FILE:START-END 범위를 포함한 목록), `format`(xml, markdown, json)을 받습니다. 확정된 커밋과 빠진 파일을 담은 CLI 스냅샷을 돌려줍니다. 원격 digest, tree, diff, pack은 없습니다. 원격 하위 프로세스마다 제한 시간은 110초입니다.

공개 스캔은 GitHub 자격 증명을 쓰지 않습니다. 비공개 저장소에 운영자의 기존 GitHub 자격 증명을 쓰게 하려면 `--allow-remote --auth`를 함께 주고 시작합니다. 도구를 호출하는 쪽은 인증을 켜거나 이 시작 정책을 바꿀 수 없습니다.

ChatGPT 클라우드에서는 이 stdio 명령을 Secure MCP Tunnel로 연결합니다. 명령을 시작하는 것만으로 ChatGPT 플러그인이 등록되지는 않습니다. [ChatGPT 비공개 연결](/ko/chatgpt-mcp)을 보십시오.
25 changes: 25 additions & 0 deletions site/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,28 @@ printf '%s\n' \
```

The second response lists, in this order: `terminal_history`, `pack`, `scan`, `diff`, `semdiff`, `digest`, `tree`.


## GitHub repositories (Python build)

Start the Python server with explicit remote access to expose `scan_github`:

```sh
uvx --python 3.15 codigest mcp --allow-remote
```

This is unreleased source functionality until a release containing this change is published.
The default `cdg mcp` tool list and local project boundary are unchanged. The Rust build does
not yet implement this option. A GitHub scan never executes the repository's code.

`scan_github` accepts `repository` (OWNER/REPO or a github.com URL), optional `ref`,
`paths` (a list, including FILE:START-END ranges), and `format` (xml, markdown, json).
It returns the CLI snapshot with the resolved commit and omitted files. Remote digest, tree,
diff and pack are not provided. Each remote child process has a 110-second timeout.

Public scans do not use GitHub credentials. To let the server use the operator's existing
GitHub credentials for private repositories, start with both `--allow-remote --auth`.
A tool caller cannot enable authentication or change that startup policy.

For ChatGPT cloud, connect this stdio command through Secure MCP Tunnel; starting the command
alone does not register a ChatGPT plugin. See [private ChatGPT setup](/chatgpt-mcp).
17 changes: 13 additions & 4 deletions site/scripts/check_reference.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,24 +55,31 @@ def walk(command: click.Command, path: list[str]) -> None:
return found


def documented_options(page: Path) -> tuple[dict[str, set[str]], dict[str, set[str]]]:
def documented_options(
page: Path,
) -> tuple[dict[str, set[str]], dict[str, set[str]], dict[str, set[str]]]:
"""Options in each command's table, and options under its binary-only headings."""
table: dict[str, set[str]] = {}
binary: dict[str, set[str]] = {}
python_only: dict[str, set[str]] = {}
current: str | None = None
for line in page.read_text(encoding="utf-8").splitlines():
if m := HEADING.match(line):
current = m[1].strip()
table.setdefault(current, set())
binary.setdefault(current, set())
python_only.setdefault(current, set())
elif current and line.startswith("#### Python-only:"):
for span in re.findall(r"`([^`]+)`", line):
python_only[current].update(OPTION.findall(span))
elif current and BINARY_ONLY.match(line):
for span in re.findall(r"`([^`]+)`", line):
binary[current].update(OPTION.findall(span))
elif current and line.startswith("|"):
first_cell = line.split("|")[1]
for span in re.findall(r"`([^`]+)`", first_cell):
table[current].update(OPTION.findall(span))
return table, binary
return table, binary, python_only


def compare(
Expand Down Expand Up @@ -117,9 +124,11 @@ def main() -> int:
)
problems: list[str] = []
for page in PAGES:
table, binary = documented_options(page)
table, binary, python_only = documented_options(page)
label = page.relative_to(SITE).as_posix()
problems += compare(label, "Python build", table, python)
problems += compare(
label, "Python build", {k: v | python_only[k] for k, v in table.items()}, python
)
for command, options in binary.items():
for option in sorted(options & python.get(command, set())):
problems.append(
Expand Down
Loading
Loading