@salesforce/vite-plugin-lwc-ui-bundle 2.2.0 → 3.0.0

package/docs/consumer-guide.md

@@ -290,6 +290,18 @@ npm run preview
 # Open http://localhost:4173
 ```
 
+### Step 6: Validate via MCP Server (optional)
+
+Once `dist/index.html` builds clean, you can validate the compiled bundle end-to-end by serving it through agentic-api-service and exercising it from MCP Inspector / MCP Jam / ChatGPT — closer to production than the local mock path. The `test-mcp-server` skill bundled with this plugin walks through the setup interactively (sfdc-bazel checkout, OrgFarm or Falcon test org, OAuth token generation, swapping your bundle into a UI-resource path, and connecting a test client).
+
+The skill lives at [`packages/vite-plugin-lwc-ui-bundle/skills/test-mcp-server/`](https://github.com/salesforce-experience-platform-emu/webapps/tree/main/packages/vite-plugin-lwc-ui-bundle/skills/test-mcp-server) in this repo. Install it the same way you'd install `setup-lwc-vite-plugin`:
+
+```bash
+cp -r node_modules/@salesforce/vite-plugin-lwc-ui-bundle/skills/test-mcp-server ~/.claude/skills/
+```
+
+Then run `/test-mcp-server` from Claude Code and answer the prompts. The skill is opinionated about the agentic-api-service path; teams using a different MCP host should treat it as a reference rather than a turnkey solution.
+
 ---
 
 ## Common Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Salesforce",
@@ -54,8 +54,8 @@
   },
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/platform-sdk-chat": "^2.2.0",
-    "@salesforce/ui-bundle": "^2.2.0",
+    "@salesforce/platform-sdk-chat": "^3.0.0",
+    "@salesforce/ui-bundle": "^3.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
   },
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.3",
     "@conduit-client/command-base": "3.19.3",
-    "@salesforce/platform-sdk-chat": "^2.2.0",
+    "@salesforce/platform-sdk-chat": "^3.0.0",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",

package/skills/test-mcp-server/README.md

@@ -0,0 +1,93 @@
+# Test MCP Server Skill
+
+An interactive skill for testing MCP servers accessed through the agentic-api-service, including both Core-hosted servers and off-core file-based servers defined in sfdc-bazel.
+
+> **Maturity note:** This skill is checked in here so the `vite-plugin-lwc-ui-bundle` workflow has a documented path for validating compiled bundles end-to-end through agentic-api-service. It has been used by the original author against `agentforce-sales` and the default test1 org, but it is **not fully exercised** across every scenario it claims to cover. Treat it as a working starting point; ideally the MCP team owns and maintains a canonical version going forward.
+
+## What This Skill Does
+
+This skill provides step-by-step guidance through the complete workflow for testing MCP servers. It covers:
+
+- Environment detection (Core-hosted vs off-core file-based)
+- Repository setup (sfdc-bazel clone and initialization)
+- Org setup (OrgFarm, External Client App, org perms)
+- MCP server activation (Core-hosted) or server definition discovery (off-core)
+- OAuth token generation
+- Service building and startup with Bazel
+- Testing with curl, MCP Inspector, and ChatGPT
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Test changes to MCP server code, tools, or resources
+- Set up a testing environment for Core-hosted or off-core MCP servers
+- Debug MCP server behavior with access to server logs
+- Validate end-to-end integration with MCP Inspector or ChatGPT
+
+**Supported workflows:**
+
+- ✅ Core-hosted MCP server — local Core/workspace development (testing code changes in Core)
+- ✅ Core-hosted MCP server — Falcon test org (testing already-deployed servers via MCP Inspector)
+- ✅ Off-core file-based servers/tools in sfdc-bazel (e.g., agentforce-sales)
+
+## Skill Structure
+
+```
+test-mcp-server/
+├── SKILL.md                          — Main skill (interactive workflow)
+├── default-test-server-config.sh     — Template for OAuth credentials (placeholder values; fill in your own ECA's Client ID/Secret before sourcing)
+├── README.md
+└── references/
+    ├── eca-setup.md                  — External Client App setup + genoauth.sh template
+    ├── testing-methods.md            — Detailed curl, MCP Inspector, ChatGPT guides
+    └── troubleshooting.md            — Troubleshooting, checklists, key points
+```
+
+## How to Install
+
+The skill ships with `@salesforce/vite-plugin-lwc-ui-bundle`. After
+`npm install @salesforce/vite-plugin-lwc-ui-bundle` in your project,
+copy the skill into Claude Code's skills directory:
+
+```bash
+cp -r node_modules/@salesforce/vite-plugin-lwc-ui-bundle/skills/test-mcp-server ~/.claude/skills/
+```
+
+Re-run this whenever you upgrade the plugin so the skill stays current.
+
+Then fill in your own org's credentials in
+`~/.claude/skills/test-mcp-server/default-test-server-config.sh`
+(see `references/eca-setup.md` for how to set up an External Client
+App and where to find the Consumer Key + Secret). Do **not** commit
+filled-in credentials back to a public repo.
+
+## How to Use
+
+Once installed, the skill triggers automatically when you mention:
+
+- "test mcp server"
+- "test mcp tool"
+- "sfdc-bazel mcp"
+- "agentic-api-service"
+- Or explicitly invoke it: `/skill test-mcp-server`
+
+The skill uses the `AskUserQuestion` tool to guide you through each step interactively, waiting for your input before proceeding.
+
+## Prerequisites
+
+- Access to sfdc-bazel repository (for local Core/workspace and off-core development)
+- OrgFarm access for org creation (local Core development)
+- An org with External Client App for OAuth (all scenarios)
+- ChatGPT Enterprise license (for ChatGPT testing method)
+- ngrok installed (for ChatGPT testing method)
+
+## Testing Methods Supported
+
+1. **curl** — Quick command-line verification (recommended for initial testing)
+2. **MCP Inspector** — Interactive GUI testing with tool/resource exploration
+3. **ChatGPT** — Production validation with natural language interaction (requires ngrok)
+
+## Feedback
+
+If you encounter issues or have suggestions for improvement, please share feedback with the skill creator.

package/skills/test-mcp-server/SKILL.md

@@ -0,0 +1,491 @@
+---
+name: test-mcp-server
+description: Use this skill for testing MCP servers via the agentic-api-service. Supports (1) Core-hosted MCP servers — both local Core/workspace development and Falcon test orgs via MCP Inspector, and (2) off-core file-based MCP servers and tools defined in sfdc-bazel (e.g., agentforce-sales with server/tool/resource JSON definitions). Covers org setup, OAuth configuration, and testing with curl/MCP Inspector/ChatGPT. Always use when user mentions MCP server testing, MCP tool testing, sfdc-bazel setup, agentic-api-service, or MCP Inspector setup.
+---
+
+# Test MCP Server
+
+This skill guides you through testing MCP servers accessed through the agentic-api-service, including both Core-hosted servers and off-core file-based servers defined in sfdc-bazel.
+
+## How to Use This Skill
+
+Use the **AskUserQuestion tool** at decision points, then actively help the user execute each step by running commands and creating files together.
+
+**Key principles:**
+
+- Present one question at a time using AskUserQuestion
+- After receiving the answer, actively execute that step (run commands via Bash tool, create files, etc.)
+- Only proceed to the next question after completing the current step
+
+## When to Use This Workflow
+
+**✅ Fully Supported — two scenarios:**
+
+1. **Core-hosted MCP Server:** For testing MCP servers or tools defined in Core.
+   - **Local Core/workspace:** Developing or modifying servers/tools with code changes in Core. **Requires:** sfdc-bazel project + local Core/workspace running.
+   - **Falcon test org:** Testing already-deployed Core-hosted servers without code changes. **Does NOT require:** sfdc-bazel project.
+   - The workflow will ask which environment you're using after you select this option.
+
+2. **Off-Core File-Based Servers/Tools:** For testing **existing MCP servers and tools defined in sfdc-bazel** (not in Core).
+   - Modifying existing off-core MCP servers (`*.server.json`), tools (`*.tool.json`), or resources (`*.resource.json`)
+   - Working with servers like `agentforce-sales`, `education-cloud`, `manufacturing-cloud`, etc.
+   - Definitions live in `agentic-api-service-shared/src/main/resources/mcp/`
+   - **Requires:** sfdc-bazel project + an org for OAuth (but NOT local Core/workspace)
+   - **Does NOT require:** MCP server activation in Setup (file-based servers load automatically)
+   - ⚠️ Off-core file-based is NOT the recommended approach for new MCP servers/tools. For new development, use the Core-hosted approach instead.
+
+## Interactive Workflow
+
+### Step 1: Determine Testing Environment
+
+Use AskUserQuestion:
+
+```
+Question: "What type of MCP server/tool are you testing?"
+Options:
+  - "Core-hosted MCP server (server/tool defined in Core)"
+  - "Off-core file-based MCP server/tool (defined in sfdc-bazel, e.g., agentforce-sales)"
+```
+
+**If "Off-core file-based":**
+
+Explain: "You're testing an off-core MCP server or tool defined in sfdc-bazel. You'll need the sfdc-bazel project to build and run the agentic-api-service, plus an org for OAuth authentication. You do NOT need a local Core server running."
+
+⚠️ For new MCP servers/tools, the recommended approach is Core-hosted. Off-core file-based is for existing servers already defined in sfdc-bazel.
+
+Proceed to **Step 2-OffCore**.
+
+**If "Core-hosted":**
+
+Use AskUserQuestion:
+
+```
+Question: "Where is your Core server running?"
+Options:
+  - "Local Core or workspace (testing code changes in Core)"
+  - "Falcon test org (testing already-deployed Core-hosted server)"
+```
+
+- **If "Falcon test org":** Proceed to **Step 2-Falcon**.
+- **If "Local Core or workspace":**
+  - Explain: "You'll need the sfdc-bazel project to build and run the agentic-api-service locally."
+  - ⚠️ Make sure your **Core server is running** before creating an org.
+  - Proceed to **Step 2-Local**.
+
+---
+
+### Step 2-Local: Repository Setup
+
+Use AskUserQuestion:
+
+```
+Question: "Do you already have the sfdc-bazel repo cloned?"
+Options:
+  - "Yes, I have it cloned"
+  - "No, I need to clone it"
+```
+
+**If "Yes":** Ask for the path, verify it exists, and set working directory.
+
+**If "No":**
+
+1. Ask where to clone (suggest `~/git/sfdc-bazel`)
+2. Guide: `git clone https://git.soma.salesforce.com/services/sfdc-bazel`
+
+**Then check if Bazel build environment is set up:**
+
+Use AskUserQuestion:
+
+```
+Question: "Have you run ./monorepo_setup.sh -i in the sfdc-bazel repo? This sets up the Bazel build environment, downloads dependencies, and configures toolchains."
+Options:
+  - "Yes, already done"
+  - "No, not yet"
+```
+
+**If "No":** Explain they need to run `./monorepo_setup.sh -i` in the sfdc-bazel root. It may take several minutes.
+
+After initialization, proceed to **Step 3-Local**.
+
+---
+
+### Step 2-Falcon: Falcon Test Org Setup
+
+#### 2-Falcon.1: Enable MCP Service in Org
+
+Guide them:
+
+1. Navigate to **Setup → Einstein Setup** and verify Einstein is turned on
+2. Enable **"MCPService"** org perm
+3. Enable **"MContentInternalApi"** org perm
+
+💡 If "MCP Servers" page is not visible after enabling the org perm, also enable `AgentforceMcpSupportPilot` and `ApiCatalogMcpPilot`.
+
+Use AskUserQuestion:
+
+```
+Question: "Can you see 'MCP Servers' in Setup after enabling MCPService org perm?"
+Options:
+  - "Yes, I can see it"
+  - "No, it's not showing"
+```
+
+**If "No":** Guide them to enable the additional org perms listed above.
+
+#### 2-Falcon.2: Activate MCP Server
+
+Guide them:
+
+1. Navigate to **Setup → MCP Servers**
+2. Find and click on their server
+3. Click **Activate**
+
+Ask: "Which MCP server are you testing?"
+
+Ask: "What is the Server URL shown on the MCP server details page?"
+
+💡 Example: `https://test.api.salesforce.com/platform/mcp/v1/platform/records`
+
+Extract apiDomainName and serverName from the URL format: `https://[domain]/platform/mcp/v1/<apiDomainName>/<serverName>`
+
+⚠️ **Troubleshooting:** If `v1` doesn't work when testing, try replacing with `v1-beta.2`.
+
+#### 2-Falcon.3: Enable Required Org Perms (If Needed)
+
+Use AskUserQuestion:
+
+```
+Question: "Does your MCP server require any specific org perms?"
+Options:
+  - "Yes, I know which perms are needed"
+  - "No, or I'm not sure"
+```
+
+Guide accordingly (e.g., `LightningTypesMcpIntegration` for `lightning-type-sample-server`).
+
+#### 2-Falcon.4: Setup OAuth for Token Generation
+
+Use AskUserQuestion:
+
+```
+Question: "Do you already have an External Client App (ECA) set up for OAuth?"
+Options:
+  - "Yes, I have an ECA"
+  - "No, I need to create one"
+```
+
+**If "Yes":**
+
+Load the default test server config and show it to the user for confirmation. Use Bash tool to run:
+
+```bash
+source ~/.claude/skills/test-mcp-server/default-test-server-config.sh
+```
+
+Show the loaded credentials (Client ID, Client Secret, Username, Org URL) and ask: "Are these the correct credentials, or do you want to use different ones?"
+
+If the user wants different credentials, ask for:
+
+1. Consumer Key (Client ID)
+2. Consumer Secret
+3. Org domain URL (the base URL for OAuth token generation, e.g., `https://your-org.my.salesforce.com`)
+
+**If "No":**
+
+Read the ECA setup guide at `references/eca-setup.md` and walk the user through creating one. After completion, ask for:
+
+1. Consumer Key (Client ID)
+2. Consumer Secret
+3. Org domain URL (the base URL for OAuth token generation, e.g., `https://your-org.my.salesforce.com`)
+
+After completing Falcon setup, proceed to **Step 3-Falcon**.
+
+---
+
+### Step 2-OffCore: Off-Core File-Based Server Setup
+
+#### Understanding Off-Core Server Structure
+
+Off-core MCP servers are defined by JSON files in sfdc-bazel at:
+
+```
+projects/services/agentic-api-access/agentic-api-service-shared/src/main/resources/mcp/
+├── servers/    ← *.server.json (server definitions)
+├── tools/      ← *.tool.json (tool definitions)
+└── resources/  ← *.resource.json (UI resource definitions)
+```
+
+**Example:** The `agentforce-sales` server is defined in `salescloud.server.json` and references tools like `agentforce-sales.get_record_details`.
+
+#### 2-OffCore.1: Repository Setup
+
+Follow the same steps as **Step 2-Local** (clone sfdc-bazel and run `./monorepo_setup.sh -i`).
+
+#### 2-OffCore.2: Identify the Server and Definitions
+
+Ask: "Which off-core MCP server are you testing?"
+
+Use Glob tool to search for server definitions:
+
+```
+projects/services/agentic-api-access/agentic-api-service-shared/src/main/resources/mcp/servers/*.server.json
+```
+
+Read the server definition to list its tools and resources. If the user is modifying a tool or resource, help locate the specific file:
+
+- Tools: `mcp/tools/<toolName>.tool.json`
+- Resources: `mcp/resources/<resourceName>.resource.json`
+
+#### 2-OffCore.3: Org Setup for OAuth
+
+Explain: "Off-core servers still need an org for OAuth authentication. You do NOT need a local Core server running."
+
+Use AskUserQuestion:
+
+```
+Question: "Do you have an org with an External Client App set up for OAuth?"
+Options:
+  - "Yes, I have an org and OAuth ready"
+  - "No, I need to set up an org"
+```
+
+**If "Yes":** Ask for org domain URL (the base URL for OAuth token generation), Consumer Key, and Consumer Secret.
+
+**If "No":** Read the ECA setup guide at `references/eca-setup.md` and walk the user through it.
+
+#### 2-OffCore.4: OAuth Token Generation
+
+Check if `genoauth.sh` exists in the sfdc-bazel root.
+
+**If it exists:** Read the file and confirm with the user that the org domain URL, Client ID, and Client Secret are correct for the org they want to test against. Update if needed.
+
+**If it doesn't exist:** Create it using the template from `references/eca-setup.md` with the user's credentials. Make executable with `chmod +x genoauth.sh`.
+
+After confirming credentials, generate and verify the token.
+
+#### 2-OffCore.5: Build, Start, and Test
+
+Follow the same build/start/test steps as the Local workflow:
+
+1. **Build:** Follow **Step 5-Local**
+2. **Start:** Follow **Step 6-Local**
+3. **Test:** Follow **Step 7-Local** and **Detailed Testing Methods** in `references/testing-methods.md`
+
+The MCP server URL for off-core servers: `http://localhost:7442/mcp/<apiDomainName>/<serverName>`
+Example: `http://localhost:7442/mcp/salescloud/agentforce-sales`
+
+💡 The `apiDomainName` comes from the server definition file name prefix (e.g., `salescloud` from `salescloud.server.json`).
+
+**Key differences from Core-hosted:**
+
+- Off-core servers load automatically — **no need to activate in Setup → MCP Servers**
+- **No local Core server required** — you only need an org for OAuth
+- If a server doesn't appear: verify `*.server.json` is in the correct directory, rebuild after changes, check service logs
+- For **ChatGPT testing**, ngrok is still required (see `references/testing-methods.md` Method 3)
+
+---
+
+### Step 3-Falcon: Testing Falcon Test Org
+
+⚠️ **ChatGPT testing for Falcon test orgs is not yet verified.** Use MCP Inspector for now.
+
+Explain: "We'll test your MCP server using MCP Inspector. You don't need agentic-api-service — you'll connect directly to the Salesforce-hosted MCP server."
+
+**Generate OAuth Token:**
+
+**If using default test server config:**
+
+Use Bash tool to run:
+
+```bash
+source ~/.claude/skills/test-mcp-server/default-test-server-config.sh && TOKEN=$(generate_default_token) && echo "$TOKEN" | tr -d '\n' | pbcopy && echo "Token copied to clipboard! First 20 chars: ${TOKEN:0:20}..."
+```
+
+**If using custom External Client App:**
+
+Check if `genoauth.sh` exists. If not, create it at `~/genoauth.sh` (Falcon users don't have sfdc-bazel) using the template from `references/eca-setup.md` with their credentials. Make executable.
+
+Use Bash tool to generate and copy token:
+
+```bash
+TOKEN=$(~/genoauth.sh) && echo "$TOKEN" | tr -d '\n' | pbcopy && echo "Token copied to clipboard! First 20 chars: ${TOKEN:0:20}..."
+```
+
+**Launch and configure MCP Inspector:**
+
+Follow the Falcon-specific instructions in `references/testing-methods.md` Method 2 (MCP Inspector for Falcon Test Org).
+
+After connection, verify tools and resources appear.
+
+---
+
+### Step 3-Local: Org Setup
+
+Use AskUserQuestion:
+
+```
+Question: "Do you have an org with your MCP server already deployed and activated?"
+Options:
+  - "Yes, I have an org ready"
+  - "No, I need to set up an org"
+```
+
+**If "Yes":**
+
+- Ask for org's domain URL (this is the base URL used for OAuth token generation, e.g., `https://orgfarm-[hash].my.salesforce-com.[domain].wc.crm.dev:[port]`)
+- **Validate:** If user provides a `lightning.force.com` URL, explain that's the Lightning UI URL. They need the org's domain URL instead — this is the base URL used to call `/services/oauth2/token` for generating OAuth tokens. They can find it in OrgFarm details or workspace configuration.
+- Verify MCPService org perm is enabled and server is activated
+- Proceed to **Step 4-Local**
+
+**If "No":**
+
+**3.1: Create Org with OrgFarm**
+
+Guide them:
+
+1. Start the app server in workspace
+2. Use OrgFarm plugin: Environment=LOCAL_CORE, Cloud=Einstein Generative AI, Farm=AppDevV2, OrgPerm=EinsteinGPTEnabled
+3. Navigate to **Setup → Einstein Setup** and verify Einstein is turned on
+4. Enable **"MCPService"** org perm
+5. Enable **"MContentInternalApi"** org perm
+
+When user provides URL, validate it's not a Lightning UI URL.
+
+**3.2: Setup External Client App**
+
+Read the ECA setup guide at `references/eca-setup.md` and walk the user through it.
+
+Ask for the Consumer Key and Consumer Secret when done.
+
+**3.3: Activate MCP Server**
+
+Guide them:
+
+1. Navigate to **Setup → MCP Servers**
+2. Find their server and **Activate** it
+
+⚠️ Inactive servers won't appear in the `/mcp/servers` API endpoint. This is the #1 cause of "server not found" errors.
+
+Use AskUserQuestion:
+
+```
+Question: "Can you see your MCP server in Setup → MCP Servers?"
+Options:
+  - "Yes, I can see it"
+  - "No, it's not showing up"
+```
+
+**If "No":** Check MCPService org perm, verify server is deployed to Core.
+
+**If "Yes":** Ask for server name (format: `apiDomainName/serverName`) and confirm it's activated.
+
+Proceed to **Step 4-Local**.
+
+---
+
+### Step 4-Local: OAuth Setup and Token Generation
+
+Use AskUserQuestion:
+
+```
+Question: "Do you already have a genoauth.sh file with your OAuth credentials?"
+Options:
+  - "Yes, I have it"
+  - "No, I need to create it"
+```
+
+**If "Yes":** Read the file, show the org domain URL, Client ID, and Client Secret to the user, and confirm they're correct for the target org. Update if needed.
+
+**If "No":** Ask for Consumer Key, Consumer Secret, and org domain URL (the base URL for OAuth token generation). Create the script using the template from `references/eca-setup.md`. Make executable.
+
+**Generate and verify token:** Run `./genoauth.sh`. Expected: JWT starting with `eyJ0...`
+
+💡 Save to variable: `export TOKEN=$(./genoauth.sh)`
+
+Proceed to **Step 5-Local**.
+
+---
+
+### Step 5-Local: Build the Service
+
+Use Bash tool to run:
+
+```bash
+bazel build projects/services/agentic-api-access/agentic-api-service
+```
+
+Expected: Build succeeds, JAR at `bazel-bin/projects/services/agentic-api-access/agentic-api-service/agentic-api-service.jar`
+
+**Common Issues:**
+
+- "Unable to locate a Java Runtime" → See `docs/java-setup-mac-troubleshooting.md` in sfdc-bazel
+
+Proceed to **Step 6-Local**.
+
+---
+
+### Step 6-Local: Start the Service
+
+Use AskUserQuestion:
+
+```
+Question: "How would you like to start the agentic-api-service?"
+Options:
+  - "With OAUTH_SERVER_TOKEN exported (Recommended)"
+  - "Without OAUTH_SERVER_TOKEN"
+```
+
+**With OAUTH_SERVER_TOKEN (Recommended):** Clients can connect with "No auth" — simpler setup, best for development.
+
+**Without OAUTH_SERVER_TOKEN:** Each client must provide authentication individually — more complex, closer to production.
+
+**Start the service** (use Bash tool):
+
+```bash
+export OAUTH_SERVER_BASE_URL="<org-url>"
+# Include next line only if "With OAUTH_SERVER_TOKEN":
+export OAUTH_SERVER_TOKEN=$(./genoauth.sh)
+
+bazel run projects/services/agentic-api-access/agentic-api-service
+```
+
+Expected output: `Started AgenticApiService`, ports 7442 and 15372.
+
+**Verify health:** `curl localhost:15372/manage/info | jq`
+
+Proceed to **Step 7-Local**.
+
+---
+
+### Step 7-Local: Test the MCP Server
+
+MCP server URL: `http://localhost:7442/mcp/<apiDomainName>/<serverName>`
+
+Use AskUserQuestion:
+
+```
+Question: "Which testing method would you like to use?"
+Options:
+  - "curl - Quick command-line test (Recommended)"
+  - "MCP Inspector - Interactive GUI testing"
+  - "ChatGPT - Production validation (requires ngrok)"
+```
+
+Based on selection, read `references/testing-methods.md` and guide the user through the appropriate method.
+
+---
+
+## Troubleshooting, Checklists, and Key Points
+
+For troubleshooting issues, verifying setup with checklists, or reviewing key points, read `references/troubleshooting.md`. It covers:
+
+- Common issues organized by scenario (All, Local, Off-Core, Falcon)
+- Testing checklists for each scenario
+- Key points to remember (URL formats, token expiry, activation requirements, etc.)
+
+## Additional Resources
+
+- `references/eca-setup.md` — External Client App setup and genoauth.sh template
+- `references/testing-methods.md` — Detailed curl, MCP Inspector, and ChatGPT testing guides
+- Java setup: `docs/java-setup-mac-troubleshooting.md` in sfdc-bazel repo
+- MCP Protocol Spec: https://spec.modelcontextprotocol.io

package/skills/test-mcp-server/default-test-server-config.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Default Test Server Configuration template for Falcon Test Org Testing.
+#
+# This file is a starting point — fill in your own org's values before
+# sourcing it. The skill's setup flow can also create this for you
+# interactively; see references/eca-setup.md for how to set up an
+# External Client App (ECA) in your org and where to find the Consumer
+# Key + Secret.
+#
+# Workflow:
+#   1. Set up an ECA in your test org (references/eca-setup.md)
+#   2. Replace the placeholders below with your ECA's credentials
+#   3. Source this file: `source default-test-server-config.sh`
+#   4. Generate a token: `generate_default_token`
+#
+# Do NOT commit real Client Secrets back to a public repo. Keep filled-in
+# copies of this file local-only or in a private dotfiles repo.
+
+# OAuth Credentials — replace with your ECA's values
+export DEFAULT_CLIENT_ID="<YOUR_CONSUMER_KEY>"
+export DEFAULT_CLIENT_SECRET="<YOUR_CONSUMER_SECRET>"
+export DEFAULT_USERNAME="<your-username@example.com>"
+export DEFAULT_ORG_URL="https://<your-org-domain>.my.salesforce.com"
+
+# Helper function to generate OAuth token
+generate_default_token() {
+    response=$(curl -s -X POST "${DEFAULT_ORG_URL}/services/oauth2/token" \
+      -H "Content-Type: application/x-www-form-urlencoded" \
+      -d "grant_type=client_credentials&client_id=${DEFAULT_CLIENT_ID}&client_secret=${DEFAULT_CLIENT_SECRET}")
+
+    if command -v jq &> /dev/null; then
+        access_token=$(echo "$response" | jq -r '.access_token')
+    else
+        access_token=$(echo "$response" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
+    fi
+
+    echo "$access_token"
+}
+
+# Print configuration info
+echo "Default Test Server Configuration Loaded:"
+echo "  Username: ${DEFAULT_USERNAME}"
+echo "  Org URL: ${DEFAULT_ORG_URL}"
+echo ""
+echo "To generate a token, run: generate_default_token"

package/skills/test-mcp-server/references/eca-setup.md

@@ -0,0 +1,58 @@
+# External Client App (ECA) Setup
+
+This is the shared setup guide for creating an External Client App for OAuth authentication. Referenced from the main skill when any scenario needs ECA configuration.
+
+## Steps
+
+1. Navigate to **Setup → External Client App Manager → New External Client App**
+2. Enter Basic Information:
+   - External Client App Name: (e.g., "MCP Testing App")
+   - API Name: (e.g., "MCP_Testing_App")
+   - Contact Email: (your email)
+3. Under **API (Enable OAuth Settings)**, check "Enable OAuth"
+4. Set **Callback URL:** `http://localhost:8080/oauth/callback`
+5. Select **OAuth Scopes:** `api`, `sfap_api`, `refresh_token`, `einstein_gpt_api`
+   - Why these scopes? `sfap_api` and `einstein_gpt_api` provide access to AI/MCP features, `api` gives general Salesforce API access, and `refresh_token` allows long-lived sessions
+6. Under **Flow Enablement**, check "Enable Client Credentials Flow"
+7. Under **Security:**
+   - ✅ Check "Issue JSON Web Token based access tokens for named users"
+   - ❌ Uncheck "Require secret for Web Server Flow"
+   - ❌ Uncheck "Require secret for Refresh Token Flow"
+8. Click **Create**
+9. After creation, go to **Policies** Tab → **Edit** → **OAuth Policies**:
+   - Check "Enable Client Credentials Flow"
+   - "Run As" → Enter your username
+   - Save
+
+After completion, note the **Consumer Key** and **Consumer Secret** — these are needed for OAuth token generation. You'll also need your **org domain URL** (the base URL used to call `/services/oauth2/token` for generating OAuth tokens, e.g., `https://orgfarm-xxx.my.salesforce-com.xxx.wc.crm.dev:6101`). This is NOT the Lightning UI URL (`lightning.force.com`) — find it in OrgFarm details or workspace configuration.
+
+## genoauth.sh Script Template
+
+Create this script to generate OAuth tokens. Replace the placeholder values with your actual credentials.
+
+```bash
+#!/bin/bash
+
+CLIENT_ID=<consumer-key>
+CLIENT_SECRET=<consumer-secret>
+ORG_URL=<org-domain-url>
+
+response=$(curl -s -X POST "${ORG_URL}/services/oauth2/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}")
+
+if command -v jq &> /dev/null; then
+    access_token=$(echo "$response" | jq -r '.access_token')
+else
+    access_token=$(echo "$response" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
+fi
+
+export OAUTH_SERVER_TOKEN="$access_token"
+echo "$access_token"
+```
+
+After creating, make executable: `chmod +x genoauth.sh`
+
+Expected output: Long JWT token starting with `eyJ0...`
+
+Tokens expire after ~2 hours. Regenerate by running `./genoauth.sh` again.

package/skills/test-mcp-server/references/testing-methods.md

@@ -0,0 +1,313 @@
+# Detailed Testing Methods
+
+After completing environment setup and starting the agentic-api-service (Local/Off-Core) or generating an OAuth token (Falcon), use one of these methods to test your MCP server.
+
+## Table of Contents
+
+- [Method 1: curl](#method-1-using-curl)
+- [Method 2: MCP Inspector](#method-2-using-mcp-inspector)
+- [Method 3: ChatGPT](#method-3-using-chatgpt)
+
+---
+
+## Method 1: Using curl
+
+curl is the most reliable way to test MCP servers. Use it for quick verification, scripting, and CI/CD integration.
+
+**Run the initialize request:**
+
+Build the server URL using the apiDomainName/serverName (e.g., `platform/lightning-type-sample-server`):
+
+```bash
+TOKEN=$(./genoauth.sh)
+
+curl -s -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  http://localhost:7442/mcp/<apiDomainName>/<serverName> \
+  -d '{
+    "jsonrpc":"2.0",
+    "id":1,
+    "method":"initialize",
+    "params":{
+      "protocolVersion":"2024-11-05",
+      "capabilities":{},
+      "clientInfo":{"name":"test","version":"1.0"}
+    }
+  }' | jq
+```
+
+Expected response:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "tools": {},
+      "prompts": {},
+      "resources": {}
+    },
+    "serverInfo": {
+      "name": "<server-name>",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+If this succeeds, the server is working! The initialize response confirms the server is reachable and responding to MCP protocol requests. Testing is complete — do not proceed to list tools or resources via curl. If the user wants to explore tools and resources interactively, they can use MCP Inspector separately.
+
+---
+
+## Method 2: Using MCP Inspector
+
+MCP Inspector (`npx @mcpjam/inspector@latest`) provides an interactive GUI for testing MCP servers.
+
+### For Local/Off-Core (agentic-api-service running locally)
+
+**Check if service was started with OAUTH_SERVER_TOKEN:**
+
+Use AskUserQuestion:
+
+```
+Question: "Did you start the service with OAUTH_SERVER_TOKEN exported?"
+Options:
+  - "Yes, token was exported before starting"
+  - "No, or service has been running for >2 hours"
+```
+
+**If "Yes" - use No Auth:**
+
+Use Bash tool to run:
+
+```bash
+npx @mcpjam/inspector@latest
+```
+
+This opens MCP Inspector in your browser. Configure:
+
+1. Server URL: `http://localhost:7442/mcp/<apiDomainName>/<serverName>`
+2. Authentication: Select **"No auth"**
+3. Click **Connect**
+
+This works because the service handles authentication internally using the token it was started with.
+
+**If "No" - use Bearer Token:**
+
+First, get a fresh token to clipboard. Use Bash tool to run:
+
+```bash
+./genoauth.sh | tr -d '\n' | pbcopy
+```
+
+Then launch MCP Inspector:
+
+```bash
+npx @mcpjam/inspector@latest
+```
+
+Configure:
+
+1. Server URL: `http://localhost:7442/mcp/<apiDomainName>/<serverName>`
+2. Authentication: Select **"Bearer token"**
+3. Paste the token (just the token, without "Bearer " prefix - it should start with `eyJ0...`)
+4. Click **Connect**
+
+### For Falcon Test Org (connecting directly to Salesforce)
+
+Use Bash tool to launch MCP Inspector:
+
+```bash
+npx @mcpjam/inspector@latest
+```
+
+Configure:
+
+1. Server URL: The Server URL from the MCP server details page (e.g., `https://test.api.salesforce.com/platform/mcp/v1/platform/records`)
+   - ⚠️ **If connection fails:** Try changing `v1` to `v1-beta.2` in the URL
+2. Authentication: Select **"Bearer token"**
+3. Paste the OAuth token (without "Bearer " prefix)
+4. Click **Connect**
+
+### After Connection (All scenarios)
+
+- Connection should show "Connected" (green)
+- Tools tab should show available tools
+- Resources tab should show UI resources (if any)
+- Test tool invocation by selecting a tool and providing inputs
+
+**Common Issue:** If you get 401 errors and MCP Inspector worked previously, the token has expired. For Local/Off-Core: restart the service with a fresh token, then reconnect with "No auth". For Falcon: regenerate the token and paste the new one.
+
+---
+
+## Method 3: Using ChatGPT (Production Testing)
+
+ChatGPT provides end-to-end testing with natural language interaction. Requires ChatGPT Enterprise license and ngrok for local services.
+
+⚠️ **ChatGPT testing for Falcon test orgs is not yet verified.** Use MCP Inspector for Falcon instead.
+
+**Prerequisites check:**
+
+Use AskUserQuestion:
+
+```
+Question: "Do you have ChatGPT Enterprise license?"
+Options:
+  - "Yes, I have access"
+  - "No, I don't have Enterprise"
+```
+
+**If "No":** Explain that ChatGPT Enterprise is required for custom app integration. Suggest using MCP Inspector for testing instead.
+
+**If "Yes", proceed with setup:**
+
+### Step 1: Set up ngrok
+
+Explain: "ChatGPT needs to access your local service via a public URL. We'll use ngrok to create a secure tunnel."
+
+Check if ngrok is installed:
+
+```bash
+which ngrok
+```
+
+**If not installed:**
+
+```bash
+brew install ngrok
+```
+
+**Start ngrok:**
+
+```bash
+ngrok http 7442
+```
+
+This creates a public URL like `https://abc123.ngrok-free.dev`. Get the URL from ngrok output or:
+
+```bash
+curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url'
+```
+
+Store the ngrok URL and explain: "This is your public URL that ChatGPT will use to reach your local service. Keep ngrok running throughout your testing session."
+
+Use AskUserQuestion:
+
+```
+Question: "Is ngrok running and showing a public URL?"
+Options:
+  - "Yes, I have the ngrok URL"
+  - "No, having issues with ngrok"
+```
+
+**If "No":** Help troubleshoot ngrok setup.
+**If "Yes":** Ask: "What is your ngrok public URL?" Store it for the next step.
+
+### Step 2: Create ChatGPT App
+
+Use AskUserQuestion:
+
+```
+Question: "Did you start the service with OAUTH_SERVER_TOKEN exported?"
+Options:
+  - "Yes, token was exported before starting"
+  - "No, or service has been running for >2 hours"
+```
+
+**If "Yes" - guide No Auth setup:**
+
+Explain: "Since the service has the token, we can use 'No auth' - the service handles authentication internally."
+
+Guide them step by step:
+
+1. Open ChatGPT and go to bottom left **"Salesforce Dev Sandbox"**
+2. Click **Sandbox → Settings → Apps**
+3. Click **Create App**
+4. Enter configuration:
+   - **External facing URL:** `<ngrok-url>/mcp/<apiDomainName>/<serverName>`
+     - Core-hosted example: `https://abc123.ngrok-free.dev/mcp/platform/records`
+     - Off-core example: `https://abc123.ngrok-free.dev/mcp/salescloud/agentforce-sales`
+   - **Authentication:** Select **"No auth"**
+5. Click **Create**
+
+Explain: "ChatGPT is now calling your server's `tools/list` and `resources/list` endpoints. This may take a few seconds."
+
+Use AskUserQuestion:
+
+```
+Question: "After ChatGPT finishes loading, do you see Actions and Templates populated?"
+Options:
+  - "Yes, I see them"
+  - "No, they're not showing"
+```
+
+**If "No" - guide OAuth setup:**
+
+Explain: "We'll configure full OAuth authentication. You'll need the Client ID and Secret from your External Client App."
+
+Guide them step by step:
+
+1. Go to **"Salesforce Dev Sandbox" → Settings → Apps**
+2. Click **Create App**
+3. Enter configuration:
+   - **External facing URL:** `<ngrok-url>/mcp/<apiDomainName>/<serverName>`
+   - **Authentication:** Select **"OAuth"**
+   - **Client ID:** Their External Client App's Consumer Key
+   - **Client Secret:** Their External Client App's Consumer Secret
+   - **Authorization URL:** `<org-url>/services/oauth2/authorize`
+   - **Token URL:** `<org-url>/services/oauth2/token`
+   - **Scopes:** `api sfap_api einstein_gpt_api refresh_token`
+4. Click **Create** and complete OAuth flow
+
+Use AskUserQuestion:
+
+```
+Question: "After ChatGPT finishes loading and OAuth completes, do you see Actions and Templates populated?"
+Options:
+  - "Yes, I see them"
+  - "No, they're not showing"
+```
+
+### Step 3: Test in ChatGPT
+
+Explain: "Now let's test your MCP server with natural language."
+
+Guide them:
+
+1. In the Chat window, click **+ → More → [Your App Name]** (or type **@[Your App Name]**)
+2. Ask: "What tools does your server provide? I'll help you craft a test utterance."
+3. Based on their tools, suggest a test utterance
+   - Example: "Show me recent accounts" or "Get record details for ID 001..."
+4. When they send the utterance, explain: "The first tool call will require approval. Click 'Allow'."
+5. After execution, ask: "Did the tool execute successfully? Are UI resources rendering correctly?"
+
+### ChatGPT Troubleshooting
+
+Use AskUserQuestion:
+
+```
+Question: "What issue are you experiencing?"
+Options:
+  - "Template changes not appearing"
+  - "Getting 401 errors"
+  - "Tools not showing up"
+  - "Other issue"
+```
+
+**If "Template changes not appearing":**
+
+1. Refresh the app in ChatGPT
+2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
+3. If still not working, disconnect and recreate app
+
+**If "Getting 401 errors":**
+
+- Token expired → restart service with fresh token (No auth) or refresh OAuth (OAuth auth)
+
+**If "Tools not showing up":**
+
+- Check server is activated in Setup → MCP Servers (Core-hosted only)
+- Verify service logs show "Loaded server definition: <name>"

package/skills/test-mcp-server/references/troubleshooting.md

@@ -0,0 +1,124 @@
+# Troubleshooting, Checklists, and Key Points
+
+Reference this file when users encounter issues during testing, or to verify their setup is complete.
+
+## Table of Contents
+
+- [Common Troubleshooting](#common-troubleshooting)
+- [Testing Checklist](#testing-checklist)
+- [Key Points to Remember](#key-points-to-remember)
+
+---
+
+## Common Troubleshooting
+
+### All Scenarios
+
+1. **Token expired (401 errors):** Tokens expire after ~2 hours. Regenerate with `./genoauth.sh` or `generate_default_token` (for default config).
+
+2. **Tools/resources not appearing:** Check service logs for "Loaded server definition: <name>". Confirm OAuth token has correct scopes (`api`, `sfap_api`, `einstein_gpt_api`).
+
+### Local Core/Workspace
+
+3. **Wrong resource renderer loaded (`acc-renderer-component.html` instead of Core's `renderer.html`):**
+
+   If your Core MCP resource defines a custom `renderer.html` but the service renders `acc-renderer-component.html` (the generic ACC Renderer Component) instead, the issue is in [`LightningTypeResourceLoader.java` (line 85-90)](https://git.soma.salesforce.com/services/sfdc-bazel/blob/main/projects/services/agentic-api-access/agentic-api-service-shared/src/main/java/com/salesforce/mcp/lightningtype/LightningTypeResourceLoader.java#L85). The `loadContent()` method checks `getUiMeta()` and short-circuits to the generic ACC renderer when it's not null:
+
+   ```java
+   if (mcpResourceDefinition.getUiMeta() != null) {
+     logger.info("Retrieving ACC Renderer Component for fqn: {}", fqn);
+     return getGenericACCRenderer(mcpRequestContext);
+   }
+   ```
+
+   **First check:** Ensure org perm `MContentInternalApi` is enabled (should be done during org setup).
+
+   **Workaround:** In your local sfdc-bazel copy, comment out or remove this `if` block (lines 85-90), then rebuild and restart the service. This forces the loader to use the Core-defined `renderer.html` instead of the generic ACC renderer.
+
+   See [GUS W-18345458](https://gus.lightning.force.com/lightning/r/ADM_Work__c/a07EE00002XeNOkYAN/view) for tracking.
+
+4. **Server not found / 500 error:** Verify server is **activated** in Setup → MCP Servers. Verify org has MCPService enabled.
+
+5. **MCP Inspector worked yesterday but returns 401 today:** Service's token expired. Restart with fresh token:
+
+   ```bash
+   lsof -ti:7442,15372 | xargs kill
+   export OAUTH_SERVER_BASE_URL="<org-url>"
+   export OAUTH_SERVER_TOKEN=$(./genoauth.sh)
+   bazel run projects/services/agentic-api-access/agentic-api-service
+   ```
+
+6. **Service won't start (port already in use):**
+   ```bash
+   lsof -ti:7442,15372 | xargs kill
+   ```
+   Wait 2-3 seconds, then retry. Check Java is in PATH (see `docs/java-setup-mac-troubleshooting.md` in sfdc-bazel).
+
+### Off-Core File-Based
+
+7. **Off-core server not loading:** Verify `*.server.json` is in `agentic-api-service-shared/src/main/resources/mcp/servers/`. Ensure rebuilt after changes. Check service logs.
+
+8. **Off-core tool returning errors:** Check `*.tool.json` has valid `inputSchema`. Verify `metadata.httpMethod` and `metadata.path` are correct.
+
+### Falcon Test Org
+
+9. **MCP Servers page not visible in Setup:** Enable `MCPService` org perm. If still not visible, also enable `AgentforceMcpSupportPilot` and `ApiCatalogMcpPilot`.
+
+10. **MCP Inspector connection fails:** Try changing `v1` to `v1-beta.2` in the Server URL. Verify token is valid and server is activated.
+
+---
+
+## Testing Checklist
+
+**Local Core/Workspace & Off-Core (agentic-api-service):**
+
+- [ ] Service builds successfully (`bazel build`)
+- [ ] OAuth token generated
+- [ ] Service starts on ports 7442 and 15372
+- [ ] Health endpoint responds: `curl localhost:15372/manage/info`
+- [ ] Initialize method returns valid response via curl
+- [ ] Tools/list returns expected tools
+- [ ] Resources/list returns UI resources (if applicable)
+- [ ] (Core-hosted only) MCP server activated in Setup → MCP Servers
+- [ ] (Off-core only) Service logs show "Loaded server definition: <name>"
+
+**Falcon Test Org:**
+
+- [ ] MCPService org perm enabled
+- [ ] MCP server visible and activated in Setup → MCP Servers
+- [ ] Required org perms enabled (if any)
+- [ ] OAuth token generated
+- [ ] MCP Inspector connects with Bearer token
+- [ ] If `v1` URL doesn't work, tried `v1-beta.2`
+- [ ] Tools and resources appear after connection
+
+**MCP Inspector (Optional):**
+
+- [ ] Connects with "No auth" (service has fresh token) or "Bearer token" (fresh token pasted)
+- [ ] Tools and resources appear after connection
+
+**ChatGPT (Optional - Local/Off-Core only, requires ngrok):**
+
+- [ ] ngrok tunnel running and URL obtained
+- [ ] App created with public URL and "No auth"
+- [ ] Actions and Templates appear after creation
+- [ ] Can invoke tools via natural language
+
+---
+
+## Key Points to Remember
+
+**Local/Off-Core (agentic-api-service):**
+
+1. **MCP server URL format** is `http://localhost:7442/mcp/<apiDomainName>/<serverName>`
+2. **Tokens expire after ~2 hours** — regenerate if you get 401 errors
+3. Export `OAUTH_SERVER_TOKEN` before starting service to use "No auth" in MCP Inspector and ChatGPT
+4. If token expired, use MCP Inspector's "Bearer token" option with a fresh token (without "Bearer " prefix)
+
+**Core-hosted (Local):** 5. **Always activate the server** in Setup → MCP Servers — this is the most common issue
+
+**Off-core file-based:** 6. **No activation needed** — off-core servers load automatically from classpath files 7. **Rebuild after changes** — modify JSON definitions, then rebuild and restart the service
+
+**Falcon test org:** 8. **URL versioning** — if `v1` doesn't work, try `v1-beta.2` 9. **ChatGPT testing** — not yet verified; use MCP Inspector for now
+
+**ChatGPT (Local/Off-Core):** 10. **ngrok required** to expose `localhost:7442` for ChatGPT 11. **Template caching** is aggressive — hard refresh browser or recreate app if changes don't appear