asana-gate은(는) 무엇을 하나요?
asana-gate는 Asana REST API 앞에 위치한 정책 게이트웨이입니다.
YAML 정책은 범위(워크스페이스, 팀, 포트폴리오, 프로젝트, 섹션, 작업)별로 에이전트가 수행할 수 있는 작업과 요청이 어떻게 구성되어야 하는지를 정의하며, 게이트는 MCP 도구 호출이든 asana-gate 명령이든 모든 요청에 대해 이를 적용합니다.
이를 통해 보고 들을 수 있는 모든 것은 정책에 의해 결정되며, Asana 자체에 의해 결정되지 않습니다. 정책이 숨기는 객체는 사용자에게 존재하지 않는 것으로 간주되며, 거부는 메시지가 asana-gate:로 시작하는 HTTP 스타일 오류로 반환됩니다.
게이트의 응답을 먼저 읽으세요
게이트가 반환하는 모든 객체는 allowed_actions를 포함합니다. 이는 정책이 현재 해당 객체에 대해 허용하는 <resource>:<verb> 작업(예: task:update 또는 story:create)입니다.
쓰기 작업을 수행하기 전에 이를 확인하세요. 누락된 작업은 거부될 수 있습니다. 시도하고 실패하기보다는 나열된 항목을 기준으로 계획을 세우세요.
| 응답 | 의미 | 수행할 작업 |
|---|---|---|
404 <type>: 알 수 없는 ID: <gid> | 객체가 존재하지 않거나 정책이 숨깁니다. 게이트는 의도적으로 두 경우를 구분할 수 없게 만듭니다(Asana가 보내는 동일한 404). | 재시도하거나 다른 gid를 시도하지 마세요. 객체가 정책 아래에 표시되지 않는다고 말하고, 소유자가 asana-gate explain <gid>를 실행하여 어떤 규칙이 숨기는지 확인할 수 있다고 알리세요. |
403 asana-gate: <action>은(는) <type> <gid>에서 허용되지 않습니다. | 객체는 표시되지만 정책이 해당 작업을 허용하지 않습니다. | 이를 보고하고 allowed_actions에서 작업을 제안하세요. 정책을 확장하는 것은 소유자의 결정입니다. |
403 asana-gate: <resource>.<member> 업데이트가 여기서 허용되지 않습니다(허용된 필드: …) | 업데이트가 규칙의 fields 허용 목록 외부의 멤버를 건드렸습니다. | 허용된 멤버만 사용하여 다시 보내세요. |
400 asana-gate: <resource>가 정책을 충족하지 않습니다: … | 정책의 제약 조건입니다. 필수 멤버가 누락되었거나 지워졌거나, 접두사나 형식이 잘못되었거나, 값이 허용되지 않거나, 멤버가 금지되었습니다. | 메시지에 정확히 명시된 대로 요청을 수정하고 다시 보내세요. |
428 asana-gate: <action>에는 사람의 확인이 필요합니다. | 정책이 사람이 이 작업을 승인하도록 요구합니다. | MCP를 통해서는 클라이언트가 표시하는 확인 요청에 응답하세요. 셸에서 실행하는 경우 --yes 플래그와 함께 다시 실행하세요. |
429 asana-gate: <action>은(는) <period>당 N개로 제한됩니다. | 정책이 이 범위의 이 작업에 대해 설정한 속도 제한입니다. | 해당 기간이 지날 때까지 기다리세요. 반복하지 마세요. |
목록(프로젝트, 작업, 검색, 타입어헤드, 이벤트)은 자동으로 필터링됩니다. 숨겨진 객체는 단순히 존재하지 않는 것으로 처리되며, 제거된 개수에 대한 정보는 제공되지 않으며, 페이지에는 offset으로 계속하기 위한 next_page.offset이 포함됩니다.
Asana 자체의 오류는 asana-gate: 접두사 없이 그대로 전달됩니다. 402는 워크스페이스의 요금제에 해당 기능(검색, 사용자 정의 필드, 포트폴리오 및 목표는 유료 요금제 필요)이 없음을 의미하고, 일반 400은 Asana가 본문을 거부했음을 의미하며, 일반 403은 토큰 자체의 권한 문제(감사 로그 이벤트, 워크스페이스 이벤트 및 조직 내보내기는 Enterprise 등급의 서비스 계정 필요; 얼리 액세스 Agents 엔드포인트는 설정의 asana.enable에서 ai_teammate_actors 플래그 필요)를 의미합니다.
접두사를 확인하세요. 접두사가 있으면 정책이 결정한 것이고, 없으면 Asana가 결정한 것입니다.
MCP를 통한 작업
서버는 정책이 허용할 수 있는 선별된 도구와 세 가지 일반 도구를 제공합니다.
asana_create_tasks및asana_update_tools는 한 번에 최대 50개의 작업을 처리하고 각 작업에 대해 하나의status_code및body를 순서대로 응답합니다. 일부는 성공하고 다른 일부는 실패할 수 있습니다.asana_request는 동일한 정책을 통해 모든 Asana REST 작업(method,/api/1.0아래의path,query,data객체로서의body)을 호출합니다. 이를 통한POST /batch는 최대 50개의 작업을 처리합니다.asana_operations는 각각에 필요한 정책 작업과 함께 작업을 나열합니다.asana_allowed_actions는 하나의 객체로 수행할 수 있는 작업을 알려줍니다.
| 도구 | 명령줄 | 설명 |
|---|---|---|
asana_search_tasks | asana-gate task search | 워크스페이스에서 전문(full-text) 및 필터링된 작업 검색(Asana Search API, 유료 요금제만 해당). 결과는 정책이 표시하는 작업으로 제한됩니다. |
asana_list_tasks | asana-gate task list | 프로젝트, 섹션, 태그 또는 사용자에게 할당된 작업(project, section, tag 또는 assignee 중 하나는 필수)을 나열합니다. 각 작업은 allowed_actions를 포함합니다. |
asana_get_task | asana-gate task get <task_gid> | 하나의 작업을 전체 필드 및 allowed_actions와 함께 읽습니다. |
asana_create_task | asana-gate task create | 하나 이상의 프로젝트(선택적으로 섹션 내), 상위 작업 아래, 또는 워크스페이스에 속하지 않은(unhomed) 작업을 생성합니다. |
asana_update_task | asana-gate task update <task_gid> | 작업의 필드를 업데이트합니다. 완료하려면 task:complete, 할당하려면 task:assign이 필요하며, 다른 필드는 task:update(허용 목록으로 제한될 수 있음)가 필요합니다. |
asana_create_tasks | asana-gate task create-many | 한 번의 호출로 최대 50개의 작업을 생성하며, 각각은 asana_create_task가 수행하는 방식과 동일합니다. 결과는 작업당 하나의 status_code 및 body를 순서대로 보유합니다. Asana는 일부를 성공시키고 다른 일부를 실패시킬 수 있습니다. 작업에 대한 정책 거부는 실행 전에 전체 호출을 거부하며, 메시지에서 작업 이름(actions[i])을 지정합니다. |
asana_update_tasks | asana-gate task update-many | 한 번의 호출로 최대 50개의 작업을 업데이트하며, 각각은 asana_update_task가 수행하는 방식과 동일합니다. 결과는 작업당 하나의 status_code 및 body를 순서대로 보유합니다. Asana는 일부를 성공시키고 다른 일부를 실패시킬 수 있습니다. 작업에 대한 정책 거부는 실행 전에 전체 호출을 거부하며, 메시지에서 작업 이름(actions[i])을 지정합니다. |
asana_delete_task | asana-gate task delete <task_gid> | 작업을 삭제합니다(Asana에서 휴지통으로 이동). |
asana_list_subtasks | asana-gate task subtasks <task_gid> | 작업의 직접 하위 작업을 나열합니다. |
asana_create_subtask | — | 작업 아래에 하위 작업을 생성합니다. 프로젝트가 제공되지 않는 한 상위 작업의 범위를 상속합니다. |
asana_set_task_parent | asana-gate task set-parent <task_gid> | 작업을 다른 작업의 하위 작업으로 만들거나(상위를 null로 설정하여 최상위 작업으로 만듭니다). |
asana_add_task_to_project | asana-gate task add-project <task_gid> | 작업을 프로젝트에 멀티호밍(multi-home)하고, 선택적으로 섹션에 추가합니다. |
asana_remove_task_from_project | asana-gate task remove-project <task_gid> | 작업을 해당 프로젝트 중 하나에서 제거합니다. |
asana_move_task_to_section | asana-gate task move <task_gid> | 작업을 속한 프로젝트의 섹션으로 이동합니다(양쪽 끝에서 task:move 필요). |
asana_add_tag_to_task | asana-gate task tag <task_gid> | 작업에 태그를 적용합니다(작업 범위 내에서 tag:apply 필요). |
asana_remove_tag_from_task | asana-gate task untag <task_gid> | 작업에서 태그를 제거합니다(작업 범위 내에서 tag:apply 필요). |
asana_add_task_dependencies | asana-gate task add-dependencies <task_gid> | 이 작업이 의존하는 작업을 표시합니다. 참조된 모든 작업은 보여야 합니다. |
asana_remove_task_dependencies | asana-gate task remove-dependencies <task_gid> | 작업의 의존성을 제거합니다. |
asana_list_task_stories | asana-gate task comments <task_gid> | 작업의 댓글 및 활동(스토리)을 나열합니다. |
asana_create_comment | asana-gate task comment <task_gid> | 작업에 댓글(스토리)을 추가합니다. |
asana_update_story | — | 스토리(댓글 또는 활동)를 업데이트합니다. |