@mastra/mcp 0.5.0 → 0.5.1-alpha.0

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/mcp@0.5.0-alpha.6 build /home/runner/work/mastra/mastra/packages/mcp
+> @mastra/mcp@0.5.1-alpha.0 build /home/runner/work/mastra/mastra/packages/mcp
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.4.0
 TSC Build start
-TSC ⚡️ Build success in 17099ms
+TSC ⚡️ Build success in 19696ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 12447ms
+DTS ⚡️ Build success in 14884ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 32.75 KB
-CJS ⚡️ Build success in 1410ms
-ESM dist/index.js 32.45 KB
-ESM ⚡️ Build success in 1416ms
+ESM dist/index.js 36.70 KB
+ESM ⚡️ Build success in 1126ms
+CJS dist/index.cjs 37.02 KB
+CJS ⚡️ Build success in 1130ms

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp
 
+## 0.5.1-alpha.0
+
+### Patch Changes
+
+- 23f258c: Add new list and get routes for mcp servers. Changed route make-up for more consistency with existing API routes. Lastly, added in a lot of extra detail that can be optionally passed to the mcp server per the mcp spec.
+- 2672a05: Add MCP servers and tool call execution to playground
+- Updated dependencies [f53a6ac]
+- Updated dependencies [eabdcd9]
+- Updated dependencies [90be034]
+- Updated dependencies [99f050a]
+- Updated dependencies [d0ee3c6]
+- Updated dependencies [23f258c]
+- Updated dependencies [2672a05]
+  - @mastra/core@0.9.5-alpha.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -330,12 +330,12 @@ console.log(Object.keys(resources)); // ['weather', 'dataService']
 if (resources.weather) {
   // Access resources from the weather server
   const weatherResources = resources.weather;
-  
+
   // Each resource has uri, name, description, and mimeType
   weatherResources.forEach(resource => {
     console.log(`${resource.uri}: ${resource.name} (${resource.mimeType})`);
   });
-  
+
   // Find a specific resource by URI
   const forecast = weatherResources.find(r => r.uri === 'weather://forecast');
   if (forecast) {

package/dist/_tsup-dts-rollup.d.cts

@@ -4,11 +4,14 @@ import type * as http from 'node:http';
 import { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
 import { MastraBase } from '@mastra/core/base';
 import { MCPServerBase } from '@mastra/core/mcp';
+import type { MCPServerConfig } from '@mastra/core/mcp';
 import type { MCPServerHonoSSEOptions } from '@mastra/core/mcp';
 import type { MCPServerSSEOptions } from '@mastra/core/mcp';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { RuntimeContext } from '@mastra/core/di';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ServerDetailInfo } from '@mastra/core/mcp';
+import type { ServerInfo } from '@mastra/core/mcp';
 import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import type { SSEStreamingApi } from 'hono/streaming';
@@ -218,15 +221,9 @@ declare class MCPServer extends MCPServerBase {
     getStreamableHTTPTransport(): StreamableHTTPServerTransport | undefined;
     /**
      * Construct a new MCPServer instance.
-     * @param opts.name - Server name
-     * @param opts.version - Server version
-     * @param opts.tools - Tool definitions to register
+     * @param opts - Configuration options for the server, including registry metadata.
      */
-    constructor({ name, version, tools }: {
-        name: string;
-        version: string;
-        tools: ToolsInput;
-    });
+    constructor(opts: MCPServerConfig);
     /**
      * Convert and validate all provided tools, logging registration status.
      * @param tools Tool definitions
@@ -295,6 +292,50 @@ declare class MCPServer extends MCPServerBase {
      * Close the MCP server and all its connections
      */
     close(): Promise<void>;
+    /**
+     * Gets the basic information about the server, conforming to the Server schema.
+     * @returns ServerInfo object.
+     */
+    getServerInfo(): ServerInfo;
+    /**
+     * Gets detailed information about the server, conforming to the ServerDetail schema.
+     * @returns ServerDetailInfo object.
+     */
+    getServerDetail(): ServerDetailInfo;
+    /**
+     * Gets a list of tools provided by this MCP server, including their schemas.
+     * This leverages the same tool information used by the internal ListTools MCP request.
+     * @returns An object containing an array of tool information.
+     */
+    getToolListInfo(): {
+        tools: Array<{
+            name: string;
+            description?: string;
+            inputSchema: any;
+        }>;
+    };
+    /**
+     * Gets information for a specific tool provided by this MCP server.
+     * @param toolId The ID/name of the tool to retrieve.
+     * @returns Tool information (name, description, inputSchema) or undefined if not found.
+     */
+    getToolInfo(toolId: string): {
+        name: string;
+        description?: string;
+        inputSchema: any;
+    } | undefined;
+    /**
+     * Executes a specific tool provided by this MCP server.
+     * @param toolId The ID/name of the tool to execute.
+     * @param args The arguments to pass to the tool's execute function.
+     * @param executionContext Optional context for the tool execution.
+     * @returns A promise that resolves to the result of the tool execution.
+     * @throws Error if the tool is not found, validation fails, or execution fails.
+     */
+    executeTool(toolId: string, args: any, executionContext?: {
+        messages?: any[];
+        toolCallId?: string;
+    }): Promise<any>;
 }
 export { MCPServer }
 export { MCPServer as MCPServer_alias_1 }

package/dist/_tsup-dts-rollup.d.ts

@@ -4,11 +4,14 @@ import type * as http from 'node:http';
 import { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
 import { MastraBase } from '@mastra/core/base';
 import { MCPServerBase } from '@mastra/core/mcp';
+import type { MCPServerConfig } from '@mastra/core/mcp';
 import type { MCPServerHonoSSEOptions } from '@mastra/core/mcp';
 import type { MCPServerSSEOptions } from '@mastra/core/mcp';
 import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { RuntimeContext } from '@mastra/core/di';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ServerDetailInfo } from '@mastra/core/mcp';
+import type { ServerInfo } from '@mastra/core/mcp';
 import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import type { SSEStreamingApi } from 'hono/streaming';
@@ -218,15 +221,9 @@ declare class MCPServer extends MCPServerBase {
     getStreamableHTTPTransport(): StreamableHTTPServerTransport | undefined;
     /**
      * Construct a new MCPServer instance.
-     * @param opts.name - Server name
-     * @param opts.version - Server version
-     * @param opts.tools - Tool definitions to register
+     * @param opts - Configuration options for the server, including registry metadata.
      */
-    constructor({ name, version, tools }: {
-        name: string;
-        version: string;
-        tools: ToolsInput;
-    });
+    constructor(opts: MCPServerConfig);
     /**
      * Convert and validate all provided tools, logging registration status.
      * @param tools Tool definitions
@@ -295,6 +292,50 @@ declare class MCPServer extends MCPServerBase {
      * Close the MCP server and all its connections
      */
     close(): Promise<void>;
+    /**
+     * Gets the basic information about the server, conforming to the Server schema.
+     * @returns ServerInfo object.
+     */
+    getServerInfo(): ServerInfo;
+    /**
+     * Gets detailed information about the server, conforming to the ServerDetail schema.
+     * @returns ServerDetailInfo object.
+     */
+    getServerDetail(): ServerDetailInfo;
+    /**
+     * Gets a list of tools provided by this MCP server, including their schemas.
+     * This leverages the same tool information used by the internal ListTools MCP request.
+     * @returns An object containing an array of tool information.
+     */
+    getToolListInfo(): {
+        tools: Array<{
+            name: string;
+            description?: string;
+            inputSchema: any;
+        }>;
+    };
+    /**
+     * Gets information for a specific tool provided by this MCP server.
+     * @param toolId The ID/name of the tool to retrieve.
+     * @returns Tool information (name, description, inputSchema) or undefined if not found.
+     */
+    getToolInfo(toolId: string): {
+        name: string;
+        description?: string;
+        inputSchema: any;
+    } | undefined;
+    /**
+     * Executes a specific tool provided by this MCP server.
+     * @param toolId The ID/name of the tool to execute.
+     * @param args The arguments to pass to the tool's execute function.
+     * @param executionContext Optional context for the tool execution.
+     * @returns A promise that resolves to the result of the tool execution.
+     * @throws Error if the tool is not found, validation fails, or execution fails.
+     */
+    executeTool(toolId: string, args: any, executionContext?: {
+        messages?: any[];
+        toolCallId?: string;
+    }): Promise<any>;
 }
 export { MCPServer }
 export { MCPServer as MCPServer_alias_1 }

package/dist/index.cjs

@@ -630,15 +630,16 @@ var MCPServer = class extends mcp.MCPServerBase {
   }
   /**
    * Construct a new MCPServer instance.
-   * @param opts.name - Server name
-   * @param opts.version - Server version
-   * @param opts.tools - Tool definitions to register
+   * @param opts - Configuration options for the server, including registry metadata.
    */
-  constructor({ name, version, tools }) {
-    super({ name, version, tools });
-    this.server = new index_js.Server({ name, version }, { capabilities: { tools: {}, logging: { enabled: true } } });
+  constructor(opts) {
+    super(opts);
+    this.server = new index_js.Server(
+      { name: this.name, version: this.version },
+      { capabilities: { tools: {}, logging: { enabled: true } } }
+    );
     this.logger.info(
-      `Initialized MCPServer '${name}' v${version} with tools: ${Object.keys(this.convertedTools).join(", ")}`
+      `Initialized MCPServer '${this.name}' v${this.version} (ID: ${this.id}) with tools: ${Object.keys(this.convertedTools).join(", ")}`
     );
     this.sseHonoTransports = /* @__PURE__ */ new Map();
     this.registerListToolsHandler();
@@ -965,6 +966,117 @@ var MCPServer = class extends mcp.MCPServerBase {
       this.logger.error("Error closing MCP server:", { error });
     }
   }
+  /**
+   * Gets the basic information about the server, conforming to the Server schema.
+   * @returns ServerInfo object.
+   */
+  getServerInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      repository: this.repository,
+      version_detail: {
+        version: this.version,
+        release_date: this.releaseDate,
+        is_latest: this.isLatest
+      }
+    };
+  }
+  /**
+   * Gets detailed information about the server, conforming to the ServerDetail schema.
+   * @returns ServerDetailInfo object.
+   */
+  getServerDetail() {
+    return {
+      ...this.getServerInfo(),
+      package_canonical: this.packageCanonical,
+      packages: this.packages,
+      remotes: this.remotes
+    };
+  }
+  /**
+   * Gets a list of tools provided by this MCP server, including their schemas.
+   * This leverages the same tool information used by the internal ListTools MCP request.
+   * @returns An object containing an array of tool information.
+   */
+  getToolListInfo() {
+    this.logger.debug(`Getting tool list information for MCPServer '${this.name}'`);
+    return {
+      tools: Object.entries(this.convertedTools).map(([toolId, tool]) => ({
+        id: toolId,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.parameters?.jsonSchema || tool.parameters
+      }))
+    };
+  }
+  /**
+   * Gets information for a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to retrieve.
+   * @returns Tool information (name, description, inputSchema) or undefined if not found.
+   */
+  getToolInfo(toolId) {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.debug(`Tool '${toolId}' not found on MCPServer '${this.name}'`);
+      return void 0;
+    }
+    this.logger.debug(`Getting info for tool '${toolId}' on MCPServer '${this.name}'`);
+    return {
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.parameters?.jsonSchema || tool.parameters
+    };
+  }
+  /**
+   * Executes a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to execute.
+   * @param args The arguments to pass to the tool's execute function.
+   * @param executionContext Optional context for the tool execution.
+   * @returns A promise that resolves to the result of the tool execution.
+   * @throws Error if the tool is not found, validation fails, or execution fails.
+   */
+  async executeTool(toolId, args, executionContext) {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.warn(`ExecuteTool: Unknown tool '${toolId}' requested on MCPServer '${this.name}'.`);
+      throw new Error(`Unknown tool: ${toolId}`);
+    }
+    this.logger.debug(`ExecuteTool: Invoking '${toolId}' with arguments:`, args);
+    let validatedArgs = args;
+    if (tool.parameters instanceof zod.z.ZodType && typeof tool.parameters.safeParse === "function") {
+      const validation = tool.parameters.safeParse(args ?? {});
+      if (!validation.success) {
+        const errorMessages = validation.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+        this.logger.warn(`ExecuteTool: Invalid tool arguments for '${toolId}': ${errorMessages}`, {
+          errors: validation.error.format()
+        });
+        throw new zod.z.ZodError(validation.error.issues);
+      }
+      validatedArgs = validation.data;
+    } else {
+      this.logger.debug(
+        `ExecuteTool: Tool '${toolId}' parameters is not a Zod schema with safeParse or is undefined. Skipping validation.`
+      );
+    }
+    if (!tool.execute) {
+      this.logger.error(`ExecuteTool: Tool '${toolId}' does not have an execute function.`);
+      throw new Error(`Tool '${toolId}' cannot be executed.`);
+    }
+    try {
+      const finalExecutionContext = {
+        messages: executionContext?.messages || [],
+        toolCallId: executionContext?.toolCallId || crypto$1.randomUUID()
+      };
+      const result = await tool.execute(validatedArgs, finalExecutionContext);
+      this.logger.info(`ExecuteTool: Tool '${toolId}' executed successfully.`);
+      return result;
+    } catch (error) {
+      this.logger.error(`ExecuteTool: Tool execution failed for '${toolId}':`, { error });
+      throw error instanceof Error ? error : new Error(`Execution of tool '${toolId}' failed: ${String(error)}`);
+    }
+  }
 };
 
 exports.MCPClient = MCPClient;

package/dist/index.js

@@ -624,15 +624,16 @@ var MCPServer = class extends MCPServerBase {
   }
   /**
    * Construct a new MCPServer instance.
-   * @param opts.name - Server name
-   * @param opts.version - Server version
-   * @param opts.tools - Tool definitions to register
+   * @param opts - Configuration options for the server, including registry metadata.
    */
-  constructor({ name, version, tools }) {
-    super({ name, version, tools });
-    this.server = new Server({ name, version }, { capabilities: { tools: {}, logging: { enabled: true } } });
+  constructor(opts) {
+    super(opts);
+    this.server = new Server(
+      { name: this.name, version: this.version },
+      { capabilities: { tools: {}, logging: { enabled: true } } }
+    );
     this.logger.info(
-      `Initialized MCPServer '${name}' v${version} with tools: ${Object.keys(this.convertedTools).join(", ")}`
+      `Initialized MCPServer '${this.name}' v${this.version} (ID: ${this.id}) with tools: ${Object.keys(this.convertedTools).join(", ")}`
     );
     this.sseHonoTransports = /* @__PURE__ */ new Map();
     this.registerListToolsHandler();
@@ -959,6 +960,117 @@ var MCPServer = class extends MCPServerBase {
       this.logger.error("Error closing MCP server:", { error });
     }
   }
+  /**
+   * Gets the basic information about the server, conforming to the Server schema.
+   * @returns ServerInfo object.
+   */
+  getServerInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      repository: this.repository,
+      version_detail: {
+        version: this.version,
+        release_date: this.releaseDate,
+        is_latest: this.isLatest
+      }
+    };
+  }
+  /**
+   * Gets detailed information about the server, conforming to the ServerDetail schema.
+   * @returns ServerDetailInfo object.
+   */
+  getServerDetail() {
+    return {
+      ...this.getServerInfo(),
+      package_canonical: this.packageCanonical,
+      packages: this.packages,
+      remotes: this.remotes
+    };
+  }
+  /**
+   * Gets a list of tools provided by this MCP server, including their schemas.
+   * This leverages the same tool information used by the internal ListTools MCP request.
+   * @returns An object containing an array of tool information.
+   */
+  getToolListInfo() {
+    this.logger.debug(`Getting tool list information for MCPServer '${this.name}'`);
+    return {
+      tools: Object.entries(this.convertedTools).map(([toolId, tool]) => ({
+        id: toolId,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.parameters?.jsonSchema || tool.parameters
+      }))
+    };
+  }
+  /**
+   * Gets information for a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to retrieve.
+   * @returns Tool information (name, description, inputSchema) or undefined if not found.
+   */
+  getToolInfo(toolId) {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.debug(`Tool '${toolId}' not found on MCPServer '${this.name}'`);
+      return void 0;
+    }
+    this.logger.debug(`Getting info for tool '${toolId}' on MCPServer '${this.name}'`);
+    return {
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.parameters?.jsonSchema || tool.parameters
+    };
+  }
+  /**
+   * Executes a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to execute.
+   * @param args The arguments to pass to the tool's execute function.
+   * @param executionContext Optional context for the tool execution.
+   * @returns A promise that resolves to the result of the tool execution.
+   * @throws Error if the tool is not found, validation fails, or execution fails.
+   */
+  async executeTool(toolId, args, executionContext) {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.warn(`ExecuteTool: Unknown tool '${toolId}' requested on MCPServer '${this.name}'.`);
+      throw new Error(`Unknown tool: ${toolId}`);
+    }
+    this.logger.debug(`ExecuteTool: Invoking '${toolId}' with arguments:`, args);
+    let validatedArgs = args;
+    if (tool.parameters instanceof z.ZodType && typeof tool.parameters.safeParse === "function") {
+      const validation = tool.parameters.safeParse(args ?? {});
+      if (!validation.success) {
+        const errorMessages = validation.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ");
+        this.logger.warn(`ExecuteTool: Invalid tool arguments for '${toolId}': ${errorMessages}`, {
+          errors: validation.error.format()
+        });
+        throw new z.ZodError(validation.error.issues);
+      }
+      validatedArgs = validation.data;
+    } else {
+      this.logger.debug(
+        `ExecuteTool: Tool '${toolId}' parameters is not a Zod schema with safeParse or is undefined. Skipping validation.`
+      );
+    }
+    if (!tool.execute) {
+      this.logger.error(`ExecuteTool: Tool '${toolId}' does not have an execute function.`);
+      throw new Error(`Tool '${toolId}' cannot be executed.`);
+    }
+    try {
+      const finalExecutionContext = {
+        messages: executionContext?.messages || [],
+        toolCallId: executionContext?.toolCallId || randomUUID()
+      };
+      const result = await tool.execute(validatedArgs, finalExecutionContext);
+      this.logger.info(`ExecuteTool: Tool '${toolId}' executed successfully.`);
+      return result;
+    } catch (error) {
+      this.logger.error(`ExecuteTool: Tool execution failed for '${toolId}':`, { error });
+      throw error instanceof Error ? error : new Error(`Execution of tool '${toolId}' failed: ${String(error)}`);
+    }
+  }
 };
 
 export { MCPClient, MCPConfiguration, MCPServer, MastraMCPClient };

package/integration-tests/src/server.test.ts

@@ -3,6 +3,7 @@ import { createServer } from 'node:http';
 import path from 'path';
 import { MCPClient } from '@mastra/mcp';
 import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { ServerInfo } from '@mastra/core/mcp';
 
 vi.setConfig({ testTimeout: 20000, hookTimeout: 20000 });
 
@@ -62,7 +63,7 @@ describe('MCPServer through Mastra HTTP Integration (Subprocess)', () => {
     client = new MCPClient({
       servers: {
         [mcpServerId]: {
-          url: new URL(`http://localhost:${port}/api/servers/${mcpServerId}/mcp`),
+          url: new URL(`http://localhost:${port}/api/mcp/${mcpServerId}/mcp`),
         },
       },
     });
@@ -112,7 +113,7 @@ describe('MCPServer through Mastra HTTP Integration (Subprocess)', () => {
   }, 25000);
 
   it('should allow a client to call a tool via Mastra MCP SSE endpoints (Subprocess)', async () => {
-    const sseUrl = new URL(`http://localhost:${port}/api/servers/${mcpServerId}/sse`);
+    const sseUrl = new URL(`http://localhost:${port}/api/mcp/${mcpServerId}/sse`);
 
     // Configure MCPClient for SSE transport
     const sseClient = new MCPClient({
@@ -146,4 +147,98 @@ describe('MCPServer through Mastra HTTP Integration (Subprocess)', () => {
     const expectedToolResult = 15; // 10 + 5
     expect(JSON.parse(toolOutput.text)).toEqual(expectedToolResult);
   }, 25000);
+
+  // --- New tests for MCP Registry API Style Routes ---
+  describe('MCP Registry API Style Endpoints', () => {
+    const defaultMcpServerLogicalId = 'myMcpServer'; // Assuming this is the ID of the default server
+
+    it('GET /api/mcp/v0/servers - should list available MCP servers', async () => {
+      const response = await fetch(`http://localhost:${port}/api/mcp/v0/servers`);
+      expect(response.status).toBe(200);
+      expect(response.headers.get('content-type')).toContain('application/json');
+      const body = await response.json();
+
+      expect(body).toHaveProperty('servers');
+      expect(body).toHaveProperty('total_count');
+      expect(Array.isArray(body.servers)).toBe(true);
+      expect(body.total_count).toBeGreaterThanOrEqual(1); // Expect at least the default server
+
+      const defaultServerInfo: ServerInfo = body.servers.find((s: ServerInfo) => s.id === defaultMcpServerLogicalId);
+      expect(defaultServerInfo).toBeDefined();
+      expect(defaultServerInfo).toHaveProperty('name');
+      expect(defaultServerInfo).toHaveProperty('version_detail');
+      // Based on default mastra dev setup, if myMcpServer is the key, its id becomes 'myMcpServer'
+      // And its name might be something like 'my-mcp-server' if not explicitly set in MCPServerConfig for it.
+      // For this test, we assume the `id` is the key used in Mastra config.
+      expect(defaultServerInfo.id).toBe(defaultMcpServerLogicalId);
+    });
+
+    it('GET /api/mcp/v0/servers/:id - should get specific server details', async () => {
+      // First, get all servers to find the actual version of the default server
+      const listResponse = await fetch(`http://localhost:${port}/api/mcp/v0/servers`);
+      const listBody = await listResponse.json();
+      const defaultServer = listBody.servers.find((s: any) => s.id === defaultMcpServerLogicalId);
+      expect(defaultServer).toBeDefined();
+      const actualVersion = defaultServer.version_detail.version;
+
+      const response = await fetch(`http://localhost:${port}/api/mcp/v0/servers/${defaultMcpServerLogicalId}`);
+      expect(response.status).toBe(200);
+      const body = await response.json();
+
+      expect(body.id).toBe(defaultMcpServerLogicalId);
+      expect(body).toHaveProperty('name');
+      expect(body).toHaveProperty('version_detail');
+      expect(body.version_detail.version).toBe(actualVersion);
+      // Add more assertions for package_canonical, packages, remotes if they are expected for the default server
+    });
+
+    it('GET /api/mcp/v0/servers/:id - should get specific server version if it matches', async () => {
+      const listResponse = await fetch(`http://localhost:${port}/api/mcp/v0/servers`);
+      const listBody = await listResponse.json();
+      const defaultServer = listBody.servers.find((s: any) => s.id === defaultMcpServerLogicalId);
+      expect(defaultServer).toBeDefined();
+      const actualVersion = defaultServer.version_detail.version;
+
+      const response = await fetch(
+        `http://localhost:${port}/api/mcp/v0/servers/${defaultMcpServerLogicalId}?version=${actualVersion}`,
+      );
+      expect(response.status).toBe(200);
+      const body = await response.json();
+      expect(body.id).toBe(defaultMcpServerLogicalId);
+      expect(body.version_detail.version).toBe(actualVersion);
+    });
+
+    it('GET /api/mcp/v0/servers/:id - should return 404 if specific server version does not match', async () => {
+      const nonExistentVersion = '0.0.0-nonexistent';
+      const response = await fetch(
+        `http://localhost:${port}/api/mcp/v0/servers/${defaultMcpServerLogicalId}?version=${nonExistentVersion}`,
+      );
+      expect(response.status).toBe(404);
+      const body = await response.json();
+      expect(body).toHaveProperty('error');
+      expect(body.error).toContain(`but not version '${nonExistentVersion}'`);
+    });
+
+    it('GET /api/mcp/v0/servers/:id - should return 404 for a non-existent server ID', async () => {
+      const nonExistentId = 'non-existent-server-id-12345';
+      const response = await fetch(`http://localhost:${port}/api/mcp/v0/servers/${nonExistentId}`);
+      expect(response.status).toBe(404);
+      const body = await response.json();
+      expect(body).toHaveProperty('error');
+      expect(body.error).toContain(`MCP server with ID '${nonExistentId}' not found`);
+    });
+
+    it('GET /api/mcp/v0/servers - should handle pagination (limit=1, offset=0)', async () => {
+      const response = await fetch(`http://localhost:${port}/api/mcp/v0/servers?limit=1&offset=0`);
+      expect(response.status).toBe(200);
+      const body = await response.json();
+      expect(body.servers.length).toBe(1);
+      expect(body.total_count).toBeGreaterThanOrEqual(1);
+      if (body.total_count > 1) {
+        expect(body.next).not.toBeNull();
+      } else {
+        expect(body.next).toBeNull();
+      }
+    });
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "0.5.0",
+  "version": "0.5.1-alpha.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "hono": "^4.7.4",
     "uuid": "^11.1.0",
     "zod-from-json-schema": "^0.0.5",
-    "@mastra/core": "^0.9.4"
+    "@mastra/core": "^0.9.5-alpha.0"
   },
   "peerDependencies": {
     "zod": "^3.0.0"

package/src/__fixtures__/weather.ts

@@ -2,11 +2,11 @@ import type { IncomingMessage, ServerResponse } from 'http';
 import { createServer } from 'http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { 
-  CallToolRequestSchema, 
-  ListToolsRequestSchema, 
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
   ListResourcesRequestSchema,
-  ReadResourceRequestSchema
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
@@ -32,7 +32,7 @@ const server = new Server(
   {
     capabilities: {
       tools: {},
-      resources: {}
+      resources: {},
     },
   },
 );
@@ -98,31 +98,31 @@ const weatherResources = [
     uri: 'weather://current',
     name: 'Current Weather Data',
     description: 'Real-time weather data for the current location',
-    mimeType: 'application/json'
+    mimeType: 'application/json',
   },
   {
     uri: 'weather://forecast',
     name: 'Weather Forecast',
     description: '5-day weather forecast',
-    mimeType: 'application/json'
+    mimeType: 'application/json',
   },
   {
     uri: 'weather://historical',
     name: 'Historical Weather Data',
     description: 'Weather data from the past 30 days',
-    mimeType: 'application/json'
-  }
+    mimeType: 'application/json',
+  },
 ];
 
 // List available resources
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-  resources: weatherResources
+  resources: weatherResources,
 }));
 
 // Read resource contents
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+server.setRequestHandler(ReadResourceRequestSchema, async request => {
   const uri = request.params.uri;
-  
+
   if (uri === 'weather://current') {
     return {
       contents: [
@@ -135,10 +135,10 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             conditions: 'Partly Cloudy',
             humidity: 65,
             windSpeed: 12,
-            updated: new Date().toISOString()
-          })
-        }
-      ]
+            updated: new Date().toISOString(),
+          }),
+        },
+      ],
     };
   } else if (uri === 'weather://forecast') {
     return {
@@ -151,10 +151,10 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             { day: 2, high: 22, low: 14, conditions: 'Clear' },
             { day: 3, high: 20, low: 13, conditions: 'Partly Cloudy' },
             { day: 4, high: 18, low: 11, conditions: 'Rain' },
-            { day: 5, high: 17, low: 10, conditions: 'Showers' }
-          ])
-        }
-      ]
+            { day: 5, high: 17, low: 10, conditions: 'Showers' },
+          ]),
+        },
+      ],
     };
   } else if (uri === 'weather://historical') {
     return {
@@ -168,13 +168,13 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             rainDays: 8,
             sunnyDays: 18,
             recordHigh: 28,
-            recordLow: 7
-          })
-        }
-      ]
+            recordLow: 7,
+          }),
+        },
+      ],
     };
   }
-  
+
   throw new Error(`Resource not found: ${uri}`);
 });
 

package/src/server.test.ts

@@ -2,9 +2,12 @@ import http from 'node:http';
 import path from 'path';
 import type { ServerType } from '@hono/node-server';
 import { serve } from '@hono/node-server';
+import type { ToolsInput } from '@mastra/core/agent';
+import type { MCPServerConfig, Repository, PackageInfo, RemoteInfo } from '@mastra/core/mcp';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Hono } from 'hono';
-import { describe, it, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, afterEach, vi, beforeEach } from 'vitest';
+import { z } from 'zod';
 import { weatherTool } from './__fixtures__/tools';
 import { MCPClient } from './configuration';
 import { MCPServer } from './server';
@@ -15,7 +18,197 @@ let httpServer: http.Server;
 
 vi.setConfig({ testTimeout: 20000, hookTimeout: 20000 });
 
+// Mock Date constructor for predictable release dates
+const mockDateISO = '2024-01-01T00:00:00.000Z';
+const mockDate = new Date(mockDateISO);
+const OriginalDate = global.Date; // Store original Date
+
+// Mock a simple tool
+const mockToolExecute = vi.fn(async (args: any) => ({ result: 'tool executed', args }));
+const mockTools: ToolsInput = {
+  testTool: {
+    description: 'A test tool',
+    parameters: z.object({ input: z.string().optional() }),
+    execute: mockToolExecute,
+  },
+};
+
+const minimalConfig: MCPServerConfig = {
+  name: 'TestServer',
+  version: '1.0.0',
+  tools: mockTools,
+};
+
 describe('MCPServer', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // @ts-ignore - Mocking Date completely
+    global.Date = vi.fn((...args: any[]) => {
+      if (args.length === 0) {
+        // new Date()
+        return mockDate;
+      }
+      // @ts-ignore
+      return new OriginalDate(...args); // new Date('some-string') or new Date(timestamp)
+    }) as any;
+
+    // @ts-ignore
+    global.Date.now = vi.fn(() => mockDate.getTime());
+    // @ts-ignore
+    global.Date.prototype.toISOString = vi.fn(() => mockDateISO);
+    // @ts-ignore // Static Date.toISOString() might be used by some libraries
+    global.Date.toISOString = vi.fn(() => mockDateISO);
+  });
+
+  describe('Constructor and Metadata Initialization', () => {
+    it('should initialize with default metadata if not provided', () => {
+      const server = new MCPServer(minimalConfig);
+      expect(server.id).toBeDefined();
+      expect(server.name).toBe('TestServer');
+      expect(server.version).toBe('1.0.0');
+      expect(server.description).toBeUndefined();
+      expect(server.repository).toBeUndefined();
+      // MCPServerBase stores releaseDate as string, compare directly or re-parse
+      expect(server.releaseDate).toBe(mockDateISO);
+      expect(server.isLatest).toBe(true);
+      expect(server.packageCanonical).toBeUndefined();
+      expect(server.packages).toBeUndefined();
+      expect(server.remotes).toBeUndefined();
+    });
+
+    it('should initialize with custom metadata when provided', () => {
+      const repository: Repository = { url: 'https://github.com/test/repo', source: 'github', id: 'repo-id' };
+      const packages: PackageInfo[] = [{ registry_name: 'npm', name: 'test-package', version: '1.0.0' }];
+      const remotes: RemoteInfo[] = [{ transport_type: 'sse', url: 'https://test.com/sse' }];
+      const customReleaseDate = '2023-12-31T00:00:00.000Z';
+      const customConfig: MCPServerConfig = {
+        ...minimalConfig,
+        id: 'custom-id-doesnt-need-uuid-format-if-set-explicitly',
+        description: 'A custom server description',
+        repository,
+        releaseDate: customReleaseDate,
+        isLatest: false,
+        packageCanonical: 'npm',
+        packages,
+        remotes,
+      };
+      const server = new MCPServer(customConfig);
+
+      expect(server.id).toBe('custom-id-doesnt-need-uuid-format-if-set-explicitly');
+      expect(server.description).toBe('A custom server description');
+      expect(server.repository).toEqual(repository);
+      expect(server.releaseDate).toBe(customReleaseDate);
+      expect(server.isLatest).toBe(false);
+      expect(server.packageCanonical).toBe('npm');
+      expect(server.packages).toEqual(packages);
+      expect(server.remotes).toEqual(remotes);
+    });
+  });
+
+  describe('getServerInfo()', () => {
+    it('should return correct ServerInfo with default metadata', () => {
+      const server = new MCPServer(minimalConfig);
+      const serverInfo = server.getServerInfo();
+
+      expect(serverInfo).toEqual({
+        id: expect.any(String),
+        name: 'TestServer',
+        description: undefined,
+        repository: undefined,
+        version_detail: {
+          version: '1.0.0',
+          release_date: mockDateISO,
+          is_latest: true,
+        },
+      });
+    });
+
+    it('should return correct ServerInfo with custom metadata', () => {
+      const repository: Repository = { url: 'https://github.com/test/repo', source: 'github', id: 'repo-id' };
+      const customReleaseDate = '2023-11-01T00:00:00.000Z';
+      const customConfig: MCPServerConfig = {
+        ...minimalConfig,
+        id: 'custom-id-for-info',
+        description: 'Custom description',
+        repository,
+        releaseDate: customReleaseDate,
+        isLatest: false,
+      };
+      const server = new MCPServer(customConfig);
+      const serverInfo = server.getServerInfo();
+
+      expect(serverInfo).toEqual({
+        id: 'custom-id-for-info',
+        name: 'TestServer',
+        description: 'Custom description',
+        repository,
+        version_detail: {
+          version: '1.0.0',
+          release_date: customReleaseDate,
+          is_latest: false,
+        },
+      });
+    });
+  });
+
+  describe('getServerDetail()', () => {
+    it('should return correct ServerDetailInfo with default metadata', () => {
+      const server = new MCPServer(minimalConfig);
+      const serverDetail = server.getServerDetail();
+
+      expect(serverDetail).toEqual({
+        id: expect.any(String),
+        name: 'TestServer',
+        description: undefined,
+        repository: undefined,
+        version_detail: {
+          version: '1.0.0',
+          release_date: mockDateISO,
+          is_latest: true,
+        },
+        package_canonical: undefined,
+        packages: undefined,
+        remotes: undefined,
+      });
+    });
+
+    it('should return correct ServerDetailInfo with custom metadata', () => {
+      const repository: Repository = { url: 'https://github.com/test/repo', source: 'github', id: 'repo-id' };
+      const packages: PackageInfo[] = [{ registry_name: 'npm', name: 'test-package', version: '1.0.0' }];
+      const remotes: RemoteInfo[] = [{ transport_type: 'sse', url: 'https://test.com/sse' }];
+      const customReleaseDate = '2023-10-01T00:00:00.000Z';
+      const customConfig: MCPServerConfig = {
+        ...minimalConfig,
+        id: 'custom-id-for-detail',
+        description: 'Custom detail description',
+        repository,
+        releaseDate: customReleaseDate,
+        isLatest: true,
+        packageCanonical: 'docker',
+        packages,
+        remotes,
+      };
+      const server = new MCPServer(customConfig);
+      const serverDetail = server.getServerDetail();
+
+      expect(serverDetail).toEqual({
+        id: 'custom-id-for-detail',
+        name: 'TestServer',
+        description: 'Custom detail description',
+        repository,
+        version_detail: {
+          version: '1.0.0',
+          release_date: customReleaseDate,
+          is_latest: true,
+        },
+        package_canonical: 'docker',
+        packages,
+        remotes,
+      });
+    });
+  });
+
   describe('MCPServer SSE transport', () => {
     let sseRes: Response | undefined;
     let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;

package/src/server.ts

@@ -4,7 +4,14 @@ import type { InternalCoreTool } from '@mastra/core';
 import { makeCoreTool } from '@mastra/core';
 import type { ToolsInput } from '@mastra/core/agent';
 import { MCPServerBase } from '@mastra/core/mcp';
-import type { MCPServerSSEOptions, ConvertedTool, MCPServerHonoSSEOptions } from '@mastra/core/mcp';
+import type {
+  MCPServerConfig,
+  ServerInfo,
+  ServerDetailInfo,
+  ConvertedTool,
+  MCPServerHonoSSEOptions,
+  MCPServerSSEOptions,
+} from '@mastra/core/mcp';
 import { RuntimeContext } from '@mastra/core/runtime-context';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
@@ -56,17 +63,18 @@ export class MCPServer extends MCPServerBase {
 
   /**
    * Construct a new MCPServer instance.
-   * @param opts.name - Server name
-   * @param opts.version - Server version
-   * @param opts.tools - Tool definitions to register
+   * @param opts - Configuration options for the server, including registry metadata.
    */
-  constructor({ name, version, tools }: { name: string; version: string; tools: ToolsInput }) {
-    super({ name, version, tools });
+  constructor(opts: MCPServerConfig) {
+    super(opts);
 
-    this.server = new Server({ name, version }, { capabilities: { tools: {}, logging: { enabled: true } } });
+    this.server = new Server(
+      { name: this.name, version: this.version },
+      { capabilities: { tools: {}, logging: { enabled: true } } },
+    );
 
     this.logger.info(
-      `Initialized MCPServer '${name}' v${version} with tools: ${Object.keys(this.convertedTools).join(', ')}`,
+      `Initialized MCPServer '${this.name}' v${this.version} (ID: ${this.id}) with tools: ${Object.keys(this.convertedTools).join(', ')}`,
     );
 
     this.sseHonoTransports = new Map();
@@ -107,7 +115,7 @@ export class MCPServer extends MCPServerBase {
         name: toolName,
         description: coreTool.description,
         parameters: coreTool.parameters,
-        execute: coreTool.execute,
+        execute: coreTool.execute!,
       };
       this.logger.info(`Registered tool: '${toolName}' [${toolInstance?.description || 'No description'}]`);
     }
@@ -430,4 +438,130 @@ export class MCPServer extends MCPServerBase {
       this.logger.error('Error closing MCP server:', { error });
     }
   }
+
+  /**
+   * Gets the basic information about the server, conforming to the Server schema.
+   * @returns ServerInfo object.
+   */
+  public getServerInfo(): ServerInfo {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      repository: this.repository,
+      version_detail: {
+        version: this.version,
+        release_date: this.releaseDate,
+        is_latest: this.isLatest,
+      },
+    };
+  }
+
+  /**
+   * Gets detailed information about the server, conforming to the ServerDetail schema.
+   * @returns ServerDetailInfo object.
+   */
+  public getServerDetail(): ServerDetailInfo {
+    return {
+      ...this.getServerInfo(),
+      package_canonical: this.packageCanonical,
+      packages: this.packages,
+      remotes: this.remotes,
+    };
+  }
+
+  /**
+   * Gets a list of tools provided by this MCP server, including their schemas.
+   * This leverages the same tool information used by the internal ListTools MCP request.
+   * @returns An object containing an array of tool information.
+   */
+  public getToolListInfo(): { tools: Array<{ name: string; description?: string; inputSchema: any }> } {
+    this.logger.debug(`Getting tool list information for MCPServer '${this.name}'`);
+    return {
+      tools: Object.entries(this.convertedTools).map(([toolId, tool]) => ({
+        id: toolId,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.parameters?.jsonSchema || tool.parameters,
+      })),
+    };
+  }
+
+  /**
+   * Gets information for a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to retrieve.
+   * @returns Tool information (name, description, inputSchema) or undefined if not found.
+   */
+  public getToolInfo(toolId: string): { name: string; description?: string; inputSchema: any } | undefined {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.debug(`Tool '${toolId}' not found on MCPServer '${this.name}'`);
+      return undefined;
+    }
+    this.logger.debug(`Getting info for tool '${toolId}' on MCPServer '${this.name}'`);
+    return {
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.parameters?.jsonSchema || tool.parameters,
+    };
+  }
+
+  /**
+   * Executes a specific tool provided by this MCP server.
+   * @param toolId The ID/name of the tool to execute.
+   * @param args The arguments to pass to the tool's execute function.
+   * @param executionContext Optional context for the tool execution.
+   * @returns A promise that resolves to the result of the tool execution.
+   * @throws Error if the tool is not found, validation fails, or execution fails.
+   */
+  public async executeTool(
+    toolId: string,
+    args: any,
+    executionContext?: { messages?: any[]; toolCallId?: string },
+  ): Promise<any> {
+    const tool = this.convertedTools[toolId];
+    if (!tool) {
+      this.logger.warn(`ExecuteTool: Unknown tool '${toolId}' requested on MCPServer '${this.name}'.`);
+      throw new Error(`Unknown tool: ${toolId}`);
+    }
+
+    this.logger.debug(`ExecuteTool: Invoking '${toolId}' with arguments:`, args);
+
+    let validatedArgs = args;
+    if (tool.parameters instanceof z.ZodType && typeof tool.parameters.safeParse === 'function') {
+      const validation = tool.parameters.safeParse(args ?? {});
+      if (!validation.success) {
+        const errorMessages = validation.error.errors
+          .map((e: z.ZodIssue) => `${e.path.join('.')}: ${e.message}`)
+          .join(', ');
+        this.logger.warn(`ExecuteTool: Invalid tool arguments for '${toolId}': ${errorMessages}`, {
+          errors: validation.error.format(),
+        });
+        throw new z.ZodError(validation.error.issues);
+      }
+      validatedArgs = validation.data;
+    } else {
+      this.logger.debug(
+        `ExecuteTool: Tool '${toolId}' parameters is not a Zod schema with safeParse or is undefined. Skipping validation.`,
+      );
+    }
+
+    if (!tool.execute) {
+      this.logger.error(`ExecuteTool: Tool '${toolId}' does not have an execute function.`);
+      throw new Error(`Tool '${toolId}' cannot be executed.`);
+    }
+
+    try {
+      const finalExecutionContext = {
+        messages: executionContext?.messages || [],
+        toolCallId: executionContext?.toolCallId || randomUUID(),
+      };
+      const result = await tool.execute(validatedArgs, finalExecutionContext);
+      this.logger.info(`ExecuteTool: Tool '${toolId}' executed successfully.`);
+      return result;
+    } catch (error) {
+      this.logger.error(`ExecuteTool: Tool execution failed for '${toolId}':`, { error });
+      throw error instanceof Error ? error : new Error(`Execution of tool '${toolId}' failed: ${String(error)}`);
+    }
+  }
 }

package/integration-tests/node_modules/.bin/mastra

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/mastra/mastra/packages/cli/dist/node_modules:/home/runner/work/mastra/mastra/packages/cli/node_modules:/home/runner/work/mastra/mastra/packages/node_modules:/home/runner/work/mastra/mastra/node_modules:/home/runner/work/mastra/node_modules:/home/runner/work/node_modules:/home/runner/node_modules:/home/node_modules:/node_modules:/home/runner/work/mastra/mastra/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/mastra/mastra/packages/cli/dist/node_modules:/home/runner/work/mastra/mastra/packages/cli/node_modules:/home/runner/work/mastra/mastra/packages/node_modules:/home/runner/work/mastra/mastra/node_modules:/home/runner/work/mastra/node_modules:/home/runner/work/node_modules:/home/runner/node_modules:/home/node_modules:/node_modules:/home/runner/work/mastra/mastra/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../mastra/dist/index.js" "$@"
-else
-  exec node  "$basedir/../mastra/dist/index.js" "$@"
-fi