# Shared Credit Tool

**English** | [简体中文](README.zh-CN.md)

Shared Credit Tool is a local MCP server for two clients only:

- Codex through newline-delimited stdio.
- ChatGPT on the web through authenticated Streamable HTTP and OAuth 2.1.

It lets those clients read and write files, create text documents, edit code,
run local applications and shell commands, manage long-running processes, use
Git, and inspect images.

> **Full-control default:** commands run with the privileges and environment of
> the process that starts the server. On Windows, use the included elevated
> launcher and approve the UAC prompt to obtain Administrator access. Anyone who
> can authorize against the public MCP URL can operate the computer with those
> privileges.

## Install

```powershell
py -m pip install -e ".[image]"
```

Python 3.11 or newer is required.

## Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.shared_credit_tool]
command = "shared-credit-tool"
args = ["--stdio"]
```

The default direct-file root is the current user's home directory. The default
cwd is the directory from which the server starts. Override the root with
`--workspace C:\` or another explicit directory when needed. Codex inherits
Administrator rights only when Codex itself was started elevated.

## ChatGPT Web

For the complete setup and project workflow, see the
[Chinese step-by-step guide](docs/chatgpt-web-guide.zh-CN.md).

The launcher automatically downloads the latest official Windows amd64
`cloudflared` release into `~/.shared-credit-tool/bin` when it is missing.
You can still install it system-wide first if preferred:

```powershell
winget install Cloudflare.cloudflared
```

Then run from an Administrator PowerShell, or let the script request elevation:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-chatgpt.ps1
```

The script starts the MCP server on loopback, enables OAuth, prints the OAuth
password, and opens a Cloudflare HTTPS tunnel. It detects the tunnel hostname,
prints the final `MCP 服务器 URL` with `/mcp` already appended, prints
`身份验证: OAuth`, and copies the URL to the clipboard. In ChatGPT, enable
Developer mode under **Settings -> Security and login**, create an app from the
plus button at [ChatGPT Plugins](https://chatgpt.com/plugins), choose OAuth, and
enter the printed password on the authorization page.

Dynamic registration accepts both `authorization_code` and `refresh_token`.
Access-token responses include a rotating refresh token so ChatGPT can renew a
session without registering and authorizing again.

HTTP never binds publicly by default. OAuth is enabled automatically whenever
HTTP starts without an explicit bearer token or `SHARED_CREDIT_TOOL_AUTH_MODE=noauth`.

## Core Tools

The MCP catalog contains server/cwd inspection, `read_file`, `write_file`,
`list_dir`, `list_files`, `search_text`, `apply_patch`, `exec_command`, command
session polling and termination, Git status/diff/log/show/blame, and
`view_image`.

`write_file` creates parent directories and writes UTF-8 text, Markdown, CSV,
JSON, HTML, or source code. For DOCX, XLSX, PPTX, PDF, Office automation, or
other binary formats, use `exec_command` with software installed on the local
computer.

## Defaults

- Permission mode: `dangerous` (all server command gates disabled).
- Shell environment: `all` (the host environment is inherited unchanged).
- File-tool root: the current user's home directory.
- HTTP bind: `127.0.0.1:8765`.
- HTTP authentication: OAuth 2.1 with PKCE and dynamic registration.

Use `--permission-mode safe` or `trusted` only when you intentionally want the
older restrictions. See [client configuration](docs/mcp-client-config.md),
[remote access](docs/remote-mcp.md), and the tool reference in
[Core Tools](docs/tools-and-schemas.md).

## Development

```powershell
py -m pip install -e ".[dev,image]"
py -m unittest discover -s tests -p "test_*.py"
py -m ruff check shared_credit_tool tests
```