@numa-tech/numa 1.20.0 → 1.20.2

package/docs/application-default-groups.md

@@ -0,0 +1,73 @@
+# 应用默认组与 CLI
+
+这些命令需要部署支持应用受管组 API 的 DevOps 后端；安装旧 CLI 或旧后端不会自动具备该能力。不会修改 Keycloak realm 的 Default roles / Default groups。
+
+## 普通用户
+
+```sh
+numa login --no-console --no-config
+numa authorization enrollment status --json
+```
+
+用户完成 `numa login`、本地网页控制台登录或 MCP `numa_auth_complete_login` 并保存本机会话后，会显式调用 `POST /api/v1/me/enrollment`。服务端根据可信登录 Client 的默认组策略同步成员。机器身份不参加人员自动入组；组黑名单以及历史 SUSPENDED / REVOKED 限制不会因登录被重新激活。登录过程固定使用发起时的配置，核对回调和当前会话 subject，不把其他登录 Client 或服务的缓存当作本次身份。
+
+`numa auth status`、profile、命令列表和 `authorization enrollment status` 不触发入组。已有会话可显式初始化，不必人工查询 subject：
+
+```sh
+numa authorization enrollment initialize --json
+```
+
+登录成功和默认组同步是不同结果。同步失败/未知/待处理不会伪报已授权；黑名单显示 BLOCKED，策略未启用显示 DISABLED。组同步完成后，按服务端 `tokenRefreshRequired` 最多强制刷新本会话一次，再通过 GET enrollment 只读回读。只在 Client、组、策略版本一致，且服务端确认当前令牌已满足角色要求时返回 READY。新后端提供 `expectedClientRoles` 时还按精确 Client 校验动态角色；兼容旧后端回读契约，不依赖三个固定角色。
+
+默认组角色由平台管理，不预设为 Notion、Skills、OSS 三个名称。READY 只证明入组及当前会话核验完成，不证明每项业务均有权限；仍需要有效 API 角色功能授权、Notion 内容 Grant、OSS Grant 和 Skills namespace 策略。CLI 不自动恢复停用角色、给组增加角色或修改空间策略。
+
+## 管理员：应用草稿与统一发布
+
+管理命令统一为 `numa authorization application --app <positive-id>`，要求平台 Client Role `mci-devops-platform-ops-admin`。只读目录不创建用户；没有用户密码或账户管理命令。所有 JSON 输出为 `{ok:true,data:...}`，保留服务端字段和分页事实；分页使用 `--page`、`--size`（1–100）及可用时的 `--query`，不自动抓取全部数据。
+
+生产操作前用 `numa auth status --json` 和 `numa config --show` 确认 PRD。固定生产前端 `https://mci-devops-platform.mcisaas.com`，issuer `https://kc.mcisaas.com/auth/realms/numa-realm`，浏览器 Client `web-client`，CLI Client `mcp-client`，角色 Client `mci-devops-platform`，API `https://apps-gw-prd.mcisaas.com/mci-devops-platform`。应用的 `--env` 选择已登记的精确身份源；不能传任意 issuer URL，也不能借用浏览器会话。
+
+```sh
+numa authorization application --app 42 identity sources --json
+numa authorization application --app 42 definition show --json
+numa authorization application --app 42 definition save --file definition.json --yes --json
+numa authorization application --app 42 definition freeze --expected-draft-version 3 --yes --json
+numa authorization application --app 42 environment list --page 1 --size 20 --json
+numa authorization application --app 42 identity directory users --env <env-uuid> --query name@example.com --json
+numa authorization application --app 42 identity client show <reference-uuid> --env <env-uuid> --json
+numa authorization application --app 42 identity group registered <definition-uuid> --env <env-uuid> --json
+numa authorization application --app 42 identity group blacklist <reference-uuid> --env <env-uuid> --instance <instance-uuid> --json
+numa authorization application --app 42 identity relations save --env <env-uuid> --file relations.json --yes --json
+numa authorization application --app 42 publication plan --file plan.json --yes --json
+numa authorization application --app 42 publication prepare <job-uuid> --expected-version 0 --expected-digest <reviewed-plan-digest> --expected-step-digest <reviewed-step-digest> --yes --json
+numa authorization application --app 42 publication apply <job-uuid> --expected-version 1 --expected-digest <reviewed-plan-digest> --expected-step-digest <reviewed-step-digest> --yes --json
+```
+
+文件只能包含对应 API 字段，不能把 app/env/file/yes 等控制参数塞入 body。定义保存 `{expectedDraftVersion,defaultRoleClientId,definition}`，完整保留 functions、业务授权、PAGE/API 等文档字段。Client/Group create/save 文件要求 mode、environmentId、全部四个 expected*Version 和对应的配置/需求字段；版本 0 表示实体不存在，不能用作忽略冲突。环境 create/update 保存平台配置，create 的 version 必须是 0。
+
+relations 文件为 `{expectedRevision,changes}`。支持 ROLE_GRANT、GROUP_MEMBER、GROUP_BLOCK、BLOCK_SOURCE_RELEASE；USER 使用目录返回的稳定 subjectId，SERVICE_ACCOUNT 使用 clientInstanceId。GROUP_BLOCK ABSENT 仅撤销本应用的阻断贡献。释放历史来源必须独立提交 BLOCK_SOURCE_RELEASE、USER、ABSENT、subjectId、groupInstanceId、releaseSource（ADMIN_BLOCK 或 LEGACY_REMOVE）、expectedBlockVersion 及 scoped blacklist 返回的 expectedBlockGeneration；不会移除其他来源阻断。
+
+LOGIN Client 的 enrollmentTrusted 和 expectedEnrollmentTrustVersion 必须同时填写；这是待发布意图，实际 admission 要等统一发布的激活与验证，不能把草稿当作已生效。共享定义的 configurationReadOnly 与精确 registered hydration 必须遵守，不把目录远端配置自动写回共享定义。
+
+plan 文件为 `{requestId,definitionVersion,environmentIds,clientModes?}`，requestId 是新 UUID，clientModes 按 instance UUID 映射 CREATE/ADOPT/UPDATE/REPAIR。每次 prepare/apply 都只执行一个阶段，确认必须来自同一 reviewed response，不自动拉取新版本接受冲突。UNKNOWN 时显式 recheck，保留协作问题、receipt、历史、allowedActions 和 finalization；需要继续时另行确认 apply。terminate/cancel 不是回滚，repreview 需要新的 requestId，没有 resume/force 命令。
+
+完整命令可通过 `numa authorization application --app 42 --help` 和 `numa commands --json` 查看。registered、versions、history、members、blacklist、catalog、subject-access 均为当前应用/来源限定的只读视图；不使用旧 registry HTTP 路径。网关绑定历史使用 `gateway-binding history <binding-uuid>`，环境历史使用 `environment runs <env-uuid>`。
+
+## 凭证只写入文件
+
+```sh
+numa authorization application --app 42 credential target --env <env-uuid> --reference <ref-uuid> --instance <instance-uuid> --json
+numa authorization application --app 42 credential download --env <env-uuid> --reference <ref-uuid> --instance <instance-uuid> --request-id <new-uuid> --expected-instance-version 3 --expected-context-digest <reviewed-digest> --output ./credential.json --yes --json
+```
+
+rotate 还需完整 `--confirm-client-id` 与 `--acknowledge-impact`。必须显式提供新的 `--output` 文件，拒绝 stdout 和覆盖已有文件；先排他创建 0600 文件，再发送一次请求，只在附件完整落盘后输出 requestId/outputPath。Secret 不进入 JSON、日志或异常。全部写请求包括 recheck 和附件都禁止 401 刷新重放、重定向及自动重试；本地写盘失败也不能重领同一个请求。
+
+轮换 A UNKNOWN 后，使用新请求下载 B 恢复当前凭证，再以新请求进行明确轮换 C；不需要等待 A 父作业 ACK。operation/recheck 仅查事实，不重新领取附件。operationRecovered 仅表示历史恢复证据，不代表当前目标凭证 READY。CREDENTIAL_ROTATION 是单阶段窄作业，与完整 IDENTITY_PUBLICATION 图分别解码。
+
+## 破坏性升级与发布
+
+旧 `authorization role list/create/provision/provisioning-run` 和 `authorization group list/members/users/directory/plan/status/items/impact/apply` 已删除，没有兼容 alias 或旧 HTTP fallback。enrollment、access-request、bootstrap 和独立业务 API 保留。使用既有 lockstep release 流程同时发布工作区包；不能只单独升级一个包。发布前执行 `npm run build` 和 `npm run check`，包括打包边界与编译后 enrollment 烟测。本文不表示已经发布或完成运行时验收。
+
+Skills/MCP 业务新路径为 `/api/v1/skills`；实例管理和 namespace 写操作为 `/api/v1/admin/nacos/registry`。CLI 不在 401/403 或写超时后退回旧路径重发。发布顺序为：后端兼容 alias 和新路径 → 网关方法映射及权限发布 → CLI 包发布。旧 CLI 继续使用后端保留的 `/api/v1/ai-registry` alias；服务 profile 中的显式 capabilityUrl 仍予以兼容。
+
+Codex 模块自己的登录使用独立服务 audience 与 token cache，不把该服务令牌转发给 DevOps enrollment；其应用入组应在该服务的可信登录回调完成。这里的自动入组只使用当前明确的 DevOps API 配置。

package/examples/cloud-bootstrap/README.md

@@ -3,7 +3,7 @@
 发布包入口为 `npx -y @numa-tech/numa@latest`，下文用 `numa` 简写。
 
 ```sh
-numa login --no-console
+numa login --platform --no-console
 numa cloud bootstrap run --account-uid 1960540977999327
 ```
 

package/examples/mcp/README.md

@@ -0,0 +1,108 @@
+# Numa MCP：管理、测试调用与本地代理
+
+使用本仓库构建产物，无需安装或发布 npm：
+
+```sh
+npm run root:build
+node dist/cli.js registry capabilities --json
+node dist/cli.js mcp --help
+```
+
+MCP 注册管理与 Skills 共用 `aiRegistry` profile 服务、Keycloak 登录缓存、namespace 选择和平台 API `/api/v1/skills`。namespace 优先级仍为命令参数、项目 `.numa/registry.json`、用户默认值、profile 默认值。同名 namespace 使用 `--instance` 消歧。Nacos 管理凭据始终保留在平台。
+
+## 管理注册记录
+
+下面的 `team-ai` 是占位 namespace，需要替换成 capabilities 中当前身份可见的 namespace。`server.json` 为本地、禁用的示例定义；提交前修改名称与实际服务地址。文件使用平台请求 envelope，`serverSpecification` 等字段为 JSON 对象；最多 1 MiB。凭据只允许 `${MCP_TOKEN}` 这样的占位符。
+
+```sh
+node dist/cli.js mcp list --namespace team-ai --name cli-local-example --json
+node dist/cli.js mcp create examples/mcp/server.json --namespace team-ai --json
+node dist/cli.js mcp inspect cli-local-example --namespace team-ai --version 1.0.0 --json
+# 修改 JSON 文件后更新同名服务
+node dist/cli.js mcp update cli-local-example examples/mcp/server.json --namespace team-ai --json
+node dist/cli.js mcp tool disable cli-local-example echo --namespace team-ai --version 1.0.0 --json
+node dist/cli.js mcp delete cli-local-example --namespace team-ai --yes --json
+```
+
+工具开关的 `--version` 是 inspect 返回的 Nacos 服务版本（例如 `1.0.0`），不是整数修订号。更新和删除会先查询当前目标；服务端仍执行授权与版本校验。
+
+| 操作 | capability 预检 | 服务端要求 |
+|---|---|---|
+| list、inspect | `read` | namespace 可读 |
+| create、update、tags、tool enable/disable | `mcp:maintain` | namespace 维护权限 |
+| online、offline | `release:publish` | 审核权限且版本已发布 |
+| delete | `namespace:admin` | 平台 ops-admin |
+
+`online`、`offline` 要求精确版本和已发布的审批记录，通过官方 Nacos MCP 更新接口修改 `enabled`，保留工具定义、endpoint 引用和 latest 指针，并读回验证。当前 Nacos 3.2 MCP Admin API 与服务 schema 不支持业务标签；`tags` 兼容入口明确返回 `AI_REGISTRY_MCP_TAGS_UNSUPPORTED`，不会假装保存成功。未发布版本不能通过 `online` 绕过发布流程。现有发布状态机将下线记录置为 `OFFLINE`；下线后恢复需要创建新版本并重新审核发布，不能直接再次上线原版本。注册记录本身也不会自动创建网关绑定、授予工具权限或保存后端密钥。
+
+## 测试工具调用
+
+针对已经完成网关绑定及统一授权的服务：
+
+```sh
+node dist/cli.js mcp tools catalog-mcp --registry --namespace team-ai --json
+node dist/cli.js mcp call catalog-mcp search_products --registry --namespace team-ai --args '{"query":"demo"}' --json
+# 敏感参数优先使用权限受限的本地 JSON 文件
+node dist/cli.js mcp call catalog-mcp search_products --registry --namespace team-ai --args-file ./arguments.json --json
+```
+
+`--registry` 使用平台 Registry 的受治理入口；不指定时优先使用 Profile 网关。`--timeout` 统一以秒为单位（1–600，默认 60）。
+
+`tools` 若返回 `nextCursor`，用 `--cursor` 查询下一页。`call` 的 `--args` 与 `--args-file` 互斥，参数必须是 JSON 对象，最多 1 MiB。工具返回 `isError` 时 CLI 以非零状态退出。
+
+调用使用平台下发的 `/mcp-connections` 与当前身份访问受治理网关。CLI 不直连注册定义中的 `backendEndpoints`，不获取 Nacos 管理凭据或后端服务密钥；具体工具权限由网关和 Keycloak 判定。调用跟随网关绑定的在线版本，因此 `tools`、`call`、`proxy` 没有 `--version` 参数。
+
+## 本地 stdio MCP
+
+将单个远端服务转换成宿主可启动的本地 MCP 进程：
+
+```sh
+node dist/cli.js mcp proxy catalog-mcp --namespace team-ai
+```
+
+宿主 MCP 配置示例（替换绝对路径和 namespace）：
+
+```json
+{
+  "mcpServers": {
+    "catalog": {
+      "command": "node",
+      "args": ["/absolute/path/to/numa/dist/cli.js", "mcp", "proxy", "catalog-mcp", "--namespace", "team-ai"]
+    }
+  }
+}
+```
+
+先在该环境完成 `node dist/cli.js login`。代理复用缓存并按需刷新凭据；stdout 仅传输协议帧，错误写到 stderr。能力协商、通知、resources、prompts 等协议消息透传；EOF 或终止信号会关闭远端 session。原有 `mcp bridge` 仍是 namespace Router 聚合入口，`mcp install` 保留现有客户端安装流程。
+
+## 本地管理烟测
+
+`management-smoke.py` 创建随机名称的禁用服务，验证查询、版本详情、更新读回、工具开关、删除读回、未发布上线拒绝、不支持标签的明确错误及只读身份越权拒绝，并清理自己创建的记录。默认不会上线服务或创建网关授权。传入 `--submitter-env-file` 时增加真实的两人发布流程：Registry 维护身份提交，admin 审核和发布，核查线上与下线状态；始终不创建网关授权，最后删除自建注册记录，平台审计与发布历史保留。
+
+统一 MVP runner 将两套独立的私有 CLI 环境写成 JSON 文件（键和值为环境变量字符串），包括各自缓存/profile 和明确的 loopback `NUMA_BACKEND_BASE_URL`。文件不可提交，脚本不输出其内容：
+
+```sh
+python3 examples/mcp/management-smoke.py \
+  --namespace team-ai --instance local-mvp \
+  --admin-env-file /private/path/admin-env.json \
+  --reader-env-file /private/path/reader-env.json \
+  --submitter-env-file /private/path/maintainer-env.json
+```
+
+正式环境不要运行该烟测；脚本要求两套环境的 API 地址都显式指向 loopback。权限拒绝测试与 CRUD 都通过 CLI 调用平台，不直接访问 Nacos Admin API。
+
+协议依据：[Nacos MCP 管理 API](https://nacos.io/docs/latest/manual/admin/admin-api/#4-mcp-%E7%AE%A1%E7%90%86)、[Nacos 运维 SDK](https://nacos.io/docs/latest/manual/admin/maintainer-sdk/)。
+
+运行态端到端脚本使用普通 reader 身份，校验真实网关工具调用、越权拒绝和本地 stdio：
+
+```sh
+node examples/mcp/runtime-smoke.mjs --extended \
+  --namespace mcp-lab-a --instance mcp-keycloak-lab \
+  --reader-env-file /private/path/reader-env.json \
+  --writer-env-file /private/path/writer-env.json \
+  --denied-env-file /private/path/denied-env.json
+```
+
+该脚本也要求显式 loopback `NUMA_BACKEND_BASE_URL`，默认使用本地 `catalog-mcp` fixture；不要使用 admin 身份执行拒绝验收。
+
+管理烟测的 `--submitter-env-file`（兼容别名 `--writer-env-file`） 必须对应 capabilities 具有 `release:submit` 的 Registry 维护身份。它和运行态烟测中仅能调用写工具的业务 writer 身份不同；不要为通过测试给普通业务调用者追加管理权限。

package/examples/mcp/management-smoke.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Exercise MCP management through local Numa CLI; fixture supplies private environments.
+
+No Nacos administrator credentials or direct upstream API calls. The script creates
+one random disabled MCP record and deletes it. It does not grant gateway access.
+"""
+import argparse
+import json
+import os
+import re
+from pathlib import Path
+import subprocess
+import tempfile
+import uuid
+from urllib.parse import urlparse
+
+
+def read_environment(path):
+    value = json.loads(Path(path).read_text())
+    if not isinstance(value, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in value.items()):
+        raise ValueError("Fixture environment must be a JSON object of string values")
+    # The fixture owns the private file; never print its values.
+    return {**os.environ, **value}
+
+
+def smoke(cli, namespace, instance, admin_env, reader_env, submitter_env=None):
+    for environment in [admin_env, reader_env] + ([submitter_env] if submitter_env else []):
+        target = urlparse(environment.get("NUMA_BACKEND_BASE_URL", ""))
+        if target.scheme not in ("http", "https") or target.hostname not in ("localhost", "127.0.0.1", "::1"):
+            raise RuntimeError("Smoke requires an explicit loopback NUMA_BACKEND_BASE_URL in both fixture environments")
+    passed = []
+    name = "numa-cli-smoke-" + uuid.uuid4().hex[:12]
+    common = ["--namespace", namespace, "--json"] + (["--instance", instance] if instance else [])
+    created = False
+
+    def command(args, env=admin_env, denied=False, expected_code=None, group="mcp", scoped=True):
+        result = subprocess.run(["node", str(cli), group, *args, *(common if scoped else ["--json"])], env=env,
+                                text=True, capture_output=True, timeout=90)
+        try:
+            payload = json.loads(result.stdout or result.stderr)
+        except (ValueError, TypeError):
+            raise RuntimeError("CLI did not return structured JSON for " + args[0]) from None
+        if expected_code is not None:
+            code = (payload.get("error") or {}).get("code", "")
+            if result.returncode == 0 or code != expected_code:
+                raise RuntimeError("Expected " + expected_code + " for " + args[0] + ", got " + str(code))
+        elif denied:
+            code = (payload.get("error") or {}).get("code", "")
+            if result.returncode == 0 or not any(word in str(code).lower() for word in ("forbidden", "denied", "permission")):
+                raise RuntimeError("Expected authorization denial for " + args[0])
+        elif result.returncode != 0 or payload.get("ok") is not True:
+            code = (payload.get("error") or {}).get("code", "unknown")
+            status = re.search(r"HTTP (\d{3})", str((payload.get("error") or {}).get("message", "")))
+            raise RuntimeError("CLI " + " ".join(args[:2]) + " failed: " + str(code) + (" HTTP " + status[1] if status else ""))
+        return payload
+
+    with tempfile.TemporaryDirectory(prefix="numa-mcp-smoke-") as directory:
+        path = Path(directory) / "server.json"
+        spec = json.loads(Path(__file__).with_name("server.json").read_text())
+        spec["serverSpecification"]["name"] = name
+        path.write_text(json.dumps(spec))
+        try:
+            command(["create", str(path)], reader_env, denied=True)
+            passed.append("reader-create-denied")
+            command(["create", str(path)])
+            created = True
+            passed.append("create-disabled")
+            listing = command(["list", "--name", name])["mcpServers"]
+            if not any(item.get("name") == name for item in listing.get("pageItems", [])):
+                raise RuntimeError("Created MCP record absent from Nacos list")
+            passed.append("list")
+            detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+            if detail.get("name") != name or detail.get("versionDetail", {}).get("version") != "1.0.0":
+                raise RuntimeError("Nacos detail did not preserve name and selected version")
+            passed.append("inspect-version")
+            if detail.get("enabled") is not False:
+                raise RuntimeError("Smoke record was unexpectedly enabled")
+            spec["serverSpecification"]["description"] = "Updated CLI smoke record"
+            path.write_text(json.dumps(spec))
+            command(["update", name, str(path)])
+            detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+            if detail.get("description") != "Updated CLI smoke record":
+                raise RuntimeError("Nacos update was not visible")
+            passed.append("update-readback")
+            for operation, expected in (("disable", False), ("enable", True)):
+                command(["tool", operation, name, "echo", "--version", "1.0.0"])
+                detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+                if detail.get("toolSpec", {}).get("toolsMeta", {}).get("echo", {}).get("enabled") is not expected:
+                    raise RuntimeError("Nacos tool state was not persisted")
+                passed.append("tool-" + operation)
+            command(["tags", name, "smoke"], expected_code="AI_REGISTRY_MCP_TAGS_UNSUPPORTED")
+            passed.append("tags-unsupported-explicit")
+            command(["online", name, "--version", "1.0.0"], expected_code="AI_REGISTRY_RELEASE_REQUEST_REQUIRED")
+            passed.append("unpublished-online-denied")
+            if submitter_env:
+                release = command(["approvals", "submit", "mcp", name, "--resource-version", "1.0.0",
+                                   "--reason", "Local MVP lifecycle verification"], submitter_env, group="registry")["result"]
+                passed.append("maintainer-release-submitted")
+                reviewed = command(["approvals", "review", release["requestId"], "--decision", "APPROVED",
+                                    "--reason", "Local disabled fixture reviewed", "--version", str(release["version"])],
+                                   group="registry", scoped=False)["result"]
+                passed.append("admin-release-reviewed")
+                published = command(["approvals", "publish", release["requestId"], "--version", str(reviewed["version"])],
+                                    group="registry", scoped=False)["result"]
+                if published.get("state") != "PUBLISHED":
+                    raise RuntimeError("Release did not reach PUBLISHED")
+                detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+                if detail.get("enabled") is not True:
+                    raise RuntimeError("Publishing did not enable selected MCP version")
+                passed.append("admin-publish-enabled-readback")
+                command(["online", name, "--version", "1.0.0"])
+                detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+                if detail.get("enabled") is not True:
+                    raise RuntimeError("Online state did not persist")
+                passed.append("published-online-readback")
+                command(["offline", name, "--version", "1.0.0"])
+                detail = command(["inspect", name, "--version", "1.0.0"])["mcpServer"]
+                if detail.get("enabled") is not False:
+                    raise RuntimeError("Offline state did not persist")
+                passed.append("offline-disabled-readback")
+            command(["delete", name, "--yes"], reader_env, denied=True)
+            passed.append("reader-delete-denied")
+            command(["delete", name, "--yes"])
+            created = False
+            listing = command(["list", "--name", name])["mcpServers"]
+            if any(item.get("name") == name for item in listing.get("pageItems", [])):
+                raise RuntimeError("Deleted MCP record still appears in Nacos list")
+            passed.append("delete-readback")
+        finally:
+            if created:
+                command(["delete", name, "--yes"])
+    return {"ok": True, "checks": passed, "count": len(passed)}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--cli", type=Path, default=Path(__file__).resolve().parents[2] / "dist/cli.js")
+    parser.add_argument("--namespace", required=True)
+    parser.add_argument("--instance")
+    parser.add_argument("--admin-env-file", required=True, help="Private JSON environment for local MVP administrator")
+    parser.add_argument("--reader-env-file", required=True, help="Private JSON environment for read-only identity")
+    parser.add_argument("--submitter-env-file", "--writer-env-file", dest="submitter_env_file", help="Separate Registry maintainer identity for two-person publication lifecycle")
+    args = parser.parse_args()
+    try:
+        print(json.dumps(smoke(args.cli.resolve(), args.namespace, args.instance,
+                               read_environment(args.admin_env_file), read_environment(args.reader_env_file),
+                               read_environment(args.submitter_env_file) if args.submitter_env_file else None), indent=2))
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+        # Exception messages are deliberately constructed without process output or secrets.
+        parser.exit(1, "MCP management smoke failed: " + (str(error) if isinstance(error, RuntimeError) else type(error).__name__) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/examples/mcp/runtime-smoke.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// Local MVP acceptance. Identity/profile/cache are supplied through the normal Numa environment.
+// No credentials are printed or written by this runner.
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const { values } = parseArgs({ options: {
+  cli: { type: "string", default: "dist/cli.js" },
+  namespace: { type: "string", default: "mcp-lab-a" },
+  instance: { type: "string" },
+  server: { type: "string", default: "catalog-mcp" },
+  tool: { type: "string", default: "search_products" },
+  "denied-tool": { type: "string", default: "update_product" },
+  "error-tool": { type: "string", default: "search_failure" },
+  "reader-env-file": { type: "string" },
+  "writer-env-file": { type: "string" },
+  "denied-env-file": { type: "string" },
+  "other-namespace": { type: "string", default: "mcp-lab-b" },
+  extended: { type: "boolean", default: false }
+} });
+async function identityEnvironment(path) {
+  const provided = path ? JSON.parse(await readFile(path, "utf8")) : {};
+  if (!provided || typeof provided !== "object" || Array.isArray(provided)
+    || Object.values(provided).some(value => typeof value !== "string")) throw new Error("Identity environment must be a string map.");
+  const environment = { ...process.env, ...provided };
+  const base = environment.NUMA_BACKEND_BASE_URL;
+  const parsed = base ? new URL(base) : undefined;
+  if (!parsed || !["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash
+    || !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)) {
+    throw new Error("This runner requires NUMA_BACKEND_BASE_URL to explicitly select the local MVP.");
+  }
+  return environment;
+}
+const readerEnvironment = await identityEnvironment(values["reader-env-file"]);
+const writerEnvironment = values["writer-env-file"] ? await identityEnvironment(values["writer-env-file"]) : undefined;
+const deniedEnvironment = values["denied-env-file"] ? await identityEnvironment(values["denied-env-file"]) : undefined;
+const cli = resolve(values.cli);
+const namespaceOptions = (name = values.namespace) => ["--namespace", name, ...(values.instance ? ["--instance", values.instance] : [])];
+const checks = [];
+let lastOperation;
+async function invoke(args, environment = readerEnvironment, targetNamespace = values.namespace) {
+  const child = spawn(process.execPath, [cli, ...args, ...namespaceOptions(targetNamespace), "--json"], {
+    env: environment, stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  child.stdout.on("data", chunk => { stdout += chunk; });
+  child.stderr.resume();
+  const timer = setTimeout(() => child.kill("SIGTERM"), 45_000);
+  const code = await new Promise((resolveCode, reject) => { child.once("error", reject); child.once("close", resolveCode); });
+  clearTimeout(timer);
+  let body;
+  try { body = JSON.parse(stdout); } catch { throw new Error("CLI did not return valid JSON; inspect local diagnostics."); }
+  lastOperation = { command: args.slice(0, 4).join(" "), namespace: targetNamespace, exitCode: code,
+    ok: body.ok, errorCode: body.error?.code, httpStatus: body.error?.details?.status ?? body.error?.status };
+  return { code, body };
+}
+async function viaProxy(operation, environment = readerEnvironment, server = values.server, targetNamespace = values.namespace) {
+  lastOperation = { command: "mcp proxy", server, namespace: targetNamespace };
+  const transport = new StdioClientTransport({ command: process.execPath,
+    args: [cli, "mcp", "proxy", server, ...namespaceOptions(targetNamespace)],
+    env: Object.fromEntries(Object.entries(environment).filter(([, value]) => value !== undefined)), stderr: "pipe" });
+  transport.stderr?.resume();
+  const client = new Client({ name: "numa-local-mvp-acceptance", version: "1" }, { capabilities: {} });
+  try { await client.connect(transport, { timeout: 30_000 }); return await operation(client); }
+  finally { await client.close(); }
+}
+try {
+  const tools = await invoke(["mcp", "tools", values.server]);
+  assert.equal(tools.code, 0);
+  assert.equal(tools.body.ok, true);
+  const names = tools.body.tools.map(tool => tool.name);
+  assert(names.includes(values.tool));
+  assert(!names.includes(values["denied-tool"]));
+  checks.push("CLI tools uses gateway-filtered list");
+
+  const call = await invoke(["mcp", "call", values.server, values.tool, "--args", "{}"]);
+  assert.equal(call.code, 0);
+  assert.equal(call.body.ok, true);
+  assert(call.body.result.content?.length > 0);
+  checks.push("CLI tool call completes through gateway and upstream");
+
+  const forbidden = await invoke(["mcp", "call", values.server, values["denied-tool"], "--args", "{}"]);
+  assert.notEqual(forbidden.code, 0);
+  assert.equal(forbidden.body.ok, false);
+  assert.equal(forbidden.body.error.code, "ai_registry_mcp_forbidden");
+  checks.push("CLI forbidden tool is denied by gateway");
+
+  const error = await invoke(["mcp", "call", values.server, values["error-tool"], "--args", "{}"]);
+  assert.notEqual(error.code, 0);
+  assert.equal(error.body.ok, false);
+  assert.equal(error.body.result.isError, true);
+  checks.push("CLI preserves executed tool isError and exits nonzero");
+
+  await viaProxy(async client => {
+    assert(client.getServerCapabilities()?.tools);
+    const listed = await client.listTools();
+    const proxyNames = listed.tools.map(tool => tool.name);
+    assert(proxyNames.includes(values.tool));
+    assert(!proxyNames.includes(values["denied-tool"]));
+    checks.push("stdio proxy negotiates real server and retains filtered tools");
+    const result = await client.callTool({ name: values.tool, arguments: {} });
+    assert(!result.isError);
+    assert(result.content?.length > 0);
+    checks.push("stdio MCP client invokes real remote tool via CLI proxy");
+    const failed = await client.callTool({ name: values["error-tool"], arguments: {} });
+    assert.equal(failed.isError, true);
+    checks.push("stdio proxy preserves protocol tool errors");
+  });
+  let denied = false; let initialized = false;
+  try {
+    await viaProxy(client => { initialized = true; return client.callTool({ name: values["denied-tool"], arguments: {} }, undefined, { timeout: 15_000 }); });
+  } catch { denied = true; }
+  assert(initialized && denied);
+  checks.push("stdio proxy cannot bypass gateway tool authorization");
+  if (values.extended) {
+    for (const [server, tool, args, expected] of [
+      ["notes-mcp", "list_notes", {}, "credentialVerified"],
+      ["stdio-mcp", "calculate_total", { unit_price: 12.5, quantity: 2 }, '"total":25']
+    ]) {
+      const call = await invoke(["mcp", "call", server, tool, "--args", JSON.stringify(args)]);
+      assert.equal(call.code, 0);
+      assert.equal(call.body.ok, true);
+      const serialized = JSON.stringify(call.body.result).replaceAll(/\s/gu, "").replaceAll('\\"', '"');
+      assert(serialized.includes(expected));
+      checks.push(`CLI reaches ${server} real upstream adapter`);
+      await viaProxy(async client => {
+        const tools = await client.listTools();
+        assert(tools.tools.some(item => item.name === tool));
+        const result = await client.callTool({ name: tool, arguments: args });
+        assert(!result.isError);
+        const serialized = JSON.stringify(result).replaceAll(/\s/gu, "").replaceAll('\\"', '"');
+        assert(serialized.includes(expected));
+      }, readerEnvironment, server);
+      checks.push(`local stdio proxy reaches ${server} real upstream adapter`);
+    }
+    await viaProxy(async client => {
+      const first = await client.listTools();
+      const second = await client.callTool({ name: values.tool, arguments: {} });
+      assert(first.tools.some(tool => tool.name === values.tool));
+      assert(!second.isError);
+    }, readerEnvironment, "session-mcp");
+    checks.push("stdio proxy retains stateful upstream session across requests");
+  }
+  if (writerEnvironment) {
+    const write = await invoke(["mcp", "call", values.server, values["denied-tool"], "--args", '{"name":"numa-local-acceptance"}'], writerEnvironment);
+    assert.equal(write.code, 0);
+    assert.equal(write.body.ok, true);
+    checks.push("writer CLI executes authorized fixture write");
+    await viaProxy(async client => {
+      const tools = await client.listTools();
+      assert(tools.tools.some(tool => tool.name === values["denied-tool"]));
+      const written = await client.callTool({ name: values["denied-tool"], arguments: { name: "numa-stdio-acceptance" } });
+      assert(!written.isError);
+    }, writerEnvironment);
+    checks.push("writer stdio proxy executes authorized fixture write");
+    const unclassified = await invoke(["mcp", "call", values.server, "unclassified_operation", "--args", "{}"], writerEnvironment);
+    assert.notEqual(unclassified.code, 0);
+    assert.equal(unclassified.body.error.code, "ai_registry_mcp_forbidden");
+    checks.push("writer still cannot invoke unclassified tool");
+    const readOther = await invoke(["mcp", "call", values.server, values.tool, "--args", "{}"], readerEnvironment, values["other-namespace"]);
+    assert.notEqual(readOther.code, 0);
+    assert.equal(readOther.body.ok, false);
+    assert.match(readOther.body.error.code, /forbidden/u);
+    checks.push("reader cannot cross into another namespace");
+    const writerOther = await invoke(["mcp", "call", values.server, values.tool, "--args", "{}"], writerEnvironment, values["other-namespace"]);
+    assert.equal(writerOther.code, 0);
+    assert.equal(writerOther.body.ok, true);
+    checks.push("explicitly granted writer can call another namespace");
+  }
+  if (deniedEnvironment) {
+    const denied = await invoke(["mcp", "tools", values.server], deniedEnvironment);
+    assert.notEqual(denied.code, 0);
+    assert.equal(denied.body.ok, false);
+    assert(denied.body.error.details?.status === 403 || /forbidden/u.test(denied.body.error.code));
+    checks.push("ungranted identity cannot discover callable server");
+  }
+  process.stdout.write(JSON.stringify({ ok: true, checks }, null, 2) + "\n");
+} catch {
+  process.stderr.write(JSON.stringify({ ok: false, completedChecks: checks, lastOperation,
+    message: "MCP runtime acceptance failed; credential-bearing responses were withheld." }, null, 2) + "\n");
+  process.exitCode = 1;
+}

package/examples/mcp/server.json

@@ -0,0 +1,17 @@
+{
+  "serverSpecification": {
+    "name": "cli-local-example",
+    "description": "Local CLI registration example; gateway access requires a separate binding and authorization.",
+    "protocol": "mcp-streamable",
+    "frontProtocol": "mcp-streamable",
+    "enabled": false,
+    "versionDetail": { "version": "1.0.0" },
+    "remoteServerConfig": { "exportPath": "/mcp" }
+  },
+  "toolSpecification": {
+    "tools": [{ "name": "echo", "description": "Example metadata only", "inputSchema": { "type": "object", "properties": {} } }],
+    "toolsMeta": {}
+  },
+  "endpointSpecification": { "type": "DIRECT", "data": { "address": "127.0.0.1", "port": "8080" } },
+  "latest": true
+}

package/examples/oss/README.md

@@ -0,0 +1,78 @@
+# OSS CLI list / write / read example
+
+Use the local build only. Nothing here publishes to npm or changes a global installation.
+
+```bash
+cd /Users/changhz/source/numa-business-issuers
+npm run build
+# A local binary still reads the global configuration unless this is set.
+export NUMA_CONFIG_DIR="$PWD/tmp/issuer-mvp-cli"
+export NUMA_PROFILE_URL='http://localhost:28080/public/v1/client-configurations/issuer-mvp'
+node dist/cli.js config --set profileUrl="$NUMA_PROFILE_URL" profileId=issuer-mvp apiBaseUrl=http://localhost:28080 checkUpdates=false
+node dist/cli.js login --no-console --no-config
+node dist/cli.js oss grants --json
+# Replace 123 with the exact ACTIVE, synced/verified read/write grant shown above.
+python3 examples/oss/roundtrip.py --grant-id 123
+```
+
+For interactive commands, `./scripts/mvp-cli.sh login --issuer cluster-b
+--no-console --no-config` and `./scripts/mvp-cli.sh oss grants --issuer cluster-b`
+set up the same isolated local directory automatically. They never change
+`~/.config/numa`. Merely setting NUMA_PROFILE_URL with your global configuration
+can still leave its pinned profileId pointing at numa-realm.
+
+The local profile must first be created and published in DevOps. Its platform
+issuer is fixed; `login` uses the business default. To explicitly select another
+business issuer, use the same selector for login and the example:
+
+```bash
+node dist/cli.js login --issuer cluster-b --no-console --no-config
+node dist/cli.js oss grants --issuer cluster-b --json
+python3 examples/oss/roundtrip.py --issuer cluster-b --grant-id 123
+```
+
+`--cli /absolute/path/dist/cli.js` selects another local build. The script never
+runs npx, downloads packages, chooses a grant automatically or changes permissions.
+It queries Grant/STS APIs through Numa, uses the STS-backed OSS client to list up
+to ten objects, uploads a small unique object, checks metadata, downloads it and
+compares bytes. Both read and write permission are required. `--prefix` must be
+inside the selected grant's scope. No existing object is overwritten. The remote
+test object is retained and its key is printed; temporary local files are removed.
+Credentials are handled internally by the CLI, never printed by the script.
+
+Machine identities use the selected issuer too. Configure
+`NUMA_KEYCLOAK_AUTH_MODE=client_credentials`, the dedicated
+`NUMA_KEYCLOAK_CLIENT_ID`, and `NUMA_KEYCLOAK_CLIENT_SECRET_FILE` (owner-only file).
+Do not run browser login in machine mode. The backend still requires the canonical
+OSS role and a grant for this exact issuer/subject.
+
+For the local acceptance run, the published `issuer-mvp` Profile defaults to
+cluster-a. Its existing fixture grants are intentionally unpublished/read-only
+and cannot run the write example. Select a separately verified read/write grant
+before executing the example against real OSS.
+
+`oss grants` lists authorization records, including records whose cloud policy is
+not yet synced/verified. Its count is not a count of grants ready for object access.
+The normal output shows each grant ID, bucket/prefix, permission and sync state.
+For example, the local MVP fixture Grant 2 has `cloudPolicySynced=false` and
+`permissionLevel=READ_ONLY`: it cannot run this roundtrip. The unified API returns
+`actions` and `effect`; the CLI authorizes operations from those fields, never
+from the template label. `oss ls` only requires Allow + `oss:ListObjects`; stat/get
+require `oss:GetObject`, and upload requires `oss:PutObject`. The roundtrip requires
+all three Actions. System ADMIN uses `oss:*`, which is broader than selecting all
+currently editable object Actions.
+The roundtrip reports all status/permission blockers before requesting STS or
+performing any object operations; it never publishes policies or expands access.
+
+If `oss ls` fails with `OSS_STS_BROKER_NOT_CONFIGURED` (HTTP 503), the platform
+account lacks an active STS broker RAM-user AK. A synced OSS policy alone does
+not make STS ready. A platform administrator must configure the dedicated broker
+identity and its managed AK, permission to assume the selected RAM Role, and the
+Role's trust policy. The default management AK is separate from the broker AK.
+`OSS_STS_ASSUME_ROLE_FAILED` means the STS call failed after broker selection;
+check broker credentials, trust, permissions and connectivity. Neither error is
+fixed by logging in with another issuer or changing the grant's read/write level.
+
+The imported OSS development branch had a hard-coded machine test bucket. This
+build uses server-authorized Grant/STS scope for both user and machine identities;
+SDK prefix and permission checks remain enabled.