add-workiq

**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** - Cross-cutting concerns. # Add Work IQ (M365 Copilot Search) Work IQ is accessed through the dedicated **Work IQ Copilot MCP** connector (`shared_a365copilotchatmcp`; shown as "Work IQ Copilot MCP (Preview)" in the maker portal). It exposes an MCP (Model Context Protocol) endpoint whose `CopilotChat` tool performs AI-powered, knowledge-grounded search and conversation over Microsoft 365 content. > This is the purpose-built Work IQ connector and generates a `WorkIQCopilotMCPService` with a single `mcp_m365copilot` operation. **Every command and code reference in this skill is specific to `shared_a365copilotchatmcp`** (connection commands, and the generated `WorkIQCopilotMCPService` / `WorkIQCopilotMCPModel` files). Do not run this skill for a different connector. If you instead need the broader `shared_a365mcpservers` "Microsoft 365 MCP Servers" bundle (Mail/Teams/SharePoint MCP servers), add it via `/add-connector` — its generated service is `MicrosoftMCPServersService`, so you must adjust the Step 2 commands and the wrapper imports accordingly. > ⚠️ **Work IQ uses MCP.** A JSON-RPC `initialize` handshake runs before the first `tools/call`. This connector's server (`Microsoft.MCPPlatform.WebApi`) is **stateless-tolerant** — do **NOT** send an `Mcp-Session-Id` on `initialize` (the server treats it as a session lookup and returns `-32001 Session not found`). Drive the connector through the `McpSession` wrapper below, which runs the handshake, sends **no** session id by default, sequences JSON-RPC ids, auto-retries on `Session not found`, and parses the nested response for you. ## Workflow 1. Check Memory Bank → 2. Add Connector → 3. Inspect Generated Service → 4. Create McpSession Wrapper → 5. Use Work IQ → 6. Build → 7. Update Memory Bank --- ### Step 1: Check Memory Bank Check for `memory-bank.md` per [shared-instructions.md](../../shared/shared-instructions.md). ### Step 2: Add Connector The Power Apps code-app CLI (`@microsoft/power-apps-cli`, invoked as `pa` or `power-apps` — resolve via [cli-binary.md](../../shared/cli-binary.md)) adds the data source and generates the typed service. Make sure the CLI is installed in the project (see cli-binary.md) and you are signed in (`pa auth status`, or `power-apps auth-status` on `power-apps`-only projects; it shares the same auth as the rest of the code-app skills). Work IQ is a **non-tabular** connector (api id `shared_a365copilotchatmcp`, shown as **Work IQ Copilot MCP (Preview)**). Get its connection as described in [connector-reference.md](../../shared/connector-reference.md#connections). #### CLI 1.3.0+ (`PA_INLINE_CONNECTIONS=yes`) Tell the user that adding Work IQ may create a connection with their account, then run the add without `-c`: ```bash pa app add data-source --connector shared_a365copilotchatmcp --non-interactive ``` Handle the result with the outcome table in connector-reference.md. Work IQ supports single sign-on, so when the user has no Work IQ connection the CLI either creates one itself or suggests `--use-sso`; with the user's OK, re-run with `--use-sso`. #### Older CLIs: Find or Create the Connection **Check for an existing connection first:** ```bash pa connection list ``` Look for a **Work IQ Copilot MCP (Preview)** connection (api id `shared_a365copilotchatmcp`) in the output. If one is listed, note its Connection ID and skip to "Older CLIs: Add the Data Source" below. **Otherwise create one**, after asking the user, with the native `create-connection` verb: ```bash pa connection create --connector shared_a365copilotchatmcp ``` - The environment is read automatically from the app's `power.config.json` — you do **not** need to pass an environment id. - If the connection needs a browser sign-in, the CLI can only do that from an interactive terminal. If it says so, follow [Create a connection with the user](../../shared/connector-reference.md#create-a-connection-with-the-user): the user runs the same command in their own terminal. - On success it prints the **Connection ID** — save it for the next step. **STOP HERE if a browser sign-in is needed:** 1. Tell the user the browser has opened (or ask them to run the command in their own terminal). 2. Ask them to sign in with their Microsoft 365 account and grant consent to the **Work IQ Copilot MCP** connector. 3. **Wait for the user to confirm** the browser shows success before continuing. **If `create-connection` fails:** - "not signed in" / auth error → run `pa auth login` (or `power-apps login` on `power-apps`-only projects), then retry. - "Connection creation was cancelled." → the browser flow was closed early; re-run and complete it. - Any other non-zero exit → report the exact error and STOP. As a fallback, the user can create the connection manually in the maker portal: `https://make.powerapps.com/environments/<environment-id>/connections` → **+ New connection** → search for "Work IQ Copilot MCP" → Create, then re-run `list-connections`. #### Older CLIs: Add the Data Source Once the connection exists, add it to the code app (this is what generates the typed service + model): ```bash pa app add data-source --connector shared_a365copilotchatmcp -c <connection-id> ``` This is a **non-tabular** connector — only `--connector` (api id) and `-c` (connection id) are needed. ### Step 3: Inspect Generated Service After adding the connector, confirm the generated service is present. This is a small, single-operation service, so you can read it directly or grep it: ``` Grep pattern="async \w+" path="src/generated/services/WorkIQCopilotMCPService.ts" ``` The `WorkIQCopilotMCPService` exposes exactly one operation — **`mcp_m365copilot`** ("Work IQ Copilot (Preview)"), plus a `Getmcp_m365copilot` GET variant used only for connection verification. Work IQ / CopilotChat is driven through **`mcp_m365copilot`**. Its generated signature is: ```typescript public static async mcp_m365copilot( Mcp_Session_Id?: string, queryRequest?: QueryRequest ): Promise<IOperationResult<void>> ``` - First argument is the **MCP session id** (the connector's `Mcp-Session-Id` parameter). Leave it **`undefined`** — this server assigns/needs no client session id, and sending one on `initialize` returns `-32001` (see below). - Second argument is the JSON-RPC body, typed as `QueryRequest` (`{ jsonrpc?, id?, method?, params?, result?, error? }`) — exported from `src/generated/models/WorkIQCopilotMCPModel.ts`. - Return type is `IOperationResult<void>`; the actual JSON-RPC / SSE body arrives in `result.data` at runtime. **Facts you can rely on (do not try to discover them at runtime):** - The tool name is **`CopilotChat`** (case-sensitive). Do not substitute `query`, `search`, or `find`. - The argument key is **`message`** — not `query`, `prompt`, or `question`. - **Do NOT send an `Mcp-Session-Id` on the `initialize` handshake.** This connector's server treats an incoming id as an existing-session lookup and returns `-32001 Session not found`. The server is **stateless-tolerant**: `initialize` and `tools/call` both succeed with **no** session id, so the `McpSession` wrapper below tracks none by default. > **Session-id handling (verified during testing).** This connector's MCP server is **stateless-tolerant**. `initialize` with **no** `Mcp-Session-Id` returns `200` with server capabilities, and a subsequent `tools/call` with **no** id returns the Copilot reply — no session id needs to be tracked or echoed. Do **not** generate a client id and send it on `initialize`: the server treats it as a lookup and returns `404 / -32001 Session not found` (this was a real bug in an earlier version of this wrapper). Note that the code-apps data layer's `IOperationResult<TResponse>` exposes only `{ success, data, error, skipToken, count, fileName }` — it does **not** surface response headers — so if a future MCP server returns a session id only in the `Mcp-Session-Id` **response header**, it would be unreadable here. The wrapper still defensively adopts a server id if one ever appears inside `result.data`. ### Step 4: Create McpSession Wrapper ⚠️ **CRITICAL:** MCP session handling and response parsing are intricate. Copy the production-ready `McpSession` class below **exactly**. It runs the `initialize` handshake (sending **no** session id), sequences JSON-RPC ids, auto-retries on "Session not found", persists the conversation id, and parses the deeply nested response. Create `src/connectors/mcpClient.ts`: ```typescript // src/connectors/mcpClient.ts import type { IOperationResult } from '@microsoft/power-apps/data' import { WorkIQCopilotMCPService } from '../generated/services/WorkIQCopilotMCPService' import type { QueryRequest } from '../generated/models/WorkIQCopilotMCPModel' export interface JsonRpcRequest { jsonrpc: '2.0' id?: string method: string params?: Record<string, unknown> } export interface JsonRpcResponse { jsonrpc?: string id?: string result?: Record<string, unknown> error?: { code?: number; message?: string; data?: unknown } } type CopilotConversationMessage = { text?: string attributions?: Array<{ attributionType?: string providerDisplayName?: string seeMoreWebUrl?: string }> } type CopilotConversation = { messages?: CopilotConversationMessage[] } function parseRpc(result: IOperationResult<unknown>): JsonRpcResponse { if (!result.success && result.error) { return { error: { message: result.error.message } } } const data: unknown = result.data if (data == null) return {} if (typeof data === 'object') return data as JsonRpcResponse if (typeof data === 'string') { // Handle SSE framing: "event: message\ndata: {JSON}" const dataLines = data .split(/\r?\n/) .filter((line) => line.startsWith('data:')) .map((line) => line.slice(5).trim()) // Per the SSE spec, multiple `data:` lines are joined with newlines — a single // JSON object can be split across lines, so joining with '' would corrupt it. const payload = dataLines.length ? dataLines.join('\n') : data try { return JSON.parse(payload) as JsonRpcResponse } catch { return { result: { raw: data } } } } return { result: { raw: data } } } export class McpSession { private nextId = 1 // MCP Streamable HTTP: the client must NOT send a session id on `initialize` — // the server assigns one. Sending a client-generated id makes this connector's // server return `404 / -32001 Session not found`. This server is stateless- // tolerant, so we send no id at all; `extractSessionId` still adopts a server // id if one ever surfaces in the response body. private sessionId: string | undefined = undefined private conversationId: string | undefined private initialized = false private extractSessionId(raw: IOperationResult<unknown>): string | undefined { const container = raw as unknown as Record<string, unknown> const dataObj = raw.data && typeof raw.data === 'object' ? (raw.data as Record<string, unknown>) : undefined const resultObj = dataObj?.result && typeof dataObj.result === 'object' ? (dataObj.result as Record<string, unknown>) : undefined const candidates: Array<unknown> = [ dataObj?.['Mcp-Session-Id'], dataObj?.mcpSessionId, dataObj?.sessionId, resultObj?.['Mcp-Session-Id'], resultObj?.mcpSessionId, resultObj?.sessionId, container['Mcp-Session-Id'], container.mcpSessionId, container.sessionId, ] const found = candidates.find((value) => typeof value === 'string' && value.length > 0) return typeof found === 'string' ? found : undefined } private isSessionNotFound(res: JsonRpcResponse): boolean { const message = (res.error?.message ?? '').toLowerCase() return message.includes('session not found') || res.error?.code === -32001 } private resetSession(): void { // Drop any session id and re-handshake from scratch (no id on `initialize`). this.sessionId = undefined this.initialized = false } private async send( method: string, params?: Record<string, unknown>, allowRetry = true ): Promise<JsonRpcResponse> { const req: JsonRpcRequest = { jsonrpc: '2.0', id: String(this.nextId++), method, params } // Send no session id on `initialize` (server treats any id as existing-session lookup). const sessionId = method === 'initialize' ? undefined : this.sessionId const raw = (await WorkIQCopilotMCPService.mcp_m365copilot( sessionId, req as unknown as QueryRequest )) as unknown as IOperationResult<unknown> const negotiatedSessionId = this.extractSessionId(raw) if (negotiatedSessionId) { this.sessionId = negotiatedSessionId } const parsed = parseRpc(raw) if (allowRetry && method !== 'initialize' && this.isSessionNotFound(parsed)) { this.resetSession() await this.initialize() return this.send(method, params, false) } return parsed } async initialize(): Promise<JsonRpcResponse> { const res = await this.send('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'Power Apps Code App', version: '1.0.0' }, }) // Fail fast: surface a failed handshake instead of continuing to `tools/call`. if (res.error) { throw new Error(`MCP initialize failed: ${res.error.message ?? JSON.stringify(res.error)}`) } this.initialized = true return res } /** Discover the available MCP tools (optional; the tool name is fixed as `CopilotChat`). */ async listTools(): Promise<JsonRpcResponse> { if (!this.initialized) await this.initialize() return this.send('tools/list', {}) } async callCopilotChat(message: string): Promise<{ text: string; conversationId?: string }> { if (!this.initialized) await this.initialize() const raw = await this.send('tools/call', { name: 'CopilotChat', arguments: { message, ...(this.conversationId ? { conversationId: this.conversationId } : {}), }, }) // Surface MCP/connector errors as thrown exceptions so callers can `try/catch` // instead of string-matching the returned text. if (raw.error) { throw new Error(raw.error.message ?? JSON.stringify(raw.error)) } const parsed = extractCopilotText(raw) if (parsed.conversationId) { this.conversationId = parsed.conversationId } return { text: parsed.text, conversationId: parsed.conversationId } } } function extractContentText(res: JsonRpcResponse): string | undefined { const content = res.result?.content as Array<{ type?: string; text?: string }> | undefined if (!Array.isArray(content)) { return undefined } const textBlocks = content .filter((c) => c.type === 'text' && typeof c.text === 'string')