DataWorks

Converts ActionTool definitions into Model Context Protocol (MCP) compliant tool schemas and registers them with the MCP server via @modelcontextprotocol/sdk. The system maintains a bidirectional mapping between internal ActionTool representations and MCP tool schemas, enabling AI clients (Cursor, Cline, etc.) to discover and invoke DataWorks operations through standardized MCP protocol messages. Schema conversion handles parameter validation, type mapping, and response formatting according to MCP specification.

Abstracts Alibaba Cloud authentication through @alicloud/credentials package, supporting multiple credential sources (Access Key/Secret Key, STS tokens, environment variables) with automatic fallback chain resolution. The OpenApiClient.createClient() factory in src/openApiClient/index.ts handles credential initialization, endpoint selection (production vs pre-release), and regional configuration via ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and REGION environment variables. Credentials are resolved once at server startup and reused across all subsequent API calls.

The system maintains comprehensive API type definitions and response schemas for DataWorks operations in src/types/ and related modules. These definitions include request/response types, error codes, status enumerations, and complex nested object structures. Type definitions are used for parameter validation, response parsing, and schema generation. The system provides TypeScript type safety for API interactions and enables IDE autocompletion for developers extending the server. Response schemas are used to normalize API responses into consistent formats for MCP clients.

The callTool function in src/tools/callTool.ts provides a unified execution engine for DataWorks OpenAPI operations. It validates input parameters against tool schemas, transforms parameters according to API requirements, constructs HTTP requests with proper headers and authentication, executes requests via the authenticated OpenAPI client, and normalizes responses into consistent output formats. The engine handles error propagation, response parsing, and type coercion for complex parameter types (arrays, nested objects, enums).

The initDataWorksTools() and initExtraTools() functions in src/index.ts populate an ActionTool registry by loading tool definitions from configuration sources and external data sources. The system maintains an in-memory registry of available tools with their schemas, descriptions, and execution handlers. Tool definitions are loaded at server startup and made available to the MCP protocol handler for registration. The registry supports both built-in DataWorks tools and extensible custom tools through the extra tools initialization pipeline.

The MCP server uses StdioServerTransport from @modelcontextprotocol/sdk to handle bidirectional communication with MCP clients over standard input/output streams. This transport mechanism enables the server to receive tool invocation requests as JSON-RPC messages on stdin and send responses and tool results on stdout, making the server compatible with any MCP client that supports stdio-based communication. The transport is initialized in src/mcp/index.ts and manages message framing, serialization, and protocol state.

The system converts DataWorks API action types into standardized tool schemas with parameter definitions, type constraints, and validation rules. This conversion happens in the tool initialization pipeline and maps API operation parameters (required/optional, type, constraints) into MCP-compatible JSON schema format. The conversion handles complex types (arrays, nested objects, enums) and generates human-readable parameter descriptions for AI agents. Schema conversion enables AI clients to understand parameter requirements without consulting API documentation.

The system supports loading tool definitions and configuration from external data sources beyond built-in definitions. The architecture in src/tools/ and configuration modules enables pluggable data source adapters that can fetch tool definitions, action types, and system constants from remote APIs, databases, or configuration files. External data sources are loaded during server initialization and merged into the tool registry, enabling dynamic tool discovery without code changes. The system maintains a separation between data source adapters and tool initialization logic.

The MCP server implementation in src/mcp/index.ts routes incoming tool invocation requests to appropriate execution handlers based on tool name and parameters. The routing logic dispatches requests to the callTool execution engine, which validates parameters, constructs API requests, and returns results. The router maintains a mapping between MCP tool names and internal tool handlers, enabling the server to execute any registered tool without explicit routing code. Error handling and response formatting are applied uniformly across all routed requests.

The system provides centralized system constants and utility functions in src/utils/ and src/constants/ modules that support API operations across the server. These include region mappings, endpoint configurations, API response type definitions, error codes, and helper functions for parameter transformation and response parsing. Utilities are shared across tool execution, schema conversion, and external data source loading, reducing code duplication and ensuring consistency. Constants are loaded at server startup and available to all components.

The OpenAPI client supports dynamic endpoint selection based on region configuration and environment variables. The system maintains mappings of Alibaba Cloud regions to production and pre-release DataWorks endpoints (dataworks.{region}.aliyuncs.com and dataworks-pre.{region}.aliyuncs.com). Endpoint selection is determined at client initialization time via the REGION environment variable, enabling multi-region deployments without code changes. The system validates region identifiers and falls back to default regions if invalid values are provided.