feat(mcp/ts): load MCP servers from JSON (strands-agents#2947)

Author: gautamsirdeshmukh

strands-ts/src/agent/__tests__/agent.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 import { Agent, type ToolList } from '../agent.js'
-import { McpClient } from '../../mcp.js'
+import { McpClient } from '../../mcp/index.js'
 import { McpTool } from '../../tools/mcp-tool.js'
 import { MockMessageModel } from '../../__fixtures__/mock-message-model.js'
 import { collectGenerator } from '../../__fixtures__/model-test-helpers.js'

strands-ts/src/agent/agent.ts

@@ -25,7 +25,7 @@ import {
 } from '../types/messages.js'
 import { deepCopy } from '../types/json.js'
 import type { JSONValue } from '../types/json.js'
-import { McpClient } from '../mcp.js'
+import { McpClient } from '../mcp/index.js'
 import { isValidToolName, type Tool, type ToolContext } from '../tools/tool.js'
 import type { ToolChoice, ToolSpec } from '../tools/types.js'
 import { cloneSystemPrompt, systemPromptFromData } from '../types/messages.js'

strands-ts/src/index.node.ts

@@ -4,7 +4,10 @@
 // or bundlers will tree-shake the registrations.
 import { defaultSandbox } from './sandbox/default.js'
 import { NotASandboxLocalEnvironment } from './sandbox/not-a-sandbox-local-environment.js'
+import { mcpServerLoader } from './mcp/config.js'
+import { resolveServerConfigs } from './mcp/config.node.js'
 
 defaultSandbox.set(new NotASandboxLocalEnvironment())
+mcpServerLoader.set(resolveServerConfigs)
 
 export * from './index.js'

strands-ts/src/index.ts

@@ -282,8 +282,9 @@ export {
   type McpCallToolOptions,
   type TasksConfig,
   type McpConnectionState,
+  type McpServerConfig,
   McpClient,
-} from './mcp.js'
+} from './mcp/index.js'
 export type { ElicitationCallback, ElicitationContext } from './types/elicitation.js'
 
 // Session management

strands-ts/src/__tests__/mcp.test.ts …ands-ts/src/mcp/__tests__/client.test.tsstrands-ts/src/__tests__/mcp.test.ts renamed to strands-ts/src/mcp/__tests__/client.test.ts strands-ts/src/__tests__/mcp.test.ts renamed to strands-ts/src/mcp/__tests__/client.test.ts

@@ -9,16 +9,16 @@ import {
 } from '@modelcontextprotocol/sdk/types.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import { ClientCredentialsProvider } from '@modelcontextprotocol/sdk/client/auth-extensions.js'
-import { McpClient } from '../mcp.js'
-import { McpTool } from '../tools/mcp-tool.js'
-import { JsonBlock, type TextBlock, type ToolResultBlock } from '../types/messages.js'
-import { ImageBlock } from '../types/media.js'
-import type { LocalAgent } from '../types/agent.js'
-import type { ToolContext } from '../tools/tool.js'
-import type { ElicitationCallback } from '../types/elicitation.js'
+import { McpClient } from '../client.js'
+import { McpTool } from '../../tools/mcp-tool.js'
+import { JsonBlock, type TextBlock, type ToolResultBlock } from '../../types/messages.js'
+import { ImageBlock } from '../../types/media.js'
+import type { LocalAgent } from '../../types/agent.js'
+import type { ToolContext } from '../../tools/tool.js'
+import type { ElicitationCallback } from '../../types/elicitation.js'
 import { context, propagation, trace, TraceFlags } from '@opentelemetry/api'
 import type { SpanContext } from '@opentelemetry/api'
-import { logger } from '../logging/index.js'
+import { logger } from '../../logging/index.js'
 import type { LoggingMessageNotificationParams } from '@modelcontextprotocol/sdk/types.js'
 
 /**
@@ -64,7 +64,7 @@ vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
   }),
 }))
 
-vi.mock('../tools/tool.js', () => ({
+vi.mock('../../tools/tool.js', () => ({
   Tool: class {},
   createErrorResult: (err: unknown, toolUseId: string) => ({
     type: 'toolResultBlock',

strands-ts/src/mcp/__tests__/config.test.browser.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest'
+import { McpClient } from '../client.js'
+
+// The unit-browser project has no setupFiles registering the MCP server loader,
+// mirroring a real browser where index.node.ts never loads.
+describe('McpClient.loadServers (browser)', () => {
+  it('throws because no Node loader is registered', async () => {
+    await expect(McpClient.loadServers({ server: { command: 'node' } })).rejects.toThrow(
+      'McpClient.loadServers is only available in Node.js'
+    )
+  })
+})