@namzu/sdk 0.1.1

package/src/connector/execution/remote.ts

@@ -0,0 +1,131 @@
+import type {
+  ExecutionEnvironment,
+  ExecutionCapability,
+  RemoteExecutionContextConfig,
+  RemoteTarget,
+  CommandOptions,
+  CommandResult,
+  RemoteCommandHandler,
+  ConnectorExecutionContextEvent,
+} from '../../types/connector/index.js'
+import { BaseExecutionContext } from '../../execution/base.js'
+
+export interface RemoteExecutionContextOptions {
+  id: string
+  target: RemoteTarget
+  capabilities?: ExecutionCapability[]
+  commandHandler?: RemoteCommandHandler
+}
+
+export class RemoteExecutionContext extends BaseExecutionContext {
+  readonly id: string
+  readonly environment: ExecutionEnvironment = 'remote'
+
+  private target: RemoteTarget
+  private connected = false
+  private capabilities: ExecutionCapability[]
+  private commandHandler: RemoteCommandHandler | undefined
+
+  constructor(options: RemoteExecutionContextOptions) {
+    super()
+    this.id = options.id
+    this.target = options.target
+    this.capabilities = options.capabilities ?? ['network']
+    this.commandHandler = options.commandHandler
+  }
+
+  protected async doInitialize(): Promise<void> {
+    this.validateTarget(this.target)
+    this.log.info(`Remote context initialized for ${this.target.type}://${this.target.host}`)
+  }
+
+  protected async doTeardown(): Promise<void> {
+    if (this.connected) {
+      this.connected = false
+      this.emit({
+        type: 'remote_disconnected',
+        contextId: this.id,
+        host: this.target.host,
+      })
+    }
+  }
+
+  async connect(): Promise<void> {
+    this.connected = true
+    this.emit({
+      type: 'remote_connected',
+      contextId: this.id,
+      target: this.target,
+    })
+    this.log.info(`Remote connected: ${this.target.type}://${this.target.host}:${this.target.port ?? 'default'}`)
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.connected) return
+    this.connected = false
+    this.emit({
+      type: 'remote_disconnected',
+      contextId: this.id,
+      host: this.target.host,
+    })
+    this.log.info(`Remote disconnected: ${this.target.host}`)
+  }
+
+  isConnected(): boolean {
+    return this.connected
+  }
+
+  getTarget(): RemoteTarget {
+    return { ...this.target }
+  }
+
+  getConnectionString(): string {
+    const port = this.target.port ? `:${this.target.port}` : ''
+    return `${this.target.type}://${this.target.host}${port}`
+  }
+
+  getCapabilities(): ExecutionCapability[] {
+    return [...this.capabilities]
+  }
+
+  hasCapability(cap: ExecutionCapability): boolean {
+    return this.capabilities.includes(cap)
+  }
+
+  setCommandHandler(handler: RemoteCommandHandler): void {
+    this.commandHandler = handler
+  }
+
+  async executeRemote(command: string, options?: CommandOptions): Promise<CommandResult> {
+    if (!this.commandHandler) {
+      throw new Error(
+        `No remote command handler configured for context "${this.id}". ` +
+        'Set one via setCommandHandler() before calling executeRemote().',
+      )
+    }
+    if (!this.connected) {
+      throw new Error(
+        `Remote context "${this.id}" is not connected. Call connect() first.`,
+      )
+    }
+    return this.commandHandler.executeRemote(command, options)
+  }
+
+  toConfig(): RemoteExecutionContextConfig {
+    return {
+      id: this.id,
+      environment: 'remote',
+      target: { ...this.target },
+      capabilities: this.capabilities,
+    }
+  }
+
+  private validateTarget(target: RemoteTarget): void {
+    if (!target.host) {
+      throw new Error('Remote target must have a host')
+    }
+    if (!['ssh', 'rdp', 'api'].includes(target.type)) {
+      throw new Error(`Unsupported remote target type: "${target.type}"`)
+    }
+  }
+}

package/src/connector/index.ts

@@ -0,0 +1,54 @@
+export { BaseConnector } from './BaseConnector.js'
+
+export { ConnectorRegistry } from '../registry/connector/definitions.js'
+export { ScopedConnectorRegistry } from '../registry/connector/scoped.js'
+
+export { ConnectorManager } from '../manager/connector/lifecycle.js'
+export type { ConnectorManagerConfig } from '../manager/connector/lifecycle.js'
+
+export { TenantConnectorManager } from '../manager/connector/tenant.js'
+export type { TenantConnectorManagerConfig } from '../manager/connector/tenant.js'
+
+export { EnvironmentConnectorManager } from '../manager/connector/environment.js'
+export type {
+  EnvironmentConnectorSetup,
+  EnvironmentConnectorManagerConfig,
+} from '../manager/connector/environment.js'
+
+export { HttpConnector } from './builtins/http.js'
+export { WebhookConnector } from './builtins/webhook.js'
+
+export { BaseExecutionContext } from '../execution/base.js'
+export { LocalExecutionContext } from '../execution/local.js'
+export type { LocalExecutionContextOptions } from '../execution/local.js'
+
+export {
+  RemoteExecutionContext,
+  HybridExecutionContext,
+  ExecutionContextFactory,
+} from './execution/index.js'
+export type {
+  RemoteExecutionContextOptions,
+  HybridExecutionContextOptions,
+} from './execution/index.js'
+
+export { StdioTransport } from './mcp/stdio.js'
+export { HttpSseTransport } from './mcp/http-sse.js'
+
+export { MCPClient } from './mcp/client.js'
+
+export {
+  mcpToolToToolDefinition,
+  toolDefinitionToMCPTool,
+  mcpJsonSchemaToZod,
+  zodToMCPJsonSchema,
+  mcpToolResultToToolResult,
+  toolResultToMCPToolResult,
+} from './mcp/adapter.js'
+
+export { MCPToolDiscovery } from './mcp/discovery.js'
+
+export { MCPConnectorBridge } from '../bridge/mcp/connector/adapter.js'
+
+export { MCPServer } from './mcp/server.js'
+export type { MCPServerToolProvider, MCPServerResourceProvider } from './mcp/server.js'

package/src/connector/mcp/adapter.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import type { ToolDefinition, ToolContext, ToolResult } from '../../types/tool/index.js'
+import type {
+  MCPToolDefinition,
+  MCPJsonSchema,
+  MCPToolResult,
+} from '../../types/connector/index.js'
+import type { MCPClient } from './client.js'
+
+export function mcpJsonSchemaToZod(schema: MCPJsonSchema): z.ZodType {
+  if (!schema.properties || Object.keys(schema.properties).length === 0) {
+    return z.object({}).passthrough()
+  }
+
+  const shape: Record<string, z.ZodType> = {}
+  const required = new Set(schema.required ?? [])
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    let field = jsonSchemaPropertyToZod(propSchema)
+    if (!required.has(key)) {
+      field = field.optional()
+    }
+    shape[key] = field
+  }
+
+  return z.object(shape).passthrough()
+}
+
+function jsonSchemaPropertyToZod(prop: unknown): z.ZodType {
+  if (typeof prop !== 'object' || prop === null) return z.unknown()
+  const schema = prop as Record<string, unknown>
+
+  switch (schema['type']) {
+    case 'string':
+      return z.string()
+    case 'number':
+    case 'integer':
+      return z.number()
+    case 'boolean':
+      return z.boolean()
+    case 'array':
+      return z.array(z.unknown())
+    case 'object':
+      return z.record(z.unknown())
+    default:
+      return z.unknown()
+  }
+}
+
+export function zodToMCPJsonSchema(zodSchema: z.ZodType): MCPJsonSchema {
+  const jsonSchema = zodToJsonSchema(zodSchema, { target: 'openApi3' })
+  return {
+    type: 'object',
+    ...jsonSchema,
+  } as MCPJsonSchema
+}
+
+export function mcpToolToToolDefinition(
+  tool: MCPToolDefinition,
+  client: MCPClient,
+  serverName: string,
+): ToolDefinition {
+  const inputSchema = mcpJsonSchemaToZod(tool.inputSchema)
+  const toolName = `mcp_${serverName}_${tool.name}`
+
+  return {
+    name: toolName,
+    description: tool.description
+      ? `[MCP:${serverName}] ${tool.description}`
+      : `[MCP:${serverName}] ${tool.name}`,
+    inputSchema,
+    category: 'network',
+    permissions: ['network_access'],
+    isReadOnly: () => tool.annotations?.readOnlyHint ?? false,
+    isDestructive: () => tool.annotations?.destructiveHint ?? false,
+    isConcurrencySafe: () => true,
+
+    async execute(input: unknown, _context: ToolContext): Promise<ToolResult> {
+      const result = await client.callTool(tool.name, input as Record<string, unknown>)
+      return mcpToolResultToToolResult(result)
+    },
+  }
+}
+
+export function toolDefinitionToMCPTool(tool: ToolDefinition): MCPToolDefinition {
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: zodToMCPJsonSchema(tool.inputSchema),
+    annotations: {
+      readOnlyHint: tool.isReadOnly?.(undefined as never),
+      destructiveHint: tool.isDestructive?.(undefined as never),
+    },
+  }
+}
+
+export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
+  const textContent = result.content
+    .filter((block): block is { type: 'text'; text: string } => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+
+  return {
+    success: !result.isError,
+    output: textContent,
+    data: result.content,
+    error: result.isError ? textContent : undefined,
+  }
+}
+
+export function toolResultToMCPToolResult(result: ToolResult): MCPToolResult {
+  const content: MCPToolResult['content'] = []
+
+  if (result.output) {
+    content.push({ type: 'text', text: result.output })
+  }
+
+  if (!result.success && result.error) {
+    content.push({ type: 'text', text: result.error })
+  }
+
+  if (content.length === 0) {
+    content.push({ type: 'text', text: '' })
+  }
+
+  return {
+    content,
+    isError: !result.success,
+  }
+}

package/src/connector/mcp/client.ts

@@ -0,0 +1,226 @@
+import type {
+  MCPTransport,
+  MCPJsonRpcMessage,
+  MCPClientConfig,
+  MCPClientState,
+  MCPConnectionStatus,
+  MCPToolDefinition,
+  MCPToolResult,
+  MCPResource,
+  MCPResourceTemplate,
+  MCPInitializeResult,
+  MCPServerCapabilities,
+  MCPTransportUnion,
+  MCPContentBlock,
+} from '../../types/connector/index.js'
+import type { MCPClientId } from '../../types/ids/index.js'
+import { generateMCPClientId } from '../../utils/id.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { StdioTransport } from './stdio.js'
+import { HttpSseTransport } from './http-sse.js'
+
+const MCP_PROTOCOL_VERSION = '2024-11-05'
+const NAMZU_CLIENT_INFO = { name: 'namzu-sdk', version: '0.1.0' }
+
+export class MCPClient {
+  readonly id: MCPClientId
+  private transport: MCPTransport
+  private status: MCPConnectionStatus = 'disconnected'
+  private serverInfo?: { name: string; version?: string }
+  private serverCapabilities?: MCPServerCapabilities
+  private connectedAt?: number
+  private error?: string
+  private pendingRequests = new Map<string | number, {
+    resolve: (value: unknown) => void
+    reject: (reason: Error) => void
+  }>()
+  private nextRequestId = 1
+  private notificationHandlers: Array<(method: string, params?: Record<string, unknown>) => void> = []
+  private log: Logger
+  private readonly config: MCPClientConfig
+
+  constructor(config: MCPClientConfig) {
+    this.config = config
+    this.id = config.id ?? generateMCPClientId()
+    this.transport = this.createTransport(config.transport)
+    this.log = getRootLogger().child({ component: 'MCPClient', serverId: config.serverName })
+  }
+
+  async connect(): Promise<MCPInitializeResult> {
+    if (this.status === 'connected') {
+      throw new Error(`MCPClient already connected to "${this.config.serverName}"`)
+    }
+
+    this.status = 'connecting'
+
+    try {
+      this.transport.onMessage((msg) => this.handleMessage(msg))
+      this.transport.onClose(() => {
+        this.status = 'disconnected'
+        this.log.info('MCP transport closed')
+      })
+      this.transport.onError((err) => {
+        this.status = 'error'
+        this.error = err.message
+        this.log.error('MCP transport error', { error: err.message })
+      })
+
+      await this.transport.connect()
+
+      const result = await this.request('initialize', {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: this.config.capabilities ?? {},
+        clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
+      }) as MCPInitializeResult
+
+      this.serverInfo = result.serverInfo
+      this.serverCapabilities = result.capabilities
+
+      await this.notify('notifications/initialized', {})
+
+      this.status = 'connected'
+      this.connectedAt = Date.now()
+      this.log.info(`Connected to MCP server: ${result.serverInfo.name}`)
+
+      return result
+    } catch (err) {
+      this.status = 'error'
+      this.error = toErrorMessage(err)
+      this.log.error('MCP connection failed', { error: this.error })
+      throw err
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.status === 'disconnected') return
+
+    for (const [, pending] of this.pendingRequests) {
+      pending.reject(new Error('MCPClient disconnecting'))
+    }
+    this.pendingRequests.clear()
+
+    await this.transport.close()
+    this.status = 'disconnected'
+    this.connectedAt = undefined
+    this.log.info('MCP client disconnected')
+  }
+
+  isConnected(): boolean {
+    return this.status === 'connected'
+  }
+
+  getState(): MCPClientState {
+    return {
+      id: this.id,
+      serverName: this.config.serverName,
+      status: this.status,
+      serverInfo: this.serverInfo,
+      serverCapabilities: this.serverCapabilities,
+      connectedAt: this.connectedAt,
+      error: this.error,
+    }
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    this.requireConnected()
+    const result = await this.request('tools/list', {}) as { tools: MCPToolDefinition[] }
+    return result.tools
+  }
+
+  async callTool(name: string, args?: Record<string, unknown>): Promise<MCPToolResult> {
+    this.requireConnected()
+    const result = await this.request('tools/call', {
+      name,
+      arguments: args ?? {},
+    }) as MCPToolResult
+    return result
+  }
+
+  async listResources(): Promise<MCPResource[]> {
+    this.requireConnected()
+    const result = await this.request('resources/list', {}) as { resources: MCPResource[] }
+    return result.resources
+  }
+
+  async readResource(uri: string): Promise<MCPContentBlock[]> {
+    this.requireConnected()
+    const result = await this.request('resources/read', { uri }) as { contents: MCPContentBlock[] }
+    return result.contents
+  }
+
+  async listResourceTemplates(): Promise<MCPResourceTemplate[]> {
+    this.requireConnected()
+    const result = await this.request('resources/templates/list', {}) as { resourceTemplates: MCPResourceTemplate[] }
+    return result.resourceTemplates
+  }
+
+  onNotification(handler: (method: string, params?: Record<string, unknown>) => void): void {
+    this.notificationHandlers.push(handler)
+  }
+
+  private createTransport(config: MCPTransportUnion): MCPTransport {
+    switch (config.type) {
+      case 'stdio':
+        return new StdioTransport(config)
+      case 'http-sse':
+        return new HttpSseTransport(config)
+      default:
+        throw new Error(`Unsupported MCP transport type: ${(config as MCPTransportUnion).type}`)
+    }
+  }
+
+  private async request(method: string, params: Record<string, unknown>): Promise<unknown> {
+    const id = this.nextRequestId++
+    const message: MCPJsonRpcMessage = {
+      jsonrpc: '2.0',
+      id,
+      method,
+      params,
+    }
+
+    return new Promise<unknown>((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject })
+      this.transport.send(message).catch((err) => {
+        this.pendingRequests.delete(id)
+        reject(err)
+      })
+    })
+  }
+
+  private async notify(method: string, params: Record<string, unknown>): Promise<void> {
+    const message: MCPJsonRpcMessage = {
+      jsonrpc: '2.0',
+      method,
+      params,
+    }
+    await this.transport.send(message)
+  }
+
+  private handleMessage(message: MCPJsonRpcMessage): void {
+    if (message.id !== undefined) {
+      const pending = this.pendingRequests.get(message.id)
+      if (pending) {
+        this.pendingRequests.delete(message.id)
+        if (message.error) {
+          pending.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`))
+        } else {
+          pending.resolve(message.result)
+        }
+        return
+      }
+    }
+
+    if (message.method && message.id === undefined) {
+      for (const handler of this.notificationHandlers) {
+        handler(message.method, message.params)
+      }
+    }
+  }
+
+  private requireConnected(): void {
+    if (this.status !== 'connected') {
+      throw new Error(`MCPClient "${this.config.serverName}" is not connected (status: ${this.status})`)
+    }
+  }
+}

package/src/connector/mcp/discovery.ts

@@ -0,0 +1,69 @@
+import type { ToolDefinition } from '../../types/tool/index.js'
+import type { MCPDiscoveredTool } from '../../types/connector/index.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+import type { MCPClient } from './client.js'
+import { mcpToolToToolDefinition } from './adapter.js'
+
+export class MCPToolDiscovery {
+  private clients: MCPClient[]
+  private log: Logger
+
+  constructor(clients: MCPClient[]) {
+    this.clients = clients
+    this.log = getRootLogger().child({ component: 'MCPToolDiscovery' })
+  }
+
+  addClient(client: MCPClient): void {
+    this.clients.push(client)
+  }
+
+  removeClient(clientId: string): void {
+    this.clients = this.clients.filter((c) => c.id !== clientId)
+  }
+
+  async discoverAll(): Promise<MCPDiscoveredTool[]> {
+    const results: MCPDiscoveredTool[] = []
+
+    for (const client of this.clients) {
+      if (!client.isConnected()) {
+        this.log.warn(`Skipping disconnected MCP client: ${client.id}`)
+        continue
+      }
+
+      try {
+        const tools = await this.discoverFrom(client)
+        results.push(...tools)
+      } catch (err) {
+        this.log.error(`Failed to discover tools from ${client.id}`, {
+          error: toErrorMessage(err),
+        })
+      }
+    }
+
+    this.log.info(`Discovered ${results.length} MCP tools from ${this.clients.length} clients`)
+    return results
+  }
+
+  async discoverFrom(client: MCPClient): Promise<MCPDiscoveredTool[]> {
+    const state = client.getState()
+    const tools = await client.listTools()
+
+    return tools.map((tool) => ({
+      tool,
+      clientId: client.id,
+      serverName: state.serverName,
+    }))
+  }
+
+  async toToolDefinitions(): Promise<ToolDefinition[]> {
+    const discovered = await this.discoverAll()
+    return discovered.map((d) => {
+      const client = this.clients.find((c) => c.id === d.clientId)
+      if (!client) {
+        throw new Error(`MCPClient not found for discovered tool: ${d.clientId}`)
+      }
+      return mcpToolToToolDefinition(d.tool, client, d.serverName)
+    })
+  }
+}