workspace-architect 1.3.0

package/assets/instructions/power-platform-connector.instructions.md

@@ -0,0 +1,430 @@
+---
+title: Power Platform Connectors Schema Development Instructions
+description: 'Comprehensive development guidelines for Power Platform Custom Connectors using JSON Schema definitions. Covers API definitions (Swagger 2.0), API properties, and settings configuration with Microsoft extensions.'
+applyTo: '**/*.{json,md}'
+---
+
+# Power Platform Connectors Schema Development Instructions
+
+## Project Overview
+This workspace contains JSON Schema definitions for Power Platform Custom Connectors, specifically for the `paconn` (Power Apps Connector) tool. The schemas validate and provide IntelliSense for:
+
+- **API Definitions** (Swagger 2.0 format)
+- **API Properties** (connector metadata and configuration)
+- **Settings** (environment and deployment configuration)
+
+## File Structure Understanding
+
+### 1. apiDefinition.swagger.json
+- **Purpose**: This file contains Swagger 2.0 API definitions with Power Platform extensions.
+- **Key Features**:
+  - Standard Swagger 2.0 properties including info, paths, definitions, and more.
+  - Microsoft-specific extensions that begin with `x-ms-*` prefixes.
+  - Custom format types specifically designed for Power Platform such as `date-no-tz` and `html`.
+  - Dynamic schema support that provides runtime flexibility.
+  - Security definitions that support OAuth2, API Key, and Basic Auth authentication methods.
+
+### 2. apiProperties.json
+- **Purpose**: This file defines connector metadata, authentication configurations, and policy configurations.
+- **Key Components**:
+  - **Connection Parameters**: These support various authentication types including OAuth, API Key, and Gateway configurations.
+  - **Policy Template Instances**: These handle data transformation and routing policies for the connector.
+  - **Connector Metadata**: This includes publisher information, capabilities, and branding elements.
+
+### 3. settings.json
+- **Purpose**: This file provides environment and deployment configuration settings for the paconn tool.
+- **Configuration Options**:
+  - Environment GUID targeting for specific Power Platform environments.
+  - File path mappings for connector assets and configuration files.
+  - API endpoint URLs for both production and testing environments (PROD/TIP1).
+  - API version specifications to ensure compatibility with Power Platform services.
+
+## Development Guidelines
+
+### When Working with API Definitions (Swagger)
+1. **Always validate against Swagger 2.0 spec** - The schema enforces strict Swagger 2.0 compliance
+
+2. **Microsoft Extensions for Operations**:
+   - `x-ms-summary`: Use this to provide user-friendly display names and ensure you use title case formatting.
+   - `x-ms-visibility`: Use this to control parameter visibility with values of `important`, `advanced`, or `internal`.
+   - `x-ms-trigger`: Use this to mark operations as triggers with values of `batch` or `single`.
+   - `x-ms-trigger-hint`: Use this to provide helpful hint text that guides users when working with triggers.
+   - `x-ms-trigger-metadata`: Use this to define trigger configuration settings including kind and mode properties.
+   - `x-ms-notification`: Use this to configure webhook operations for real-time notifications.
+   - `x-ms-pageable`: Use this to enable pagination functionality by specifying the `nextLinkName` property.
+   - `x-ms-safe-operation`: Use this to mark POST operations as safe when they don't have side effects.
+   - `x-ms-no-generic-test`: Use this to disable automatic testing for specific operations.
+   - `x-ms-operation-context`: Use this to configure operation simulation settings for testing purposes.
+
+3. **Microsoft Extensions for Parameters**:
+   - `x-ms-dynamic-list`: Use this to enable dynamic dropdown lists populated from API calls.
+   - `x-ms-dynamic-values`: Use this to configure dynamic value sources that populate parameter options.
+   - `x-ms-dynamic-tree`: Use this to create hierarchical selectors for nested data structures.
+   - `x-ms-dynamic-schema`: Use this to allow runtime schema changes based on user selections.
+   - `x-ms-dynamic-properties`: Use this for dynamic property configuration that adapts to context.
+   - `x-ms-enum-values`: Use this to provide enhanced enum definitions with display names for better user experience.
+   - `x-ms-test-value`: Use this to provide sample values for testing, but never include secrets or sensitive data.
+   - `x-ms-trigger-value`: Use this to specify values specifically for trigger parameters with `value-collection` and `value-path` properties.
+   - `x-ms-url-encoding`: Use this to specify URL encoding style as either `single` or `double` (defaults to `single`).
+   - `x-ms-parameter-location`: Use this to provide parameter location hints for the API (AutoRest extension - ignored by Power Platform).
+   - `x-ms-localizeDefaultValue`: Use this to enable localization for default parameter values.
+   - `x-ms-skip-url-encoding`: Use this to skip URL encoding for path parameters (AutoRest extension - ignored by Power Platform).
+
+4. **Microsoft Extensions for Schemas**:
+   - `x-ms-notification-url`: Use this to mark a schema property as a notification URL for webhook configurations.
+   - `x-ms-media-kind`: Use this to specify the media type for content, with supported values of `image` or `audio`.
+   - `x-ms-enum`: Use this to provide enhanced enum metadata (AutoRest extension - ignored by Power Platform).
+   - Note that all parameter extensions listed above also apply to schema properties and can be used within schema definitions.
+
+5. **Root-Level Extensions**:
+   - `x-ms-capabilities`: Use this to define connector capabilities such as file-picker and testConnection functionality.
+   - `x-ms-connector-metadata`: Use this to provide additional connector metadata beyond the standard properties.
+   - `x-ms-docs`: Use this to configure documentation settings and references for the connector.
+   - `x-ms-deployment-version`: Use this to track version information for deployment management.
+   - `x-ms-api-annotation`: Use this to add API-level annotations for enhanced functionality.
+
+6. **Path-Level Extensions**:
+   - `x-ms-notification-content`: Use this to define notification content schemas for webhook path items.
+
+7. **Operation-Level Capabilities**:
+   - `x-ms-capabilities` (at operation level): Use this to enable operation-specific capabilities such as `chunkTransfer` for large file transfers.
+
+8. **Security Considerations**:
+   - You should define appropriate `securityDefinitions` for your API to ensure proper authentication.
+   - **Multiple security definitions are allowed** - you can define up to two auth methods (e.g., oauth2 + apiKey, basic + apiKey).
+   - **Exception**: If using "None" authentication, no other security definitions can be present in the same connector.
+   - You should use `oauth2` for modern APIs, `apiKey` for simple token authentication, and consider `basic` auth only for internal/legacy systems.
+   - Each security definition must be exactly one type (this constraint is enforced by oneOf validation).
+
+9. **Parameter Best Practices**:
+   - You should use descriptive `description` fields to help users understand each parameter's purpose.
+   - You should implement `x-ms-summary` for better user experience (title case is required).
+   - You must mark required parameters correctly to ensure proper validation.
+   - You should use appropriate `format` values (including Power Platform extensions) to enable proper data handling.
+   - You should leverage dynamic extensions for better user experience and data validation.
+
+10. **Power Platform Format Extensions**:
+   - `date-no-tz`: This represents a date-time that has no time-offset information.
+   - `html`: This format tells clients to emit an HTML editor when editing and an HTML viewer when viewing content.
+   - Standard formats include: `int32`, `int64`, `float`, `double`, `byte`, `binary`, `date`, `date-time`, `password`, `email`, `uri`, `uuid`.
+
+### When Working with API Properties
+1. **Connection Parameters**:
+   - You should choose appropriate parameter types such as `string`, `securestring`, or `oauthSetting`.
+   - You should configure OAuth settings with correct identity providers.
+   - You should use `allowedValues` for dropdown options when appropriate.
+   - You should implement parameter dependencies when needed for conditional parameters.
+
+2. **Policy Templates**:
+   - You should use `routerequesttoendpoint` for backend routing to different API endpoints.
+   - You should implement `setqueryparameter` for setting default values on query parameters.
+   - You should use `updatenextlink` for pagination scenarios to handle paging correctly.
+   - You should apply `pollingtrigger` for trigger operations that require polling behavior.
+
+3. **Branding and Metadata**:
+   - You must always specify `iconBrandColor` as this property is required for all connectors.
+   - You should define appropriate `capabilities` to specify whether your connector supports actions or triggers.
+   - You should set meaningful `publisher` and `stackOwner` values to identify the connector's ownership.
+
+### When Working with Settings
+1. **Environment Configuration**:
+   - You should use proper GUID format for `environment` that matches the validation pattern.
+   - You should set correct `powerAppsUrl` and `flowUrl` for your target environment.
+   - You should match API versions to your specific requirements.
+
+2. **File References**:
+   - You should maintain consistent file naming with the defaults of `apiProperties.json` and `apiDefinition.swagger.json`.
+   - You should use relative paths for local development environments.
+   - You should ensure icon file exists and is properly referenced in your configuration.
+
+## Schema Validation Rules
+
+### Required Properties
+- **API Definition**: `swagger: "2.0"`, `info` (with `title` and `version`), `paths`
+- **API Properties**: `properties` with `iconBrandColor`
+- **Settings**: No required properties (all optional with defaults)
+
+### Pattern Validation
+- **Vendor Extensions**: Must match `^x-(?!ms-)` pattern for non-Microsoft extensions
+- **Path Items**: Must start with `/` for API paths
+- **Environment GUID**: Must match UUID format pattern `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`
+- **URLs**: Must be valid URIs for endpoint configurations
+- **Host Pattern**: Must match `^[^{}/ :\\\\]+(?::\\d+)?$` (no spaces, protocols, or paths)
+
+### Type Constraints
+- **Security Definitions**:
+  - Up to two security definitions allowed in `securityDefinitions` object
+  - Each individual security definition must be exactly one type (oneOf validation: `basic`, `apiKey`, `oauth2`)
+  - **Exception**: "None" authentication cannot coexist with other security definitions
+- **Parameter Types**: Limited to specific enum values (`string`, `number`, `integer`, `boolean`, `array`, `file`)
+- **Policy Templates**: Type-specific parameter requirements
+- **Format Values**: Extended set including Power Platform formats
+- **Visibility Values**: Must be one of `important`, `advanced`, or `internal`
+- **Trigger Types**: Must be `batch` or `single`
+
+### Additional Validation Rules
+- **$ref References**: Should only point to `#/definitions/`, `#/parameters/`, or `#/responses/`
+- **Path Parameters**: Must be marked as `required: true`
+- **Info Object**: Description should be different from title
+- **Contact Object**: Email must be valid email format, URL must be valid URI
+- **License Object**: Name is required, URL must be valid URI if provided
+- **External Docs**: URL is required and must be valid URI
+- **Tags**: Must have unique names within the array
+- **Schemes**: Must be valid HTTP schemes (`http`, `https`, `ws`, `wss`)
+- **MIME Types**: Must follow valid MIME type format in `consumes` and `produces`
+
+## Common Patterns and Examples
+
+### API Definition Examples
+
+#### Basic Operation with Microsoft Extensions
+```json
+{
+  "get": {
+    "operationId": "GetItems",
+    "summary": "Get items",
+    "x-ms-summary": "Get Items",
+    "x-ms-visibility": "important",
+    "description": "Retrieves a list of items from the API",
+    "parameters": [
+      {
+        "name": "category",
+        "in": "query",
+        "type": "string",
+        "x-ms-summary": "Category",
+        "x-ms-visibility": "important",
+        "x-ms-dynamic-values": {
+          "operationId": "GetCategories",
+          "value-path": "id",
+          "value-title": "name"
+        }
+      }
+    ],
+    "responses": {
+      "200": {
+        "description": "Success",
+        "x-ms-summary": "Success",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "x-ms-summary": "Items",
+              "items": {
+                "$ref": "#/definitions/Item"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Trigger Operation Configuration
+```json
+{
+  "get": {
+    "operationId": "WhenItemCreated",
+    "x-ms-summary": "When an Item is Created",
+    "x-ms-trigger": "batch",
+    "x-ms-trigger-hint": "To see it work now, create an item",
+    "x-ms-trigger-metadata": {
+      "kind": "query",
+      "mode": "polling"
+    },
+    "x-ms-pageable": {
+      "nextLinkName": "@odata.nextLink"
+    }
+  }
+}
+```
+
+#### Dynamic Schema Example
+```json
+{
+  "name": "dynamicSchema",
+  "in": "body",
+  "schema": {
+    "x-ms-dynamic-schema": {
+      "operationId": "GetSchema",
+      "parameters": {
+        "table": {
+          "parameter": "table"
+        }
+      },
+      "value-path": "schema"
+    }
+  }
+}
+```
+
+#### File Picker Capability
+```json
+{
+  "x-ms-capabilities": {
+    "file-picker": {
+      "open": {
+        "operationId": "OneDriveFilePickerOpen",
+        "parameters": {
+          "dataset": {
+            "value-property": "dataset"
+          }
+        }
+      },
+      "browse": {
+        "operationId": "OneDriveFilePickerBrowse",
+        "parameters": {
+          "dataset": {
+            "value-property": "dataset"
+          }
+        }
+      },
+      "value-title": "DisplayName",
+      "value-collection": "value",
+      "value-folder-property": "IsFolder",
+      "value-media-property": "MediaType"
+    }
+  }
+}
+```
+
+#### Test Connection Capability (Note: Not Supported for Custom Connectors)
+```json
+{
+  "x-ms-capabilities": {
+    "testConnection": {
+      "operationId": "TestConnection",
+      "parameters": {
+        "param1": "literal-value"
+      }
+    }
+  }
+}
+```
+
+#### Operation Context for Simulation
+```json
+{
+  "x-ms-operation-context": {
+    "simulate": {
+      "operationId": "SimulateOperation",
+      "parameters": {
+        "param1": {
+          "parameter": "inputParam"
+        }
+      }
+    }
+  }
+}
+```
+
+### Basic OAuth Configuration
+```json
+{
+  "type": "oauthSetting",
+  "oAuthSettings": {
+    "identityProvider": "oauth2",
+    "clientId": "your-client-id",
+    "scopes": ["scope1", "scope2"],
+    "redirectMode": "Global"
+  }
+}
+```
+
+#### Multiple Security Definitions Example
+```json
+{
+  "securityDefinitions": {
+    "oauth2": {
+      "type": "oauth2",
+      "flow": "accessCode",
+      "authorizationUrl": "https://api.example.com/oauth/authorize",
+      "tokenUrl": "https://api.example.com/oauth/token",
+      "scopes": {
+        "read": "Read access",
+        "write": "Write access"
+      }
+    },
+    "apiKey": {
+      "type": "apiKey",
+      "name": "X-API-Key",
+      "in": "header"
+    }
+  }
+}
+```
+
+**Note**: Maximum of two security definitions can coexist, but "None" authentication cannot be combined with other methods.
+
+### Dynamic Parameter Setup
+```json
+{
+  "x-ms-dynamic-values": {
+    "operationId": "GetItems",
+    "value-path": "id",
+    "value-title": "name"
+  }
+}
+```
+
+### Policy Template for Routing
+```json
+{
+  "templateId": "routerequesttoendpoint",
+  "title": "Route to backend",
+  "parameters": {
+    "x-ms-apimTemplate-operationName": ["GetData"],
+    "x-ms-apimTemplateParameter.newPath": "/api/v2/data"
+  }
+}
+```
+
+## Best Practices
+
+1. **Use IntelliSense**: These schemas provide rich autocomplete and validation capabilities that help during development.
+2. **Follow Naming Conventions**: Use descriptive names for operations and parameters to improve code readability.
+3. **Implement Error Handling**: Define appropriate response schemas and error codes to handle failure scenarios properly.
+4. **Test Thoroughly**: Validate schemas before deployment to catch issues early in the development process.
+5. **Document Extensions**: Comment Microsoft-specific extensions for team understanding and future maintenance.
+6. **Version Management**: Use semantic versioning in API info to track changes and compatibility.
+7. **Security First**: Always implement appropriate authentication mechanisms to protect your API endpoints.
+
+## Troubleshooting
+
+### Common Schema Violations
+- **Missing required properties**: `swagger: "2.0"`, `info.title`, `info.version`, `paths`
+- **Invalid pattern formats**:
+  - GUIDs must match exact format `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`
+  - URLs must be valid URIs with proper scheme
+  - Paths must start with `/`
+  - Host must not include protocol, paths, or spaces
+- **Incorrect vendor extension naming**: Use `x-ms-*` for Microsoft extensions, `^x-(?!ms-)` for others
+- **Mismatched security definition types**: Each security definition must be exactly one type
+- **Invalid enum values**: Check allowed values for `x-ms-visibility`, `x-ms-trigger`, parameter types
+- **$ref pointing to invalid locations**: Must point to `#/definitions/`, `#/parameters/`, or `#/responses/`
+- **Path parameters not marked as required**: All path parameters must have `required: true`
+- **Type 'file' in wrong context**: Only allowed in `formData` parameters, not in schemas
+
+### API Definition Specific Issues
+- **Dynamic schema conflicts**: Can't use `x-ms-dynamic-schema` with fixed schema properties
+- **Trigger configuration errors**: `x-ms-trigger-metadata` requires both `kind` and `mode`
+- **Pagination setup**: `x-ms-pageable` requires `nextLinkName` property
+- **File picker misconfiguration**: Must include both `open` operation and required properties
+- **Capability conflicts**: Some capabilities may conflict with certain parameter types
+- **Test value security**: Never include secrets or PII in `x-ms-test-value`
+- **Operation context setup**: `x-ms-operation-context` requires a `simulate` object with `operationId`
+- **Notification content schema**: Path-level `x-ms-notification-content` must define proper schema structure
+- **Media kind restrictions**: `x-ms-media-kind` only supports `image` or `audio` values
+- **Trigger value configuration**: `x-ms-trigger-value` must have at least one property (`value-collection` or `value-path`)
+
+### Validation Tools
+- Use JSON Schema validators to check your schema definitions for compliance.
+- Leverage VS Code's built-in schema validation to catch errors during development.
+- Test with paconn CLI before deployment using: `paconn validate --api-def apiDefinition.swagger.json`
+- Validate against Power Platform connector requirements to ensure compatibility.
+- Use the Power Platform Connector portal for validation and testing in the target environment.
+- Check that operation responses match expected schemas to prevent runtime errors.
+
+Remember: These schemas ensure your Power Platform connectors are properly formatted and will work correctly in the Power Platform ecosystem.

package/assets/instructions/power-platform-mcp-development.instructions.md

@@ -0,0 +1,88 @@
+---
+description: 'Instructions for developing Power Platform custom connectors with Model Context Protocol (MCP) integration for Microsoft Copilot Studio'
+applyTo: '**/*.{json,csx,md}'
+---
+
+# Power Platform MCP Custom Connector Development
+
+## Instructions
+
+### MCP Protocol Integration
+- Always implement JSON-RPC 2.0 standard for MCP communication
+- Use `x-ms-agentic-protocol: mcp-streamable-1.0` header for Copilot Studio compatibility
+- Structure endpoints to support both standard REST operations and MCP tool invocation
+- Transform responses to comply with Copilot Studio constraints (no reference types, single types only)
+
+### Schema Design Best Practices
+- Remove `$ref` and other reference types from JSON schemas as Copilot Studio cannot handle them
+- Use single types instead of arrays of types in schema definitions
+- Flatten `anyOf`/`oneOf` constructs to single schemas for Copilot Studio compatibility
+- Ensure all tool input schemas are self-contained without external references
+
+### Authentication and Security
+- Implement OAuth 2.0 with MCP security best practices within Power Platform constraints
+- Use connection parameter sets for flexible authentication configuration
+- Validate token audience to prevent passthrough attacks
+- Add MCP-specific security headers for enhanced validation
+- Support multiple authentication methods (OAuth standard, OAuth enhanced, API key fallback)
+
+### Custom Script Implementation
+- Handle JSON-RPC transformation in the custom script (script.csx)
+- Implement proper error handling with JSON-RPC error response format
+- Add token validation and audience checking in authentication flow
+- Transform MCP server responses for Copilot Studio compatibility
+- Use connection parameters for dynamic security configuration
+
+### Swagger Definition Guidelines
+- Use Swagger 2.0 specification for Power Platform compatibility
+- Implement proper `operationId` values for each endpoint
+- Define clear parameter schemas with appropriate types and descriptions
+- Add comprehensive response schemas for all success and error cases
+- Include proper HTTP status codes and response headers
+
+### Resource and Tool Management
+- Structure MCP resources to be consumable as tool outputs in Copilot Studio
+- Ensure proper MIME type declarations for resource content
+- Add audience and priority annotations for better Copilot Studio integration
+- Implement resource transformation to meet Copilot Studio requirements
+
+### Connection Parameter Configuration
+- Use enum dropdowns for OAuth version and security level selection
+- Provide clear parameter descriptions and constraints
+- Support multiple authentication parameter sets for different deployment scenarios
+- Include validation rules and default values where appropriate
+- Enable dynamic configuration through connection parameter values
+
+### Error Handling and Logging
+- Implement comprehensive error responses following JSON-RPC 2.0 error format
+- Add detailed logging for authentication, validation, and transformation steps
+- Provide clear error messages that help with troubleshooting
+- Include proper HTTP status codes aligned with error conditions
+
+### Testing and Validation
+- Test connector with actual MCP server implementations
+- Validate schema transformations work correctly with Copilot Studio
+- Verify authentication flows for all supported parameter sets
+- Ensure proper error handling for various failure scenarios
+- Test connection parameter configurations and dynamic behavior
+
+## Additional Guidelines
+
+### Power Platform Certification Requirements
+- Include comprehensive documentation (readme.md, CUSTOMIZE.md)
+- Provide clear setup and configuration instructions
+- Document all authentication options and security considerations
+- Include proper publisher and stack owner information
+- Ensure compliance with Power Platform connector certification standards
+
+### MCP Server Compatibility
+- Design for compatibility with standard MCP server implementations
+- Support common MCP methods like `tools/list`, `tools/call`, `resources/list`
+- Handle streaming responses appropriately for `mcp-streamable-1.0` protocol
+- Implement proper protocol negotiation and capability detection
+
+### Copilot Studio Integration
+- Ensure tool definitions work correctly within Copilot Studio's constraints
+- Test resource access and tool invocation from Copilot Studio interface
+- Validate that transformed schemas produce expected behavior in conversations
+- Confirm proper integration with Copilot Studio's agent framework