MCP-enabled agent assisted process

.github/plans/plan-mcp-agentic-invocation.md

@@ -0,0 +1,140 @@
+## Plan: MCP Agentic Tool Invocation in PPTB
+
+Enable reliable MCP-driven invocation for PPTB tools with explicit one-way and two-way contracts, while reusing existing invocation plumbing. The recommended approach is to keep current windowed execution for v1, add explicit invocation mode semantics at the MCP boundary, tighten schema and security validation, and publish a clear tool-author contract plus migration guide.
+
+**Steps**
+
+1. Phase 1: Lock scope and invocation model
+
+- Define supported MCP invocation modes and map to PPTB behavior.
+  Mode A: One-way (fire-and-forget) returns immediate accepted response and does not wait for tool return payload.
+  Mode B: Two-way (request-response) waits for tool return payload via existing invocation return path.
+- Set defaults and compatibility.
+  Default to two-way for existing tools.
+  If mode is omitted but tool declares no return schema, treat as one-way.
+- Declare v1 constraints.
+  Keep execution windowed only for now.
+  No streaming partial results in v1.
+  No parallel nested invocations from a single MCP request in v1.
+
+2. Phase 2: Extend contracts and shared types
+
+- Extend invocation contract in type definitions used by tools and host.
+  Add optional mode capabilities in InvocationConfig so each tool can declare allowed agent invocation modes and expected timeout behavior.
+- Extend MCP request contract in server code.
+  Add invocation metadata fields in MCP tool input envelope (for example mode and optional timeout), while preserving backward compatibility with existing prefill schema.
+- Extend schema conversion and registry output.
+  Expose mode support and return expectations in MCP tool descriptions and input schema hints so agents can choose one-way vs two-way correctly.
+
+3. Phase 3: Main-process orchestration changes
+
+- Add MCP invocation mode routing in McpServerManager.
+  One-way path: validate input, launch tool, return accepted result quickly, log correlation id.
+  Two-way path: validate input, launch tool, await returnData result, return structured payload.
+- Reuse ToolWindowManager launch-with-context pipeline.
+  Pass a normalized invocation context including source mcp, mode, correlation id, caller metadata, and timeout envelope.
+- Add timeout and cancellation guardrails.
+  Two-way: enforce per-request timeout and deterministic timeout response.
+  One-way: optional launch timeout only.
+- Add stronger input and output validation.
+  Validate MCP input against converted prefill schema before launch.
+  For two-way mode, validate return payload against returnTopic before responding.
+
+4. Phase 4: Security, auditability, and policy
+
+- Harden tool eligibility checks.
+  Require invocation.agentInvokable true and explicit support for requested mode.
+  Reject mode mismatches with actionable errors.
+- Expand audit logging.
+  Log mode, tool id, correlation id, duration, outcome, schema-validation result, and timeout/cancel reasons.
+- Redaction policy.
+  Ensure sensitive connection-related fields are redacted from invocation logs and MCP error surfaces.
+
+5. Phase 5: Tool runtime surface and compatibility helpers
+
+- Keep existing tool runtime APIs as primary contract.
+  Tools continue to use getLaunchContext and returnData.
+- Add optional invocation metadata to launch context.
+  Include source, mode, correlation id, requested timeout, and expectsResponse boolean so tools can branch behavior safely.
+- Add optional helper semantics.
+  If mode is one-way, returnData is optional and ignored for MCP response lifecycle.
+  If mode is two-way, returnData remains required for successful completion.
+
+6. Phase 6: Documentation and tool-author rollout
+
+- Update inter-tool and MCP docs with normative behavior.
+  Document exact one-way and two-way semantics, error codes, timeout behavior, and compatibility rules.
+- Publish tool-author migration guide.
+  Provide minimal manifest and runtime changes required per mode, plus test checklist.
+- Add validation guidance.
+  Extend docs and validator messaging so tool authors get warnings for inconsistent invocation declarations.
+
+7. Phase 7: Verification via MCP Inspector
+
+- External harness.
+  Use MCP Inspector to exercise list-tools and call-tool flows instead of adding a repository test runner for this phase.
+- Manual checks.
+  Verify one-way and two-way behavior, unsupported mode errors, and timeout handling with MCP Inspector.
+- Regression checks.
+  Existing inter-tool invocation from toolboxAPI remains unchanged.
+- Build gates.
+  Run typecheck, lint, and build before merge.
+
+**Relevant files**
+
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/mcp/mcpServer.ts — add MCP mode routing, timeout handling, validation orchestration, and response shaping.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/mcp/agentToolRegistry.ts — enrich exposed agent tool metadata with supported invocation modes and constraints.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/mcp/schemaConverter.ts — include mode-related schema hints and compatibility mapping.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/mcp/agentInvocationLogger.ts — add correlation-rich, redacted mode-aware logs.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/managers/toolWindowManager.ts — pass normalized invocation context and enforce launch/return lifecycle constraints.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/main/toolPreloadBridge.ts — ensure invocation context metadata reaches tools without breaking existing API.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/src/common/ipc/channels.ts — add any new channel constants only if needed for explicit mode/timeout signaling.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/packages/types/pptbConfig.d.ts — extend InvocationConfig with mode support declarations and optional timeout policy fields.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/packages/types/toolboxAPI.d.ts — document/extend invocation context typing for source and mode metadata.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/docs/INTER_TOOL_INVOCATION.md — add MCP normative section for one-way and two-way.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/docs/IMPLEMENTATION_CHECKLIST.md — add rollout and validation checklist for agentic invocation readiness.
+- /Users/danish/SourceCode/GitHub/PowerPlatformToolBox/desktop-app/README.md — link to tool-author guidance and MCP enablement overview.
+
+**Verification**
+
+1. Type and lint gates
+   Run pnpm run typecheck and pnpm run lint.
+1. Build gate
+   Run pnpm run build.
+1. MCP discovery verification
+   Call MCP list-tools and verify only tools with agentInvokable true appear and mode metadata is present.
+1. One-way invocation verification
+   Invoke a one-way-enabled tool through MCP, confirm immediate accepted response, confirm tool launch and completion in logs.
+1. Two-way invocation verification
+   Invoke a two-way-enabled tool through MCP with valid input, confirm returned payload is schema-valid and surfaced to MCP caller.
+1. Negative-path verification
+   Attempt mode not supported by tool, invalid prefill shape, and timeout scenario; confirm deterministic error codes and redacted logs.
+1. Regression verification
+   Run an existing tool-to-tool invocation flow from UI to ensure legacy launchTool behavior remains intact.
+
+**Decisions**
+
+- Included scope: MCP-triggered one-way and two-way invocation semantics, schema validation hardening, logging, and tool-author contract updates.
+- Excluded scope: headless execution mode, streaming partial responses, generalized workflow orchestration across multiple tools, and non-windowed runtime.
+- Compatibility rule: existing tools continue to work without changes; new declaration fields are optional with safe defaults.
+
+**Tool-side changes required**
+
+1. Manifest updates
+   Each tool that should be MCP-callable keeps invocation.agentInvokable true and declares supported invocation mode(s) plus accurate prefill and returnTopic schemas.
+1. Runtime handling for one-way tools
+   Tool reads launch context and performs action without assuming caller waits for return data. returnData may be omitted unless needed for local flow.
+1. Runtime handling for two-way tools
+   Tool must call returnData with payload matching returnTopic schema before completing user flow.
+1. Connection assumptions
+   Tools must not assume inherited secondary connection unless declared and selected; handle nulls explicitly.
+1. Validation hygiene
+   Tool output should remain stable and schema-aligned; avoid returning ad-hoc fields not in returnTopic for two-way flows.
+1. UX behavior
+   Because v1 is windowed, tools should render minimal actionable UI for agent-driven launches and auto-complete where safe.
+
+**Further Considerations**
+
+1. Decide whether one-way MCP responses should be pure accepted acknowledgements or include lightweight launch metadata such as correlation id and started timestamp. Recommendation: include correlation id for observability.
+2. Decide timeout defaults globally vs per-tool override in manifest. Recommendation: global default with optional per-tool override.
+3. Decide whether to treat missing returnTopic as implicit one-way eligibility. Recommendation: allow only when tool explicitly declares one-way support to avoid ambiguity.

README.md

@@ -127,6 +127,8 @@
 > [!IMPORTANT]
 > Full documentation of the toolbox including How tos, FAQs, architecture, design & security principles is available on our main website [https://docs.powerplatformtoolbox.com/](https://docs.powerplatformtoolbox.com/)
 
+For tool authors working on inter-tool or MCP-based invocation, start with [docs/INTER_TOOL_INVOCATION.md](docs/INTER_TOOL_INVOCATION.md), [docs/MCP_IMPLEMENTATION.md](docs/MCP_IMPLEMENTATION.md), and [docs/MCP_TOOL_AUTHOR_MIGRATION.md](docs/MCP_TOOL_AUTHOR_MIGRATION.md).
+
 ## Releases & Downloads
 
 Power Platform ToolBox releases are published on GitHub:

docs/INTER_TOOL_INVOCATION.md

@@ -25,6 +25,10 @@ This document covers the **Inter-Tool Invocation** feature of Power Platform Too
         - [2.4 Tag-based capability discovery](#24-tag-based-capability-discovery)
             - [Well-known capability tags](#well-known-capability-tags)
         - [2.5 Complete caller example](#25-complete-caller-example)
+        - [Part 3 – MCP Agentic Invocation](#part-3--mcp-agentic-invocation)
+            - [3.1 Where MCP fits](#31-where-mcp-fits)
+            - [3.2 What tool authors need to do](#32-what-tool-authors-need-to-do)
+            - [3.3 Validation and rollout](#33-validation-and-rollout)
     - [End-to-End Scenario: FXS "Send To" Flyout](#end-to-end-scenario-fxs-send-to-flyout)
         - [Scenario summary](#scenario-summary)
         - [Step 1 – Callee tools declare the `"fetchxml"` capability](#step-1--callee-tools-declare-the-fetchxml-capability)
@@ -238,6 +242,41 @@ The following is a minimal but complete callee implementation for an entity-pick
 }
 ```
 
+---
+
+## Part 3 – MCP Agentic Invocation
+
+### 3.1 Where MCP fits
+
+MCP agentic invocation is a separate contract from PPTB-to-PPTB tool invocation.
+
+- Inter-tool invocation uses `toolboxAPI.invocation.launchTool()`, `getLaunchContext()`, and `returnData()` between PPTB tools.
+- MCP invocation uses the built-in MCP server to expose selected tools to external agents.
+- The runtime pipeline is shared, but the caller contract and discovery metadata are different.
+
+If you are publishing a tool for external automation, read [MCP Implementation](MCP_IMPLEMENTATION.md) and the migration guide at [MCP Tool Author Migration](MCP_TOOL_AUTHOR_MIGRATION.md).
+
+### 3.2 What tool authors need to do
+
+Tool authors do not need to change the core BrowserView runtime for Phase 3–6 work. The required updates are:
+
+- Add an `agents` section to `pptb.config.json` with `invokable: true`.
+- Declare the supported MCP invocation modes in `agents.modes`.
+- Set `agents.defaultMode` when a tool should prefer one mode over another.
+- Set `agents.timeoutMS` when a tool needs a longer or shorter default timeout for two-way calls.
+- Keep `invocation.prefill` and `invocation.returnTopic` accurate so MCP input and output validation stays stable.
+
+### 3.3 Validation and rollout
+
+MCP Inspector is the recommended manual harness for validating the MCP surface in this repo. Use it to confirm:
+
+- the tool appears in `list-tools`
+- the supported mode hints are visible
+- one-way and two-way calls behave as expected
+- invalid modes and bad payloads return deterministic errors
+
+The repo does not require a dedicated automated MCP test runner for this phase.
+
 **`index.ts`**
 
 ```typescript
@@ -439,6 +478,8 @@ async function openEntityPicker(entityName: string) {
 
 ---
 
+For agent/MCP-specific invocation behavior, see [MCP Implementation](MCP_IMPLEMENTATION.md).
+
 ## End-to-End Scenario: FXS "Send To" Flyout
 
 This section illustrates a concrete real-world scenario where **FetchXML Studio (FXS)** exposes a "Send To ▾" flyout button that lets users push the current FetchXML query directly into another installed tool — such as **DRB** (Dataverse Rest Builder) or **DMS** (Data Migration Studio) — without expecting a return value.

docs/LOGGING_BEST_PRACTICES.md

@@ -351,6 +351,14 @@ logWarn("Connection expired", { connectionId }); // Console + Sentry always
 // Don't use captureMessage for info - it creates Issues
 ```
 
+## Invocation Log Redaction
+
+Agent invocation logs must not store raw connection identifiers or sensitive launch metadata.
+
+- Redact `connectionId`, `primaryConnectionId`, `secondaryConnectionId`, and similar fields before writing logs.
+- Redact nested prefill data fields whose names include `connection`, `token`, `secret`, `password`, `credential`, `auth`, or `refresh`.
+- Keep correlation IDs and tool names so the log still supports diagnostics without exposing secrets.
+
 ## Questions?
 
 For questions about logging:

docs/MCP_IMPLEMENTATION.md

@@ -0,0 +1,126 @@
+# MCP Implementation
+
+This document covers how Power Platform ToolBox exposes tools to external automation agents through the built-in MCP server.
+
+## Table of Contents
+
+- [MCP Implementation](#mcp-implementation)
+    - [Table of Contents](#table-of-contents)
+    - [Overview](#overview)
+    - [Agent Contract](#agent-contract)
+    - [MCP Invocation Envelope](#mcp-invocation-envelope)
+    - [Mode Semantics](#mode-semantics)
+    - [Tool Runtime Context](#tool-runtime-context)
+    - [Implementation Notes](#implementation-notes)
+    - [Validation and Troubleshooting](#validation-and-troubleshooting)
+
+## Overview
+
+External automation agents can invoke selected PPTB tools through the MCP server. PPTB keeps the execution windowed for now, but the agent boundary is explicit and separate from PPTB-to-PPTB tool invocation.
+
+## Agent Contract
+
+To expose a tool to MCP, add a top-level `agents` section in `pptb.config.json`.
+
+```json
+{
+    "invocation": {
+        "version": "1.0.0",
+        "capabilities": ["entity-picker"],
+        "prefill": {
+            "properties": {
+                "entityName": { "type": "string" },
+                "allowMultiSelect": { "type": "boolean" }
+            }
+        },
+        "returnTopic": {
+            "properties": {
+                "selectedId": { "type": "string" },
+                "selectedName": { "type": "string" }
+            }
+        }
+    },
+    "agents": {
+        "version": "1.0.0",
+        "invokable": true,
+        "modes": ["one-way", "two-way"],
+        "defaultMode": "two-way",
+        "timeoutMS": 12000
+    }
+}
+```
+
+Field summary:
+
+- `agents.version`: required semantic version for the agent contract.
+- `agents.invokable`: required to expose the tool to MCP.
+- `agents.modes`: supported invocation modes.
+- `agents.defaultMode`: fallback mode when the agent does not specify one.
+- `agents.timeoutMS`: timeout hint for two-way calls.
+
+## MCP Invocation Envelope
+
+MCP callers can pass PPTB-specific invocation metadata under `arguments.__pptb`.
+
+```json
+{
+    "entityName": "account",
+    "__pptb": {
+        "mode": "two-way",
+        "timeoutMs": 60000
+    }
+}
+```
+
+Supported metadata:
+
+- `mode`: `"one-way"` or `"two-way"`.
+- `timeoutMs`: positive number in milliseconds.
+
+## Mode Semantics
+
+- `two-way`: MCP waits for the callee to call `returnData(...)` and validates the result against `returnTopic`.
+- `one-way`: MCP returns an immediate accepted response and does not wait for a payload from the callee.
+
+## Tool Runtime Context
+
+When a tool is launched by MCP, `toolboxAPI.invocation.getLaunchContext()` returns the prefill data. If present, invocation metadata is attached under `__pptb`.
+
+```json
+{
+    "entityName": "account",
+    "__pptb": {
+        "source": "mcp",
+        "mode": "two-way",
+        "correlationId": "mcp-...",
+        "timeoutMs": 60000,
+        "expectsResponse": true
+    }
+}
+```
+
+## Implementation Notes
+
+Current implementation points:
+
+- MCP server entry point: [src/main/mcp/mcpServer.ts](../src/main/mcp/mcpServer.ts)
+- Agent tool registry: [src/main/mcp/agentToolRegistry.ts](../src/main/mcp/agentToolRegistry.ts)
+- Invocation context bridge: [src/main/toolPreloadBridge.ts](../src/main/toolPreloadBridge.ts)
+- Logging: [src/main/mcp/agentInvocationLogger.ts](../src/main/mcp/agentInvocationLogger.ts)
+
+The runtime currently:
+
+- Validates agent eligibility from `agents`.
+- Validates input against the tool's `prefill` schema.
+- Validates output against `returnTopic` for two-way calls.
+- Logs mode, correlation id, and result outcome.
+
+## Validation and Troubleshooting
+
+- Run `pnpm run build` after changing MCP-related TypeScript or docs.
+- If a tool does not appear in MCP discovery, confirm `agents.invokable` is `true`.
+- If a call fails schema validation, compare the payload against `prefill` or `returnTopic`.
+- If a call times out, adjust `agents.timeoutMS` or the per-call `__pptb.timeoutMs` hint.
+- Use MCP Inspector as the manual test harness for this feature area.
+- Verify that `list-tools` shows the supported modes and that `call-tool` returns the expected one-way or two-way response.
+- Check that invocation logs redact connection-related identifiers and sensitive payload fields.