diff --git a/server/mcp_server_vefaas_function/README.md b/server/mcp_server_vefaas_function/README.md index 2b030ca..f15c401 100644 --- a/server/mcp_server_vefaas_function/README.md +++ b/server/mcp_server_vefaas_function/README.md @@ -1,76 +1,10 @@ # veFaaS MCP Server -veFaaS MCP Server 提供创建、更新、发布函数和添加触发器的能力。 +veFaaS MCP Server 提供创建、更新、发布 veFaaS 函数以及管理应用的自动化能力，帮助在 MCP 体系内快速对接 veFaaS 服务。 -| | | -|------|------| -| 描述 | veFaaS MCP Server 助你轻松管理函数和触发器生命周期| -| 分类 | 容器与中间件 | -| 标签 | FaaS，函数服务，函数，生命周期 | +## 安装与快速开始 -## 能力概览 - -- 创建/更新/发布 veFaaS 函数，并管理依赖安装与触发器配置。 -- 支持上传本地代码或通过已有制品（TOS、镜像）更新函数。 -- 覆盖 API 网关触发器和函数列表/存在性查询等补充能力。 - -最新的参数、调用约束和注意事项都写在 `src/mcp_server_vefaas_function/vefaas_server.py` 的工具描述中，优先以代码为准。 - -## 推荐流程 - -1. `create_function` 创建函数（或确认已有函数 ID）。 -2. `upload_code` 推送代码，必要时排除 `.venv`、`node_modules` 等本地依赖。 -3. 如果触发了依赖安装任务，使用 `get_dependency_install_task_status` 轮询直至 `Succeeded/Failed`。 -4. 重新发布：`release_function`，随后持续调用 `get_function_release_status` 直到成功或失败。 -5. 发布成功后，再创建 API 网关触发器或其它下游资源。 - -## 支持的运行时 - -- `native-python3.12/v1` -- `native-node20/v1` -- `native/v1` - -以上运行时均为原生环境，仅提供解释器/运行时，不包含任何 Web 框架或额外工具。请把依赖声明在 `requirements.txt` / `package.json` 中，由 veFaaS 自动安装。 - -## 常见注意事项 - -- 本地修改完成后务必重新执行 `upload_code`；直接调用 `release_function` 只会复用旧制品。 -- 依赖安装长时间 `InProgress` 时，遵循工具描述中的退避策略并及时上报。 -- API 网关相关操作在创建触发器前应复用现有关联服务，避免重复创建。 - -## 可适配平台 - -streamable-http: 方舟，Python -stdio: Python, Cursor, Claude macOS App, Cline - -## 服务开通链接 (整体产品) - - - -## 鉴权方式 - -OAuth 2.0 - -## 在不同平台的配置 - -### 方舟 - -#### 体验中心 - -1. 查看 MCP Server 详情 -在大模型生态广场，选择合适的 veFaaS MCP Server，并查看详情 -2. 选择 MCP Server 即将运行的平台 -检查当前 MCP Server 已适配的平台，并选择合适的平台 -3. 查看并对比可用的 Tools -仔细查看可用的 Tools 的功能描述与所需的输入参数，并尝试运行对应的功能。 -4. 获取专属的URL或代码示例 -检查账号登录状态与服务开通情况，生成唯一URL -5. 去对应的Client的平台进行使用 -点击快捷跳转按钮，前往方舟平台的体验中心进行对应MCP Server的体验 - -### UVX - -请预先获取环境变量 VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY。 +推荐使用 `uvx` 在本地快速拉起服务，请将 VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY 内容替换为您账号的 AK/SK。 ```json { @@ -91,6 +25,33 @@ OAuth 2.0 } ``` +## 前置条件与注意事项 + +- 凭证管理：AK/SK 为账号敏感信息，请妥善保管，避免泄露。 +- 服务开通：生成公网访问链接依赖 API 网关等前置资源，使用前请确认账号已在控制台开通相关服务。 +- 代码包与运行时：编译型语言需先在本地生成 Linux 可执行文件；解释型语言需提供启动脚本和依赖声明文件（`requirements.txt` / `package.json`）以便平台自动安装依赖。 +- 模型与 Agent 效果：MCP 的执行效果受所选模型和 Agent 策略影响，若结果不理想，可补充上下文、调整提示词或切换模型/Agent。 + +## 能力概览 + +- 函数生命周期：创建、更新、发布、删除 veFaaS 函数，支持本地代码包、TOS 制品或镜像等多种来源。 +- 代码与依赖：上传代码、触发依赖安装任务、轮询安装状态，并可下载线上代码。 +- 运行时与配置：管理命令、环境变量、VPC 配置等基础属性。 +- 应用与访问：查询可用的 API 网关资源，创建并发布 veFaaS 应用，检索模板信息。 + +## 支持的运行时 + +- `native-python3.12/v1` +- `native-node20/v1` +- `native/v1` + +以上运行时均为原生环境，仅提供解释器/运行时，不包含额外框架或工具。 + +## 官方资源 + +- veFaaS 控制台： +- veFaaS MCP 操作文档： + ## License volcengine/mcp-server is licensed under the MIT License. diff --git a/server/mcp_server_vefaas_function/src/mcp_server_vefaas_function/vefaas_server.py b/server/mcp_server_vefaas_function/src/mcp_server_vefaas_function/vefaas_server.py index e226b9e..91457f4 100644 --- a/server/mcp_server_vefaas_function/src/mcp_server_vefaas_function/vefaas_server.py +++ b/server/mcp_server_vefaas_function/src/mcp_server_vefaas_function/vefaas_server.py @@ -77,8 +77,6 @@ def validate_and_set_region(region: str = None) -> str: Note: - veFaaS Application is the top-level collection that contains veFaaS function, api-gateway and other production. - - After all steps done, provide veFaaS Application infos like application_id, name, region and platform link if these info can get from context directly. - - veFaaS platform link template: https://console.volcengine.com/vefaas/region:vefaas+`region`/application/detail/`application_id`?tab=detail Error Handle Tips: - If there is **any authentication** error about vefaas application(create/release/get), let user apply auth by link: https://console.volcengine.com/iam/service/attach_custom_role?ServiceName=vefaas&policy1_1=APIGFullAccess&policy1_2=VeFaaSFullAccess&role1=ServerlessApplicationRole, then retry. @@ -87,10 +85,10 @@ def validate_and_set_region(region: str = None) -> str: - This tool **CAN ONLY** be called if `create_function` tool be called in previous step. - If user want to create a veFaaS Application, **MUST** follow the steps: 1. Use `list_vefaas_application_templates` to get all available templates. - 2. Find most suitable template from all the templates and use `get_application_template_detail` to get template code. + 2. Find most suitable template from all the templates and use `get_application_template_detail` to get template code. If no related template found, no need to use template. 3. Create/Release vefaas function. 4. Create/Release vefaas application. -- MUST EDIT vefaas.yml: Add application_id to `vefaas.yml` immediately after application created successfully. +- MUST EDIT vefaas.yml after application created successfully: Add application_id to `vefaas.yml` immediately after application created successfully. """) def create_vefaas_application(function_id: Required[str], function_name: Required[str], gateway_name: Required[str], region: Optional[str] = None): @@ -234,6 +232,7 @@ def get_vefaas_application(application_id: Required[str], region: Optional[str] Note: - veFaaS Application status **NOT** related to veFaaS function release status. - Usually use this tool to check application deployment status after application release. + - **MUST** provide some important info for user after application deployment finished: application_id, region, deployment status, access_url and app_platform_url. (can get these info from tool return value) """) def poll_vefaas_application_status(application_id: Required[str], region: Optional[str] = None): @@ -291,13 +290,23 @@ def poll_vefaas_application_status(application_id: Required[str], region: Option errLogs.append("Failed to release application due to an authentication error. Please visit https://console.volcengine.com/iam/service/attach_custom_role?ServiceName=vefaas&policy1_1=APIGFullAccess&policy1_2=VeFaaSFullAccess&role1=ServerlessApplicationRole to grant the required permissions and then try again.") except Exception as e: logger.error(f"Failed to get application log: {str(e)}") - + + # get system_url + system_url = "" + try: + cloud_resource = json.loads(result["CloudResource"]) + system_url = cloud_resource['framework']['url']['system_url'] + except Exception as e: + logger.error(f"Failed to get system_url: {str(e)}") + responseInfo = { "Id": result["Id"], "Name": result["Name"], "Status": result["Status"], "Config": result["Config"], "Region": result["Region"], + "AccessUrl": system_url, + "AppPlatformUrl": f"https://console.volcengine.com/vefaas/region:vefaas+{region}/application/detail/{application_id}?tab=detail", "NewRevisionNumber": result.get("NewRevisionNumber"), } if len(errLogs) > 0: @@ -319,10 +328,6 @@ def poll_vefaas_application_status(application_id: Required[str], region: Option - command **MUST** be a runnable script, e.g., `./run.sh`. - region **MUST** be `cn-beijing`, `cn-shanghai`, `cn-guangzhou`, or `ap-southeast-1`. - Supplying `enable_vpc=true` requires `vpc_id`, `subnet_ids`, and `security_group_ids`. - - Declare every framework/server dependency in `requirements.txt` / `package.json`; do not bundle virtualenvs. - - Module CLIs are not on PATH. Invoke them with `python -m module_name ...` or start the server in code—running `gunicorn ...` or `uvicorn ...` directly will fail. - - Keep startup scripts focused on launching the app; skip extra installs/build once `upload_code` has run. - - Store templates/static assets as files and sanity-check imports before uploading. - After all steps done, provide veFaaS function infos like function_id, name, region, runtime and platfrom link if these infos can get from context directly. - veFaaS platform link template: https://console.volcengine.com/vefaas/region:vefaas+`region`/function/detail/`function_id`?tab=config @@ -614,6 +619,8 @@ def get_function_release_status(function_id: str, region: str = None): **CRITICAL REQUIREMENT**: - Can **only** use this tool to check vefaas function release status, **NEVER** try to get release status by other ways. + - After function release finished, provide some important info for user: function_id, region, release status, and vefaas function platform url. + - `vefaas function platform url` is `https://console.volcengine.com/vefaas/function/detail?functionId={function_id}®ion={region}` """) def poll_function_release_status(function_id: str, region: str = None): region = validate_and_set_region(region) @@ -631,6 +638,7 @@ def poll_function_release_status(function_id: str, region: str = None): time.sleep(interval) else: return response + return response def generate_random_name(prefix="mcp", length=8): @@ -691,7 +699,7 @@ def list_existing_api_gateways(region: str = None): if gateway.get("Region") == region and gateway.get("Status") in ["Running", "Creating"]: result.append({ "Name": gateway.get("Name", ""), - "ID": gateway.get("ID", ""), + "ID": gateway.get("Id", ""), "Region": gateway.get("Region", ""), "Type": gateway.get("Type", ""), "Status": gateway.get("Status", ""), @@ -746,7 +754,7 @@ def create_api_gateway(name: str = None, region: str = "cn-beijing"): Note: - Use this tool to select one running api gateway for create veFaaS Application. - If no running gateway exists, will create a new one and wait for it to be running. - - If can this tool can not fetch a running gateway after timeout, please retry and at most try 3 times. + - If can this tool returned error, should retry and at most retry 3 times. """) def fetch_running_api_gateway(region: str = None): @@ -784,9 +792,9 @@ def fetch_running_api_gateway(region: str = None): raise Exception(f"Failed to create API Gateway after {create_api_gateway_failed_times} times") time.sleep(interval) except Exception as e: - return f"Failed to fetch an running API Gateway: {str(e)}" + raise Exception(f"Failed to fetch an running API Gateway: {str(e)}") - return f"Failed to fetch an running API Gateway after {timeout} seconds" + raise Exception(f"Failed to fetch an running API Gateway after {timeout} seconds") def ensure_executable_permissions(folder_path: str): for root, _, files in os.walk(folder_path): @@ -922,7 +930,11 @@ def _get_upload_code_description() -> str: " - Rule 4: Python/Node deps: put them in 'requirements.txt'/'package.json'; veFaaS installs them as needed.\n" " - Rule 5: HTTP server **MUST** listen on IP: 0.0.0.0, PORT: 8000.\n" " - Rule 6: Store templates/static assets as files and sanity-check imports before uploading.\n" - " - Rule 7: When uploading code, exclude local deps and noise (e.g., `.venv`, `site-packages`, `node_modules`, `.git`, build artifacts) via `local_folder_exclude`.\n\n" + " - Rule 7: Declare every framework/server dependency in `requirements.txt` / `package.json`; do not bundle virtualenvs.\n" + " - Rule 8: Module CLIs are not on PATH. Invoke them with `python -m module_name ...` or start the server in code—running `gunicorn ...` or `uvicorn ...` directly will fail.\n" + " - Rule 9: Keep startup scripts focused on launching the app; skip extra installs/build once `upload_code` has run.\n" + " - Rule 10: Store templates/static assets as files and sanity-check imports before uploading.\n" + " - Rule 11: When uploading code, exclude local deps and noise (e.g., `.venv`, `site-packages`, `node_modules`, `.git`, build artifacts) via `local_folder_exclude`.\n\n" ) # Detect run mode via FASTMCP_* environment variables.