JN Engine Contributor MCP

A bounded REST and Streamable HTTP MCP gateway for contributors working on JN Engine. It exposes a reviewed, immutable repository snapshot to ChatGPT, Claude, MCP-compatible coding agents, and ordinary HTTP clients without giving those clients shell or Git access to the host.

This is the public, contributor-safe distribution. It contains the complete service, tests, snapshot exporters, Docker configuration, and example deployment files. It does not contain production credentials, personal paths, private hostnames, audit records, incident reports, or mutable operator data.

What It Provides

The engine profile exposes nine tools:

• search and fetch for commit-bound source and documentation retrieval;
• list_tasks and project_context for bounded project orientation;
• claim_task and release_task for audited, expiring task ownership;
• lookup_symbol for recovered symbol/address lookup; and
• check_status for fail-closed core and assets GitHub Actions status;
• open_pr for a narrowly constrained contributor pull-request path.

An optional source profile exposes this repository itself through search, fetch, and repository_context. That profile lets a web or app-based agent inspect the MCP implementation even when the platform's account-level GitHub integration is not available as a callable chat tool.

Both profiles use immutable snapshots. Search IDs include the active commit and become invalid after a snapshot refresh, so clients must search again rather than silently mixing content from different revisions.

Why Sanitization Does Not Reduce Contributor Value

The useful parts are present: application behavior, interfaces, tests, fixture data, dependency locks, container boundaries, deployment examples, and contribution rules. Only environment-specific material was excluded. Contributors can:

• run all unit and integration tests;
• build and inspect the container;
• create snapshots from the public JN Engine repository;
• exercise either MCP profile locally without authentication;
• configure their own GitHub OAuth deployment;
• develop new bounded tools and submit pull requests; and
• use the source profile to ground ChatGPT or Claude in this implementation.

See Intended Usage for contributor and operator workflows, and Public Repository Boundary for the exact public/private split.

Quick Start

Requirements: Python 3.11 through 3.13, Git, and ripgrep.

python3 -m venv .venv
.venv/bin/python -m pip install --constraint requirements.lock -e '.[test]'

Build a local immutable snapshot of JN Engine:

JN_REPO_MIRROR_PATH="$PWD/.local/jn-engine.git" \
JN_SNAPSHOT_ROOT="$PWD/.local/snapshots" \
deploy/refresh_snapshot.sh --build-only

The command prints the promoted snapshot path. Start a loopback-only development server with that path:

APP_ENV=development \
AUTH_MODE=authless_local \
API_HOST=127.0.0.1 \
JN_SNAPSHOT_PATH="$PWD/.local/snapshots/<commit>" \
.venv/bin/python -m app.run

Connect an MCP client to http://127.0.0.1:8788/mcp. Authless mode is deliberately restricted to a loopback listener and is not a production configuration.

Verification

CI constructs its own immutable JN Engine fixture before running the suite. Locally, set JN_TEST_SNAPSHOT_PATH to the snapshot created above:

JN_TEST_SNAPSHOT_PATH="$PWD/.local/snapshots/<commit>" \
  .venv/bin/python -m pytest -q

Production GitHub OAuth configuration and secret-file permissions are documented in Deployment. MCP contracts are in MCP Surface.

Security Properties

• Repository identity and ref are code-owned and cannot be redirected by environment variables.
• Snapshot files are inventory checked, contained, non-symlink, regular, bounded, and read-only in production.
• OAuth state is encrypted before being stored in a mode-0700 file-tree directory.
• Secret values are accepted through mode-0600 files, not command-line arguments or URLs.
• Expiring task ownership uses a dedicated versioned mode-0600 ledger, separate from the rotatable status/PR audit log.
• Write actions require the authenticated engine profile and a dedicated PR token; shell actions always fail startup when enabled.
• The container runs non-root with a read-only root filesystem, no capabilities, no Docker socket, and no Git executable.

Report vulnerabilities privately as described in SECURITY.md.

License

Licensed under the MIT License. See LICENSE.