Add general connector namespace skill#121
Closed
apranaseth wants to merge 14 commits into
Closed
Conversation
Adds the azure-connectorgateway skill (ported from Azure-Samples/azure-container-apps-sandboxes PR #13) under Skills/Sandbox/azure-connectorgateway, plus the plugin descriptors needed for both Copilot CLI and Claude Code: - marketplace.json at the repo root registers the plugin - .plugin/plugin.json for Copilot CLI direct installs - .claude-plugin/plugin.json for Claude Code direct installs - README + Skills/Sandbox/README with install instructions Verified end-to-end with 'copilot plugin install <local-path>' — the skill is discovered and registered. Once merged, users can install via: /plugin install Azure/Connectors or via the marketplace flow: /plugin marketplace add Azure/Connectors /plugin install azure-connectorgateway@Azure-Connectors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
New skill under Skills/General/azure-connectorgateway providing a sandbox-agnostic playbook for managing Microsoft.Web connector gateways, connections, trigger configs, and MCP server configs. The customer-owned callback URL and notification authentication are user-provided; the skill never assumes a sandbox runtime. Trigger types covered: connector-event, Recurrence, SlidingWindow. MCP focus is on ManagedMcpServer; HostedMcpServer is referenced briefly. Reuses dynamic-values resolution and consent flow from the existing Skills/Sandbox/azure-connectorgateway skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand mcp-server-config.md with a full "Resolving dynamic parameters for MCP config" section that covers all four x-ms-dynamic-* kinds, the cascading-dependency pattern (e.g., channel depends on team), dynamic schema for body shapes, and a rule of thumb for what to bake into userParameters vs leave LLM-supplied. Mirror the same triage in SKILL.md Step 4B. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
User correction: 'audience is not a required field' on ManagedServiceIdentity callback auth. Updated the skill to treat it as optional and to always ASK the user whether to set one: - notification-authentication.md sec 4: audience-less example first, audience-with-value second; validation rules say 'optional, omit for non-AAD callbacks'. - SKILL.md auth-type table + STOP-and-ask list updated. - trigger-setup.md example shows audience commented out + gotcha table updated. - gotchas.md row replaced (was 'audience required', now 'fabricated audience -> always ask'). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
If the user doesn't provide an MSI audience, default to https://management.azure.com/ (a real AAD-protected resource — ARM). Never use the callback URL as the audience. Updated: - notification-authentication.md sec 4: workflow (ask -> use / default to ARM), examples lead with default-audience pattern, validation rule reverted to 'audience required, default if not given'. - SKILL.md auth-type table, rules table, STOP-and-ask list. - trigger-setup.md example shows default audience + comment, gotcha table updated. - gotchas.md row updated to reflect default-audience behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
MCP server config access policies require BOTH a principal.type of 'ActiveDirectory' AND a sibling properties.principalType of 'User' or 'Group' (the shared ActiveDirectory enum is insufficient here). The access-policy resource name in the URL must equal the caller's objectId (case-insensitive). MIs/service principals are not supported as MCP principals - only Entra users and groups. Discovered while creating servicebus-send-aigateway MCP config on apseth-msi gateway. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The MCP runtime validates that every required Swagger parameter — including required body sub-properties — is declared in either userParameters (fixed value) or agentParameters (caller-supplied JSON Schema). Skipping this triage causes runtime failures like: The API operation 'SendEmailV2' is missing required property 'emailMessage/To'. Changes: - mcp-server-config.md: rewrote the parameter section to cover userParameters vs agentParameters, body decomposition (one agentParameter named after the body root with a nested object schema), and a STOP-and-ask triage workflow per parameter. Added the ConvertTo-Json depth gotcha and updated the PUT example to show both arrays. - SKILL.md: added the per-parameter triage rule + STOP-and-ask entry; updated Step 4B to enumerate body sub-properties and triage each one; updated the PUT example to include agentParameters. - gotchas.md: added rows for the "missing required property" runtime error and the ConvertTo-Json depth truncation symptom. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The trigger wizard (Cascade `serializeTriggerParams`) aggregates every body- sourced leaf — including dotted nested paths — into ONE `parameters[]` entry whose name is literally `"body"` (independent of the Swagger body parameter's own name, e.g. Teams declares it as `requestBody`) and whose `value` is the nested object. Non-body dotted leaves group under their root segment via `groupDottedEntriesToNestedObjects`. The skill previously only showed flat scalar examples and would have produced broken `body.<path>` dotted entries. Also calls out the wrapper-name asymmetry between MCP and triggers: - MCP: body wrapper name = Swagger body param's own name (e.g. `emailMessage`). - Trigger: body wrapper name = literal `"body"`, always. Changes: - trigger-setup.md: added §2a (per-parameter enumeration + STOP-and-ask) and §2b (wire-shape rules with a nested-body example and an anti-pattern). Bumped the PUT example to ConvertTo-Json -Depth 20. Added Common-Mistakes rows for flat dotted body names, wrong wrapper name, and depth truncation. - SKILL.md: rewrote Step 4A item 2 to spell out body decomposition and the literal `"body"` wrapper. Updated the rules table entry for "Trigger body schema" to document the wrapper convention. Clarified MCP triage rule to highlight the wrapper-name difference. - gotchas.md: added rows for "body leaves visible as flat dotted params" and "trigger body wrapper named after the Swagger param". Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both MCP and trigger configs need to build nested-object payloads from per-leaf user answers. The previous commit covered the rules and shapes but didn't walk through the Swagger → user answers → assembled wire entry flow. Add concrete worked examples in both docs: - trigger-setup.md §2c: Teams PostMessageToChannelV3 → user picks team/channel, types message content, picks contentType → assembled as ONE entry named "body" (literal) with the recipient/messageBody sub-objects. - mcp-server-config.md "Worked example": SharePoint PostItem → user splits Title (agent), Status (user="Open"), Assignee.Email (agent), Tags (agent) → assembled as paired userParameters/agentParameters entries with the same root name "item" (Swagger body param's own name). The two examples make the user-vs-agent / fixed-vs-dynamic distinction and the wrapper-name asymmetry (literal "body" for triggers vs Swagger name for MCP) concrete. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds connector-gateway skills and documentation so coding agents can manage Azure Connector Gateway workflows, including sandbox-targeted triggers and a new generic skill for arbitrary webhook callbacks, MCP server configs, and direct dynamicInvoke calls.
Changes:
- Adds Sandbox connector-gateway skill content, references, and a getting-started script.
- Adds General connector-gateway skill content with trigger, MCP, authentication, and connection references.
- Adds plugin/marketplace metadata and root README install instructions.
Reviewed changes
Copilot reviewed 34 out of 34 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
.plugin/plugin.json |
Adds Copilot plugin descriptor. |
.claude-plugin/plugin.json |
Adds Claude Code plugin descriptor. |
marketplace.json |
Adds marketplace listing. |
README.md |
Documents agent skill installation and available skills. |
Skills/Sandbox/README.md |
Documents Sandbox skill installation and summary. |
Skills/Sandbox/azure-connectorgateway/version.json |
Adds Sandbox skill version. |
Skills/Sandbox/azure-connectorgateway/SKILL.md |
Adds Sandbox connector-gateway skill workflow. |
Skills/Sandbox/azure-connectorgateway/scripts/trigger-getting-started.py |
Adds trigger setup reference script. |
Skills/Sandbox/azure-connectorgateway/references/consent.md |
Adds OAuth consent flow reference. |
Skills/Sandbox/azure-connectorgateway/references/direct-api.md |
Adds dynamicInvoke reference. |
Skills/Sandbox/azure-connectorgateway/references/dynamic-values.md |
Adds dynamic parameter resolution reference. |
Skills/Sandbox/azure-connectorgateway/references/gateway-connections.md |
Adds sandbox gatewayConnections wiring reference. |
Skills/Sandbox/azure-connectorgateway/references/gotchas.md |
Adds Sandbox troubleshooting notes. |
Skills/Sandbox/azure-connectorgateway/references/handler-guide.md |
Adds sandbox handler development guidance. |
Skills/Sandbox/azure-connectorgateway/references/prerequisites.md |
Adds Sandbox prerequisites. |
Skills/Sandbox/azure-connectorgateway/references/quickstart.md |
Adds Sandbox quickstart commands. |
Skills/Sandbox/azure-connectorgateway/references/runtime-url-examples.md |
Adds sandbox runtime URL examples. |
Skills/Sandbox/azure-connectorgateway/references/trigger-flow.md |
Adds Sandbox trigger architecture/lifecycle reference. |
Skills/Sandbox/azure-connectorgateway/references/trigger-setup.md |
Adds Sandbox trigger setup reference. |
Skills/Sandbox/azure-connectorgateway/references/tutorial-welcome-emailer.md |
Adds Sandbox welcome-emailer walkthrough. |
Skills/General/azure-connectorgateway/version.json |
Adds General skill version. |
Skills/General/azure-connectorgateway/SKILL.md |
Adds generic connector-gateway skill workflow. |
Skills/General/azure-connectorgateway/references/connections.md |
Adds connection CRUD and ACL reference. |
Skills/General/azure-connectorgateway/references/consent.md |
Adds General OAuth consent flow reference. |
Skills/General/azure-connectorgateway/references/direct-api.md |
Adds General dynamicInvoke reference. |
Skills/General/azure-connectorgateway/references/dynamic-values.md |
Adds General dynamic parameter resolution reference. |
Skills/General/azure-connectorgateway/references/gotchas.md |
Adds General troubleshooting notes. |
Skills/General/azure-connectorgateway/references/mcp-server-config.md |
Adds MCP server config reference. |
Skills/General/azure-connectorgateway/references/notification-authentication.md |
Adds callback authentication reference. |
Skills/General/azure-connectorgateway/references/prerequisites.md |
Adds General prerequisites. |
Skills/General/azure-connectorgateway/references/quickstart.md |
Adds General quickstart commands. |
Skills/General/azure-connectorgateway/references/trigger-flow.md |
Adds General trigger lifecycle reference. |
Skills/General/azure-connectorgateway/references/trigger-setup.md |
Adds General trigger setup reference. |
Skills/General/azure-connectorgateway/references/tutorial.md |
Adds General end-to-end tutorials. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Cascade portal has renamed the user-facing term to "Connector Namespace"
(see CreateConnectorNamespacePanel.tsx, ConnectorNamespaceIcon.tsx, the
CONNECTOR_NAMESPACE_REGIONS_* constants, etc.). Update the skill to match.
What changed:
- Folder: Skills/General/azure-connectorgateway/ ->
Skills/General/azure-connectornamespace/ (git mv preserves history).
- SKILL.md frontmatter: name -> azure-connectornamespace; description
rewritten with "Connector Namespace"; kept "connector gateway" as a
legacy discovery keyword so users searching the old term still hit
this skill.
- All prose in SKILL.md + references/*.md: "Connector Gateway"/"gateway"
-> "Connector Namespace"/"namespace" with proper case handling.
- Variable placeholders: {gw} -> {namespace}, $gw -> $namespace,
$gwBody -> $namespaceBody, $gwMi -> $namespaceMi, $gwTenant ->
$namespaceTenant.
- Example resource names: gateway-acl -> namespace-acl, tutorial-gw ->
tutorial-ns, <gateway-host> -> <namespace-host>.
- Added a "Naming note" section on SKILL.md explaining the rename and
what stayed unchanged.
- Added a gotchas.md row clarifying display name vs API strings.
What stayed unchanged (API contracts):
- ARM resource type: Microsoft.Web/connectorGateways (URL segment is
the live REST API path).
- Sandbox-group property: gatewayConnections[].
- RBAC string: Microsoft.Web/connectorGateways/*.
- Cascade source folder reference: src/.../ConnectorGateways/.
- Sandbox companion skill folder: Skills/Sandbox/azure-connectorgateway/
(separate skill, out of scope for this rebrand).
- Test class name: AIGatewayApiTests_NotificationAuthValidation_*.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
DevArjun23
previously approved these changes
May 31, 2026
apranaseth
dismissed
DevArjun23’s stale review
The merge-base changed after approval.
Member
|
Please rename this to connector-namespace instead of azure-connectorgateway This way the CLI extension adn skill stay in sync. |
apranaseth
changed the title
DevArjun23
previously approved these changes
May 31, 2026
apranaseth
dismissed
DevArjun23’s stale review
The merge-base changed after approval.
rarayudu
previously approved these changes
May 31, 2026
apranaseth
dismissed
rarayudu’s stale review
The merge-base changed after approval.
DevArjun23
previously approved these changes
May 31, 2026
apranaseth
dismissed
DevArjun23’s stale review
The merge-base changed after approval.
DevArjun23
previously approved these changes
May 31, 2026
apranaseth
dismissed
DevArjun23’s stale review
The merge-base changed after approval.
rarayudu
previously approved these changes
Jun 1, 2026
apranaseth
dismissed
rarayudu’s stale review
The merge-base changed after approval.
Comment on lines
+93
to
+94
| > **ARM base:** `https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorNamespaces` | ||
| > **API version:** `2026-05-01-preview` |
Comment on lines
+37
to
+40
| > the Cascade portal rename — see `Cascade.Portal.Client/src/components/CreateConnectorNamespacePanel.tsx`). | ||
| > **The ARM resource type is still `Microsoft.Web/connectorGateways`** (legacy | ||
| > URL segment kept for backwards compatibility) and the property `gatewayConnections[]` | ||
| > on sandbox groups also keeps its name. Do not rewrite those API strings. |
Comment on lines
+165
to
+166
| > `parameters[]` entry. This mirrors Cascade's `serializeTriggerParams` exactly | ||
| > (`src\Cascade.Portal.Client\src\components\ConnectorGateways\TriggerWizard\utils\serializeTriggerParams.ts`). |
Comment on lines
+213
to
+217
| "activationMode": "OnDemand", | ||
| "command": f"echo 'Trigger {config_name} fired!' >> /tmp/trigger.log", | ||
| }, | ||
| "callbackUrl": f"https://management.azuredevcompute.io/subscriptions/{subscription_id}/resourceGroups/{rg}/sandboxGroups/{sandbox_group}/sandboxes/{sandbox_id}/executeShellCommand?api-version=2026-02-01-preview", | ||
| "httpMethod": "Post", |
Comment on lines
+193
to
+196
| parameters = DEFAULT_PARAMS.get(connector, []) | ||
| if not parameters: | ||
| print(f" ℹ️ No default parameters for '{connector}'. Trigger will use operation defaults.") | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add general connectorgateway skill
Linked issue
Type of change
Checklist