MaxCompute:MaxCompute MCP service

In sales_dw.dwd in the China (Shanghai) region, generate an SQL query to count the number of paid orders and the total payment amount for each channel over the last 30 days, sorted by payment amount in descending order. Only generate and validate the SQL, do not execute it yet.

{
  "question": "Count the number of paid orders and the total payment amount for each channel over the last 30 days, sorted by payment amount in descending order",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "sales_dw",
      "schema": "dwd"
    }
  ],
  "analysis_context": {
    "project": "sales_dw",
    "schema": "dwd"
  }
}

Exemple : Restriction à des tables spécifiques

{
  "question": "Find the team with the highest points in each race and calculate their cumulative season points",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "analytics",
      "schema": "formula_1",
      "tables": ["constructors", "constructorresults", "races"]
    }
  ]
}

{
  "question": "Query the 20 jobs with the highest CU consumption in the last 7 days. Return the instance ID, project, submitter, and CU hours",
  "region": "cn-shanghai",
  "analysis_context": {
    "project": "<A project where the current identity can create query instances in this region>"
  }
}

Diagnostic des jobs

{
  "instance_id": "<INSTANCE_ID>",
  "project": "sales_dw",
  "region": "cn-shanghai",
  "depth": "standard"
}

Diagnose job <INSTANCE_ID> in sales_dw. First, identify the failed stage and the most likely cause. 
Provide actionable recommendations for a fix. Do not rerun or cancel the job.

Perform a deep dive on this job. The initial analysis did not explain the root cause. 
Check the available logs from failed workers and stage evidence. 
Distinguish between confirmed facts, inferences, and missing evidence.

Analyse des quotas

{
  "region": "cn-shanghai",
  "quota_nickname": "team_etl_quota",
  "question": "Analyze the 10 jobs with the highest CPU usage in the last 7 days and describe any verifiable abnormal signals"
}

Analyze team_etl_quota in cn-shanghai. Find the jobs with the highest CPU consumption in the last 7 days. Attribute a job as abnormal only if there are direct abnormal signals for the job. Otherwise, state that the cause is unknown. Provide only recommendations. Do not modify quotas or jobs.

{
  "region": "cn-shanghai",
  "question": "Compare compute quotas with active jobs in the last 7 days, sorted by job CPU usage. List capacity utilization separately for Subscription quotas, but do not calculate capacity percentages for Pay-As-You-Go and Spot quotas"
}

Compare my compute quotas in cn-shanghai that had active jobs in the last 7 days, including Subscription, Pay-As-You-Go, and Spot.
Sort them by job CPU usage and list high-consumption jobs. Add capacity utilization only for Subscription quotas.

Exigences relatives à Information Schema

Generate SQL peut utiliser les vues Information Schema au niveau du locataire. L'analyse des quotas pour l'utilisation de la capacité et les preuves liées aux jobs n'utilise pas Information Schema. Generate SQL autorise uniquement les vues figurant sur la liste blanche côté serveur, telles que :

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS_HISTORY

Lorsque Generate SQL utilise ces vues, il doit respecter les conditions suivantes :

1. L'identité actuellement authentifiée doit disposer d'autorisations de lecture pour Information Schema au niveau du locataire. Les comptes Root disposent généralement de cet accès par défaut. L'accès pour les utilisateurs RAM ou les rôles RAM dépend de la configuration définie par l'administrateur du locataire.

2. L'identité actuelle doit disposer d'au moins un projet MaxCompute visible dans la région cible. Ce projet est utilisé pour soumettre des requêtes SQL Information Schema en lecture seule. L'identité doit également disposer des autorisations requises pour créer des instances de requête.

3. La région cible doit fournir les vues au niveau du locataire mentionnées ci-dessus ainsi que leurs dépendances backend.

Limitations de sécurité et de portée :

• Generate SQL lit les vues au niveau du locataire enregistrées par les compétences intégrées, mais il ne peut pas interroger des vues système inconnues ni mixer des requêtes avec des tables physiques.

• Avant que le modèle ne sélectionne une vue système, Generate SQL charge la compétence racine d'Information Schema. Il utilise la granularité des données, l'actualité et les colonnes de la vue pour déterminer la source de faits requise. Une fois la vue sélectionnée, Generate SQL charge la documentation complète des colonnes pour cette vue.

• Les ébauches de vues système pour Generate SQL doivent inclure une plage temporelle et une clause LIMIT.

• Les requêtes sont toujours en lecture seule. Elles ne modifient ni les quotas, ni les configurations de planification, ni les jobs.

Cas d'utilisation des outils d'analyse intelligente

1. Use maxcompute_generate_sql to generate and validate the SQL for channel revenue over the last 30 days.
2. After reviewing and confirming the SQL, use maxcompute_sql_execute to run execute_args.
3. If the job fails or slows down significantly, use maxcompute_diagnose_job to analyze the instance.

1. Omit quota_nickname and use maxcompute_analyze_quota_usage to find compute quotas that have had jobs in the last 7 days.
2. Find high-consumption jobs based on actual job consumption. Check capacity utilization only for Subscription quotas.
3. Call maxcompute_diagnose_job for instances with abnormal signals.
4. Optimize the SQL or scheduling based on job evidence. Do not automatically scale up based only on historical consumption.

Analyze the owner distribution and CPU consumption of failed jobs for team_etl_quota over the last 7 days.
Investigate the cause for the failed instance with the highest CPU consumption.

Recommandations pour l'utilisation de l'outil d'analyse intelligente

• Fournissez uniquement les champs de portée pris en charge par l'outil actuel. Pour la génération SQL, utilisez region, sources et le paramètre optionnel analysis_context. Pour le diagnostic de job, utilisez le projet et l'ID d'instance ou une URL Logview. Pour l'analyse des quotas, utilisez region et le surnom exact du quota. N'incluez pas de champs de contexte provenant d'autres outils dans l'appel actuel.

• Pour générer du code SQL pour une portée de données connue, fournissez sources. Cela évite un processus de découverte trop large qui pourrait ne renvoyer aucun candidat ou plusieurs jeux de données ambigus.

• Pour le diagnostic de job, utilisez d'abord standard. N'utilisez deep que lorsque les résultats sont inconclusifs ou qu'une investigation plus poussée est nécessaire.

• Pour l'analyse des quotas, comparez d'abord les données de consommation des jobs renvoyées. Ensuite, examinez en détail quelques quotas et instances à forte demande. Ne considérez pas les résultats partiels comme une liste exhaustive.

• Distinguez toujours les faits confirmés, les jugements du modèle et missing_evidence.

• Les utilisateurs doivent confirmer séparément toute opération de mise à l'échelle, de planification, de migration, d'exécution SQL, de relance ou d'annulation.

Règles générales d'appel

• Les outils peuvent accéder uniquement aux ressources MaxCompute pour lesquelles l'identité actuelle dispose d'une autorisation. Ne confondez pas la visibilité des outils avec l'autorisation d'accès aux ressources.

• Après avoir identifié les tables candidates, consultez la structure exacte de la table avant de générer ou d'exécuter du code SQL. Ne devinez ni les colonnes, ni les partitions, ni le schéma en vous basant uniquement sur le nom de la table.

• Le client doit obtenir une confirmation explicite de l'utilisateur avant d'effectuer des opérations d'écriture. Ces opérations incluent l'écriture de code SQL, la création de tables, l'insertion de données, la mise à jour des métadonnées et la modification de SemanticSpec. La passerelle n'effectue pas de confirmation secondaire interactive pour le client.

• Pour les jeux de résultats volumineux, utilisez la pagination, réduisez la portée de la requête ou lisez les données depuis une instance asynchrone. Local MCP peut également écrire dans un fichier local via file://output_uri. Ce chemin fait référence à la machine où s'exécute Local MCP, et non à la machine cliente MCP.

• Le paramètre execution_mode de maxcompute_sql_execute est défini par défaut sur wlm. Lorsque vous utilisez MaxQA (MCQA v2), transmettez explicitement execution_mode=maxqa ainsi que le quota_name interactif. Ne transmettez pas simultanément settings.odps.task.wlm.quota. Pour les appels ultérieurs concernant l'état, les résultats ou l'annulation, transmettez uniquement le project et l'instance_id. Ne transmettez ni n'enregistrez la connexion MaxQA côté serveur ni les cookies associés.

Le client MCP ne trouve pas les outils

• Pour les connexions OAuth directes via navigateur, assurez-vous que le point de terminaison du service Remote MCP inclut /mcp et que la même configuration client ne mélange pas les points de terminaison réseau public et VPC.

• Vérifiez que le client utilisé pour la connexion directe OAuth via navigateur prend en charge Streamable HTTP, OAuth et tools/list.

• Vérifiez si la command du lanceur local pointe vers alibabacloud-maxcompute-mcp-server installé, et si alibabacloud-maxcompute-mcp-server --help s'exécute correctement dans le même environnement d'exécution.

• Vérifiez si MAXCOMPUTE_CATALOG_CONFIG pointe vers un fichier de configuration lisible, ou si MAXCOMPUTE_REGION et MAXCOMPUTE_NETWORK sont tous deux définis.

• Vérifiez si default a sélectionné local car Remote MCP n'est pas disponible. Si les dépendances locales sont manquantes, installez alibabacloud-maxcompute-mcp-server[local] comme indiqué dans le message d'erreur.

• Vérifiez si la liste des outils disponibles inclut l'outil cible. Remote MCP utilise les noms d'outils maxcompute_*, tandis que le mode local utilise les noms d'outils SDK d'origine. Les deux ne sont pas directement interchangeables.

• Après avoir modifié la configuration, redémarrez Cursor, Claude Code ou le client MCP correspondant.

Échecs d'authentification, de connexion ou d'autorisation

• Pour les connexions directes OAuth via navigateur, vérifiez que l'utilisateur a terminé l'autorisation OAuth Alibaba Cloud. Si la page OAuth ne s'ouvre pas, vérifiez si le client prend en charge MCP OAuth et si le navigateur local ou le port de rappel est bloqué.

• Si vous recevez une erreur 401 avec une connexion directe OAuth via navigateur, réautorisez l'accès et vérifiez que le jeton d'accès enregistré par le client est valide.

• Vérifiez que le lanceur local a obtenu un AccessKey valide, des informations d'identification temporaires STS, un URI d'informations d'identification ou des informations d'identification issues de la chaîne d'informations d'identification par défaut. Assurez-vous que le jeton de sécurité STS n'a pas expiré. Le lanceur local ne nécessite pas d'OAuth via navigateur.

• Vérifiez que la region et le network correspondent à l'environnement MaxCompute cible et que les adresses de service FE et CatalogAPI dans la configuration d'origine pointent vers la même région et le même type de réseau.

• Vérifiez que votre environnement VPC peut accéder au point de terminaison VPC CatalogAPI et au point de terminaison VPC MCP dans la même région. Une configuration VPC ne peut pas être utilisée pour se connecter à un point de terminaison MCP réseau public.

• Le mode remote renvoie une erreur lorsque Remote MCP n'est pas disponible. Le mode default tente d'utiliser l'outil SDK local.

• En cas d'erreur 403, assurez-vous que le compte Alibaba Cloud actuel dispose des autorisations MaxCompute et RAM pour le projet cible.

• Vérifiez que l'ID de région cible dans la conversation ou les paramètres de l'outil est correct. S'il n'est pas spécifié explicitement, le service utilise la région par défaut du point d'entrée actuel.

• Lorsque vous utilisez un URI d'informations d'identification, assurez-vous que la machine exécutant le lanceur peut accéder à ALIBABA_CLOUD_CREDENTIALS_URI.

• Utilisez maxcompute_access_check de Remote MCP ou check_access du mode local pour vérifier votre identité actuelle avant de procéder au dépannage de l'outil spécifique.

Échecs de recherche de métadonnées

Le maxcompute_schema_search_metadata pour Remote MCP et le search_meta_data pour le mode local utilisent la même syntaxe de requête Catalog. Les causes d'erreur courantes incluent :

• Vous utilisez search_meta_data en mode local, mais namespaceId ou MAXCOMPUTE_NAMESPACE_ID n'est pas configuré. Remote MCP ne nécessite pas cette configuration.

• L'instruction de requête omet type=TABLE, type=RESOURCE ou type=SCHEMA.

• Utilisation de conditions de projet et de région incompatibles dans la même requête.

Échecs d'analyse, d'exécution ou de récupération des résultats SQL

Si la résolution du nom de table SQL échoue, utilisez d'abord maxcompute_schema_describe_table de Remote MCP ou get_table_schema de Local MCP pour lire le schéma de la table, afin que l'agent puisse utiliser la référence de table précise renvoyée. Les formats de nom de table courants sont schema.table ou project.schema.table pour un modèle à trois couches, et table ou project.table pour un modèle à deux couches.

Si Remote MCP rejette une instruction SQL en tant qu'opération d'écriture, confirmez que l'utilisateur a l'intention d'effectuer l'écriture et utilisez explicitement mode=write après avoir reçu la confirmation. Ne modifiez pas le mode pour contourner la vérification en lecture seule.

Si l'exécution SQL expire ou si le résultat est tronqué :

• Privilégiez l'exécution asynchrone.

  • Remote MCP utilise maxcompute_sql_get_status et maxcompute_sql_fetch_result pour poursuivre l'interrogation.

  • Local MCP effectue les requêtes de suivi en utilisant get_instance_status et get_instance.

• Remote MCP utilise limit et cursor pour paginer et réduire la portée de la requête. Local MCP peut également utiliser output_uri=file:///path/to/result.jsonl pour écrire sur la machine où s'exécute Local MCP.

• Avant d'exécuter l'opération, appelez l'outil d'estimation d'utilisation des ressources correspondant et limitez la consommation de ressources en fonction des définitions de paramètres dans tools/list.