add-workiq

**📋 Shared Instructions: [shared-instructions.md](${PLUGIN_ROOT}/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](${PLUGIN_ROOT}/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](${PLUGIN_ROOT}/shared/cli-binary.md)) creates the connection and generates the typed service itself. Make sure the CLI is installed (`npm install`) 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).

#### 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 "Add the Data Source" below.

**Otherwise create one** 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.
- This connector requires OAuth, so the CLI **opens a browser to complete sign-in/consent** (SSO-only connectors complete silently with no browser).
- On success it prints the **Connection ID** — save it for the next step.

**STOP HERE — interactive sign-in required:**

1. Tell the user the browser has opened (or share the URL the CLI prints).
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 status` (or `power-apps auth-status` on `power-apps`-only projects), sign in if needed, and 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`.

#### 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`.
- **