Scaffold read-only GitHub MCP entry

backend/__tests__/unit/integrations/hostedMcpClientWiring.test.js

@@ -3,11 +3,10 @@
  * names derived from its id (`hostedMcpClientConfigKeys`). Those names reach
  * the backend only if the helm chart maps them from `api-keys`, and `api-keys`
  * carries them only if the ExternalSecret references their Secret Manager keys.
- * Nothing else holds the three layers together: an entry added without its
- * wiring reads `not_configured` in production while every other test stays
- * green (review-checklist rule 7, a phantom cross-layer contract). This pins
- * the chain for every pre-registered entry, so the next one cannot ship
- * half-wired.
+ * Nothing else holds the three layers together (review-checklist rule 7).
+ * GitHub's ExternalSecret entries are off by default for self-hosted instances.
+ * Dev enables them only after both App client values exist with versions, and
+ * both backend refs remain optional.
  */
 const fs = require('fs');
 const path = require('path');
@@ -17,6 +16,8 @@ const { hostedMcpClientConfigKeys } = require('../../../services/hostedMcpIntake
 const chart = path.join(__dirname, '../../../../k8s/helm/commonly');
 const deployment = fs.readFileSync(path.join(chart, 'templates/core/backend-deployment.yaml'), 'utf8');
 const apiKeys = fs.readFileSync(path.join(chart, 'templates/secrets/api-keys.yaml'), 'utf8');
+const values = fs.readFileSync(path.join(chart, 'values.yaml'), 'utf8');
+const devValues = fs.readFileSync(path.join(chart, 'values-dev.yaml'), 'utf8');
 
 // `- name: ENV` mapped from api-keys, optional so an instance with the entry's
 // flag off still starts. Returns the api-keys key, or null when unmapped.
@@ -51,6 +52,13 @@ const wiringTable = preRegistered.length
   ? preRegistered.map((entry) => [entry.id])
   : [['no-pre-registered-entry']];
 
+test('GitHub client mapping is off by default and enabled only in configured dev', () => {
+  expect(preRegistered.map((entry) => entry.id)).toContain('github-mcp');
+  expect(values).toMatch(/hostedMcp:\n(?:.|\n)*?githubMcp:\n\s+enabled: false/);
+  expect(devValues).toMatch(/hostedMcp:\n(?:.|\n)*?githubMcp:\n\s+enabled: true/);
+  expect(apiKeys).toMatch(/{{- if \.Values\.hostedMcp\.githubMcp\.enabled }}[\s\S]*?secretKey: github-mcp-client-id[\s\S]*?secretKey: github-mcp-client-secret[\s\S]*?{{- end }}/);
+});
+
 describe.each(wiringTable)('%s client wiring', (entryId) => {
   const { clientId, clientSecret } = hostedMcpClientConfigKeys(entryId);
 

backend/__tests__/unit/routes/hostedMcpConnect.callback.test.js

@@ -576,6 +576,19 @@ describe('hosted-mcp connect: callback', () => {
     expect(update.$set['config.grantedScope']).toBe('read');
   });
 
+  it('records an explicit empty scope response without inventing requested scopes', async () => {
+    // GitHub App user tokens can report scope="" even when offline_access
+    // was requested. The callback must preserve what the vendor returned.
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ access_token: 'access-1', scope: '' }),
+    });
+    const res = await callback();
+    expect(outcome(res).hostedMcp).toBe('connected');
+    const [, update] = Integration.findOneAndUpdate.mock.calls[1];
+    expect(update.$set['config.grantedScope']).toBe('');
+  });
+
   it('exchanges a pre-registered callback with instance credentials while retaining PKCE', async () => {
     const originalEntry = { ...FIXTURE_ENTRY };
     const originalId = process.env.GOOGLE_CALENDAR_CLIENT_ID;

backend/__tests__/unit/services/hostedMcpEntry.test.js

@@ -27,6 +27,8 @@ const AIRTABLE_AS_CAPTURE = require('../../fixtures/hostedMcp/airtable-authoriza
 const SENTRY_CAPTURE = require('../../fixtures/hostedMcp/sentry-tools-list-2026-10-19.json');
 const NOTION_CAPTURE = require('../../fixtures/hostedMcp/notion-tools-list-2026-10-19.json');
 const GITLAB_CAPTURE = require('../../fixtures/hostedMcp/gitlab-tools-list-2026-10-19.json');
+const GITHUB_MCP_SOURCE = require('../../fixtures/hostedMcp/github-mcp-tools-source-2026-10-15.json');
+const GITHUB_MCP_PIN = require('../../../integrations/hostedMcp/githubMcpSchemas.json');
 
 const ENTRY_TEXT = 'ENTRY TEXT the pin agreed to.';
 const VENDOR_TEXT = 'VENDOR TEXT nobody reviewed.';
@@ -582,7 +584,7 @@ describe('the shipped catalogue cannot land half-wired', () => {
     // The catalogue is the one place that says what an instance offers before
     // any member has connected anything. Its ordering follows the build plan.
     expect(HOSTED_MCP_ENTRIES.map((entry) => entry.id)).toEqual([
-      'linear', 'google-calendar', 'atlassian', 'airtable', 'sentry', 'notion', 'gitlab',
+      'linear', 'google-calendar', 'atlassian', 'airtable', 'sentry', 'notion', 'gitlab', 'github-mcp',
     ]);
     const catalogue = [linear(), linear({ id: 'notion', title: 'Notion' })];
     expect(findHostedMcpEntry(catalogue, 'notion').title).toBe('Notion');
@@ -830,6 +832,55 @@ describe('the shipped catalogue cannot land half-wired', () => {
     }
   });
 
+  test('GitHub pins six read tools from one fixed upstream commit and exposes no writer', () => {
+    const entry = findHostedMcpEntry(HOSTED_MCP_ENTRIES, 'github-mcp');
+    expect(GITHUB_MCP_SOURCE.sourceCommit).toBe('796afb74711ddc856fe587debc49373e21c8d0f7');
+    expect(GITHUB_MCP_PIN.sourceCommit).toBe(GITHUB_MCP_SOURCE.sourceCommit);
+    expect(entry).toMatchObject({
+      resource: 'https://api.githubcopilot.com/mcp/',
+      issuer: 'https://github.com/login/oauth',
+      client: 'pre-registered',
+      scopes: ['offline_access'],
+      tokenEndpointAuthMethod: 'client_secret_post',
+      revoke: { page: 'https://github.com/settings/applications' },
+    });
+    const expected = [
+      'get_me', 'list_issues', 'issue_read', 'list_pull_requests',
+      'pull_request_read', 'get_file_contents',
+    ];
+    expect(entry.tools.map((tool) => tool.name)).toEqual(expected);
+    expect(GITHUB_MCP_SOURCE.tools.map((tool) => tool.name)).toEqual(expected);
+    const source = new Map(GITHUB_MCP_SOURCE.tools.map((tool) => [tool.name, tool]));
+    for (const tool of entry.tools) {
+      const upstream = source.get(tool.name);
+      expect(tool.upstreamName).toBe(tool.name);
+      expect(tool.class).toBe('read');
+      expect(tool.annotations.readOnlyHint).toBe(true);
+      expect(upstream.annotations.readOnlyHint).toBe(true);
+      expect(canonicalJson(tool.inputSchema)).toBe(canonicalJson(upstream.inputSchema));
+      expect(tool.description).not.toBe(upstream.description);
+      const propertyNames = [];
+      const visit = (value) => {
+        if (!value || typeof value !== 'object') return;
+        if (value.properties && typeof value.properties === 'object') {
+          propertyNames.push(...Object.keys(value.properties));
+        }
+        Object.values(value).forEach(visit);
+      };
+      visit(tool.inputSchema);
+      for (const targetKey of ['url', 'uri', 'fetch_target', 'target_url', 'source_url']) {
+        expect(propertyNames).not.toContain(targetKey);
+      }
+    }
+    const offered = entryToolProjections(entry);
+    expect(offered.map((tool) => tool.name)).toEqual(expected.map((name) => `github-mcp.${name}`));
+    expect(offered.every((tool) => tool.requiredWriteMode === 'read')).toBe(true);
+    for (const name of ['create_issue', 'add_issue_comment', 'create_pull_request', 'merge_pull_request']) {
+      expect(offered.some((tool) => tool.name === `github-mcp.${name}`)).toBe(false);
+    }
+    expect(assessEntryTools(entry, GITHUB_MCP_SOURCE.tools).every((row) => row.verdict === 'ok')).toBe(true);
+  });
+
   test('the Linear pin is the measured list minus caller-chosen fetch paths', () => {
     // The latest capture `connector-ops` took (2026-10-14) is committed beside
     // this suite, so the pin's schemas are compared with the measurement rather

backend/__tests__/unit/services/hostedMcpIntake.test.js

@@ -426,6 +426,28 @@ describe('hosted-mcp intake: pre-registered client authentication', () => {
     );
   });
 
+  it('uses GitHub App client_secret_post for exchange and refresh when metadata omits methods', () => {
+    const { GITHUB_MCP_ENTRY } = require('../../../integrations/hostedMcp/githubMcp');
+    const client = { clientId: 'github-client', clientSecret: 'github-secret' };
+    const exchange = buildTokenExchangeRequest(GITHUB_MCP_ENTRY, {}, client, {
+      redirectUri: 'https://api.commonly.me/api/hosted-mcp/github-mcp/callback',
+      code: 'code', codeVerifier: 'pkce-verifier',
+    });
+    const refresh = buildRefreshRequest(GITHUB_MCP_ENTRY, {}, client, { refreshToken: 'refresh' });
+    for (const request of [exchange, refresh]) {
+      expect(request.headers.Authorization).toBeUndefined();
+      expect(request.body.get('client_id')).toBe(client.clientId);
+      expect(request.body.get('client_secret')).toBe(client.clientSecret);
+      expect(request.body.get('resource')).toBe(GITHUB_MCP_ENTRY.resource);
+    }
+    expect(exchange.body.get('code_verifier')).toBe('pkce-verifier');
+    expect(() => buildRefreshRequest(GITHUB_MCP_ENTRY, {
+      token_endpoint_auth_methods_supported: ['client_secret_basic'],
+    }, client, { refreshToken: 'refresh' })).toThrow(expect.objectContaining({
+      code: 'client_auth_unsupported',
+    }));
+  });
+
   it('uses client_secret_post when both endpoints advertise it', () => {
     const staticEntry = entry({ id: 'google-calendar', client: 'pre-registered' });
     const metadata = {

backend/__tests__/unit/services/toolInstallables.test.js

@@ -229,6 +229,24 @@ describe('one tool Installable per catalogue entry', () => {
     expect(metas['google-calendar'].readiness()).toEqual({ available: false, reason: 'not_configured' });
   });
 
+  test('the pending GitHub MCP entry stays unavailable until both App client values exist', () => {
+    const noConfig = toolInstallableMetas(HOSTED_MCP_ENTRIES, {});
+    expect(noConfig['github-mcp']).toMatchObject({
+      connectionType: 'hosted-mcp',
+      entryId: 'github-mcp',
+    });
+    expect(noConfig['github-mcp'].readiness()).toEqual({ available: false, reason: 'not_configured' });
+
+    const idOnly = toolInstallableMetas(HOSTED_MCP_ENTRIES, { GITHUB_MCP_CLIENT_ID: 'app-client' });
+    expect(idOnly['github-mcp'].readiness()).toEqual({ available: false, reason: 'not_configured' });
+
+    const configured = toolInstallableMetas(HOSTED_MCP_ENTRIES, {
+      GITHUB_MCP_CLIENT_ID: 'app-client',
+      GITHUB_MCP_CLIENT_SECRET: 'app-secret',
+    });
+    expect(configured['github-mcp'].readiness()).toEqual({ available: true });
+  });
+
   test('a hosted entry cannot shadow the builtin GitHub Installable meta', () => {
     expect(() => toolInstallableMetas([{ ...LINEAR_ENTRY, id: 'github' }]))
       .toThrow(/collides with a builtin tool installable: github/);

backend/integrations/hostedMcp/entries.ts

@@ -16,6 +16,7 @@ import { AIRTABLE_ENTRY } from './airtable';
 import { ATLASSIAN_ENTRY } from './atlassian';
 import { GOOGLE_CALENDAR_ENTRY } from './googleCalendar';
 import { GITLAB_ENTRY } from './gitlab';
+import { GITHUB_MCP_ENTRY } from './githubMcp';
 import { LINEAR_ENTRY } from './linear';
 import { NOTION_ENTRY } from './notion';
 import { SENTRY_ENTRY } from './sentry';
@@ -24,6 +25,7 @@ export const HOSTED_MCP_ENTRIES: HostedMcpEntry[] = [
   LINEAR_ENTRY, GOOGLE_CALENDAR_ENTRY, ATLASSIAN_ENTRY, AIRTABLE_ENTRY, SENTRY_ENTRY,
   NOTION_ENTRY,
   GITLAB_ENTRY,
+  GITHUB_MCP_ENTRY,
 ];
 
 /**

backend/integrations/hostedMcp/githubMcp.ts

@@ -0,0 +1,49 @@
+/**
+ * GitHub's remote MCP server. The six input schemas are pinned from
+ * github/github-mcp-server at 796afb74711ddc856fe587debc49373e21c8d0f7
+ * (the upstream tool snapshots), not from a live account. A consenting
+ * account's first tools/list remains the drift check before this is offered.
+ *
+ * The credential is a separate, public GitHub App. GitHub App user tokens use
+ * the app's permissions rather than OAuth scopes; offline_access asks GitHub
+ * for a refresh token only. This entry pins only reads; any write tool must be
+ * pinned separately with owner confirmation. The App's client id and secret
+ * are optional instance configuration. Until registration supplies both, the
+ * catalogue reports not_configured and offers no Connect.
+ */
+import type { HostedMcpEntry, HostedMcpPinnedTool } from '../../services/hostedMcpEntryService';
+import pin from './githubMcpSchemas.json';
+
+const descriptions: Record<string, string> = {
+  get_me: 'Read the account profile for this GitHub connection.',
+  list_issues: 'List issues in a GitHub repository.',
+  issue_read: 'Read an issue and its comments or related issues.',
+  list_pull_requests: 'List pull requests in a GitHub repository.',
+  pull_request_read: 'Read a pull request, its files, reviews or comments.',
+  get_file_contents: 'Read a file or directory in a GitHub repository.',
+};
+
+const tools: HostedMcpPinnedTool[] = pin.tools.map((tool) => ({
+  name: tool.name,
+  upstreamName: tool.name,
+  description: descriptions[tool.name],
+  class: 'read',
+  inputSchema: tool.inputSchema,
+  annotations: { readOnlyHint: true },
+}));
+
+export const GITHUB_MCP_ENTRY: HostedMcpEntry = {
+  id: 'github-mcp',
+  title: 'GitHub',
+  description: 'Read files, issues and pull requests in repositories this GitHub App can access.',
+  resource: 'https://api.githubcopilot.com/mcp/',
+  issuer: 'https://github.com/login/oauth',
+  client: 'pre-registered',
+  // GitHub's AS metadata omits auth methods. Its GitHub App token guide names
+  // client_id and client_secret as POST parameters, so pin that method instead
+  // of applying RFC 8414's Basic default. Confirm on the first live consent.
+  tokenEndpointAuthMethod: 'client_secret_post',
+  scopes: ['offline_access'],
+  revoke: { page: 'https://github.com/settings/applications' },
+  tools,
+};