diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5bb934da..9951402a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Fixed
- **security**: ⚠️ Several security improvements and access control hardenings. Upgrading to this release is strongly recommended.
+- **mcp**: Gracefully disable MCP OAuth 2.1 with an error log when deploying on remote HTTP IP addresses without breaking the main server or API token MCP access
+- **web**: Add immutable cache headers and conditional 304 Not Modified support for production JavaScript and CSS chunks to prevent unnecessary refetches on page reload
### Changed
diff --git a/README.md b/README.md
index c835f303..f69ac925 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,7 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](https://docs.shumai.one/configuration/hardware-transcoding).
3. Configure environment variables:
- * `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments.
+ * `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. Note: Remote deployments must use HTTPS for MCP OAuth 2.1; if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
* `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
diff --git a/README_CN.md b/README_CN.md
index 39da1f36..6820e79a 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -127,7 +127,7 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
3. 配置环境变量:
- * `BETTER_AUTH_URL`:Shumai 服务的外部公开访问地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。在远程服务器或生产环境中部署时必须配置该变量。
+ * `BETTER_AUTH_URL`:Shumai 服务的外部公开访问地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。在远程服务器或生产环境中部署时必须配置该变量。注意:MCP OAuth 2.1 依赖 HTTPS(本地 loopback 除外);若远程部署使用 HTTP,系统会优雅禁用 MCP OAuth 2.1 并记录日志,Web UI 与基于 API Token 的 MCP 访问不受影响。
* `AWS_ENDPOINT_URL_S3`:默认情况下指向 `http://localhost:{SHUMAI_SERVER_PORT}`。当你使用本地存储(即默认配置 `STORAGE_BACKEND: local`)并在远程服务器、自定义域名或自定义端口上公开访问 Shumai 时,请将 `AWS_ENDPOINT_URL_S3` 设置为客户端浏览器上传和下载文件所使用的外部 URL。
例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
diff --git a/apps/web/src/index.ts b/apps/web/src/index.ts
index c2ec12e4..c43e36d4 100644
--- a/apps/web/src/index.ts
+++ b/apps/web/src/index.ts
@@ -21,6 +21,7 @@ import { embeddingService } from '@shumai/core/src/search/embedding-service'
import { sandboxService } from '@shumai/core'
import { notificationJobService } from '@shumai/core/src/notification/notification-job'
import { autoArchiveJobService } from '@shumai/core/src/asset/auto-archive-job'
+import { createHtmlHandler, createStaticFileHandler } from './static'
if (process.argv.includes('--check')) {
console.log('✅ Web app evaluated successfully!')
@@ -151,7 +152,8 @@ async function run() {
for (const file of bundle.files) {
const routePath = file.path.startsWith('.') ? file.path.slice(1) : file.path
const filePath = join(import.meta.dir, file.path)
- routes[routePath] = () => new Response(Bun.file(filePath), { headers: file.headers })
+ const isHtml = file.loader === 'html' || file.path.endsWith('.html')
+ routes[routePath] = createStaticFileHandler(filePath, file.headers, !isHtml)
}
const sampleFile = bundle.files[0]?.path || bundle.index || ''
@@ -163,13 +165,14 @@ async function run() {
const routePath = '/' + pdfWorkerFile
const filePath = join(bundleDir, pdfWorkerFile)
const bunFile = Bun.file(filePath)
- routes[routePath] = () =>
- new Response(bunFile, {
- headers: {
- 'content-type': 'text/javascript;charset=utf-8',
- etag: `"${bunFile.size}-${bunFile.lastModified}"`,
- },
- })
+ routes[routePath] = createStaticFileHandler(
+ filePath,
+ {
+ 'content-type': 'text/javascript;charset=utf-8',
+ etag: `"${bunFile.size}-${bunFile.lastModified}"`,
+ },
+ true,
+ )
}
} catch (err) {
console.warn('Failed to register pdf.worker route:', err)
@@ -185,16 +188,22 @@ async function run() {
.replaceAll('href="./', 'href="/')
.replaceAll('src="./', 'src="/')
.replaceAll('content="./', 'content="/')
- const serveMainHtml = () => new Response(mainHtmlText, { headers: mainHtmlHeaders })
+ const serveMainHtml = createHtmlHandler(mainHtmlText, mainHtmlHeaders)
routes['/'] = serveMainHtml
routes['/*'] = serveMainHtml
} else {
const fallbackHtmlPath = join(import.meta.dir, 'shumai-app.html')
- const serveFallbackHtml = () =>
- new Response(Bun.file(fallbackHtmlPath), {
- headers: { 'content-type': 'text/html;charset=utf-8' },
- })
+ const fallbackHtmlFile = Bun.file(fallbackHtmlPath)
+ if (!(await fallbackHtmlFile.exists())) {
+ throw new Error(
+ `Production HTML bundle is missing: neither bundle.files nor ${fallbackHtmlPath} exists.`,
+ )
+ }
+ const fallbackRaw = await fallbackHtmlFile.text()
+ const serveFallbackHtml = createHtmlHandler(fallbackRaw, {
+ 'content-type': 'text/html;charset=utf-8',
+ })
routes['/'] = serveFallbackHtml
routes['/*'] = serveFallbackHtml
}
diff --git a/apps/web/src/static.test.ts b/apps/web/src/static.test.ts
new file mode 100644
index 00000000..0376db62
--- /dev/null
+++ b/apps/web/src/static.test.ts
@@ -0,0 +1,175 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { createHtmlHandler, createStaticFileHandler, isEtagMatching, normalizeEtag } from './static'
+
+describe('Static Asset Serving & Caching', () => {
+ const tempChunkPath = join(tmpdir(), `test-chunk-${Date.now()}.js`)
+ const chunkContent = 'console.log("chunk loaded");'
+
+ beforeAll(() => {
+ writeFileSync(tempChunkPath, chunkContent, 'utf8')
+ })
+
+ afterAll(() => {
+ try {
+ unlinkSync(tempChunkPath)
+ } catch {
+ // Ignore cleanup error if already deleted
+ }
+ })
+
+ describe('normalizeEtag', () => {
+ it('quotes unquoted ETags according to RFC 9110', () => {
+ expect(normalizeEtag('hHRmXFeFVSk')).toBe('"hHRmXFeFVSk"')
+ expect(normalizeEtag('ACJrxcts9Iw')).toBe('"ACJrxcts9Iw"')
+ })
+
+ it('preserves already-quoted strong and weak ETags', () => {
+ expect(normalizeEtag('"hHRmXFeFVSk"')).toBe('"hHRmXFeFVSk"')
+ expect(normalizeEtag('W/"hHRmXFeFVSk"')).toBe('W/"hHRmXFeFVSk"')
+ })
+
+ it('returns undefined for empty or missing ETags', () => {
+ expect(normalizeEtag(undefined)).toBeUndefined()
+ expect(normalizeEtag('')).toBeUndefined()
+ expect(normalizeEtag(' ')).toBeUndefined()
+ })
+ })
+
+ describe('isEtagMatching', () => {
+ it('matches exact etag string', () => {
+ expect(isEtagMatching('"12345"', '"12345"')).toBe(true)
+ })
+
+ it('matches weak etag to strong or weak candidates', () => {
+ expect(isEtagMatching('W/"12345"', '"12345"')).toBe(true)
+ expect(isEtagMatching('"12345"', 'W/"12345"')).toBe(true)
+ expect(isEtagMatching('W/"12345"', 'W/"12345"')).toBe(true)
+ })
+
+ it('matches wildcard *', () => {
+ expect(isEtagMatching('"12345"', '*')).toBe(true)
+ })
+
+ it('matches comma-separated candidate lists', () => {
+ expect(isEtagMatching('"12345"', '"old-etag", "12345", "other"')).toBe(true)
+ expect(isEtagMatching('"12345"', '"old-etag", "mismatch"')).toBe(false)
+ })
+
+ it('returns false when etag or ifNoneMatch is missing or empty', () => {
+ expect(isEtagMatching(undefined, '"12345"')).toBe(false)
+ expect(isEtagMatching('"12345"', null)).toBe(false)
+ expect(isEtagMatching('', '"12345"')).toBe(false)
+ expect(isEtagMatching('"12345"', '')).toBe(false)
+ })
+ })
+
+ describe('createStaticFileHandler', () => {
+ it('sets immutable Cache-Control for immutable content-hashed assets', async () => {
+ const handler = createStaticFileHandler(
+ tempChunkPath,
+ { 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
+ true,
+ )
+
+ const req = new Request('http://localhost/chunk-123.js')
+ const res = handler(req)
+
+ expect(res.status).toBe(200)
+ expect(res.headers.get('content-type')).toBe('text/javascript;charset=utf-8')
+ expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
+ expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
+ expect(await res.text()).toBe(chunkContent)
+ })
+
+ it('returns 304 Not Modified when If-None-Match matches the file etag', async () => {
+ const handler = createStaticFileHandler(
+ tempChunkPath,
+ { 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
+ true,
+ )
+
+ const req = new Request('http://localhost/chunk-123.js', {
+ headers: { 'if-none-match': '"chunk-hash-1"' },
+ })
+ const res = handler(req)
+
+ expect(res.status).toBe(304)
+ expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
+ expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
+ expect(await res.text()).toBe('')
+ })
+
+ it('sets no-cache Cache-Control for non-immutable static assets', async () => {
+ const handler = createStaticFileHandler(
+ tempChunkPath,
+ { 'content-type': 'text/plain', etag: '"plain-1"' },
+ false,
+ )
+
+ const req = new Request('http://localhost/robots.txt')
+ const res = handler(req)
+
+ expect(res.status).toBe(200)
+ expect(res.headers.get('cache-control')).toBe('no-cache')
+ })
+
+ it('normalizes unquoted manifest ETags to quoted RFC 9110 strings', async () => {
+ const handler = createStaticFileHandler(
+ tempChunkPath,
+ { 'content-type': 'text/javascript;charset=utf-8', etag: 'hHRmXFeFVSk' },
+ true,
+ )
+
+ const req = new Request('http://localhost/chunk-123.js')
+ const res = handler(req)
+
+ expect(res.status).toBe(200)
+ expect(res.headers.get('etag')).toBe('"hHRmXFeFVSk"')
+
+ const revalidateRes = handler(
+ new Request('http://localhost/chunk-123.js', {
+ headers: { 'if-none-match': '"hHRmXFeFVSk"' },
+ }),
+ )
+ expect(revalidateRes.status).toBe(304)
+ expect(revalidateRes.headers.get('etag')).toBe('"hHRmXFeFVSk"')
+ })
+ })
+
+ describe('createHtmlHandler', () => {
+ const htmlText = '
Shumai'
+
+ it('sets no-cache and generates deterministic ETag for HTML', async () => {
+ const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
+
+ const req = new Request('http://localhost/')
+ const res = handler(req)
+
+ expect(res.status).toBe(200)
+ expect(res.headers.get('content-type')).toBe('text/html;charset=utf-8')
+ expect(res.headers.get('cache-control')).toBe('no-cache')
+ const etag = res.headers.get('etag')
+ expect(etag).toBeTruthy()
+ expect(await res.text()).toBe(htmlText)
+ })
+
+ it('returns 304 Not Modified when HTML If-None-Match matches', async () => {
+ const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
+
+ const initialRes = handler(new Request('http://localhost/'))
+ const etag = initialRes.headers.get('etag')!
+
+ const revalidateReq = new Request('http://localhost/', {
+ headers: { 'if-none-match': etag },
+ })
+ const revalidateRes = handler(revalidateReq)
+
+ expect(revalidateRes.status).toBe(304)
+ expect(revalidateRes.headers.get('cache-control')).toBe('no-cache')
+ expect(await revalidateRes.text()).toBe('')
+ })
+ })
+})
diff --git a/apps/web/src/static.ts b/apps/web/src/static.ts
new file mode 100644
index 00000000..abddbb0f
--- /dev/null
+++ b/apps/web/src/static.ts
@@ -0,0 +1,106 @@
+/**
+ * Helpers for serving static production assets with caching headers and ETag revalidation.
+ */
+
+/**
+ * Checks whether an incoming `If-None-Match` header matches the asset's ETag.
+ * Supports weak ETags (`W/"..."`), exact matches, and comma-separated lists.
+ */
+export function isEtagMatching(etag: string | undefined, ifNoneMatch: string | null): boolean {
+ if (!etag || !ifNoneMatch) {
+ return false
+ }
+
+ const cleanTarget = etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '')
+ if (!cleanTarget) {
+ return false
+ }
+
+ const candidates = ifNoneMatch
+ .split(',')
+ .map((candidate) => candidate.trim().replace(/^W\//, '').replace(/^"|"$/g, ''))
+
+ return candidates.includes(cleanTarget) || candidates.includes('*')
+}
+
+/**
+ * Normalizes an ETag to ensure it is enclosed in quotes according to RFC 9110.
+ * Preserves weak validators (`W/"..."`).
+ */
+export function normalizeEtag(etag: string | undefined): string | undefined {
+ if (!etag) {
+ return undefined
+ }
+ const trimmed = etag.trim()
+ if (!trimmed) {
+ return undefined
+ }
+ if (trimmed.startsWith('W/"') && trimmed.endsWith('"')) {
+ return trimmed
+ }
+ if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+ return trimmed
+ }
+ return `"${trimmed.replace(/^"|"$/g, '')}"`
+}
+
+/**
+ * Creates a route handler for a static file on disk.
+ * Content-hashed assets (e.g. `chunk-*.js`, `chunk-*.css`) should be marked `isImmutable: true`
+ * to be aggressively cached locally by browsers across page reloads.
+ */
+export function createStaticFileHandler(
+ filePath: string,
+ baseHeaders: Record,
+ isImmutable: boolean,
+): (req: Request) => Response {
+ const bunFile = Bun.file(filePath)
+ const rawEtag = baseHeaders.etag || baseHeaders.ETag
+ const normalizedEtag = normalizeEtag(rawEtag)
+ const headers: Record = {
+ ...baseHeaders,
+ ...(normalizedEtag ? { etag: normalizedEtag } : {}),
+ 'cache-control': isImmutable ? 'public, max-age=31536000, immutable' : 'no-cache',
+ }
+ const etag = headers.etag
+
+ return (req: Request): Response => {
+ const ifNoneMatch = req.headers.get('if-none-match')
+ if (etag && isEtagMatching(etag, ifNoneMatch)) {
+ return new Response(null, {
+ status: 304,
+ headers,
+ })
+ }
+ return new Response(bunFile, { headers })
+ }
+}
+
+/**
+ * Creates a route handler for in-memory transformed HTML entry points.
+ * Sets `cache-control: no-cache` with a deterministic ETag, allowing browsers to cache locally
+ * while always revalidating to ensure new chunk hashes are picked up immediately after deployment.
+ */
+export function createHtmlHandler(
+ htmlText: string,
+ baseHeaders: Record,
+): (req: Request) => Response {
+ const rawEtag = baseHeaders.etag || baseHeaders.ETag
+ const etag = normalizeEtag(rawEtag) || `"${Bun.hash(htmlText).toString(16)}"`
+ const headers: Record = {
+ ...baseHeaders,
+ etag,
+ 'cache-control': 'no-cache',
+ }
+
+ return (req: Request): Response => {
+ const ifNoneMatch = req.headers.get('if-none-match')
+ if (isEtagMatching(etag, ifNoneMatch)) {
+ return new Response(null, {
+ status: 304,
+ headers,
+ })
+ }
+ return new Response(htmlText, { headers })
+ }
+}
diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
index fdb4033a..4cecdfd3 100644
--- a/docs/getting-started/quickstart.mdx
+++ b/docs/getting-started/quickstart.mdx
@@ -44,7 +44,7 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
3. **Configure Environment Variables**:
Open `docker-compose.yaml` to adjust environment variables for your deployment:
- - `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments.
+ - `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). This is required for remote servers and production deployments. Note: Remote deployments must use HTTPS for MCP OAuth 2.1; if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
- `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
diff --git a/packages/api/src/mcp-server.remote-http.test.ts b/packages/api/src/mcp-server.remote-http.test.ts
new file mode 100644
index 00000000..d0beab97
--- /dev/null
+++ b/packages/api/src/mcp-server.remote-http.test.ts
@@ -0,0 +1,100 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { Hono } from 'hono'
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { prisma, type User } from '@shumai/db'
+import { setupTestDbHooks } from '@shumai/db/test'
+import { apiTokenService } from '@shumai/core/src/user/api-token'
+import { projectService } from '@shumai/core/src/project/project'
+
+describe('MCP server on remote HTTP BETTER_AUTH_URL', () => {
+ setupTestDbHooks()
+
+ const originalEnv = process.env.BETTER_AUTH_URL
+ let user: User
+ let token: string
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ let app: Hono
+ let isMcpOauthEnabled: boolean
+
+ beforeAll(async () => {
+ process.env.BETTER_AUTH_URL = 'http://43.133.100.178:3000'
+ vi.resetModules()
+
+ const authModule = await import('@shumai/core/src/auth/auth')
+ isMcpOauthEnabled = authModule.isMcpOauthEnabled
+ const mcpServerModule = await import('./mcp-server')
+
+ app = new Hono().route('/', mcpServerModule.default)
+
+ user = await prisma.user.create({
+ data: { name: 'Remote HTTP User', email: `remote-http-${Date.now()}@test.com` },
+ })
+ const team = await prisma.team.create({ data: { name: 'Remote HTTP Team' } })
+ await prisma.teamMember.create({ data: { teamId: team.id, userId: user.id, role: 'owner' } })
+ await projectService.createProject(user, { teamId: team.id, name: 'Remote HTTP Project' })
+
+ const tokenRes = await apiTokenService.createToken(user.id, 'remote-http-test')
+ token = tokenRes.token
+ })
+
+ afterAll(() => {
+ if (originalEnv !== undefined) {
+ process.env.BETTER_AUTH_URL = originalEnv
+ } else {
+ delete process.env.BETTER_AUTH_URL
+ }
+ vi.resetModules()
+ })
+
+ it('omits MCP OAuth plugin and disables isMcpOauthEnabled', () => {
+ expect(isMcpOauthEnabled).toBe(false)
+ })
+
+ it('returns 503 Service Unavailable for unauthenticated requests to /mcp', async () => {
+ const res = await app.request('/mcp', { method: 'POST' })
+ expect(res.status).toBe(503)
+ const body = await res.json()
+ expect(body).toMatchObject({
+ jsonrpc: '2.0',
+ error: {
+ code: -32000,
+ message: expect.stringContaining(
+ 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS',
+ ),
+ },
+ id: null,
+ })
+ })
+
+ it('allows valid API tokens to access /mcp and execute tools even when OAuth is disabled', async () => {
+ const transport = new StreamableHTTPClientTransport(new URL('http://localhost/mcp'), {
+ fetch: async (input, init) => {
+ const headers = new Headers(init?.headers)
+ headers.set('Authorization', `Bearer ${token}`)
+ return app.request(String(input), {
+ ...init,
+ headers,
+ })
+ },
+ })
+ const client = new Client({ name: 'remote-http-client', version: '1.0.0' })
+ await client.connect(transport)
+
+ expect(client.getServerVersion()).toMatchObject({ name: 'shumai' })
+ const { tools } = await client.listTools()
+ expect(tools.length).toBeGreaterThan(0)
+ expect(tools.map((t) => t.name)).toContain('list_projects')
+
+ await client.close()
+ })
+
+ it('rejects invalid API tokens with 401 Unauthorized', async () => {
+ const res = await app.request('/mcp', {
+ method: 'POST',
+ headers: {
+ Authorization: 'Bearer shumai_invalidtoken1234567890',
+ },
+ })
+ expect(res.status).toBe(401)
+ })
+})
diff --git a/packages/api/src/mcp-server.test.ts b/packages/api/src/mcp-server.test.ts
index b82c9126..f53f0432 100644
--- a/packages/api/src/mcp-server.test.ts
+++ b/packages/api/src/mcp-server.test.ts
@@ -6,7 +6,7 @@ import { teamService } from '@shumai/core/src/team/team'
import { s3Service } from '@shumai/core/src/s3/s3'
import { createFolderOp, readAssetOp, runOperation } from '@shumai/core/src/operations'
import { MAX_INLINE_IMAGE_BYTES, MAX_INLINE_IMAGES } from './mcp-extensions/read-asset'
-import mcpServerRoute, { MCP_SERVER_INSTRUCTIONS } from './mcp-server'
+import mcpServerRoute, { disabledOauthHandler, MCP_SERVER_INSTRUCTIONS } from './mcp-server'
vi.mock('@shumai/core/src/operations', async (importOriginal) => ({
...(await importOriginal()),
@@ -402,4 +402,22 @@ describe('MCP server', () => {
])
})
})
+
+ describe('Disabled OAuth Fallback', () => {
+ it('returns 503 Service Unavailable with standard JSON-RPC error payload', async () => {
+ const res = await disabledOauthHandler()
+ expect(res.status).toBe(503)
+ expect(res.headers.get('content-type')).toContain('application/json')
+ const body = await res.json()
+ expect(body).toEqual({
+ jsonrpc: '2.0',
+ error: {
+ code: -32000,
+ message:
+ 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS or a loopback address. Please configure HTTPS or authenticate with a Shumai API token.',
+ },
+ id: null,
+ })
+ })
+ })
})
diff --git a/packages/api/src/mcp-server.ts b/packages/api/src/mcp-server.ts
index 9e791e69..ad9ff3d8 100644
--- a/packages/api/src/mcp-server.ts
+++ b/packages/api/src/mcp-server.ts
@@ -5,7 +5,7 @@ import type { z } from 'zod'
import type { Prisma } from '@shumai/db'
import { dropNullOptionals } from '@shumai/operations'
import { getOperationsForSurface, runOperation, type Operation } from '@shumai/core/src/operations'
-import { auth, authBaseUrl, mcpResource } from '@shumai/core/src/auth/auth'
+import { auth, authBaseUrl, isMcpOauthEnabled, mcpResource } from '@shumai/core/src/auth/auth'
import { apiTokenService } from '@shumai/core/src/user/api-token'
import { mcpExtensions, type McpToolExtension } from './mcp-extensions'
import { assertWritableInDemoMode, describeOperationError } from './operation-support'
@@ -134,40 +134,60 @@ const mcpHandler = createMcpHandler(({ authInfo }) => {
return buildMcpServer(userId)
})
-const oauthHandler = requireMcpAuth(
- auth,
- (req, claims) => {
- const userId = claims.sub
- if (!userId) {
- throw new Error('OAuth token has no sub claim')
- }
- const clientId = (claims.azp as string) ?? (claims.client_id as string) ?? ''
- const scopes =
- typeof claims.scope === 'string'
- ? claims.scope.split(' ')
- : ((claims.scopes as string[]) ?? [])
- return mcpHandler.fetch(req, {
- authInfo: {
- token: '',
- clientId,
- scopes,
- extra: { userId },
+export const disabledOauthHandler = async (): Promise => {
+ return new Response(
+ JSON.stringify({
+ jsonrpc: '2.0',
+ error: {
+ code: -32000,
+ message:
+ 'MCP OAuth 2.1 is disabled on this server because BETTER_AUTH_URL is not HTTPS or a loopback address. Please configure HTTPS or authenticate with a Shumai API token.',
},
- })
- },
- {
- resource: mcpResource,
- // In-process verification: avoids HTTP loopback round-trip and works even in test environments
- // where no HTTP port is bound.
- jwksUrl: (async () => {
- const res = await auth.handler(new Request(`${authBaseUrl}/api/auth/jwks`))
- if (!res.ok) {
- throw new Error(`Failed to load JWKS in-process: ${res.statusText}`)
- }
- return await res.json()
- }) as unknown as string,
- },
-)
+ id: null,
+ }),
+ {
+ status: 503,
+ headers: { 'Content-Type': 'application/json' },
+ },
+ )
+}
+
+const oauthHandler = isMcpOauthEnabled
+ ? requireMcpAuth(
+ auth,
+ (req, claims) => {
+ const userId = claims.sub
+ if (!userId) {
+ throw new Error('OAuth token has no sub claim')
+ }
+ const clientId = (claims.azp as string) ?? (claims.client_id as string) ?? ''
+ const scopes =
+ typeof claims.scope === 'string'
+ ? claims.scope.split(' ')
+ : ((claims.scopes as string[]) ?? [])
+ return mcpHandler.fetch(req, {
+ authInfo: {
+ token: '',
+ clientId,
+ scopes,
+ extra: { userId },
+ },
+ })
+ },
+ {
+ resource: mcpResource,
+ // In-process verification: avoids HTTP loopback round-trip and works even in test environments
+ // where no HTTP port is bound.
+ jwksUrl: (async () => {
+ const res = await auth.handler(new Request(`${authBaseUrl}/api/auth/jwks`))
+ if (!res.ok) {
+ throw new Error(`Failed to load JWKS in-process: ${res.statusText}`)
+ }
+ return await res.json()
+ }) as unknown as string,
+ },
+ )
+ : disabledOauthHandler
/** Shumai's MCP server (Streamable HTTP). Mounted at `/mcp` with dual API token and OAuth 2.1 auth. */
const route = new Hono<{ Variables: { user: User } }>().all('/mcp', async (c) => {
diff --git a/packages/core/src/auth/auth.test.ts b/packages/core/src/auth/auth.test.ts
index b471279e..9dd3584c 100644
--- a/packages/core/src/auth/auth.test.ts
+++ b/packages/core/src/auth/auth.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
import { prisma } from '@shumai/db'
import { setupTestDbHooks } from '@shumai/db/test'
-import { auth, authService } from './auth'
+import { auth, authService, isLoopbackHost, isMcpResourceValid } from './auth'
import { userMetadataService } from '../user-metadata/user-metadata'
import { teamService } from '@shumai/core/src/team/team'
@@ -326,3 +326,48 @@ describe('AuthService Password Reset', () => {
}
})
})
+
+describe('MCP Resource Validation & Loopback Checking', () => {
+ it('correctly identifies loopback hostnames', () => {
+ expect(isLoopbackHost('localhost')).toBe(true)
+ expect(isLoopbackHost('127.0.0.1')).toBe(true)
+ expect(isLoopbackHost('127.0.0.254')).toBe(true)
+ expect(isLoopbackHost('[::1]')).toBe(true)
+
+ expect(isLoopbackHost('43.133.100.178')).toBe(false)
+ expect(isLoopbackHost('192.168.1.100')).toBe(false)
+ expect(isLoopbackHost('10.0.0.1')).toBe(false)
+ expect(isLoopbackHost('example.com')).toBe(false)
+ expect(isLoopbackHost('128.0.0.1')).toBe(false)
+ })
+
+ it('validates MCP resource URLs according to RFC 9728 and MCP security rules', () => {
+ // Loopback HTTP URLs are allowed for development
+ expect(isMcpResourceValid('http://localhost:3000/mcp')).toEqual({ valid: true })
+ expect(isMcpResourceValid('http://127.0.0.1:3000/mcp')).toEqual({ valid: true })
+ expect(isMcpResourceValid('http://[::1]:3000/mcp')).toEqual({ valid: true })
+
+ // HTTPS is allowed for any host (including domains and remote IPs)
+ expect(isMcpResourceValid('https://shumai.example.com/mcp')).toEqual({ valid: true })
+ expect(isMcpResourceValid('https://43.133.100.178:3000/mcp')).toEqual({ valid: true })
+
+ // Remote HTTP IPs and hostnames are rejected (the user issue)
+ const remoteIpResult = isMcpResourceValid('http://43.133.100.178:3000/mcp')
+ expect(remoteIpResult.valid).toBe(false)
+ expect(remoteIpResult.error).toContain(
+ 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs',
+ )
+
+ const remoteDomainResult = isMcpResourceValid('http://shumai.example.com/mcp')
+ expect(remoteDomainResult.valid).toBe(false)
+ expect(remoteDomainResult.error).toContain(
+ 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs',
+ )
+
+ // Invalid URL formats
+ expect(isMcpResourceValid('not-a-url').valid).toBe(false)
+ expect(isMcpResourceValid('http://user:pass@localhost:3000/mcp').valid).toBe(false)
+ expect(isMcpResourceValid('http://localhost:3000/mcp#frag').valid).toBe(false)
+ expect(isMcpResourceValid('http://localhost:3000/mcp?query=1').valid).toBe(false)
+ })
+})
diff --git a/packages/core/src/auth/auth.ts b/packages/core/src/auth/auth.ts
index 4d38114d..ad63eb41 100644
--- a/packages/core/src/auth/auth.ts
+++ b/packages/core/src/auth/auth.ts
@@ -8,6 +8,7 @@ import { teamService } from '@shumai/core/src/team/team'
import { inviteService } from '@shumai/core/src/invite/invite'
import { createAuthMiddleware } from 'better-auth/api'
import { userMetadataService } from '@shumai/core/src/user-metadata/user-metadata'
+import { logger } from '@shumai/core/src/logger'
interface GeneratedResetLink {
url: string
@@ -22,22 +23,80 @@ export const authBaseUrl = (
export const mcpResource = `${authBaseUrl}/mcp`
export { hashPassword } from 'better-auth/crypto'
+/**
+ * Checks whether a host is a loopback address (localhost, 127.0.0.0/8, or [::1]).
+ */
+export function isLoopbackHost(hostname: string): boolean {
+ const ipv4Octets = hostname.split('.')
+ const isIpv4Loopback =
+ ipv4Octets.length === 4 &&
+ ipv4Octets[0] === '127' &&
+ ipv4Octets.every((octet) => /^\d+$/.test(octet) && Number(octet) <= 255)
+ return hostname === 'localhost' || hostname === '[::1]' || isIpv4Loopback
+}
+
+/**
+ * Validates whether an MCP resource URL meets RFC 9728 and MCP security requirements
+ * (HTTPS required unless using a localhost or loopback IP address).
+ */
+export function isMcpResourceValid(resource: string): { valid: boolean; error?: string } {
+ if (typeof resource !== 'string' || !resource) {
+ return { valid: false, error: 'MCP resource must be a non-empty string URL' }
+ }
+ let url: URL
+ try {
+ url = new URL(resource)
+ } catch {
+ return { valid: false, error: 'MCP resource must be an absolute URL' }
+ }
+ if (url.username || url.password) {
+ return { valid: false, error: 'MCP resource URL must not contain credentials' }
+ }
+ if (resource.includes('#')) {
+ return { valid: false, error: 'MCP resource URL must not contain a fragment' }
+ }
+ if (resource.includes('?')) {
+ return { valid: false, error: 'MCP resource URL must not contain a query' }
+ }
+ if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHost(url.hostname))) {
+ return {
+ valid: false,
+ error:
+ 'MCP resource URL must use HTTPS, except for localhost or loopback IP development URLs',
+ }
+ }
+ return { valid: true }
+}
+
+const mcpValidation = isMcpResourceValid(mcpResource)
+export const isMcpOauthEnabled = mcpValidation.valid
+if (!isMcpOauthEnabled) {
+ logger.error(
+ { mcpResource, error: mcpValidation.error },
+ 'MCP OAuth 2.1 is disabled: resource URL must use HTTPS for remote hosts. The main server and Web UI will continue running normally, but MCP OAuth clients cannot connect until HTTPS is configured.',
+ )
+}
+
export const auth = betterAuth({
database: prismaAdapter(prisma, {
provider: 'postgresql',
}),
plugins: [
jwt(),
- mcp({
- loginPage: '/login',
- consentPage: '/consent',
- resource: mcpResource,
- resources: [{ identifier: mcpResource, allowedScopes: ['mcp'] }],
- scopes: ['openid', 'profile', 'email', 'offline_access', 'mcp'],
- allowDynamicClientRegistration: true,
- allowUnauthenticatedClientRegistration: true,
- clientRegistrationDefaultApplicationType: 'infer',
- }),
+ ...(isMcpOauthEnabled
+ ? [
+ mcp({
+ loginPage: '/login',
+ consentPage: '/consent',
+ resource: mcpResource,
+ resources: [{ identifier: mcpResource, allowedScopes: ['mcp'] }],
+ scopes: ['openid', 'profile', 'email', 'offline_access', 'mcp'],
+ allowDynamicClientRegistration: true,
+ allowUnauthenticatedClientRegistration: true,
+ clientRegistrationDefaultApplicationType: 'infer',
+ }),
+ ]
+ : []),
],
emailAndPassword: {
enabled: true,