[mcp] change get-project-path to get-project-metadata (#84619)

Author: huozhi

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -758,12 +758,13 @@ export async function createHotReloaderTurbopack(
     }),
     ...(nextConfig.experimental.mcpServer
       ? [
-          getMcpMiddleware(
+          getMcpMiddleware({
             projectPath,
             distDir,
-            (message) => hotReloader.send(message),
-            () => clients.size
-          ),
+            sendHmrMessage: (message) => hotReloader.send(message),
+            getActiveConnectionCount: () => clients.size,
+            getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
+          }),
         ]
       : []),
   ]

packages/next/src/server/dev/hot-reloader-webpack.ts

@@ -1632,12 +1632,14 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
       }),
       ...(this.config.experimental.mcpServer
         ? [
-            getMcpMiddleware(
-              this.dir,
-              this.distDir,
-              (message) => this.send(message),
-              () => this.webpackHotMiddleware?.getClientCount() ?? 0
-            ),
+            getMcpMiddleware({
+              projectPath: this.dir,
+              distDir: this.distDir,
+              sendHmrMessage: (message) => this.send(message),
+              getActiveConnectionCount: () =>
+                this.webpackHotMiddleware?.getClientCount() ?? 0,
+              getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
+            }),
           ]
         : []),
     ]

packages/next/src/server/mcp/get-mcp-middleware.ts

@@ -1,15 +1,12 @@
 import type { ServerResponse, IncomingMessage } from 'http'
-import { getOrCreateMcpServer } from './get-or-create-mcp-server'
+import {
+  getOrCreateMcpServer,
+  type McpServerOptions,
+} from './get-or-create-mcp-server'
 import { parseBody } from '../api-utils/node/parse-body'
 import { StreamableHTTPServerTransport } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/streamableHttp'
-import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
 
-export function getMcpMiddleware(
-  projectPath: string,
-  distDir: string,
-  sendHmrMessage: (message: HmrMessageSentToBrowser) => void,
-  getActiveConnectionCount: () => number
-) {
+export function getMcpMiddleware(options: McpServerOptions) {
   return async function (
     req: IncomingMessage,
     res: ServerResponse,
@@ -19,12 +16,7 @@ export function getMcpMiddleware(
     if (!pathname.startsWith('/_next/mcp')) {
       return next()
     }
-    const mcpServer = getOrCreateMcpServer(
-      projectPath,
-      distDir,
-      sendHmrMessage,
-      getActiveConnectionCount
-    )
+    const mcpServer = getOrCreateMcpServer(options)
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: undefined,
     })

packages/next/src/server/mcp/get-or-create-mcp-server.ts

@@ -1,19 +1,22 @@
 import { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
-import { registerGetProjectPathTool } from './tools/get-project-path'
+import { registerGetProjectMetadataTool } from './tools/get-project-metadata'
 import { registerGetErrorsTool } from './tools/get-errors'
 import { registerGetPageMetadataTool } from './tools/get-page-metadata'
 import { registerGetLogsTool } from './tools/get-logs'
 import { registerGetActionByIdTool } from './tools/get-server-action-by-id'
 import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
 
+export interface McpServerOptions {
+  projectPath: string
+  distDir: string
+  sendHmrMessage: (message: HmrMessageSentToBrowser) => void
+  getActiveConnectionCount: () => number
+  getDevServerUrl: () => string | undefined
+}
+
 let mcpServer: McpServer | undefined
 
-export const getOrCreateMcpServer = (
-  projectPath: string,
-  distDir: string,
-  sendHmrMessage: (message: HmrMessageSentToBrowser) => void,
-  getActiveConnectionCount: () => number
-) => {
+export const getOrCreateMcpServer = (options: McpServerOptions) => {
   if (mcpServer) {
     return mcpServer
   }
@@ -23,15 +26,23 @@ export const getOrCreateMcpServer = (
     version: '0.1.0',
   })
 
-  registerGetProjectPathTool(mcpServer, projectPath)
-  registerGetErrorsTool(mcpServer, sendHmrMessage, getActiveConnectionCount)
+  registerGetProjectMetadataTool(
+    mcpServer,
+    options.projectPath,
+    options.getDevServerUrl
+  )
+  registerGetErrorsTool(
+    mcpServer,
+    options.sendHmrMessage,
+    options.getActiveConnectionCount
+  )
   registerGetPageMetadataTool(
     mcpServer,
-    sendHmrMessage,
-    getActiveConnectionCount
+    options.sendHmrMessage,
+    options.getActiveConnectionCount
   )
-  registerGetLogsTool(mcpServer, distDir)
-  registerGetActionByIdTool(mcpServer, distDir)
+  registerGetLogsTool(mcpServer, options.distDir)
+  registerGetActionByIdTool(mcpServer, options.distDir)
 
   return mcpServer
 }

packages/next/src/server/mcp/tools/get-project-path.ts renamed to packages/next/src/server/mcp/tools/get-project-metadata.ts

@@ -1,14 +1,15 @@
 import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
 
-export function registerGetProjectPathTool(
+export function registerGetProjectMetadataTool(
   server: McpServer,
-  projectPath: string
+  projectPath: string,
+  getDevServerUrl: () => string | undefined
 ) {
   server.registerTool(
-    'get_project_path',
+    'get_project_metadata',
     {
       description:
-        'Returns the absolute path of the root directory for this Next.js project.',
+        'Returns the the metadata of this Next.js project, including project path, dev server URL, etc.',
       inputSchema: {},
     },
     async (_request) => {
@@ -24,11 +25,16 @@ export function registerGetProjectPathTool(
           }
         }
 
+        const devServerUrl = getDevServerUrl()
+
         return {
           content: [
             {
               type: 'text',
-              text: projectPath,
+              text: JSON.stringify({
+                projectPath,
+                devServerUrl,
+              }),
             },
           ],
         }

test/development/mcp-server/mcp-server-get-project-path.test.ts renamed to test/development/mcp-server/mcp-server-get-project-metadata.test.ts

@@ -1,14 +1,14 @@
 import { FileRef, nextTestSetup } from 'e2e-utils'
 import path from 'path'
 
-describe('mcp-server get_project_path tool', () => {
+describe('mcp-server get_project_metadata tool', () => {
   const { next } = nextTestSetup({
     files: new FileRef(path.join(__dirname, 'fixtures', 'default-template')),
   })
-  it('should return correct project path via get_project_path tool', async () => {
+  it('should return correct project metadata via get_project_metadata tool', async () => {
     const mcpEndpoint = `${next.url}/_next/mcp`
 
-    // Call get_project_path tool
+    // Call get_project_metadata tool
     const callToolResponse = await fetch(mcpEndpoint, {
       method: 'POST',
       headers: {
@@ -20,7 +20,7 @@ describe('mcp-server get_project_path tool', () => {
         id: 'call-tool-1',
         method: 'tools/call',
         params: {
-          name: 'get_project_path',
+          name: 'get_project_metadata',
           arguments: {},
         },
       }),
@@ -38,12 +38,23 @@ describe('mcp-server get_project_path tool', () => {
     expect(content).toBeInstanceOf(Array)
     expect(content?.[0]?.type).toBe('text')
 
-    const actualProjectPath = content?.[0]?.text
+    const metadataText = content?.[0]?.text
+    expect(metadataText).toBeTruthy()
 
-    // Verify it's an absolute path
-    expect(path.isAbsolute(actualProjectPath)).toBe(true)
+    const metadata = JSON.parse(metadataText)
 
-    // Should match the test directory
-    expect(actualProjectPath).toBe(next.testDir)
+    // Verify projectPath
+    expect(metadata.projectPath).toBeTruthy()
+    expect(path.isAbsolute(metadata.projectPath)).toBe(true)
+    expect(metadata.projectPath).toBe(next.testDir)
+
+    // Verify devServerUrl
+    expect(metadata.devServerUrl).toBeTruthy()
+    expect(metadata.devServerUrl).toMatch(/^https?:\/\//)
+    expect(metadata.devServerUrl).toContain('localhost')
+
+    // The devServerUrl should match the next.url (base URL without path)
+    const expectedBaseUrl = next.url
+    expect(metadata.devServerUrl).toBe(expectedBaseUrl)
   })
 })