Rephrased MCP

Local Rephrased MCP is the required team toolkit for engineers. The canonical package lives in the Perforce depot at tools/rephrased-mcp/; the standalone Rephrased-Games/Rephrased-agent-toolkit git repo is a legacy reference copy. Your coding agent (Cursor, Claude Code, Codex, Antigravity, or another IDE that can run MCP) uses it so you can talk normally — you do not name tools.

After setup, the server wraps the Perforce get latest → task → review → submit flow, runs your own pre-review check (engineers get convention_check on C++; designers/artists get content_check on asset paths, naming, and World Partition shape), a pass on the team review server, wiki search, and devlog. Onboarding asks your role first (engineer / designer / artist / producer; QA/usability → designer, audio → artist) and hands back the toolbox for that discipline. Producers onboard for wiki search and Accretion board access (their agent creates/moves tasks over the REST API with the producer's own ace_ token) — they do not use Perforce changelist tools. Unreal MCP (the in-editor bridge) and Perforce source control now auto-connect from the project config — see Auto-connect below.

Prerequisites

• [ ] You have the project synced from Perforce (P4V or p4, client GL_Main_PC)
• [ ] A coding agent is installed (Cursor, Claude Code, Codex, Antigravity, or another MCP-capable IDE)
• [ ] uv is installed, or the first MCP launch can reach the internet so the project launcher can install it automatically

Setup (about 2 minutes)

1. Confirm the MCP launcher

From the project root in your workspace:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/Run-RephrasedMcp.ps1 -CheckOnly

This guardrail checks for uvx. If it is missing, it installs uv with Astral's official Windows installer, refreshes PATH for the current process, then reports success. It writes installer output to %TEMP%\rephrased-uv-install.log so MCP stdout stays clean.

2. Point your IDE at the local server

The project already ships both servers in its configs — rephrased (the team toolkit) and unreal-mcp (the in-editor bridge). You normally do not hand-edit these; sync the project and they are there.

Cursor — .cursor/mcp.json (shipped):

{
  "mcpServers": {
    "rephrased": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts/Run-RephrasedMcp.ps1"]
    },
    "unreal-mcp": {
      "url": "http://127.0.0.1:6388/mcp"
    }
  }
}

Claude Code — root .mcp.json at the project root, next to Rephrased.uproject and CLAUDE.md (shipped, with both servers; the unreal-mcp entry uses "type": "http"). Claude Code does not use Cursor's .cursor/mcp.json; launch Claude Code from the repo root and approve the project MCP when prompted.

Codex — run scripts/Onboard-Codex.ps1. It writes both [mcp_servers.rephrased] and [mcp_servers.unreal-mcp] into ~/.codex/config.toml with an absolute launcher path, explicit cwd, and a 120 s startup timeout; it self-repairs older entries and offers -Verify. Codex does not read .mcp.json (that file feeds Claude Code) or .cursor/mcp.json (Cursor) — Codex loads MCP servers only from config.toml, so verify the install with codex mcp list before restarting. App-UI fallback: Settings → MCP servers → Add server → STDIO, command powershell, args -NoProfile -ExecutionPolicy Bypass -File <absolute path to scripts/Run-RephrasedMcp.ps1>, then Restart. Requires a Codex build with streamable-HTTP MCP support (0.15x+).

Antigravity / other MCP-capable IDEs — paste the same two blocks into that product's MCP settings. Setup pages: Cursor, Claude Code, Codex, Antigravity.

Auto-connect: Unreal MCP + Perforce

• Unreal MCP auto-starts inside the UE 5.8 editor. Rephrased.uproject ships the ModelContextProtocol plugins enabled, and Config/DefaultEditorPerProjectUserSettings.ini pins bAutoStartServer=True on port 6388. Combined with the shipped unreal-mcp client entry above, the flow is hands-off: sync → open the editor (server auto-starts) → launch your agent (endpoint already wired) → connected. It only answers while the editor is open (shows "disconnected" otherwise). See Unreal MCP.
• Perforce (in-editor) auto-connects from Config/DefaultSourceControlSettings.ini, which defaults a fresh workspace to the Perforce provider with UseP4Config=True — the editor reads each user's own p4 set values (P4PORT/P4USER/P4CLIENT), so no credentials live in version control. A user's existing Saved/Config/.../SourceControlSettings.ini still wins, so current setups are untouched; this only seeds first-time opens. Worst case if the seed is not picked up: the Revision Control dialog opens pre-filled from your p4 set and you click Accept Settings once (leave Use P4 Config as shipped).

Unreal MCP is separate from Rephrased MCP: Rephrased MCP handles Perforce workflow, review, wiki, and devlog; Unreal MCP is the live editor bridge for maps/assets/PIE.

Restart the IDE (or reload MCP servers) after syncing.

3. Register (onboard) — "onboard me" flow

Open the project and say "onboard me". The flow has two phases:

Phase 1 (first session, MCP not installed/loaded): 1. Codex: the agent runs scripts/Onboard-Codex.ps1 for you — it adds the rephrased server to ~/.codex/config.toml (absolute launcher path, cwd, 120 s startup timeout) and installs the /onboard prompt. Cursor / Claude Code: approve the project MCP (.cursor/mcp.json for Cursor, root .mcp.json for Claude Code) when prompted. 2. Verify the install landed (Codex): run codex mcp list — the rephrased row must be present and enabled. Codex ignores .mcp.json; if the row is missing, re-run the installer with Codex fully closed, or add the server in the app UI (Settings → MCP servers → Add server → STDIO → command powershell, args -NoProfile -ExecutionPolicy Bypass -File <absolute path to scripts/Run-RephrasedMcp.ps1> → Restart). A restart cannot fix a server that was never registered — if verification fails, report the exact codex mcp list output, don't just restart again. 3. You see the welcome message. 4. Fully quit your tool (system tray → Quit — closing the window is not a quit) and open a new task in the project. MCP tools only load when a session starts.

Phase 2 (after restart): 1. Say "onboard me" again. 2. The agent calls onboarding check. It reports your Perforce workspace health (connection, exclusive-lock typemap on binary assets, P4IGNORE), and your Discord ID state. If you are not registered yet, it asks your role first, then the credentials: - Your role — engineer, designer, artist, or producer (QA/usability → designer; audio → artist). This sets your toolbox: engineers get convention_check, designers/artists get content_check, producers get wiki_query + devlog plus Accretion board access. - Your review key (starts with rephr_, from your lead) — engineers only. Designers, artists, and producers skip it. - Your Discord user ID, so review threads can ping you directly. In Discord, enable User Settings -> Advanced -> Developer Mode, then right-click yourself and choose Copy User ID. - Your Accretion API token (starts with ace_) — producers only. Mint it in Accretion -> Settings -> API Tokens -> Generate. Onboarding validates it against Accretion and stores it locally at ~/.rephrased/accretion-token.txt so the agent can create and move board tasks over the REST API (endpoints and ID tables: Accretion API). Never paste it in Discord. - (Optional) your display name 3. The agent calls onboarding register with your role and Discord ID (engineers also pass their review key, producers their Accretion token). The result lists your discipline's toolbox and confirms the connections (Rephrased MCP, Unreal MCP, in-editor Perforce — producers get the Accretion board instead of the Perforce leg).

This writes ~/.rephrased/config.json and verifies the review server. Task-board moves (start → in progress, review → needs review, submit → submitted) happen on the review server with the shared team Accretion token — content roles never hold a task-board credential. Producers are the exception: they hold their own Accretion token (stored at ~/.rephrased/accretion-token.txt) so their agent can create and move tasks on the production board directly; see Accretion API. If onboarding warns that P4IGNORE is not set, run p4 set P4IGNORE=.p4ignore so the depot ignore rules are honored.

4. Verify

After onboarding, confirm the agent can see the shared tools: onboarding, sync_latest, start_task, request_review, submit, wiki_query, devlog — plus the one for your role: convention_check (engineer) or content_check (designer/artist). Producers: your toolbox is wiki_query and devlog; the Perforce tools exist on the server but are not for you. All nine are registered on the server; your onboarding result shows the toolbox for your discipline.

The first onboarding message now teaches where to get each credential (review key from your lead — engineers only; Discord user ID via Developer Mode) before asking for them.

When you request review, the Rephrased Review Bot opens a thread in the team Discord review channel. The bold first line and thread title identify the changelist, risk, and verdict, and the thread pings you and Gabriel. Review keys are issued per engineer; if your label is wrong, Gabriel can rename it without reissuing your key.

Ask:

What does convention_check do?

If the agent answers from the wiki and repo state, setup is done. If not, check that the rephrased MCP server is running and that you are onboarded.

What Rephrased MCP does

It wraps the Perforce workflow. The agent runs the tools; you ask in normal language.

1. Get latest (sync_latest)

p4 sync your workspace before you start and before you check anything out — binary .uasset/.umap cannot be merged, so you must work from the newest revision.

2. Start a task (start_task)

Syncs latest, then opens a numbered pending changelist described <task_code> [Name] <description>. The task code stays first for Accretion/review automation; the locally onboarded engineer name preserves human attribution when engineers share a Perforce guest account. Each engineer must use a separate workspace/client and register their real display name. If the agent doesn't have the Accretion task code, the MCP asks you for it (a small form if your coding tool supports MCP forms; otherwise the agent asks you in chat). The review server moves that work item to in progress. Perforce replacement for the old git branches — the team works one mainline with exclusive checkout, not per-task branches. Set the new changelist as your current changelist in the editor so checkouts land there.

3. Your code review (convention_check)

Local scan of the C++ you have checked out (p4 diff) against Rephrased UE conventions (AGENTS.md / Coding conventions):

• UE_LOG ASCII only — no emoji, no decorative banners, no empty logs
• No sectional banner comments
• Actor ids via GetActorNameOrLabel(), not GetName()
• Include order: own header → engine → project → third-party
• No speculative placeholder blocks (TODO/FIXME unused/placeholder)

The agent runs this after it edits Source/ C++, and again before submit. It fixes every error/warning, then re-runs until clean. This is your review — it never leaves the machine. It does not replace the team review server or a human.

4. Team review (request_review)

After convention_check is clean and you have compiled, the agent sends your opened change to the team review server — a Rephrased-design review server with a separate, clean review LLM. It picks up the changelist and task code by itself and only asks you if one is missing. If your work is sitting in the default changelist, it gets moved into a numbered changelist first. The review server moves the Accretion work item to IN REVIEW and opens the Discord thread. It reads:

• Source/ C++ text (p4 diff of opened files)
• Config/ text
• Content/ map and uasset paths (not binary guts)

It is a second pass for gameplay / systems mistakes convention check will not catch. Pass a changelist number with shelve: true and it will p4 shelve the change so a reviewer (or Swarm) can pull the exact changelist — this is the pre-commit review that replaces the old pull request. If it returns issues, the agent fixes and sends again until pass. Your compile and PIE still happen. It does not replace a human reviewer.

5. Submit (submit)

After review passes, reverts unchanged opened files and runs p4 submit. Small, frequent changelists — a held lock on a .umap blocks that level for everyone.

Order before submit:

sync_latest → start_task → (work) → convention_check → you compile → request_review → you PIE → devlog → submit

Wiki search (wiki_query) and session devlog also go through this same MCP. They are not a review step.

Daily usage

Engineers talk normally ("fix the overlap", "help me submit"). The coding agent must call MCP tools from AGENTS.md / CLAUDE.md without being asked.

You say	Agent must call
How does camera / runes work?	wiki_query
Get me latest / start a task	sync_latest → start_task
Help me submit / done	convention_check → you compile → request_review → you PIE → devlog → submit

Enforcement that a change was reviewed before it lands is a server-side Perforce trigger (USC admin required); there is no local guard hook. Exclusive checkout on binary assets prevents concurrent clobbering.

Troubleshooting

Symptom	Likely cause	Fix
MCP tools missing in Claude Code	Claude Code was launched outside the repo root, project MCP was not approved, or root .mcp.json is missing	Launch Claude Code from the folder containing Rephrased.uproject, CLAUDE.md, and .mcp.json; run claude mcp list or /mcp; approve rephrased; restart if needed
MCP tools missing in Codex (loops on "restart")	~/.codex/config.toml has no [mcp_servers.rephrased] entry — Codex does not read .mcp.json, so restarts can never fix it	Run scripts/Onboard-Codex.ps1, then codex mcp list must show the rephrased row. If still missing, re-run the installer with Codex fully closed (system tray → Quit) or add the server in the app UI (Settings → MCP servers → Add server). If the row exists but tools are missing, run scripts/Run-RephrasedMcp.ps1 in a terminal to see the real startup error
MCP tools missing in Cursor	Server not configured / not reloaded	Check .cursor/mcp.json, run scripts/Run-RephrasedMcp.ps1 -CheckOnly, reload MCP
uvx not found	uv is missing or not on PATH	Run scripts/Run-RephrasedMcp.ps1 -CheckOnly; it installs uv automatically when internet is available
Not onboarded	No ~/.rephrased/config.json	Run /onboard again
onboarding says not connected	Not logged in to Perforce	p4 login; check p4 set (P4PORT/P4USER/P4CLIENT)
P4IGNORE warning	Ignore file not wired	p4 set P4IGNORE=.p4ignore
Review thread does not ping you	Discord ID missing or wrong	Re-run onboarding register with discord_user_id from Copy User ID
Accretion work item stays unchanged	Review server has no Accretion credential, or the code is not on the item	Ping Gabriel: the server needs ACCRETION_URL / ACCRETION_TOKEN / ACCRETION_PROJECT_ID in its env, or the item needs a code
Review model error on non-C++	Droplet prompt still C++-only	Update droplet review prompt to accept asset path lists; client already sends them

Related

• Perforce workflow — the week-one guide these tools wrap
• Unreal MCP — suggested UE 5.8 editor tools (levels, assets, PIE)
• First day (engineering)
• Self-review workflow
• Working without an AI agent
• Root AGENTS.md / CLAUDE.md

Change history

• 2026-09-28 - Gabriel Li - Producer role in MCP onboarding: producers register for wiki search and Accretion board access — their agent creates/moves tasks over the REST API with the producer's own ace_ token (validated during onboarding, stored locally at ~/.rephrased/accretion-token.txt). Producers skip the review key and the Perforce changelist tools. See Accretion API.
• 2026-09-27 - Gabriel Li - MCP 0.7.0: task board migrated from ClickUp to Accretion. The MCP asks for the Accretion work-item task code (e.g. TOOL-011) instead of a ClickUp code, and every stage move (start → IN PROGRESS, review → IN REVIEW, submit → SUBMITTED) runs on the review server with the shared Accretion token — onboarding no longer collects a ClickUp token.
• 2026-09-27 - Gabriel Li - Fixed the Codex "onboard me" loop: Codex ignores .mcp.json, so the installer now writes an absolute launcher path, explicit cwd, and startup_timeout_sec = 120 into ~/.codex/config.toml, self-repairs stale entries, and offers -Verify. The flow now requires codex mcp list to show the rephrased row before restart, and documents the app-UI fallback and the tray-quit requirement.
• 2026-09-10 - Gabriel Li - MCP 0.6.0: start_task, request_review, and submit ask you for the ClickUp task code if it's missing and find the changelist on their own, so review threads always show a real CL and task code.

• 2026-09-07 - Gabriel Li - Role-aware onboarding: "onboard me" asks engineer/designer/artist first (QA/usability → designer, audio → artist) and returns a role-specific toolbox — engineers keep convention_check, designers/artists get content_check (asset paths, naming, World Partition). Both unreal-mcp (streamable HTTP, port 6388) and rephrased now ship in .mcp.json, .cursor/mcp.json, and the Codex installer. Added Config/DefaultSourceControlSettings.ini so the editor auto-selects Perforce and reads each user's p4 set (UseP4Config=True, no versioned credentials). Onboarding output now confirms the three connections.

• 2026-09-07 - Gabriel Li - Codex onboarding installer now writes the Run-RephrasedMcp.ps1 launcher block instead of calling uvx directly, so Codex shares the same uv install-if-missing guardrail as Claude Code and Cursor. All three tools now behave identically.

• 2026-09-07 - Gabriel Li - Added root .mcp.json for Claude Code project MCP loading and clarified the Claude Code troubleshooting path.

• 2026-09-07 - Gabriel Li - Added scripts/Run-RephrasedMcp.ps1 so Claude Code/Cursor MCP launch checks for uvx and installs uv automatically if missing; clarified that Unreal MCP is separate from Rephrased MCP.

• 2026-09-07 - Gabriel Li - Review threads identify the changelist, risk, and verdict and the Rephrased Review Bot now runs in the team server review channel; key labels can be renamed.

• 2026-09-07 - Gabriel Li - Review threads are now task-code-first with pings under the title; onboarding message teaches the credential steps; keys can be renamed by the lead; review bot moved to the team server review channel.

• 2026-09-07 - Gabriel Li - Added per-engineer onboarding fields for Discord user ID and personal ClickUp token. MCP now uses the engineer's local token for start_task and request_review status transitions, with server fallback for missing tokens.

• 2026-09-06 - Gabriel Li - Documented ClickUp status automation: start_task can move task codes to in progress and request_review moves them to need review.

• 2026-09-06 - Gabriel Li - Added task_code guidance for review requests so Discord review threads can connect shelves back to ClickUp tasks.

• 2026-09-05 — Gabriel Li — Reworked from git to Perforce: tools are now sync_latest, start_task, convention_check, request_review, submit, onboarding, wiki_query, devlog. create_branch retired; convention_check/request_review read p4 diff; onboarding verifies the P4 workspace instead of installing git hooks; review can p4 shelve; added the submit step and the P4IGNORE note.

• 2026-08-27 - Gabriel Li - Added two-phase "onboard me" flow: auto-install via scripts/Onboard-Codex.ps1 (Codex) or repo MCP configs (Cursor/Claude Code), welcome message, restart, then key registration.

• 2026-08-27 - Gabriel Li - Added create_branch and local branch guard hooks for standard task branches; supersedes the earlier reminder-only wording.
• 2026-08-27 - Gabriel Li - Added note that GitHub validates PR template sections separately from MCP review.
• 2026-08-27 - Gabriel Li - Clarified that MCP review complements the GitHub PR template; it does not replace the PR body.
• 2026-08-26 — Gabriel Li — Clarified main repo as canonical MCP source, standalone toolkit as outward reference copy, and confirmed current five-tool MCP state.
• 2026-08-23 — Gabriel Li — Removed Accretion Engine (task system retired); onboarding is review-key only; task tools removed from toolkit.
• 2026-08-14 — Gabriel Li — Page titled Rephrased MCP; after setup, Accretion, local convention review, and the team review server are spelled out.
• 2026-08-13 — Gabriel Li — Linked Unreal MCP; shipped mcp.json example includes port 6388.
• 2026-08-10 — Gabriel Li — Added task_create/task_assign, timer hours, risk tier; Cursor mcp.json in repo.
• 2026-08-10 — Gabriel Li — Rewrote for local uvx MCP, onboarding register, review gate, English-only; removed obsolete remote URL + env-token flow.
• 2026-07-21 — Gabriel Li — Initial doc (remote MCP + ACCRETION_TOKEN env).