AI/MCP Integration API

/**
 * Constants for AI and MCP protocol configuration
 */
class AiConstants {
    /**
     * MCP protocol and configuration constants
     */
    static class Mcp {
        /** Default namespace for MCP services */
        static final String MCP_DEFAULT_NAMESPACE = "public";
        
        /** Standard I/O protocol for local MCP servers */
        static final String MCP_PROTOCOL_STDIO = "stdio";
        
        /** Server-Sent Events protocol for streaming communication */
        static final String MCP_PROTOCOL_SSE = "mcp-sse";
        
        /** Streamable protocol for real-time data exchange */
        static final String MCP_PROTOCOL_STREAMABLE = "mcp-streamable";
        
        /** HTTP protocol for REST-based communication */
        static final String MCP_PROTOCOL_HTTP = "http";
        
        /** Dubbo RPC protocol for high-performance communication */
        static final String MCP_PROTOCOL_DUBBO = "dubbo";
        
        /** Reference-based endpoint type using Nacos service discovery */
        static final String MCP_ENDPOINT_TYPE_REF = "REF";
        
        /** Direct endpoint type with explicit address configuration */
        static final String MCP_ENDPOINT_TYPE_DIRECT = "DIRECT";
    }
}

/**
 * MCP Tool definition with schema and metadata
 */
class McpTool {
    /** Tool name identifier */
    private String name;
    
    /** Human-readable tool description */
    private String description;
    
    /** JSON Schema for tool input validation */
    private Map<String, Object> inputSchema;
    
    String getName();
    void setName(String name);
    String getDescription();
    void setDescription(String description);
    Map<String, Object> getInputSchema();
    void setInputSchema(Map<String, Object> inputSchema);
}

/**
 * Tool metadata and execution context configuration
 */
class McpToolMeta {
    /** Execution context parameters for tool invocation */
    private Map<String, String> invokeContext;
    
    /** Tool availability flag */
    private boolean enabled = true;
    
    /** Template configurations for dynamic tool behavior */
    private Map<String, Object> templates;
    
    Map<String, String> getInvokeContext();
    void setInvokeContext(Map<String, String> invokeContext);
    boolean isEnabled();
    void setEnabled(boolean enabled);
    Map<String, Object> getTemplates();
    void setTemplates(Map<String, Object> templates);
}

/**
 * Complete tool specification container
 */
class McpToolSpecification {
    /** List of available tools */
    private List<McpTool> tools = new LinkedList<>();
    
    /** Metadata mapping for each tool by name */
    private Map<String, McpToolMeta> toolsMeta = new HashMap<>(1);
    
    List<McpTool> getTools();
    void setTools(List<McpTool> tools);
    Map<String, McpToolMeta> getToolsMeta();
    void setToolsMeta(Map<String, McpToolMeta> toolsMeta);
}

/**
 * MCP Server capability enumeration
 */
enum McpCapability {
    /** Server provides executable tools */
    TOOL,
    
    /** Server provides AI prompts and templates */
    PROMPT,
    
    /** Server provides accessible resources */
    RESOURCE;
}

/**
 * Basic MCP server information and configuration
 */
class McpServerBasicInfo {
    /** Unique server identifier */
    private String id;
    
    /** Human-readable server name */
    private String name;
    
    /** Communication protocol (stdio, mcp-sse, mcp-streamable, http, dubbo) */
    private String protocol;
    
    /** Frontend protocol for client communication */
    private String frontProtocol;
    
    /** Server description and purpose */
    private String description;
    
    /** Repository information for server source */
    private Repository repository;
    
    /** Version details and metadata */
    private ServerVersionDetail versionDetail;
    
    /** Current server version */
    private String version;
    
    /** Remote service configuration (for non-stdio protocols) */
    private McpServerRemoteServiceConfig remoteServerConfig;
    
    /** Local server configuration (for stdio protocol) */
    private Map<String, Object> localServerConfig;
    
    /** Server availability status */
    private boolean enabled = true;
    
    /** Auto-discovered server capabilities */
    private List<McpCapability> capabilities;
    
    // Standard getters and setters for all properties
    String getId();
    void setId(String id);
    String getName();
    void setName(String name);
    String getProtocol();
    void setProtocol(String protocol);
    String getFrontProtocol();
    void setFrontProtocol(String frontProtocol);
    String getDescription();
    void setDescription(String description);
    Repository getRepository();
    void setRepository(Repository repository);
    ServerVersionDetail getVersionDetail();
    void setVersionDetail(ServerVersionDetail versionDetail);
    String getVersion();
    void setVersion(String version);
    McpServerRemoteServiceConfig getRemoteServerConfig();
    void setRemoteServerConfig(McpServerRemoteServiceConfig remoteServerConfig);
    Map<String, Object> getLocalServerConfig();
    void setLocalServerConfig(Map<String, Object> localServerConfig);
    boolean isEnabled();
    void setEnabled(boolean enabled);
    List<McpCapability> getCapabilities();
    void setCapabilities(List<McpCapability> capabilities);
}

/**
 * Extended server information with detailed endpoint and tool specifications
 */
class McpServerDetailInfo extends McpServerBasicInfo {
    /** Backend endpoint information list */
    private List<McpEndpointInfo> backendEndpoints;
    
    /** Complete tool specification */
    private McpToolSpecification toolSpec;
    
    /** All available versions */
    private List<ServerVersionDetail> allVersions;
    
    /** Nacos namespace identifier */
    private String namespaceId;
    
    List<McpEndpointInfo> getBackendEndpoints();
    void setBackendEndpoints(List<McpEndpointInfo> backendEndpoints);
    McpToolSpecification getToolSpec();
    void setToolSpec(McpToolSpecification toolSpec);
    List<ServerVersionDetail> getAllVersions();
    void setAllVersions(List<ServerVersionDetail> allVersions);
    String getNamespaceId();
    void setNamespaceId(String namespaceId);
}

/**
 * Server version information with release details
 */
class McpServerVersionInfo extends McpServerBasicInfo {
    /** Latest published version identifier */
    private String latestPublishedVersion;
    
    /** Detailed version information list */
    private List<ServerVersionDetail> versionDetails;
    
    String getLatestPublishedVersion();
    void setLatestPublishedVersion(String latestPublishedVersion);
    List<ServerVersionDetail> getVersionDetails();
    void setVersions(List<ServerVersionDetail> versionDetails);
}

/**
 * Nacos service reference for MCP server discovery
 */
class McpServiceRef {
    /** Target namespace for service lookup */
    private String namespaceId;
    
    /** Service group classification */
    private String groupName;
    
    /** Service name for discovery */
    private String serviceName;
    
    String getNamespaceId();
    void setNamespaceId(String namespaceId);
    String getGroupName();
    void setGroupName(String groupName);
    String getServiceName();
    void setServiceName(String serviceName);
}

/**
 * Remote service configuration for non-local MCP servers
 */
class McpServerRemoteServiceConfig {
    /** Service reference for Nacos discovery */
    private McpServiceRef serviceRef;
    
    /** API export path for service endpoints */
    private String exportPath;
    
    McpServiceRef getServiceRef();
    void setServiceRef(McpServiceRef serviceRef);
    String getExportPath();
    void setExportPath(String exportPath);
}

/**
 * Endpoint specification with flexible configuration
 */
class McpEndpointSpec {
    /** Endpoint type: DIRECT or REF */
    private String type;
    
    /** 
     * Endpoint configuration data:
     * - For DIRECT: includes 'address' and 'port'
     * - For REF: includes 'namespaceId', 'groupName', 'serviceName'
     */
    private Map<String, String> data = new HashMap<>();
    
    String getType();
    void setType(String type);
    Map<String, String> getData();
    void setData(Map<String, String> data);
}

/**
 * Concrete endpoint information for backend communication
 */
class McpEndpointInfo {
    /** Server IP address or hostname */
    private String address;
    
    /** Server port number */
    private int port;
    
    /** API path for MCP communication */
    private String path;
    
    String getAddress();
    void setAddress(String address);
    int getPort();
    void setPort(int port);
    String getPath();
    void setPath(String path);
}

/**
 * Basic registry server information
 */
class McpRegistryServer {
    /** Server unique identifier */
    private String id;
    
    /** Server display name */
    private String name;
    
    /** Server description */
    private String description;
    
    /** Repository source information */
    private Repository repository;
    
    /** Version detail information */
    private ServerVersionDetail version_detail;
    
    String getId();
    void setId(String id);
    String getName();
    void setName(String name);
    String getDescription();
    void setDescription(String description);
    Repository getRepository();
    void setRepository(Repository repository);
    ServerVersionDetail getVersion_detail();
    void setVersion_detail(ServerVersionDetail version_detail);
}

/**
 * Detailed registry server with remote endpoints
 */
class McpRegistryServerDetail extends McpRegistryServer {
    /** List of remote communication endpoints */
    private List<Remote> remotes;
    
    List<Remote> getRemotes();
    void setRemotes(List<Remote> remotes);
}

/**
 * Nacos-specific registry server extension
 */
class NacosMcpRegistryServerDetail extends McpRegistryServerDetail {
    /** Nacos-specific endpoint specification */
    private McpEndpointSpec nacosMcpEndpointSpec;
    
    /** Tool specification for the server */
    private McpToolSpecification mcpToolSpecification;
    
    /** Associated Nacos namespace */
    private String nacosNamespaceId;
    
    McpEndpointSpec getNacosMcpEndpointSpec();
    void setNacosMcpEndpointSpec(McpEndpointSpec nacosMcpEndpointSpec);
    String getNacosNamespaceId();
    void setNacosNamespaceId(String nacosNamespaceId);
    McpToolSpecification getMcpToolSpecification();
    void setMcpToolSpecification(McpToolSpecification mcpToolSpecification);
}

/**
 * Registry server list with pagination support
 */
class McpRegistryServerList {
    /** List of registry servers */
    private List<McpRegistryServer> servers;
    
    /** Total count of available servers */
    private int total_count;
    
    /** Pagination token for next page */
    private String next;
    
    List<McpRegistryServer> getServers();
    void setServers(List<McpRegistryServer> servers);
    int getTotal_count();
    void setTotal_count(int total_count);
    String getNext();
    void setNext(String next);
}

/**
 * Version detail information
 */
class ServerVersionDetail {
    /** Version identifier */
    private String version;
    
    /** Release date timestamp */
    private String release_date;
    
    /** Latest version flag */
    private Boolean is_latest;
    
    String getVersion();
    void setVersion(String version);
    String getRelease_date();
    void setRelease_date(String releaseDate);
    Boolean getIs_latest();
    void setIs_latest(Boolean is_latest);
}

/**
 * Remote endpoint configuration
 */
class Remote {
    /** Transport protocol type */
    private String transport_type;
    
    /** Complete endpoint URL */
    private String url;
    
    String getTransport_type();
    void setTransport_type(String transport_type);
    String getUrl();
    void setUrl(String url);
}

/**
 * Repository placeholder for server source information
 */
class Repository {
    // Repository implementation details
}

/**
 * AI service credential configuration
 */
class AiCredential {
    /** 
     * Credential type: OAuth2.0, JWT token, or custom
     * Default: "custom"
     */
    private String type = "custom";
    
    /** Credential reference or identifier */
    private String ref;
    
    String getType();
    void setType(String type);
    String getRef();
    void setRef(String ref);
}

/**
 * MCP registry error response
 */
class McpErrorResponse {
    /** Error message or code */
    private String error;
    
    String getError();
    void setError(String error);
}

import com.alibaba.nacos.api.ai.model.mcp.*;
import com.alibaba.nacos.api.ai.constant.AiConstants;

// Create a basic MCP server configuration
McpServerBasicInfo server = new McpServerBasicInfo();
server.setName("example-mcp-server");
server.setDescription("Example MCP server for AI tools");
server.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_HTTP);
server.setEnabled(true);

// Configure remote service
McpServerRemoteServiceConfig remoteConfig = new McpServerRemoteServiceConfig();
McpServiceRef serviceRef = new McpServiceRef();
serviceRef.setNamespaceId("public");
serviceRef.setGroupName("AI_GROUP");
serviceRef.setServiceName("mcp-tool-service");
remoteConfig.setServiceRef(serviceRef);
remoteConfig.setExportPath("/mcp/api");
server.setRemoteServerConfig(remoteConfig);

// Create tool specification
McpTool tool = new McpTool();
tool.setName("calculate");
tool.setDescription("Perform mathematical calculations");

// Define input schema
Map<String, Object> schema = new HashMap<>();
schema.put("type", "object");
Map<String, Object> properties = new HashMap<>();
properties.put("expression", Map.of("type", "string", "description", "Mathematical expression"));
schema.put("properties", properties);
tool.setInputSchema(schema);

// Create tool specification container
McpToolSpecification toolSpec = new McpToolSpecification();
toolSpec.getTools().add(tool);

// Add tool metadata
McpToolMeta meta = new McpToolMeta();
meta.setEnabled(true);
Map<String, String> context = new HashMap<>();
context.put("timeout", "30s");
meta.setInvokeContext(context);
toolSpec.getToolsMeta().put("calculate", meta);

// Direct endpoint configuration
McpEndpointSpec directEndpoint = new McpEndpointSpec();
directEndpoint.setType(AiConstants.Mcp.MCP_ENDPOINT_TYPE_DIRECT);
Map<String, String> data = new HashMap<>();
data.put("address", "192.168.1.100");
data.put("port", "8080");
directEndpoint.setData(data);

// Reference-based endpoint configuration
McpEndpointSpec refEndpoint = new McpEndpointSpec();
refEndpoint.setType(AiConstants.Mcp.MCP_ENDPOINT_TYPE_REF);
Map<String, String> refData = new HashMap<>();
refData.put("namespaceId", "public");
refData.put("groupName", "AI_GROUP");
refData.put("serviceName", "mcp-service");
refEndpoint.setData(refData);

// Configure AI service credentials
AiCredential credential = new AiCredential();
credential.setType("OAuth2.0");
credential.setRef("oauth-token-reference");

// For JWT tokens
AiCredential jwtCredential = new AiCredential();
jwtCredential.setType("jwt");
jwtCredential.setRef("jwt-token-key");