The JN Engine collaboration control plane
jn-engine-ai-gateway is the central operating hub for AI-assisted JN
Engine collaboration. It gives ChatGPT and Claude an exact engine snapshot, live CI,
expiring task ownership, and one audited PR-only write path—without exposing a shell,
a maintainer token, or direct writes to master.
The private jn-engine-ai-gateway
repository is the maintainer-facing home for service operations and this public guide.
Contributors do most work through the two connectors below. The current hardened runtime
is reviewed in the sanitized public jn-engine-contributor-mcp
repository; the native game product remains jn-engine.
Default choice: enable JN Engine AI Gateway first. It is the day-to-day collaboration surface for engine work. Add JN Gateway Repository when you need to inspect or review the MCP implementation, tests, policy, containers, or deployment docs.
The primary contributor surface: native C source, reverse-engineering records,
recovered symbols, committed work queues, active task claims, protected CI status,
and guarded pull-request creation for jn-engine.
https://jn-ai.exentt.com/mcp
Verified snapshot: jn-engine@9f4d2f6 on master. Search IDs begin jn1_; call check_status for current live state.
The read-only review corpus for the hardened gateway implementation: application source, tests, Docker and Compose definitions, workflows, deployment scripts, security policy, and docs. The sanitized implementation is public at jn-engine-contributor-mcp.
https://jn-gateway-ai.exentt.com/mcp
Independently deployed with its own OAuth app, token audience, secrets, snapshot, loopback origin, tunnel ingress, and edge limit.
Verified snapshot: jn-engine-contributor-mcp@c4d8ff4. IDs begin jng1_.
| Question | Use | Why |
|---|---|---|
| What did the original game do at an address or vtable slot? | JN Engine | It contains recovered bodies, symbols, class docs, and linkage evidence. |
| Where is native engine behavior implemented or still open? | JN Engine | It contains source, task ledgers, ownership state, build context, and required CI status. |
| Can I claim work or propose a reviewed engine change? | JN Engine | Its audited ownership tools coordinate the task, and open_pr creates only a guarded contrib/* branch and PR. |
| How does MCP search, OAuth, snapshotting, Docker, or deployment work? | Gateway Repository | Those files belong to the gateway repository, not the game snapshot. |
| Does the gateway expose the Docker and workflow files Claude previously missed? | Gateway Repository | Its allowlist explicitly includes Docker, Compose, tests, deploy, and workflows. |
| Does work cross the engine and gateway? | Both | Use engine evidence and coordination from the primary MCP, then inspect the gateway implementation with its separate read-only corpus. |
Six tools read project or CI evidence. claim_task and
release_task change only the durable ownership ledger.
open_pr is the sole GitHub mutation surface. All nine are bounded,
idempotent, non-destructive, and scoped to the fixed JN Engine project.
| Tool | Use it for | Key inputs and behavior |
|---|---|---|
project_context | Orienting a new session. | Pass max_chars=1000..20000. Read the returned architecture, build, evidence, and handoff guidance before making project claims. |
search | Finding current engine evidence. | Literal query; scope all|source|docs|re|tasks; limit 1..50. Results are pinned to one snapshot commit. |
fetch | Reading an exact search result. | Accepts only a commit-bound jn1_ ID. If the snapshot changed, search again instead of reusing the stale ID. |
lookup_symbol | Resolving recovered code facts. | Query by name, address, class, or FourCC; limit 1..50. Separate fetched evidence from inference. |
list_tasks | Finding committed work. | Filter by status/source; limit 1..100. Copy the exact returned task_id into claim_task. |
check_status | Checking protected CI and live master. | Provide exactly one of pr or branch, plus an optional full commit SHA. Both core and assets must be successful. |
claim_task | Taking auditable, expiring ownership. | Exact task_id, unique idempotency_key, and duration_minutes=15..1440 (default 120). Identity comes from OAuth, never an owner field. |
release_task | Ending ownership safely. | Requires the exact task_id and opaque claim_id. A stale or wrong claim ID cannot release a newer claim. |
open_pr | Proposing engine changes for review. | Creates one contrib/* branch, one commit, and one non-draft PR to master. Use a stable idempotency key; add expected_base_commit for snapshot-derived full-file writes. |
There is no shell, merge, push-to-master, workflow-edit, or arbitrary-repository tool.
open_pr accepts 1–32 UTF-8 files (up to 200k characters each and 1M total),
rejects dot segments, .git/, and .github/workflows/, and leaves
merge authority with human review plus protected core and assets checks.
Use MCP as the project control plane and evidence source. Use a local checkout for editing, builds, and tests. The normal sequence keeps ownership visible, evidence commit-pinned, writes reviewable, and retries safe.
Call project_context and read the live handoff.
Call check_status(branch="master"); require the snapshot SHA and both checks to match.
Use list_tasks, then search and fetch fresh evidence.
Claim the exact task ID with a unique key and practical expiry.
Edit locally. Follow AGENTS.md; run focused tests and make check.
Call open_pr on a new contrib/* branch with complete file contents.
Call check_status(pr=...); review artifacts and resolve feedback normally.
Release with the returned claim ID before stopping or handing off.
Recommended session instruction
“Use JN Engine AI Gateway as the primary source of truth and coordination surface.
Begin with project context and master status, claim an exact task before editing,
search before fetch, cite the active commit, distinguish evidence from inference,
validate locally, open only a guarded contrib/* PR, check both required
contexts, and release the claim before stopping. Use JN Gateway Repository when the
question is about the MCP implementation itself.”
Check master, list the remote-ownable tasks, claim one for two hours, then fetch the implementation and evidence files I must read before coding.
Look up address 00437c40, fetch its class evidence, and separate recovered facts from inference.
Use repository context, then show how task ownership, stale-base PR rejection, and audit durability fail closed.
Check PR 23 at its current commit, report core and assets independently, and tell me which artifact to inspect if either blocks.
Idempotency is a retry contract, not a naming convenience. Reuse the same
key only when retrying the same logical claim or PR. A replay returns the original result;
a different operation needs a new key and, for open_pr, a fresh branch.
The authenticated engine profile derives contributor identity from OAuth and keeps credentials server-side. Claim events and PR calls are durably audited. The separate Gateway Repository connector stays read-only and cannot be turned into a write service by a contributor.
list_tasks.claim_task with a task-specific key and expiry. Save the returned claim_id.replayed=true and the same claim ID and timestamps.released=false.Claims expire automatically after 15 minutes to 24 hours. A competing caller receives typed conflict with current owner and expiry; callers cannot self-assert an owner.
open_pr does not accept diffs or shell commands.contrib/<topic> branch and an 8–64 character idempotency key.expected_base_commit.check_status. Never treat PR creation as merge approval.An existing branch with the same key replays safely. A different key, stale expected base, disallowed path, unavailable audit path, or unavailable dedicated credential fails closed.
Requesting missing original-game evidence uses composition, not a tenth tool.
docs/ground_truth_requests.md.check_status(branch="master") to resolve to the same snapshot commit.GTR-YYYYMMDD-short-slug request without changing prior rows.open_pr with only that file, a fresh contrib/ground-truth-* branch, its ground-truth-* idempotency key, and the fetched SHA as expected_base_commit.Existing capture-only rows for bare 3SPR, 3ROK, and 3DAI
are already queued. Do not duplicate them or substitute guessed behavior for capture evidence.
Each person connects with their own GitHub identity. Ask the project maintainer for collaborator access, accept the invitation, and never share gateway tokens or browser sessions. Add each live endpoint as a separate app or connector.
Remote connectors are account-based. Once configured, Anthropic documents them for Claude web, Desktop, Cowork, and mobile. Connections originate from Anthropic's cloud, not from your local device.
https://jn-ai.exentt.com/mcp.https://jn-gateway-ai.exentt.com/mcp and the distinct name JN Gateway Repository.Team and Enterprise: an Owner or Primary Owner first uses Organization settings → Connectors → Add → Custom → Web. Members then connect individually from Customize → Connectors.
Free plan: Anthropic currently limits Free accounts to one custom connector. Choose JN Engine first; adding both requires a plan that allows two.
Create developer-mode apps from ChatGPT web. After creation, add the app to a new conversation from the chat's More menu. Availability is controlled by account and workspace settings.
https://jn-ai.exentt.com/mcp.https://jn-gateway-ai.exentt.com/mcp. Do not replace the engine app.Desktop and mobile: app creation is documented through ChatGPT web. Use the resulting app on another ChatGPT surface only when it appears in that surface's app picker; return to web to create, remove, or rescan it.
Tool changes: open the developer-mode app under Settings → Plugins and choose Refresh. Verify the exact nine engine tools or three repository tools before using the app.
Both MCPs are live: register them as separate apps. Their OAuth tokens,
resource audiences, snapshots, and content IDs are intentionally not interchangeable.
Review your client's per-app confirmation policy before invoking claim_task,
release_task, or open_pr.
Access can be pseudonymous in public, but it is not anonymous to every party. GitHub, the MCP operator, the AI provider, Cloudflare, and infrastructure providers may retain account or network metadata. The services do not disclose the operator's private vault, live checkout, credentials, or host paths.
Engine content tools read one immutable snapshot. check_status reads
bounded GitHub CI metadata. Status and PR calls append sanitized, fsynced audit
records; claim and release decisions append to a separate mode-0600 ownership ledger.
Records include authenticated caller identity, bounded arguments, commits, outcome,
and upstream status trail. PR file paths and sizes are recorded, never file contents,
bearer tokens, or GitHub credentials. Gateway Repository tools are closed-world reads
and add no application audit log.
Tool queries and responses still pass through the selected AI platform. Reverse proxy, DNS, and provider logs sit outside the application. Do not put private personal data or secrets into prompts. The write tools' narrow scope does not make prompt content private.
These outcomes distinguish setup, identity, upstream availability, snapshot state, and guarded write conflicts without exposing server internals.
| No app menu | Use the documented web setup path and check plan or workspace policy. Team and Enterprise users may need an owner to register the connector first. |
|---|---|
| Wrong tools | Refresh the developer-mode app or recreate the connector, then require exactly nine engine tools or three Gateway Repository tools. Do not proceed with writes from an older six- or seven-tool client snapshot. |
| 401 | Your MCP session is missing or expired. Disconnect and reconnect the individual app, then complete GitHub OAuth again. |
| 403 | GitHub does not currently report your identity as an authorized JN Engine collaborator. Confirm that the invitation was accepted. |
| 503 | The service could not verify contributor status and failed closed. Wait briefly and retry; do not switch to shared credentials. |
| Client ID | The client retained an OAuth registration the server no longer recognizes. Remove or clear that app's authentication, restart the client if needed, and reconnect so dynamic registration runs again. |
| Stale ID | The immutable snapshot changed after search. Search again, then fetch the newly returned commit-bound ID. |
| Redirect URI | ChatGPT assigns an app-specific callback. If the server rejects it, send the exact callback URL—not an OAuth secret—to the maintainer for explicit allowlisting, then retry the same app. |
conflict | Do not force the operation. Inspect whether another owner holds the task, the claim ID is stale, the branch already belongs to another idempotency key, or master advanced beyond expected_base_commit. Refresh evidence and use a new branch/key only for a genuinely new attempt. |
write_disabled | The authenticated engine profile is not currently write-enabled. Stop; do not try the read-only Gateway Repository connector or ask for a shared token. |
credential_unavailable | A dedicated server-side GitHub credential is absent or unusable. The service fails closed. Contributors should report the typed result; operators must repair the correct least-privilege credential rather than reuse another one. |