@lowdefy/server-dev 6.1.0 → 7.0.0

package/src/routes/mcp.test.mjs

@@ -0,0 +1,215 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+// The real URI helpers drive the challenge strings, so the header assertions
+// below exercise the actual BETTER_AUTH_URL derivation - only createMcpServer
+// is stubbed out.
+const uriHelpers = await import('@lowdefy/api/routes/mcp/getMcpUri.js');
+
+const mockCreateMcpServer = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  ...uriHelpers,
+  createMcpServer: mockCreateMcpServer,
+}));
+
+jest.unstable_mockModule('@hono/mcp', () => ({
+  StreamableHTTPTransport: class {
+    handleRequest() {
+      return new Response(JSON.stringify({ served: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  },
+}));
+
+const mockAuthJson = { configured: true, oauthProvider: { consentPage: '/oauth/consent' } };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mcpHandler } = await import('./mcp.js');
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+const mockReadConfigFile = jest.fn();
+
+let contextOverrides;
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      config: { basePath: '' },
+      logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+      readConfigFile: mockReadConfigFile,
+      ...contextOverrides,
+    });
+    await next();
+  });
+  app.all('/api/mcp', mcpHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  contextOverrides = {};
+  mockReadConfigFile.mockReset();
+  mockCreateMcpServer.mockReset();
+  mockCreateMcpServer.mockResolvedValue({ connect: jest.fn() });
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: true, endpoints: [] });
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('mcpHandler returns 404 when mcp is not configured', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: false });
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(404);
+  expect(await res.json()).toEqual({ error: 'MCP is not configured.' });
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler challenges an invalid token with the resource metadata pointer', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler extends the challenge with invalid_token when the bearer is not a JWT', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: false };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="The access token is not a JWT. Connect with a client that sends the RFC 8707 resource parameter.", resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+});
+
+test('mcpHandler tells a revoked grant to reconnect and choose an organization', async () => {
+  contextOverrides.mcpAuth = {
+    clientId: 'client_1',
+    organizationId: 'org_1',
+    tokenStatus: 'invalid',
+    parseableJwt: true,
+    revoked: true,
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This connection was disconnected. Reconnect to choose the organization to work in.", resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler gives a token without membership the same challenge as an invalid token', async () => {
+  contextOverrides.mcpAuth = {
+    clientId: 'client_1',
+    organizationId: 'org_1',
+    tokenStatus: 'invalid',
+    parseableJwt: true,
+    noMembership: true,
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler challenges an anonymous request when the surface has no public tool', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: false, endpoints: [] });
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer resource_metadata="https://app.test.com/.well-known/oauth-protected-resource/api/mcp"'
+  );
+});
+
+test('mcpHandler serves an anonymous request when the surface has a public tool', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});
+
+test('mcpHandler serves a valid-token request and never challenges past the boundary', async () => {
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: false, endpoints: [] });
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'valid',
+    parseableJwt: true,
+    grantedScopes: ['mcp:read'],
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});
+
+test('mcpHandler refuses a foreign Origin with a 403', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://evil.test' },
+  });
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({ error: 'Origin not allowed.' });
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler accepts the pinned canonical origin', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://app.test.com' },
+  });
+  expect(res.status).toEqual(200);
+});
+
+test('mcpHandler accepts an origin registered on BetterAuth trustedOrigins', async () => {
+  contextOverrides.mcpAuth = { tokenStatus: 'none', parseableJwt: true };
+  contextOverrides.auth = { options: { trustedOrigins: ['https://studio.test.com'] } };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://studio.test.com' },
+  });
+  expect(res.status).toEqual(200);
+});
+
+test('mcpHandler serves openly with no envelope when oauthProvider is not configured', async () => {
+  delete mockAuthJson.oauthProvider;
+  contextOverrides.mcpAuth = { tokenStatus: 'invalid', parseableJwt: false };
+  const res = await createApp().request('/api/mcp', {
+    method: 'POST',
+    headers: { Origin: 'https://evil.test' },
+  });
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ served: true });
+});

package/src/routes/mcpMemberToken.test.mjs

@@ -0,0 +1,125 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+// The real URI helpers drive the challenge strings, so the header assertions
+// below exercise the actual BETTER_AUTH_URL derivation - only createMcpServer
+// is stubbed out.
+const uriHelpers = await import('@lowdefy/api/routes/mcp/getMcpUri.js');
+
+const mockCreateMcpServer = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  ...uriHelpers,
+  createMcpServer: mockCreateMcpServer,
+}));
+
+jest.unstable_mockModule('@hono/mcp', () => ({
+  StreamableHTTPTransport: class {
+    handleRequest() {
+      return new Response(JSON.stringify({ served: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  },
+}));
+
+const mockAuthJson = { configured: true, oauthProvider: { consentPage: '/oauth/consent' } };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mcpHandler } = await import('./mcp.js');
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+const mockReadConfigFile = jest.fn();
+
+let contextOverrides;
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      config: { basePath: '' },
+      logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+      readConfigFile: mockReadConfigFile,
+      ...contextOverrides,
+    });
+    await next();
+  });
+  app.all('/api/mcp', mcpHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  contextOverrides = {};
+  mockReadConfigFile.mockReset();
+  mockCreateMcpServer.mockReset();
+  mockCreateMcpServer.mockResolvedValue({ connect: jest.fn() });
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: true, endpoints: [] });
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('mcpHandler answers a refused member token with its reason and no resource metadata', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: 'This token has expired.',
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token has expired."'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler answers a member token whose member is gone with that reason', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: "This token's member can no longer use it.",
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token\'s member can no longer use it."'
+  );
+});
+
+test('mcpHandler serves a valid member token caller', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'valid',
+    tokenId: 'token_1',
+    organizationId: 'org_1',
+    grantedScopes: ['mcp:read', 'mcp:write'],
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(mockCreateMcpServer).toHaveBeenCalledTimes(1);
+});

package/src/routes/mcpProtectedResourceMetadata.js

@@ -0,0 +1,34 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { getAsIssuer, getMcpResourceUri, MCP_OAUTH_SCOPES } from '@lowdefy/api';
+
+import lowdefyConfig from '../../lib/build/config.js';
+
+// RFC 9728 protected-resource metadata for the MCP endpoint. Constant per
+// deployment: the URIs derive from the pinned BETTER_AUTH_URL, never a Host
+// header. The organization a token acts in is not part of the resource - it is
+// chosen at authorization and carried as a token claim.
+function mcpProtectedResourceMetadataHandler(c) {
+  return c.json({
+    resource: getMcpResourceUri({ config: lowdefyConfig }),
+    authorization_servers: [getAsIssuer({ config: lowdefyConfig })],
+    scopes_supported: MCP_OAUTH_SCOPES,
+    bearer_methods_supported: ['header'],
+  });
+}
+
+export default mcpProtectedResourceMetadataHandler;

package/src/routes/mcpProtectedResourceMetadata.test.mjs

@@ -0,0 +1,65 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+jest.unstable_mockModule('../../lib/build/config.js', () => ({
+  default: { basePath: '' },
+}));
+
+const { default: mcpProtectedResourceMetadataHandler } = await import(
+  './mcpProtectedResourceMetadata.js'
+);
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+function createApp() {
+  const app = new Hono();
+  app.get('/.well-known/oauth-protected-resource/api/mcp', mcpProtectedResourceMetadataHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('metadata handler serves the single MCP resource document', async () => {
+  const res = await createApp().request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({
+    resource: 'https://app.test.com/api/mcp',
+    authorization_servers: ['https://app.test.com/api/auth'],
+    scopes_supported: ['mcp:read', 'mcp:write', 'offline_access'],
+    bearer_methods_supported: ['header'],
+  });
+});
+
+test('metadata handler derives the resource from BETTER_AUTH_URL, never the request host', async () => {
+  const res = await createApp().request(
+    'http://evil.example.com/.well-known/oauth-protected-resource/api/mcp'
+  );
+  expect(res.status).toEqual(200);
+  expect((await res.json()).resource).toEqual('https://app.test.com/api/mcp');
+});

package/src/routes/mountDevPageRoutes.js

@@ -0,0 +1,25 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// Every page path renders the same dev shell; the client reads the page from
+// the URL. `.*`, not `.+`: under a basePath, `<basePath>/` arrives with an
+// empty rest, and is the app root like `<basePath>` itself.
+function mountDevPageRoutes({ app, renderPage }) {
+  app.get('/', renderPage);
+  app.get('/:rest{.*}', renderPage);
+}
+
+export default mountDevPageRoutes;

package/src/routes/mountDevPageRoutes.test.mjs

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+
+import mountDevPageRoutes from './mountDevPageRoutes.js';
+
+test.each([
+  ['/app', '/app'],
+  ['/app', '/app/'],
+  ['/app', '/app/invoices'],
+])('with basePath "%s", %s renders the dev shell', async (basePath, path) => {
+  const app = basePath === '' ? new Hono() : new Hono().basePath(basePath);
+  mountDevPageRoutes({ app, renderPage: (c) => c.text('shell') });
+  const res = await app.request(path);
+  expect(await res.text()).toEqual('shell');
+});

package/src/routes/mountOauthDiscovery.js

@@ -0,0 +1,44 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { createAsMetadataHandler } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
+
+import authJson from '../../lib/build/auth.js';
+import mcpProtectedResourceMetadataHandler from './mcpProtectedResourceMetadata.js';
+
+// OAuth discovery for the MCP resource. Both documents are public,
+// unauthenticated and constant per deployment, so they mount outside the api
+// context. Nothing mounts when the app is not an authorization server - the
+// build then guaranteed an all-public tool surface with nothing to discover.
+function mountOauthDiscovery({ app, auth }) {
+  if (type.isNone(authJson.oauthProvider)) {
+    return;
+  }
+  app.get('/.well-known/oauth-protected-resource/api/mcp', mcpProtectedResourceMetadataHandler);
+  // The auth instance is absent only in dev mock mode, which runs no auth
+  // engine - the static resource document above still serves there.
+  if (type.isNone(auth)) {
+    return;
+  }
+  // The oauth-provider serves its AS metadata relative to the auth mount, so
+  // the RFC 8414 path-inserted location a client derives from the issuer must
+  // be mounted here, re-exposing the same live document.
+  const asMetadataHandler = createAsMetadataHandler({ auth });
+  app.get('/.well-known/oauth-authorization-server/api/auth', (c) => asMetadataHandler(c.req.raw));
+}
+
+export default mountOauthDiscovery;

package/src/routes/mountOauthDiscovery.test.mjs

@@ -0,0 +1,79 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const mockCreateAsMetadataHandler = jest.fn(
+  () => async () =>
+    new Response(JSON.stringify({ issuer: 'https://app.test.com/api/auth' }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+);
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  createAsMetadataHandler: mockCreateAsMetadataHandler,
+}));
+
+jest.unstable_mockModule('./mcpProtectedResourceMetadata.js', () => ({
+  default: (c) => c.json({ resource: 'mcp' }),
+}));
+
+const mockAuthJson = { configured: true };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mountOauthDiscovery } = await import('./mountOauthDiscovery.js');
+
+beforeEach(() => {
+  delete mockAuthJson.oauthProvider;
+});
+
+test('mountOauthDiscovery mounts nothing when oauthProvider is not configured', async () => {
+  const app = new Hono();
+  mountOauthDiscovery({ app, auth: { api: {} } });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(404);
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(404);
+  expect(mockCreateAsMetadataHandler).not.toHaveBeenCalled();
+});
+
+test('mountOauthDiscovery mounts both discovery documents when oauthProvider is configured', async () => {
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  const app = new Hono();
+  const auth = { api: {} };
+  mountOauthDiscovery({ app, auth });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(200);
+  expect(await resourceRes.json()).toEqual({ resource: 'mcp' });
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(200);
+  expect(await asRes.json()).toEqual({ issuer: 'https://app.test.com/api/auth' });
+  expect(mockCreateAsMetadataHandler).toHaveBeenCalledWith({ auth });
+});
+
+test('mountOauthDiscovery serves only the static resource document without an auth instance', async () => {
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  const app = new Hono();
+  mountOauthDiscovery({ app, auth: null });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(200);
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(404);
+  expect(mockCreateAsMetadataHandler).not.toHaveBeenCalled();
+});

package/src/routes/normalizeMcpProtocolVersionHeader.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// Claude Code merges the protocol version it negotiated (mcp-protocol-version)
+// with a static MCP-Protocol-Version it sets on every request, and the Fetch
+// Headers constructor folds the two spellings of one header into a single
+// comma-joined value: "2025-11-25, 2025-11-25". @hono/mcp compares that raw
+// string against its supported list, so a client that agrees with the server
+// twice over is answered 404 "Unsupported protocol version" - which Claude Code
+// shows as "MCP endpoint not found". Collapsing a repeated value to the one
+// version it names is lossless; a header naming two DIFFERENT versions is left
+// for the transport to refuse. Runs before the transport reads the header: the
+// transport reads c.req.header(), which reads the raw request headers live.
+function normalizeMcpProtocolVersionHeader({ request }) {
+  const value = request.headers.get('mcp-protocol-version');
+  if (value === null || !value.includes(',')) {
+    return;
+  }
+  const versions = [
+    ...new Set(
+      value
+        .split(',')
+        .map((version) => version.trim())
+        .filter(Boolean)
+    ),
+  ];
+  if (versions.length !== 1) {
+    return;
+  }
+  request.headers.set('mcp-protocol-version', versions[0]);
+}
+
+export default normalizeMcpProtocolVersionHeader;