[Maintenance] Replace the deprecated unpinned GitHub MCP package

[fettpl]

Audit metadata

• Priority: P1
• Estimated effort: M
• Implementation risk: MED
• Category: migration
• Evidence baseline: 07be5be7ce69bea0c3118744ab90d148b010fce0 (origin/main on 2026-07-17)

Dependencies

• P1 proposal 039 — Reapprove changed plugin artifacts and minimize MCP child environments. Included in the current P1 issue wave.

Description and impact

The GitHub catalog entry uses npx -y to download and execute the latest version of a deprecated, unsupported package. That is both a supply-chain risk and an uncontrolled compatibility change on first use. GitHub now maintains an official server with cross-platform release artifacts, read-only mode, and explicit toolsets.

Current state

• frontend/src/features/settings/connectors-section.tsx:27-36 configures npx -y @modelcontextprotocol/server-github with no version.
• services/agent-runtime/src/connector-pool.ts:40-49 exposes every advertised tool when no allowlist exists. audit proposal 021 establishes the permission model, audit proposal 028 makes the runtime independently verifiable, and audit proposal 039 binds approval to the exact artifact; all must land first.
• The legacy npm package is marked deprecated and redirects users to GitHub's maintained implementation.
• The official GitHub MCP server supports toolsets and --read-only; at audit time its latest release was v1.6.0 with Darwin, Linux, and Windows archives plus a checksum file.
• Official documentation states that read-only mode removes write tools even when requested explicitly.

Issue specification

Description

Adding the GitHub connector executes whatever package version the npm registry currently serves, without artifact pinning or integrity verification. The selected package is deprecated and lacks the maintained server's read-only/toolset controls.

Steps to reproduce

1. On a machine without an npm cache entry, add the GitHub catalog connector.
2. Inspect the saved command and process invocation.
3. Observe npx -y resolving the current registry package at execution time.
4. Observe no pinned version, digest, read-only flag, or minimal toolset.

Solution design

Replace the catalog entry with GitHub's official local MCP server. Pin a reviewed release and SHA-256 per supported platform/architecture in repository-owned metadata. Download only after explicit user action, verify before extraction, install atomically under the Local Studio data directory, and execute the resolved binary path. Start with --read-only and a minimal reviewed toolset; broader grants flow through audit proposal 021.

Acceptance criteria

• No GitHub connector invokes npx or an unversioned package.
• Every supported archive URL, version, and SHA-256 is checked in and reviewable.
• Hash mismatch, unsupported platform, unsafe archive entry, partial download, and interrupted extraction fail closed without replacing a working install.
• The default GitHub server is read-only with a documented minimal toolset.
• Exact legacy catalog configurations migrate predictably; customized configurations are never overwritten silently.
• A startup/inventory smoke test runs against the pinned official binary or a hermetic fixture with the same CLI contract.

Related issues

#200 covers Windows stdio spawning and process-tree cleanup. audit proposal 021 owns tool authorization. This issue owns only the server artifact and configuration migration.

Verification commands

Purpose	Command	Expected on success
Focused tests	bun test tests/frontend/agent-runtime/connectors-service.test.ts tests/frontend/regression/github-connector-artifact.test.ts	all artifact, migration, and policy cases pass
Frontend test	npm --prefix frontend run test	all tests pass
Frontend quality	npm --prefix frontend run check:quality	exit 0
Full repository	npm run check	exit 0
Integration	npm run test:integration	all tests pass

Scope

In scope:

• frontend/src/features/settings/connectors-section.tsx
• GitHub install/status endpoints under frontend/src/app/api/agent/connectors/
• services/agent-runtime/src/connector-artifacts.ts (create)
• services/agent-runtime/src/connectors-service.ts
• services/agent-runtime/src/connector-contract.ts
• tests/frontend/agent-runtime/connectors-service.test.ts
• tests/frontend/regression/github-connector-artifact.test.ts (create)
• frontend/package.json and frontend/package-lock.json only if direct, pinned archive readers are required

Out of scope:

• Generic plugin/connector marketplace installation (audit proposal 034).
• Connector action approval (audit proposal 021).
• Credential-schema migration (audit proposal 050).
• Automatically updating the binary after this issue lands.

Implementation plan

Step 1: Check in a pinned artifact manifest

Record the selected official version, release base URL, supported OS/architecture archive names, and SHA-256 values. At plan time the reviewed candidate is v1.6.0; if it is changed, require a separate human review of release notes, checksums, and licenses. Reject unsupported tuples before network access.

Verify: manifest tests → every supported tuple resolves one immutable URL/checksum and all others fail.

Step 2: Implement verified atomic installation

Download into a unique owner-only staging directory with a byte/time cap, calculate SHA-256, reject mismatches, prevent archive traversal/symlink escapes, extract, verify the expected executable, and atomically promote to <dataDir>/runtime/connectors/github-mcp-server/<version>. Preserve a known-good version until promotion completes.

Verify: fixture tests → good archive installs; wrong hash, oversized archive, traversal entry, interruption, and duplicate install leave no executable change or temp-secret leak.

Step 3: Migrate the catalog and saved configuration

Make catalog installation explicit rather than automatic at agent execution. Save the absolute verified binary plus official stdio/read-only/minimal-toolset arguments and the explicit audit proposal 021 allowlist. Detect only the exact legacy generated npx -y @modelcontextprotocol/server-github configuration; retain its credential reference while requiring install/review. Leave customized entries untouched and surface a migration notice.

Verify: focused tests → exact legacy config migrates once, custom config remains byte-for-byte unchanged, and new config contains no npx.

Step 4: Add startup and inventory verification

Probe --version/--help and a stdio initialize/list-tools exchange with a test credential boundary that never contacts real repositories. Assert read-only mode exposes no known write tools and the configured toolsets match policy.

Verify: focused smoke → process starts, identifies the pinned version, lists the expected read-only surface, and closes cleanly.

Step 5: Run canonical gates and desktop verification

Run all listed gates, rebuild/reinstall per AGENTS.md, install the artifact through the packaged UI, and confirm desktop health is 200. Do not commit the downloaded binary or credentials.

Verify: all commands exit 0; packaged install path is under user data and matches the checked-in checksum.

Test plan

• Use local fixture archives; unit and CI tests must not depend on GitHub availability.
• Cover every supported OS/architecture mapping and an unsupported tuple.
• Cover integrity, archive traversal, interruption, atomic replacement, permissions, idempotency, and migration.
• Add a process-level CLI/inventory smoke where the CI platform supports the reviewed artifact.

Acceptance criteria

• rg '@modelcontextprotocol/server-github|npx.*github' frontend services tests finds no live catalog/runtime configuration.
• Official artifact version and checksums are checked in.
• Default configuration includes read-only and minimal-toolset controls plus an explicit audit proposal 021 allowlist.
• Focused, frontend, quality, full-repo, and integration gates pass.
• Installed desktop health returns 200.

Risks and stop conditions

• The selected official release lacks a checksum or supported archive for a platform Local Studio claims to support.
• Archive extraction would rely on an undeclared transitive package or unsafe shell parsing.
• The official CLI's read-only/toolset contract differs from the reviewed documentation.
• Migration would overwrite a user-customized GitHub connector.

Maintenance considerations

Artifact upgrades are security-sensitive migrations: update version and every checksum in a dedicated review with release-note and smoke evidence. Never revert to “latest” resolution at connector execution time.

---

Generated from Local Studio 2.0 main-branch audit proposal 038.