[mcp] get server action tool

huozhi · huozhi · commit c5338685ccc0 · 2025-09-30T18:06:11.000+02:00
diff --git a/packages/next/src/server/mcp/get-or-create-mcp-server.ts b/packages/next/src/server/mcp/get-or-create-mcp-server.ts
@@ -3,6 +3,7 @@ import { registerGetProjectPathTool } from './tools/get-project-path'
 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'
 
 let mcpServer: McpServer | undefined
@@ -30,6 +31,7 @@ export const getOrCreateMcpServer = (
     getActiveConnectionCount
   )
   registerGetLogsTool(mcpServer, distDir)
+  registerGetActionByIdTool(mcpServer, distDir)
 
   return mcpServer
 }
diff --git a/packages/next/src/server/mcp/tools/get-server-action-by-id.ts b/packages/next/src/server/mcp/tools/get-server-action-by-id.ts
@@ -0,0 +1,144 @@
+import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
+import { z } from 'next/dist/compiled/zod'
+import { promises as fs } from 'fs'
+import { join } from 'path'
+
+const INLINE_ACTION_PREFIX = '$$RSC_SERVER_ACTION_'
+
+interface ActionEntry {
+  workers?: Record<string, any>
+  layer?: Record<string, string>
+  filename: string
+  exportedName: string
+}
+
+interface ServerReferenceManifest {
+  node: Record<string, ActionEntry>
+  edge: Record<string, ActionEntry>
+  encryptionKey: string
+}
+
+export function registerGetActionByIdTool(server: McpServer, distDir: string) {
+  server.registerTool(
+    'get_server_action_by_id',
+    {
+      description:
+        'Locates a Server Action by its ID in the server-reference-manifest.json. Returns the filename and export name for the action.',
+      inputSchema: {
+        actionId: z.string(),
+      },
+    },
+    async (request) => {
+      try {
+        const { actionId } = request
+
+        if (!actionId) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'Error: actionId parameter is required',
+              },
+            ],
+          }
+        }
+
+        const manifestPath = join(
+          distDir,
+          'server',
+          'server-reference-manifest.json'
+        )
+
+        let manifestContent: string
+        try {
+          manifestContent = await fs.readFile(manifestPath, 'utf-8')
+        } catch (error) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error: Could not read server-reference-manifest.json at ${manifestPath}.`,
+              },
+            ],
+          }
+        }
+
+        const manifest: ServerReferenceManifest = JSON.parse(manifestContent)
+
+        // Search in node entries
+        if (manifest.node && manifest.node[actionId]) {
+          const entry = manifest.node[actionId]
+          const isInlineAction =
+            entry.exportedName.startsWith(INLINE_ACTION_PREFIX)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    actionId,
+                    runtime: 'node',
+                    filename: entry.filename,
+                    functionName: isInlineAction
+                      ? 'inline server action'
+                      : entry.exportedName,
+                    layer: entry.layer,
+                    workers: entry.workers,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+          }
+        }
+
+        // Search in edge entries
+        if (manifest.edge && manifest.edge[actionId]) {
+          const entry = manifest.edge[actionId]
+          const isInlineAction =
+            entry.exportedName.startsWith(INLINE_ACTION_PREFIX)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    actionId,
+                    runtime: 'edge',
+                    filename: entry.filename,
+                    functionName: isInlineAction
+                      ? 'inline server action'
+                      : entry.exportedName,
+                    layer: entry.layer,
+                    workers: entry.workers,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: Action ID "${actionId}" not found in server-reference-manifest.json`,
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+        }
+      }
+    }
+  )
+}
diff --git a/test/development/mcp-server/fixtures/actions-app/app/actions.ts b/test/development/mcp-server/fixtures/actions-app/app/actions.ts
@@ -0,0 +1,9 @@
+'use server'
+
+export async function myAction() {
+  return { success: true }
+}
+
+export async function anotherAction() {
+  return { result: 'done' }
+}
diff --git a/test/development/mcp-server/fixtures/actions-app/app/inline/page.tsx b/test/development/mcp-server/fixtures/actions-app/app/inline/page.tsx
@@ -0,0 +1,14 @@
+export default function InlinePage() {
+  async function inlineAction() {
+    'use server'
+    return { inline: true, message: 'This is an inline action' }
+  }
+
+  return (
+    <div>
+      <form action={inlineAction}>
+        <button type="submit">Inline Action</button>
+      </form>
+    </div>
+  )
+}
diff --git a/test/development/mcp-server/fixtures/actions-app/app/layout.tsx b/test/development/mcp-server/fixtures/actions-app/app/layout.tsx
@@ -0,0 +1,11 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
diff --git a/test/development/mcp-server/fixtures/actions-app/app/page.tsx b/test/development/mcp-server/fixtures/actions-app/app/page.tsx
@@ -0,0 +1,11 @@
+'use client'
+
+import { myAction } from './actions'
+
+export default function Page() {
+  return (
+    <div>
+      <button onClick={() => myAction()}>Click me</button>
+    </div>
+  )
+}
diff --git a/test/development/mcp-server/fixtures/actions-app/next.config.js b/test/development/mcp-server/fixtures/actions-app/next.config.js
@@ -0,0 +1,5 @@
+module.exports = {
+  experimental: {
+    mcpServer: true,
+  },
+}
diff --git a/test/development/mcp-server/mcp-server-get-server-action-by-id.test.ts b/test/development/mcp-server/mcp-server-get-server-action-by-id.test.ts
@@ -0,0 +1,174 @@
+import { FileRef, nextTestSetup } from 'e2e-utils'
+import path from 'path'
+import fs from 'fs/promises'
+
+describe('mcp-server get_server_action_by_id tool', () => {
+  const { next } = nextTestSetup({
+    files: new FileRef(path.join(__dirname, 'fixtures', 'actions-app')),
+  })
+
+  it('should return action details via get_server_action_by_id tool', async () => {
+    const mcpEndpoint = `${next.url}/_next/mcp`
+
+    // Visit the page to trigger action registration
+    await next.render('/')
+
+    // Read the manifest to get a valid action ID
+    const manifestPath = path.join(
+      next.testDir,
+      '.next',
+      'server',
+      'server-reference-manifest.json'
+    )
+    const manifestContent = await fs.readFile(manifestPath, 'utf-8')
+    const manifest = JSON.parse(manifestContent)
+
+    // Get the first action ID from the manifest
+    const actionId = Object.keys(manifest.node || {})[0]
+    expect(actionId).toBeTruthy()
+
+    // Call get_server_action_by_id tool
+    const callToolResponse = await fetch(mcpEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 'call-tool-1',
+        method: 'tools/call',
+        params: {
+          name: 'get_server_action_by_id',
+          arguments: {
+            actionId,
+          },
+        },
+      }),
+    })
+
+    const callToolText = await callToolResponse.text()
+    const callToolDataMatch = callToolText.match(/data: ({.*})/s)
+    expect(callToolDataMatch).toBeTruthy()
+
+    const callToolResult = JSON.parse(callToolDataMatch![1])
+    expect(callToolResult.jsonrpc).toBe('2.0')
+    expect(callToolResult.id).toBe('call-tool-1')
+
+    const content = callToolResult.result?.content
+    expect(content).toBeInstanceOf(Array)
+    expect(content?.[0]?.type).toBe('text')
+
+    const actionDetails = JSON.parse(content?.[0]?.text)
+
+    // Verify the action details
+    expect(actionDetails.actionId).toBe(actionId)
+    expect(actionDetails.runtime).toBe('node')
+    expect(actionDetails.filename).toContain('app/actions.ts')
+    expect(actionDetails.functionName).toBeTruthy()
+  })
+
+  it('should return error for non-existent action ID', async () => {
+    const mcpEndpoint = `${next.url}/_next/mcp`
+
+    // Call get_server_action_by_id tool with non-existent ID
+    const callToolResponse = await fetch(mcpEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 'call-tool-2',
+        method: 'tools/call',
+        params: {
+          name: 'get_server_action_by_id',
+          arguments: {
+            actionId: 'non-existent-id-12345',
+          },
+        },
+      }),
+    })
+
+    const callToolText = await callToolResponse.text()
+    const callToolDataMatch = callToolText.match(/data: ({.*})/s)
+    expect(callToolDataMatch).toBeTruthy()
+
+    const callToolResult = JSON.parse(callToolDataMatch![1])
+    expect(callToolResult.jsonrpc).toBe('2.0')
+    expect(callToolResult.id).toBe('call-tool-2')
+
+    const content = callToolResult.result?.content
+    expect(content).toBeInstanceOf(Array)
+    expect(content?.[0]?.type).toBe('text')
+    expect(content?.[0]?.text).toContain('not found')
+  })
+
+  it('should return inline server action details', async () => {
+    const mcpEndpoint = `${next.url}/_next/mcp`
+
+    // Visit the page to trigger action registration
+    await next.render('/inline')
+
+    // Read the manifest to get inline action ID
+    const manifestPath = path.join(
+      next.testDir,
+      '.next',
+      'server',
+      'server-reference-manifest.json'
+    )
+    const manifestContent = await fs.readFile(manifestPath, 'utf-8')
+    const manifest = JSON.parse(manifestContent)
+
+    // Find the inline action ID (inline actions defined in server components)
+    const inlineActionId = Object.keys(manifest.node || {}).find((id) => {
+      const action = manifest.node[id]
+      return (
+        action.filename === 'app/inline/page.tsx' &&
+        action.exportedName?.startsWith('$$RSC_SERVER_ACTION_')
+      )
+    })
+    expect(inlineActionId).toBeTruthy()
+
+    // Call get_server_action_by_id tool for inline action
+    const callToolResponse = await fetch(mcpEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 'call-tool-3',
+        method: 'tools/call',
+        params: {
+          name: 'get_server_action_by_id',
+          arguments: {
+            actionId: inlineActionId,
+          },
+        },
+      }),
+    })
+
+    const callToolText = await callToolResponse.text()
+    const callToolDataMatch = callToolText.match(/data: ({.*})/s)
+    expect(callToolDataMatch).toBeTruthy()
+
+    const callToolResult = JSON.parse(callToolDataMatch![1])
+    expect(callToolResult.jsonrpc).toBe('2.0')
+    expect(callToolResult.id).toBe('call-tool-3')
+
+    const content = callToolResult.result?.content
+    expect(content).toBeInstanceOf(Array)
+    expect(content?.[0]?.type).toBe('text')
+
+    const actionDetails = JSON.parse(content?.[0]?.text)
+
+    // Verify the inline action details
+    expect(actionDetails.actionId).toBe(inlineActionId)
+    expect(actionDetails.runtime).toBe('node')
+    expect(actionDetails.filename).toBeTruthy()
+    expect(actionDetails.functionName).toBe('inline server action')
+  })
+})
