# feat\(mcp\): add project management tools · PR \#8677 · pingdotgg/t3code

[View on GitCafe](https://git.cafe/pingdotgg/t3code/pull/8677)

Repository: [pingdotgg/t3code](https://git.cafe/pingdotgg/t3code)

Visibility: public

State: closed

Source repository: pingdotgg/t3code

Source branch: agents/mcp-projects/management

Target branch: t3code/codex-turn-mapping

Head commit: e3f2cdaae2c69d7d84ee05baabec32b1b26c4b10

[Discussion and reviews](https://git.cafe/pingdotgg/t3code/pull/8677)

[Commits](https://git.cafe/pingdotgg/t3code/pull/8677/commits?format=markdown)

[Files changed](https://git.cafe/pingdotgg/t3code/pull/8677/diffs?format=markdown)

## Description

---

## Problem

Agents can work inside projects but cannot discover, register, clone, configure, or safely remove project records through T3's MCP boundary.

## Change

- Add typed `t3_project_list`, `t3_project_read`, `t3_project_create`, `t3_project_update`, and `t3_project_delete` tools backed by `ProjectService`.
- Support existing directories, explicit missing-directory creation, and mutually exclusive URL or provider/repository clone sources.
- Preserve omitted versus explicit-null project defaults, icons, and thread environment modes end to end.
- Serialize receipt-aware thread creation with project deletion through the shared V2 executor.
- Return truthful committed cascade counts while preserving ordinary HTTP and WebSocket project deletion behavior.

## Behavior

Project listing is paginated before per-project configuration reads; full scripts remain on `t3_project_read`. Clone recovery adopts only a completed checkout whose canonical root, exact source, HEAD, origin ref, and destination match. Deletion includes archived and app-owned child threads but never removes workspace files. Accepted create retries replay before mutable project checks, while a deleted stable project ID cannot be resurrected.

## Validation

- 81 focused project MCP, clone, HTTP, ProjectService deletion, shared admission, ThreadLaunch, V2 integration, and contract tests.
- Scoped contracts, client-runtime, shared, and server typechecks.
- Formatting and type-aware lint for the complete changed-file set.

## Stack

Bottom of native stack 8774 on `t3code/codex-turn-mapping` at `415ed0f73b97f1655b6282492f81d0b2bba3a9cc`. [#8678](https://github.com/pingdotgg/t3code/pull/8678) is the dependent launch-targeting layer.

Implemented by GPT-5.6-Sol via Codex in T3 Code.


<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible markers, and the markers themselves will not be visible in the GitHub rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's description, Macroscope will append its summary at the bottom of the description. -->
> [!NOTE]
> ### Add project management MCP tools for list, read, create, update, and delete
> - Adds `ProjectToolkit` with five MCP tools and `ProjectMcpService` backing them, exposing project CRUD operations to MCP clients via [tools.ts](apps/server/src/mcp/toolkits/project/tools.ts) and [ProjectMcpService.ts](apps/server/src/mcp/ProjectMcpService.ts)
> - Adds `ClientCommandDispatch` service that serializes thread creation through project admission and returns `ProjectMutationError` for new commands whose project is absent ([ClientCommandDispatch.ts](apps/server/src/orchestration-v2/ClientCommandDispatch.ts))
> - Adds project creation admission and project mutation locking to `ThreadManagementService`, serializing thread creation and fork/delegated-task dispatch per project ([ThreadManagementService.ts](apps/server/src/orchestration-v2/ThreadManagementService.ts))
> - Reworks `SourceControlRepositoryService.cloneRepository` to serialize clones by canonical destination, recover verified matching clones, and use explicit origin naming ([SourceControlRepositoryService.ts](apps/server/src/sourceControl/SourceControlRepositoryService.ts))
> - Adds `defaultThreadEnvMode` and `faviconPath` fields to project contracts, creation commands, and the client runtime; `ProjectFaviconPath` is validated with a length limit and image-extension allowlist ([project.ts](packages/contracts/src/project.ts))
> - Risk: `ThreadLaunchService.launch` now performs project lookup under the project lock, which changes the ordering of project validation relative to thread claiming; `SourceControlRepositoryService.prepareDestination` no longer rejects populated destinations at preparation time, deferring rejection to matching-clone validation in `isMatchingClone`
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized e3f2cda.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- Macroscope's pull request summary ends here -->