Metadata-Version: 2.3
Name: project-mcp
Version: 0.1.6
Summary: 把一个本地项目作为 token 保护的 MCP 服务暴露给 ChatGPT。
Requires-Dist: fastapi>=0.138.1
Requires-Dist: mcp[cli]>=1.28,<2
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Requires-Dist: uvicorn[standard]>=0.49.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Project MCP

把一个本地项目作为 token 保护的 MCP 服务暴露给 ChatGPT。

Project MCP 故意保持很小：

- 一个本地项目根目录
- 一个固定项目 token
- 一个 Streamable HTTP MCP 端点：`/mcp`
- 通过 Cloudflare quick tunnel 暴露公网 HTTPS
- 不做登录、不做托管 relay、不做 ChatGPT 自定义 UI 卡片

## 快速开始

不安装，直接运行：

```bash
uvx project-mcp
```

或安装成持久 CLI：

```bash
uv tool install project-mcp
project-mcp
```

默认会把当前目录作为项目目录，并输出 ChatGPT 需要粘贴的 Server URL，例如：

```text
https://example.trycloudflare.com/mcp?project_mcp_token=pmcp_...
```

如果保存的本地端口被占用，`start` 会自动换一个空闲端口继续启动；公网 tunnel URL 不受影响。
Cloudflare quick tunnel 的 `*.trycloudflare.com` Host 会被默认允许，其他公网 Host 默认拒绝。

在 ChatGPT Developer Mode 里创建 app/connector：

```text
Connection: Server URL
Authentication: None / No Authentication
```

## 命令

```bash
project-mcp
project-mcp --root /path/to/project
project-mcp --read-only
project-mcp --no-bash
project-mcp setup --root . --port 8080
project-mcp start --root .
project-mcp doctor
project-mcp token rotate
project-mcp settings show
```

项目配置保存在仓库外：

```text
~/.project-mcp/workspaces/<sha256-realpath>.json
```

token 按“设备 + 项目根目录”固定保存，直到你显式轮换它。

## MCP 工具

Project MCP 暴露：

- `server_config`
- `workspace_info`
- `tree`
- `search`
- `read_file`
- `write_file`
- `edit_file`
- `show_changes`
- `run_check`

`--read-only` 会隐藏 `write_file` 和 `edit_file`。`--no-bash` 会隐藏 `run_check`。

`run_check` 默认使用安全白名单，覆盖 codexpro 风格的只读/验证命令，并额外支持更多常见检查器：

- `pwd`、`ls`、`find`
- `git status`、`git diff`、`git log`、`git show`、`git branch`、`git rev-parse`、`git ls-files`
- `pytest`、`python -m pytest`、`python -m unittest`、`uv run pytest`
- `npm/pnpm/yarn/bun test|lint|typecheck|build|check|validate`
- `npm/pnpm/yarn/bun run build:clients`、`bun run smoke:network-propagation` 这类带冒号后缀的检查/验证脚本
- `bun --filter @scope/pkg smoke:case-name` 这类 Bun monorepo 定向验证脚本
- `go test`、`cargo test/check/clippy`
- `tsc`、`eslint`、`biome check`、`prettier --check`
- `ruff check`、`ruff format --check`、`mypy`、`pyright`、`basedpyright`

危险命令和参数仍会被拦截，例如 `rm`、`curl`、`git push`、`--fix`、`--write`、`find -delete`、管道和重定向。

Project MCP 默认不会屏蔽 `.tmp/`、`.pi/`、`data/` 这类项目运行目录，因为它们可能是理解项目状态所必需的上下文。若某个项目希望减少噪音，可以通过 `PROJECT_MCP_BLOCKED_GLOBS` 追加自己的排除规则。

## 开发

```bash
uv sync
uv run ruff check .
uv run pytest
uv build
uv publish
```
