2026/9/17 14:24:16
FEATURED · 精选文章 
Klavis Asana MCP Server 详解20 个工具让 AI Agent 管理 Asana 任务、项目与团队协作【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文基于开源仓库中的 mcp_servers/asana/README.md 及其完整源码讲解 Klavis Asana MCP Server 的部署方式托管与 Docker 自托管、双模式鉴权机制、全部 20 个 MCP 工具的参数与实现细节以及底层 HTTP 客户端的限流、响应规范化与错误处理设计。读完后你将能够将该服务接入任意支持 MCP 的 AI 应用并理解其每个工具背后的 Asana API 调用链路。1. 服务定位与快速启动Asana MCP Server 是一个基于 Model Context ProtocolMCP实现的 Asana 集成服务器通过 Asana 官方 API 让 AI Agent 管理任务、项目、团队与标签并支持 OAuth 鉴权。源码位于 mcp_servers/asana/ 目录由 server.py 作为入口、tools/ 包实现各业务工具构成。1.1 托管服务方式Klavis 平台README 推荐的生产方式是使用 Klavis 托管基础设施无需自行搭建pip install klavis # or npm install klavisfrom klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(ASANA, user123)即通过 Klavis SDK 创建 API Key 后以ASANA作为服务标识创建一个 server 实例第二个参数为用户标识即可在 AI 应用中直接调用 Asana 工具OAuth 流程由托管平台代管。1.2 Docker 自托管方式自托管拉取官方镜像即可运行# Pull latest image docker pull ghcr.io/klavis-ai/asana-mcp-server:latest # Run Asana MCP Server with OAuth Support through Klavis AI docker run -p 5000:5000 -e KLAVIS_API_KEY$KLAVIS_API_KEY \ ghcr.io/klavis-ai/asana-mcp-server:latest # Run Asana MCP Server (no OAuth support) docker run -p 5000:5000 -e AUTH_DATA{access_token:your_asana_api_key_here} \ ghcr.io/klavis-ai/asana-mcp-server:latest两种启动模式的区别OAuth 模式传入KLAVIS_API_KEY环境变量由 OAuth 层自动完成 Asana 授权流程直连模式通过AUTH_DATA环境变量直接注入 JSON 格式的凭证{access_token: ...}跳过 OAuth。结合 Dockerfile 可以看到其构建细节基于python:3.12-slim镜像先复制 requirements.txt 安装依赖利用 Docker 层缓存再复制server.py与tools/目录EXPOSE 5000并默认执行python server.py。核心依赖包括mcp1.11.0、httpx、starlette、uvicorn[standard]、fastapi、click与python-dotenv。2. 鉴权机制从请求头到请求上下文Asana 要求 OAuth 鉴权这也是 README 中强调使用KLAVIS_API_KEY的原因。仓库在 _oauth_support/README.md 中完整描述了托管镜像的 OAuth 包装层架构容器启动时由entrypoint_wrapper.sh调用oauth_acquire.sh向 Klavis API 请求创建 OAuth 实例并向用户展示授权 URL用户完成浏览器授权后脚本轮询状态最终把凭证写入AUTH_DATA环境变量再启动原始 MCP Server。相关环境变量约定如下环境变量作用KLAVIS_API_KEYOAuth 流程所需的 Klavis API KeyOAuth 模式必填AUTH_DATAOAuth 鉴权数据JSON 字符串由脚本设置后供 MCP Server 使用SKIP_OAUTH置为true时完全跳过 OAuth 层直连启动在 Server 侧凭证的读取逻辑集中在 server.py 的 extract_access_token 函数中其优先级为优先读取环境变量AUTH_DATA若不存在则从请求的x-auth-data头中提取Base64 解码后为 JSON 字符串该逻辑同时兼容 SSE 请求对象与 StreamableHTTP 的 scope 字典两种入参形态将 JSON 解析后取出access_token字段解析失败时记录警告并返回空字符串。每收到一个请求Server 都会把提取到的 token 存入 tools/base.py 中定义的ContextVarauth_token_context并在请求结束于finally块中重置见 server.py 的 handle_sse 与 handle_streamable_http。业务工具通过 get_asana_client() 从该上下文中读取 token 构造AsanaClient上下文缺失时会抛出RuntimeError。这种基于ContextVar的设计使单个容器实例可以按请求携带不同用户的凭证是多租户托管场景的关键。3. 全部 20 个 MCP 工具一览server.py 的 list_tools 定义 声明了 20 个工具覆盖 README 中列出的任务管理、项目操作、团队协作与标签对应 Custom Fields 场景等能力。每个工具都带有category注解如ASANA_TASK只读工具额外标注readOnlyHint: true。3.1 任务工具7 个工具必填参数主要可选参数说明asana_create_taskname,workspace_idstart_date/due_dateYYYY-MM-DD、description、parent_task_id、projectID 或名称、assignee_id默认me、tags名称或 ID 列表创建任务描述要求先调用asana_get_workspaces获取 workspace_idasana_get_tasktask_idmax_subtasks0–100默认 1000 时附带子任务按 ID 查询任务asana_search_tasksworkspace_idkeywords、assignee_id、project、team_id、tags、due_on/due_on_or_after/due_on_or_before、start_on/start_on_or_after/start_on_or_before、completed、limit1–100默认 100、sort_bycreated_at/modified_at/due_date默认modified_at、sort_order默认descending工作区内全文搜索任务asana_update_tasktask_idname、completed、start_date、due_date、description、assignee_id部分更新任务asana_mark_task_completedtask_id—将任务标记为完成asana_get_subtaskstask_idlimit1–100、next_page_token分页获取子任务asana_attach_file_to_tasktask_id,file_namefile_content_str文本、file_content_base64二进制、file_content_url外链、file_encoding默认 utf-8三者提供其一即可挂载附件3.2 项目工具3 个工具必填参数主要可选参数说明asana_get_projectsworkspace_idteam_id、limit、next_page_token、filtercreated_at/modified_at的gt/gte/lt/lte时间戳条件列出项目支持时间戳过滤asana_get_projectproject_id—按 ID 查询项目asana_get_project_tasksproject_idcompleted_sinceISO 8601 或关键字now、limit、next_page_token获取项目任务源码注释明确该端点免费可用search_tasks需要 Asana Premium按项目内优先级排序3.3 工作区、用户、团队与标签工具10 个asana_get_workspaces/asana_get_workspace工作区列表与单查前者是唯一无必填参数的工具是多数操作的前置入口asana_get_users/asana_get_user按工作区列用户与按 ID 查用户asana_get_teams/asana_get_team/asana_get_user_teams工作区团队、单个团队、当前用户所属团队/users/me/teamsasana_get_tags/asana_get_tag标签列表与单查asana_create_tag创建标签color支持 TagColor 枚举 中的 18 个取值dark-pink、light-blue等。所有列表类工具均支持limit1–100默认 100与next_page_token分页返回统一的{items, count, next_page}结构。4. 核心工具的源码级实现细节4.1 创建任务的智能解析workspace、项目与标签create_task 的实现远不止一次POST /tasks。它先调用 handle_new_task_associations 完成三项解析项目名 → 项目 IDproject参数既接受纯数字 ID也接受项目名称。名称会被 get_project_by_name_or_raise_error 解析后者借助 find_projects_by_name 遍历各工作区的项目最多扫描 MAX_PROJECTS_TO_SCAN_BY_NAME 1000 个做大小写不敏感的名称匹配匹配到多个同名项目时抛出可重试错误并把候选项目列表回传给模型workspace 兜底若父任务、项目、workspace 均未提供则调用 get_unique_workspace_id_or_raise_error——用户只有一个工作区时自动使用多个则抛出RetryableToolError并附带可选工作区清单引导模型补参仅给父任务 ID 时通过GET /tasks/{id}?opt_fieldsworkspace反查其所属工作区。随后 handle_new_task_tags 处理tags参数数字直接作为 tag ID名称则走find_tags_by_name查找找不到的标签会被自动创建后取其 ID。最终通过remove_none_values过滤空值后提交POST /tasks。这套「名称优先 自动解析/自动创建」的设计使 LLM 无需精确 ID 即可完成创建显著降低了多轮对话成本。4.2 任务搜索查询参数映射与日期校验search_tasks 将 MCP 工具参数映射到 Asana 搜索 API 的查询串keywords → text、assignee_id → assignee.any、project → projects.any、team_id → team.any、tags → tags.any日期区间映射为due_on.after/due_on.before/start_on.after/start_on.before见 build_task_search_query_params 与 add_task_search_date_params。所有日期参数都会经过 validate_date_format 的YYYY-MM-DD严格校验。sort_by/sort_order的字符串到 TaskSortBy/SortOrder 枚举的转换发生在 server.py 的 call_tool 分发层并带有兜底默认值modified_atdescending。4.3 项目时间戳过滤的客户端实现asana_get_projects的filter参数在 Asana API 层没有对应端点参数因此 list_projects 采用了客户端过滤方案带 filter 时把抓取量放大为min(100, limit * 3)拉取后用 filter_projects_by_timestamps 依据gt/gte/lt/lte条件逐项判断时间戳解析见 parse_timestamp兼容Z后缀与无时区输入过滤后再截断到limit由于放大抓取无法保证过滤后的结果完整覆盖所有页源码在返回中将next_page置为None并注释说明「过滤时分页是复杂的」。另外源码注释特别提醒大域名下建议传team_id过滤以避免超时引用了 Asana 官方建议。4.4 标签创建的长度约束与颜色枚举create_tag 在提交前校验标签名长度必须为 1–100 字符workspace_id缺省时同样走唯一工作区兜底颜色字符串在分发层被映射为 TagColor 枚举后以color.value提交。5. 底层 HTTP 客户端限流、规范化与错误语义所有工具共享 tools/base.py 中的AsanaClient数据类定义 L321-L473它封装了GET/POST/PUT三个方法关键设计如下API 基址与版本ASANA_BASE_URL https://app.asana.com/api、ASANA_API_VERSION 1.0URL 由 _build_url 拼接并发限流通过asyncio.Semaphore限制并发请求数默认 ASANA_MAX_CONCURRENT_REQUESTS 3可用同名环境变量覆盖非法值回退为 3ASANA_MAX_TIMEOUT_SECONDS默认 20 秒constants.py L12-L15响应规范化normalizeAsana 原始返回字段名gid、notes、due_on等对 LLM 不够直观。clean_asana_response 装饰器 递归把gid改写为id随后各实体经 TASK_RULES、PROJECT_RULES 等映射规则转换为驼峰命名的精简结构如isCompleted、dueDate、assignee: {id, name}并剔除所有None字段。请求字段列表由 constants.py 中的 TASK_OPT_FIELDS / PROJECT_OPT_FIELDS 等 常量集中声明其中TASK_OPT_FIELDS_BASIC专门剔除了需要额外 OAuth scope如custom_type相关的字段供免费端点get_project_tasks使用——这解释了 projects.py 中该工具选用 BASIC 字段集 的原因错误分层_raise_for_status会把 Asana 的错误体errors[].message/help解析为面向模型的error_message与带 HTTP 状态码的developer_message抛出AsanaToolExecutionError另有RetryableToolError携带retry_after_ms与additional_prompt_content例如可选工作区/项目清单。server.py 的统一异常处理 将这些结构化错误以 JSON 文本返回给调用方使 Agent 能基于「可重试 补充信息」自主修正参数后重试而不是直接失败。6. HTTP 协议层SSE 与 StreamableHTTP 双传输server.py 使用mcpSDK 的低层Server构建应用并通过 Starlette 暴露双传输端点路由定义 L911-L922端点传输说明GET /ssePOST /messages/SSE传统 Server-Sent Events 通道POST /mcpStreamableHTTP无状态statelessTrue、event_storeNone会话管理启动参数由 click 提供main 函数 L72-L89--port默认取环境变量ASANA_MCP_SERVER_PORT缺省 5000与 Dockerfile 的EXPOSE 5000对应、--log-level默认 INFO、--json-responseStreamableHTTP 返回 JSON 而非 SSE 流。服务通过 uvicorn 绑定0.0.0.0启动因此容器内端口 5000 对外可达MCP 客户端可按所选传输分别连接http://host:5000/sse或http://host:5000/mcp。7. 实战建议结合工具描述中的强约束You MUST callasana_get_workspacesfirst推荐 Agent 按以下顺序组织调用asana_get_workspaces获取workspace_id唯一 workspace 时多数工具可省略该参数源码会自动兜底用asana_get_users/asana_get_teams/asana_get_tags建立 ID 与名称的对照列表与取数优先asana_get_projects→asana_get_project_tasks免费端点跨项目语义检索再使用asana_search_tasks需 Asana Premium写入操作使用asana_create_task/asana_update_task时优先传名称而非 ID——项目与标签的自动解析、自动创建逻辑tasks.py L110-L226会代为消解歧义遇多工作区/多同名项目场景工具会返回候选清单的RetryableToolError按additional_prompt_content补参重试即可。相关延伸阅读仓库整体贡献与许可见 CONTRIBUTING.md 与 LICENSE其他服务的 MCP 实现可参考 mcp_servers/ 目录OAuth 包装层的完整机制见 _oauth_support/README.md。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Klavis Asana MCP Server 详解：20 个工具让 AI Agent 管理 Asana 任务、项目与团队协作
Klavis Asana MCP Server 详解20 个工具让 AI Agent 管理 Asana 任务、项目与团队协作【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文基于开源仓库中的 mcp_servers/asana/README.md 及其完整源码讲解 Klavis Asana MCP Server 的部署方式托管与 Docker 自托管、双模式鉴权机制、全部 20 个 MCP 工具的参数与实现细节以及底层 HTTP 客户端的限流、响应规范化与错误处理设计。读完后你将能够将该服务接入任意支持 MCP 的 AI 应用并理解其每个工具背后的 Asana API 调用链路。1. 服务定位与快速启动Asana MCP Server 是一个基于 Model Context ProtocolMCP实现的 Asana 集成服务器通过 Asana 官方 API 让 AI Agent 管理任务、项目、团队与标签并支持 OAuth 鉴权。源码位于 mcp_servers/asana/ 目录由 server.py 作为入口、tools/ 包实现各业务工具构成。1.1 托管服务方式Klavis 平台README 推荐的生产方式是使用 Klavis 托管基础设施无需自行搭建pip install klavis # or npm install klavisfrom klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(ASANA, user123)即通过 Klavis SDK 创建 API Key 后以ASANA作为服务标识创建一个 server 实例第二个参数为用户标识即可在 AI 应用中直接调用 Asana 工具OAuth 流程由托管平台代管。1.2 Docker 自托管方式自托管拉取官方镜像即可运行# Pull latest image docker pull ghcr.io/klavis-ai/asana-mcp-server:latest # Run Asana MCP Server with OAuth Support through Klavis AI docker run -p 5000:5000 -e KLAVIS_API_KEY$KLAVIS_API_KEY \ ghcr.io/klavis-ai/asana-mcp-server:latest # Run Asana MCP Server (no OAuth support) docker run -p 5000:5000 -e AUTH_DATA{access_token:your_asana_api_key_here} \ ghcr.io/klavis-ai/asana-mcp-server:latest两种启动模式的区别OAuth 模式传入KLAVIS_API_KEY环境变量由 OAuth 层自动完成 Asana 授权流程直连模式通过AUTH_DATA环境变量直接注入 JSON 格式的凭证{access_token: ...}跳过 OAuth。结合 Dockerfile 可以看到其构建细节基于python:3.12-slim镜像先复制 requirements.txt 安装依赖利用 Docker 层缓存再复制server.py与tools/目录EXPOSE 5000并默认执行python server.py。核心依赖包括mcp1.11.0、httpx、starlette、uvicorn[standard]、fastapi、click与python-dotenv。2. 鉴权机制从请求头到请求上下文Asana 要求 OAuth 鉴权这也是 README 中强调使用KLAVIS_API_KEY的原因。仓库在 _oauth_support/README.md 中完整描述了托管镜像的 OAuth 包装层架构容器启动时由entrypoint_wrapper.sh调用oauth_acquire.sh向 Klavis API 请求创建 OAuth 实例并向用户展示授权 URL用户完成浏览器授权后脚本轮询状态最终把凭证写入AUTH_DATA环境变量再启动原始 MCP Server。相关环境变量约定如下环境变量作用KLAVIS_API_KEYOAuth 流程所需的 Klavis API KeyOAuth 模式必填AUTH_DATAOAuth 鉴权数据JSON 字符串由脚本设置后供 MCP Server 使用SKIP_OAUTH置为true时完全跳过 OAuth 层直连启动在 Server 侧凭证的读取逻辑集中在 server.py 的 extract_access_token 函数中其优先级为优先读取环境变量AUTH_DATA若不存在则从请求的x-auth-data头中提取Base64 解码后为 JSON 字符串该逻辑同时兼容 SSE 请求对象与 StreamableHTTP 的 scope 字典两种入参形态将 JSON 解析后取出access_token字段解析失败时记录警告并返回空字符串。每收到一个请求Server 都会把提取到的 token 存入 tools/base.py 中定义的ContextVarauth_token_context并在请求结束于finally块中重置见 server.py 的 handle_sse 与 handle_streamable_http。业务工具通过 get_asana_client() 从该上下文中读取 token 构造AsanaClient上下文缺失时会抛出RuntimeError。这种基于ContextVar的设计使单个容器实例可以按请求携带不同用户的凭证是多租户托管场景的关键。3. 全部 20 个 MCP 工具一览server.py 的 list_tools 定义 声明了 20 个工具覆盖 README 中列出的任务管理、项目操作、团队协作与标签对应 Custom Fields 场景等能力。每个工具都带有category注解如ASANA_TASK只读工具额外标注readOnlyHint: true。3.1 任务工具7 个工具必填参数主要可选参数说明asana_create_taskname,workspace_idstart_date/due_dateYYYY-MM-DD、description、parent_task_id、projectID 或名称、assignee_id默认me、tags名称或 ID 列表创建任务描述要求先调用asana_get_workspaces获取 workspace_idasana_get_tasktask_idmax_subtasks0–100默认 1000 时附带子任务按 ID 查询任务asana_search_tasksworkspace_idkeywords、assignee_id、project、team_id、tags、due_on/due_on_or_after/due_on_or_before、start_on/start_on_or_after/start_on_or_before、completed、limit1–100默认 100、sort_bycreated_at/modified_at/due_date默认modified_at、sort_order默认descending工作区内全文搜索任务asana_update_tasktask_idname、completed、start_date、due_date、description、assignee_id部分更新任务asana_mark_task_completedtask_id—将任务标记为完成asana_get_subtaskstask_idlimit1–100、next_page_token分页获取子任务asana_attach_file_to_tasktask_id,file_namefile_content_str文本、file_content_base64二进制、file_content_url外链、file_encoding默认 utf-8三者提供其一即可挂载附件3.2 项目工具3 个工具必填参数主要可选参数说明asana_get_projectsworkspace_idteam_id、limit、next_page_token、filtercreated_at/modified_at的gt/gte/lt/lte时间戳条件列出项目支持时间戳过滤asana_get_projectproject_id—按 ID 查询项目asana_get_project_tasksproject_idcompleted_sinceISO 8601 或关键字now、limit、next_page_token获取项目任务源码注释明确该端点免费可用search_tasks需要 Asana Premium按项目内优先级排序3.3 工作区、用户、团队与标签工具10 个asana_get_workspaces/asana_get_workspace工作区列表与单查前者是唯一无必填参数的工具是多数操作的前置入口asana_get_users/asana_get_user按工作区列用户与按 ID 查用户asana_get_teams/asana_get_team/asana_get_user_teams工作区团队、单个团队、当前用户所属团队/users/me/teamsasana_get_tags/asana_get_tag标签列表与单查asana_create_tag创建标签color支持 TagColor 枚举 中的 18 个取值dark-pink、light-blue等。所有列表类工具均支持limit1–100默认 100与next_page_token分页返回统一的{items, count, next_page}结构。4. 核心工具的源码级实现细节4.1 创建任务的智能解析workspace、项目与标签create_task 的实现远不止一次POST /tasks。它先调用 handle_new_task_associations 完成三项解析项目名 → 项目 IDproject参数既接受纯数字 ID也接受项目名称。名称会被 get_project_by_name_or_raise_error 解析后者借助 find_projects_by_name 遍历各工作区的项目最多扫描 MAX_PROJECTS_TO_SCAN_BY_NAME 1000 个做大小写不敏感的名称匹配匹配到多个同名项目时抛出可重试错误并把候选项目列表回传给模型workspace 兜底若父任务、项目、workspace 均未提供则调用 get_unique_workspace_id_or_raise_error——用户只有一个工作区时自动使用多个则抛出RetryableToolError并附带可选工作区清单引导模型补参仅给父任务 ID 时通过GET /tasks/{id}?opt_fieldsworkspace反查其所属工作区。随后 handle_new_task_tags 处理tags参数数字直接作为 tag ID名称则走find_tags_by_name查找找不到的标签会被自动创建后取其 ID。最终通过remove_none_values过滤空值后提交POST /tasks。这套「名称优先 自动解析/自动创建」的设计使 LLM 无需精确 ID 即可完成创建显著降低了多轮对话成本。4.2 任务搜索查询参数映射与日期校验search_tasks 将 MCP 工具参数映射到 Asana 搜索 API 的查询串keywords → text、assignee_id → assignee.any、project → projects.any、team_id → team.any、tags → tags.any日期区间映射为due_on.after/due_on.before/start_on.after/start_on.before见 build_task_search_query_params 与 add_task_search_date_params。所有日期参数都会经过 validate_date_format 的YYYY-MM-DD严格校验。sort_by/sort_order的字符串到 TaskSortBy/SortOrder 枚举的转换发生在 server.py 的 call_tool 分发层并带有兜底默认值modified_atdescending。4.3 项目时间戳过滤的客户端实现asana_get_projects的filter参数在 Asana API 层没有对应端点参数因此 list_projects 采用了客户端过滤方案带 filter 时把抓取量放大为min(100, limit * 3)拉取后用 filter_projects_by_timestamps 依据gt/gte/lt/lte条件逐项判断时间戳解析见 parse_timestamp兼容Z后缀与无时区输入过滤后再截断到limit由于放大抓取无法保证过滤后的结果完整覆盖所有页源码在返回中将next_page置为None并注释说明「过滤时分页是复杂的」。另外源码注释特别提醒大域名下建议传team_id过滤以避免超时引用了 Asana 官方建议。4.4 标签创建的长度约束与颜色枚举create_tag 在提交前校验标签名长度必须为 1–100 字符workspace_id缺省时同样走唯一工作区兜底颜色字符串在分发层被映射为 TagColor 枚举后以color.value提交。5. 底层 HTTP 客户端限流、规范化与错误语义所有工具共享 tools/base.py 中的AsanaClient数据类定义 L321-L473它封装了GET/POST/PUT三个方法关键设计如下API 基址与版本ASANA_BASE_URL https://app.asana.com/api、ASANA_API_VERSION 1.0URL 由 _build_url 拼接并发限流通过asyncio.Semaphore限制并发请求数默认 ASANA_MAX_CONCURRENT_REQUESTS 3可用同名环境变量覆盖非法值回退为 3ASANA_MAX_TIMEOUT_SECONDS默认 20 秒constants.py L12-L15响应规范化normalizeAsana 原始返回字段名gid、notes、due_on等对 LLM 不够直观。clean_asana_response 装饰器 递归把gid改写为id随后各实体经 TASK_RULES、PROJECT_RULES 等映射规则转换为驼峰命名的精简结构如isCompleted、dueDate、assignee: {id, name}并剔除所有None字段。请求字段列表由 constants.py 中的 TASK_OPT_FIELDS / PROJECT_OPT_FIELDS 等 常量集中声明其中TASK_OPT_FIELDS_BASIC专门剔除了需要额外 OAuth scope如custom_type相关的字段供免费端点get_project_tasks使用——这解释了 projects.py 中该工具选用 BASIC 字段集 的原因错误分层_raise_for_status会把 Asana 的错误体errors[].message/help解析为面向模型的error_message与带 HTTP 状态码的developer_message抛出AsanaToolExecutionError另有RetryableToolError携带retry_after_ms与additional_prompt_content例如可选工作区/项目清单。server.py 的统一异常处理 将这些结构化错误以 JSON 文本返回给调用方使 Agent 能基于「可重试 补充信息」自主修正参数后重试而不是直接失败。6. HTTP 协议层SSE 与 StreamableHTTP 双传输server.py 使用mcpSDK 的低层Server构建应用并通过 Starlette 暴露双传输端点路由定义 L911-L922端点传输说明GET /ssePOST /messages/SSE传统 Server-Sent Events 通道POST /mcpStreamableHTTP无状态statelessTrue、event_storeNone会话管理启动参数由 click 提供main 函数 L72-L89--port默认取环境变量ASANA_MCP_SERVER_PORT缺省 5000与 Dockerfile 的EXPOSE 5000对应、--log-level默认 INFO、--json-responseStreamableHTTP 返回 JSON 而非 SSE 流。服务通过 uvicorn 绑定0.0.0.0启动因此容器内端口 5000 对外可达MCP 客户端可按所选传输分别连接http://host:5000/sse或http://host:5000/mcp。7. 实战建议结合工具描述中的强约束You MUST callasana_get_workspacesfirst推荐 Agent 按以下顺序组织调用asana_get_workspaces获取workspace_id唯一 workspace 时多数工具可省略该参数源码会自动兜底用asana_get_users/asana_get_teams/asana_get_tags建立 ID 与名称的对照列表与取数优先asana_get_projects→asana_get_project_tasks免费端点跨项目语义检索再使用asana_search_tasks需 Asana Premium写入操作使用asana_create_task/asana_update_task时优先传名称而非 ID——项目与标签的自动解析、自动创建逻辑tasks.py L110-L226会代为消解歧义遇多工作区/多同名项目场景工具会返回候选清单的RetryableToolError按additional_prompt_content补参重试即可。相关延伸阅读仓库整体贡献与许可见 CONTRIBUTING.md 与 LICENSE其他服务的 MCP 实现可参考 mcp_servers/ 目录OAuth 包装层的完整机制见 _oauth_support/README.md。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
