sincekmori/asana-gate

Was macht asana-gate?

asana-gate ist eine Policy-Gateway vor der Asana REST API. Eine YAML-Policy legt pro Scope (Workspace, Team, Portfolio, Projekt, Abschnitt, Aufgabe) fest, welche Aktionen ein Agent durchführen darf und wie seine Anfragen geformt werden; die Gateway erzwingt dies bei jeder Anfrage, unabhängig davon, ob sie als MCP-Tool-Aufruf oder als asana-gate Befehl eingeht. Alles, was Sie darüber sehen oder tun können, wird durch diese Policy entschieden, nicht durch Asana: Objekte, die die Policy verbirgt, existieren für Sie nicht, und Verweigerungen kommen als HTTP-ähnliche Fehler zurück, deren Nachricht mit asana-gate: beginnt.

Lesen Sie zuerst die Antworten der Gateway

Jedes von der Gateway zurückgegebene Objekt enthält allowed_actions: die <Resource>:<Verb>-Aktionen, die die Policy aktuell darauf erlaubt, wie task:update oder story:create. Überprüfen Sie es vor dem Schreiben, denn eine nicht darin enthaltene Aktion wird verweigert: Planen Sie basierend auf dem, was aufgeführt ist, anstatt es zu versuchen und zu scheitern.

Antwort	Bedeutung	Was zu tun ist
404 <Typ>: Keine erkannte ID: <gid>	Das Objekt existiert nicht oder die Policy verbirgt es; die Gateway macht die beiden bewusst ununterscheidbar (derselbe 404, den Asana sendet)	Wiederholen Sie nicht oder versuchen Sie andere gids. Sagen Sie, das Objekt ist unter der Policy nicht sichtbar; sein Besitzer kann asana-gate explain <gid> ausführen, um zu sehen, welche Regel es verbirgt
403 asana-gate: <Aktion> ist für <Typ> <gid> nicht erlaubt	Das Objekt ist sichtbar, aber die Policy erlaubt diese Aktion dort nicht	Melden Sie es und bieten Sie eine Aktion aus allowed_actions an; die Erweiterung der Policy ist Sache des Besitzers
403 asana-gate: Das Aktualisieren von <Resource>.<Mitglied> ist hier nicht erlaubt (erlaubte Felder: …)	Die Aktualisierung betraf ein Mitglied außerhalb der fields-Whitelist der Regel	Senden Sie es nur mit den erlaubten Mitgliedern erneut
400 asana-gate: Die <Resource> erfüllt die Policy nicht: …	Eine Einschränkung der Policy: ein erforderliches Mitglied fehlt oder wurde gelöscht, ein Präfix oder Format ist falsch, ein Wert ist nicht erlaubt, ein Mitglied ist verboten	Korrigieren Sie die Anfrage genau wie in der Nachricht beschrieben und senden Sie sie erneut
428 asana-gate: <Aktion> benötigt die Bestätigung einer Person	Die Policy möchte, dass ein Mensch diese Aktion genehmigt	Antworten Sie über MCP auf die Abfrage, die der Client zeigt; führen Sie von einer Shell aus den Befehl mit --yes erneut aus
429 asana-gate: <Aktion> ist auf N pro <Zeitraum> begrenzt	Ein von der Policy für diese Aktion in diesem Scope festgelegtes Rate-Limit	Warten Sie, bis der Zeitraum abgelaufen ist; wiederholen Sie es nicht in einer Schleife

Listen (Projekte, Aufgaben, Suche, Typeahead, Ereignisse) werden still herausgefiltert: versteckte Objekte sind einfach nicht vorhanden, es wird nicht angegeben, wie viele entfernt wurden, und eine Seite enthält next_page.offset, um mit offset fortzufahren. Asanas eigene Fehler werden unverändert durchgelassen, ohne das Präfix asana-gate:: ein 402 bedeutet, dass dem Workspace-Plan die Funktion fehlt (Suche, benutzerdefinierte Felder, Portfolios und Ziele benötigen einen kostenpflichtigen Plan), ein einfacher 400 ist Asanas Ablehnung des Bodys, ein einfacher 403 ist die eigene Berechtigung des Tokens (Audit-Log-Ereignisse, Workspace-Ereignisse und Organisationsexporte benötigen ein Servicekonto auf Enterprise-Stufe; die Early-Access-Agents-Endpunkte benötigen das Flag ai_teammate_actors in den Einstellungen von asana.enable). Achten Sie auf das Präfix: Damit hat die Policy entschieden, ohne hat Asana entschieden.

Arbeiten über MCP

Der Server stellt die kuratierten Tools bereit, die die Policy jemals erlauben könnte, plus drei generische:

• asana_create_tasks und asana_update_tasks akzeptieren bis zu 50 Aufgaben auf einmal und antworten mit einem status_code und body pro Aufgabe, in der Reihenfolge; einige können fehlschlagen, während andere erfolgreich sind.
• asana_request ruft jede beliebige Asana REST-Operation (method, path unter /api/1.0, query, body als data-Objekt) durch dieselbe Policy auf; ein POST /batch darüber akzeptiert bis zu 50 Aktionen.
• asana_operations listet die Operationen mit der Policy-Aktion auf, die jede benötigt; asana_allowed_actions sagt Ihnen, was Sie mit einem Objekt tun dürfen.

Tool	Kommandozeile	Was es tut
asana_search_tasks	asana-gate task search	Volltext- und gefilterte Aufgabensuche im Workspace (Asana Search API; nur kostenpflichtige Pläne). Ergebnisse sind auf Aufgaben beschränkt, die die Policy sichtbar macht.
asana_list_tasks	asana-gate task list	Listet Aufgaben in einem Projekt, einem Abschnitt, mit einem Tag oder einem Benutzer zugewiesen (eines von Projekt, Abschnitt, Tag oder Zugewiesener ist erforderlich). Jede Aufgabe enthält allowed_actions.
asana_get_task	asana-gate task get <task_gid>	Liest eine Aufgabe mit ihren vollständigen Feldern und allowed_actions.
asana_create_task	asana-gate task create	Erstellt eine Aufgabe in einem oder mehreren Projekten (optional in einem Abschnitt), unter einer übergeordneten Aufgabe oder ohne Startpunkt im Workspace.
asana_update_task	asana-gate task update <task_gid>	Aktualisiert Felder einer Aufgabe. Abschließen benötigt task:complete, Zuweisen benötigt task:assign; andere Felder benötigen task:update (möglicherweise auf eine Whitelist beschränkt).
asana_create_tasks	asana-gate task create-many	Erstellt bis zu 50 Aufgaben in einem Aufruf, jede wie asana_create_task es tun würde. Das Ergebnis enthält einen status_code und body pro Aufgabe, in der Reihenfolge; Asana kann einige fehlschlagen lassen, während andere erfolgreich sind. Eine Policy-Ablehnung einer Aufgabe lehnt den gesamten Aufruf ab, bevor etwas ausgeführt wird, und ihre Nachricht nennt die Aufgabe (actions[i]).
asana_update_tasks	asana-gate task update-many	Aktualisiert bis zu 50 Aufgaben in einem Aufruf, jede wie asana_update_task es tun würde. Das Ergebnis enthält einen status_code und body pro Aufgabe, in der Reihenfolge; Asana kann einige fehlschlagen lassen, während andere erfolgreich sind. Eine Policy-Ablehnung einer Aufgabe lehnt den gesamten Aufruf ab, bevor etwas ausgeführt wird, und ihre Nachricht nennt die Aufgabe (actions[i]).
asana_delete_task	asana-gate task delete <task_gid>	Löscht eine Aufgabe (sie wird in Asana in den Papierkorb verschoben).
asana_list_subtasks	asana-gate task subtasks <task_gid>	Listet die direkten Unteraufgaben einer Aufgabe auf.
asana_create_subtask	—	Erstellt eine Unteraufgabe unter einer Aufgabe; sie erbt den Scope des übergeordneten Elements, es sei denn, Projekte werden angegeben.
asana_set_task_parent	asana-gate task set-parent <task_gid>	Macht eine Aufgabe zu einer Unteraufgabe einer anderen (oder zu einer Aufgabe der obersten Ebene mit parent null).
asana_add_task_to_project	asana-gate task add-project <task_gid>	Fügt eine Aufgabe in ein Projekt ein, optional in einen Abschnitt.
asana_remove_task_from_project	asana-gate task remove-project <task_gid>	Entfernt eine Aufgabe aus einem ihrer Projekte.
asana_move_task_to_section	asana-gate task move <task_gid>	Verschiebt eine Aufgabe in einen Abschnitt eines Projekts, zu dem sie gehört (benötigt task:move an beiden Enden).
asana_add_tag_to_task	asana-gate task tag <task_gid>	Wendet einen Tag auf eine Aufgabe an (benötigt tag:apply im Scope der Aufgabe).
asana_remove_tag_from_task	asana-gate task untag <task_gid>	Entfernt einen Tag von einer Aufgabe (benötigt tag:apply im Scope der Aufgabe).
asana_add_task_dependencies	asana-gate task add-dependencies <task_gid>	Markiert Aufgaben, von denen diese Aufgabe abhängt; jede referenzierte Aufgabe muss sichtbar sein.
asana_remove_task_dependencies	asana-gate task remove-dependencies <task_gid>	Entfernt Abhängigkeiten einer Aufgabe.
asana_list_task_stories	asana-gate task comments <task_gid>	Listet die Kommentare und Aktivitäten (Stories) einer Aufgabe auf.
asana_create_comment	asana-gate task comment <task_gid>	Fügt einer Aufgabe einen Kommentar (Story) hinzu.
asana_update_story	—	Aktualisiert den Text eines Kommentars (Story).
asana_delete_story	—	Löscht einen Kommentar (Story).
asana_get_story	—	Ruft einen einzelnen Kommentar (Story) ab.
asana_list_projects	asana-gate project list	Listet Projekte im Workspace auf, die die Policy sichtbar macht.
asana_get_project	asana-gate project get <project_gid>	Ruft ein Projekt mit seinen vollständigen Feldern und allowed_actions ab.
asana_create_project	asana-gate project create	Erstellt ein Projekt.
asana_update_project	asana-gate project update <project_gid>	Aktualisiert die Felder eines Projekts (benötigt project:update).
asana_delete_project	asana-gate project delete <project_gid>	Löscht ein Projekt.
asana_get_project_section	—	Ruft einen einzelnen Abschnitt in einem Projekt ab.
asana_list_project_sections	asana-gate project sections <project_gid>	Listet die Abschnitte eines Projekts auf.
asana_create_section	asana-gate project create-section <project_gid>	Erstellt einen neuen Abschnitt in einem Projekt.
asana_update_section	asana-gate project update-section <section_gid>	Aktualisiert den Namen eines Abschnitts.
asana_delete_section	asana-gate project delete-section <section_gid>	Löscht einen Abschnitt (Aufgaben darin werden nicht gelöscht).
asana_get_task_count_for_project	—	Gibt die Anzahl der Aufgaben in einem Projekt zurück.
asana_list_teams	asana-gate team list	Listet Teams im Workspace auf.
asana_get_team	asana-gate team get <team_gid>	Ruft ein Team mit allowed_actions ab.
asana_list_team_users	asana-gate team users <team_gid>	Listet Benutzer in einem Team auf.
asana_list_portfolios	asana-gate portfolio list	Listet Portfolios im Workspace auf.
asana_get_portfolio	asana-gate portfolio get <portfolio_gid>	Ruft ein Portfolio mit allowed_actions ab.
asana_create_portfolio	asana-gate portfolio create	Erstellt ein Portfolio.
asana_update_portfolio	asana-gate portfolio update <portfolio_gid>	Aktualisiert die Felder eines Portfolios.
asana_add_items_to_portfolio	asana-gate portfolio add-items <portfolio_gid>	Fügt Projekte zu einem Portfolio hinzu.
asana_remove_items_from_portfolio	asana-gate portfolio remove-items <portfolio_gid>	Entfernt Projekte aus einem Portfolio.
asana_list_portfolio_items	asana-gate portfolio items <portfolio_gid>	Listet die Elemente (Projekte) eines Portfolios auf.
asana_get_user	asana-gate user get <user_gid>	Ruft einen Benutzer ab.
asana_get_workspace	asana-gate workspace get <workspace_gid>	Ruft den Workspace ab.
asana_list_workspaces	asana-gate workspace list	Listet die Workspaces des authentifizierten Tokens auf.
asana_list_custom_fields	asana-gate custom-field list	Listet benutzerdefinierte Felder im Workspace auf.
asana_get_custom_field	asana-gate custom-field get <gid>	Ruft ein benutzerdefiniertes Feld ab.
asana_search_projects	asana-gate project search	Führt eine Volltextsuche nach Projekten durch.
asana_search_objects	asana-gate object search	Führt eine asana-übergreifende Suche nach Objekten durch (Asana Search API; kostenpflichtige Pläne).
asana_get_goal	asana-gate goal get <goal_gid>	Ruft ein Ziel ab.
asana_list_goals	asana-gate goal list	Listet Ziele im Workspace auf.
asana_get_goal_metric	asana-gate goal metric <goal_gid>	Ruft eine Metrik eines Ziels ab.
asana_get_goal_metric_current_value	-	Ruft den aktuellen Wert einer Zielmetrik ab.
asana_list_goal_links	asana-gate goal links <goal_gid>	Listet die Verknüpfungen eines Ziels auf.
asana_get_workspace_membership	asana-gate workspace membership <workspace_gid>	Ruft die Mitgliedschaft des authentifizierten Benutzers im Workspace ab.
asana_get_membership	-	Ruft die Mitgliedschaft eines Benutzers in einem Projekt/Portfolio/Team ab.
asana_get_enum_option	-	Ruft eine einzelne Aufzählungsoption eines benutzerdefinierten Feldes ab.
asana_insert_enum_option	-	Fügt eine Aufzählungsoption in ein benutzerdefiniertes Feld eines Aufzählungstyps ein.
asana_rules	asana-gate rules	Gibt die Policy im YAML-Format zurück (der Policy-String, den asana-gate liest).
asana_allowed_actions	asana-gate allowed-actions <Typ> <gid>	Gibt die erlaubten Aktionen für ein einzelnes Objekt zurück.
asana_operations	-	Listet alle Operationen auf, die asana_request annehmen kann, mit der Policy-Aktion, die jede benötigt.
asana_request	-	Führt einen beliebigen REST-Aufruf durch die Policy aus.
asana_batch	-	Führt bis zu 50 Aktionen über einen einzigen POST /batch-Aufruf aus. Ergebnis ist ein Array von Antworten in derselben Reihenfolge wie die Eingabe. Fehlgeschlagene Aktionen enthalten ein error-Objekt.

Policy schreiben und verwalten

Eine asana-gate-Policy ist eine einfache YAML-Datei, die definiert, worauf ein Agent zugreifen darf. Sie wird durch Umgebungsvariablen oder Befehlszeilenargumente geladen.

Schnellstart

# Aktuelle Policy anzeigen (das ist alles, was verfügbar ist)
asana-gate rules

# Policy aus einer Datei laden
export ASANA_GATE_POLICY=$(cat /pfad/zu/policy.yaml)
# oder
asana-gate --policy policy.yaml task search

Policy-Referenz

Eine Policy-Datei hat einen scopes-Eintrag. Jeder Schlüssel identifiziert ein Objekt, auf das die Regeln angewendet werden:

scopes:
  workspace:
    - where: gid == "<workspace_gid>"
      allow: "*"
      deny: ["*:delete", "*:batch", "*:search", "*:create"]
    - where: gid == "<workspace_gid>"
      allow: ["task:create", "task:update", "project:create", "story:create"]
  project:
    - where: gid == "<project_gid>"
      allow: "*"
      deny: ["task:delete"]

Policy-Elemente:

• where: Ein Filter, der Objekte anhand ihrer Felder (gid, name, resource_type, parent.gid, members, followers) mithilfe von ==, !=, in und has-Operatoren auswählt.
• allow: Aktionen, die erlaubt sind ("*" für alle, oder eine Liste).
• deny: Aktionen, die verboten sind ("*" für alle, oder eine Liste; überschreibt allow).
• fields: (optional) Auf eine Liste von Feldern beschränken, die aktualisiert werden dürfen.
• constraints: (optional) Erzwingt Regeln auf dem Objekt: erfordert must, verbietet forbidden, schreibt prefix vor, erzwingt eine format-Regex, setzt allow_on_clear-Verhalten oder verlangt eine menschliche confirmation.

Aktionen

Aktionen sind <Ressourcentyp>:<Verb>. Die Policy verwendet dieselben Aktionen für alle Scopes:

Aktion	Bedeutung
task:create	Aufgabe erstellen
task:read	Aufgabe lesen
task:update	Aufgabe aktualisieren
task:delete	Aufgabe löschen
task:complete	Aufgabe abschließen
task:assign	Aufgabe zuweisen
task:move	Aufgabe verschieben
task:add-project	Aufgabe zu Projekt hinzufügen
task:remove-project	Aufgabe aus Projekt entfernen
story:create	Kommentar hinzufügen
story:read	Kommentar lesen
story:update	Kommentar bearbeiten
story:delete	Kommentar löschen
project:create	Projekt erstellen
project:read	Projekt lesen
project:update	Projekt aktualisieren
project:delete	Projekt löschen
section:create	Abschnitt erstellen
section:update	Abschnitt aktualisieren
section:delete	Abschnitt löschen
tag:apply	Tag anwenden/entfernen
portfolio:create	Portfolio erstellen
portfolio:read	Portfolio lesen
portfolio:update	Portfolio aktualisieren
portfolio:delete	Portfolio löschen
portfolio:add-items	Elemente zu Portfolio hinzufügen
portfolio:remove-items	Elemente aus Portfolio entfernen
team:read	Team lesen
team:list-members	Teammitglieder auflisten
goal:read	Ziel lesen
custom_field:read	Benutzerdefiniertes Feld lesen
custom_field:write	Benutzerdefiniertes Feld schreiben
user:read	Benutzer lesen
workspace:read	Workspace lesen

Was passiert, wenn beides erlaubt und verweigert wird

Das Verhalten lautet: Standardmäßig alles verweigern, außer was erlaubt ist. Das erste passende allow gewährt eine Aktion; selbst wenn sie gewährt wurde, kann ein deny auf derselben Ebene sie widerrufen.

Fehlersuche in der Policy

# Erklären, welche Regel eine bestimmte ID verbirgt
asana-gate explain 1234567890

# Erlaubte Aktionen für ein Objekt anzeigen
asana-gate allowed-actions task 1234567890