microsoft · Gregory Joseph (gnjoseph) · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,108 @@
+name: 🐛 Bug report
+description: Report a defect in the SPE MCP server or a scaffolded sample — tool failures, scaffolding/build/deploy, install/packaging, or unexpected output.
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! Please **search
+        [existing issues](https://github.com/microsoft/SharePoint-Embedded-MCP-Server/issues)**
+        first to avoid duplicates.
+
+        > 🔑 **Sign-in / `AADSTS…` error?** Use the dedicated
+        > **"Sign-in / AADSTS error"** template instead — it collects the exact
+        > diagnostics needed to root-cause auth failures.
+
+        > 🔒 **Never paste secrets** (client secrets, refresh/access tokens, `az`
+        > output containing credentials). Redact tenant/subscription GUIDs if you
+        > consider them sensitive.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of the workflow is affected?
+      options:
+        - MCP tool call (server)
+        - Scaffolding / generated sample
+        - Local run / build (npm run dev, Vite)
+        - Deployment (Static Web Apps / Azure)
+        - Install / packaging (npx, npm i -g)
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including the exact error text or the client-facing correlation ID.
+      placeholder: |
+        e.g. `container_create` returned "The tool failed. See server logs for details. (correlationId: a1b2c3d4)"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: The natural-language prompt(s) and/or tool calls that trigger the problem.
+      placeholder: |
+        1. Prompt the agent: "Create a trial SPE app and scaffold a React sample"
+        2. Run `project_run_local`
+        3. …
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: dropdown
+    id: mcp-client
+    attributes:
+      label: MCP client
+      options:
+        - VS Code (Copilot)
+        - Cursor
+        - Claude Desktop
+        - Azure AI Foundry
+        - MCP Inspector
+        - Other (describe below)
+    validations:
+      required: true
+  - type: input
+    id: server-version
+    attributes:
+      label: Server version
+      description: "`@microsoft/spe-mcp` version (e.g. 0.2.0-alpha.1), or the commit SHA if built from source."
+    validations:
+      required: true
+  - type: input
+    id: tool
+    attributes:
+      label: Tool(s) involved
+      description: Which MCP tool name(s), if known (e.g. `project_app_create`, `container_create`).
+  - type: input
+    id: env
+    attributes:
+      label: OS and Node.js version
+      placeholder: "e.g. Windows 11 / macOS 14; Node 22.11.0"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste the server stderr lines for the correlation ID (`grep <id> spe-mcp.log`). Redact any secrets.
+      render: text
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: This is **not** a security vulnerability (those go through [SECURITY.md](https://github.com/microsoft/SharePoint-Embedded-MCP-Server/blob/main/SECURITY.md)).
+          required: true
+        - label: I removed all secrets/tokens from the details above.
+          required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📘 Support & documentation
+    url: https://github.com/microsoft/SharePoint-Embedded-MCP-Server/blob/main/SUPPORT.md
+    about: How to get help and where to find docs. Please search existing issues first.
+  - name: 📖 Troubleshooting guide
+    url: https://github.com/microsoft/SharePoint-Embedded-MCP-Server/blob/main/docs/TROUBLESHOOTING.md
+    about: Fixes for common problems — container-type registration delays, deploy/config, and sign-in (AADSTS) errors. Often resolves the issue without filing.
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/microsoft/SharePoint-Embedded-MCP-Server/blob/main/SECURITY.md
+    about: Do NOT open a public issue for security problems — follow the private process described here.
diff --git a/.github/ISSUE_TEMPLATE/signin_issue.yml b/.github/ISSUE_TEMPLATE/signin_issue.yml
@@ -0,0 +1,136 @@
+name: 🔑 Sign-in / AADSTS error
+description: Sign-in fails in a scaffolded sample (e.g. AADSTS9002326, AADSTS50011, AADSTS650051).
+title: "[Sign-in]: AADSTS"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template collects the diagnostics needed to root-cause sign-in
+        failures. Most `AADSTS9002326` reports turn out to be a **configuration
+        mismatch** — the running build signs in as a *different* app/tenant than
+        the one edited in the portal — not a missing redirect URI. See the
+        [sign-in troubleshooting guide](https://github.com/microsoft/SharePoint-Embedded-MCP-Server/blob/main/docs/TROUBLESHOOTING.md#react-spa-sign-in-fails-with-aadsts9002326-redirect-uri-already-registered)
+        before filing; it resolves most cases in a couple of minutes.
+
+        > 🔒 **Do not paste tokens or secrets.** The values below (client id,
+        > tenant id, redirect URIs) are **not** secrets, but if you consider your
+        > tenant/client GUIDs sensitive you may mask the middle characters.
+  - type: input
+    id: aadsts-code
+    attributes:
+      label: Exact AADSTS code
+      placeholder: "e.g. AADSTS9002326"
+    validations:
+      required: true
+  - type: textarea
+    id: error-text
+    attributes:
+      label: Full error text
+      description: The complete error shown in the app and/or browser console.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: request-url
+    attributes:
+      label: Token request URL
+      description: From browser DevTools → Network. Include the path/tenant segment; you may trim query params.
+      placeholder: "https://login.microsoftonline.com/<tenant-guid>/oauth2/v2.0/token?..."
+  - type: markdown
+    attributes:
+      value: |
+        ### The key comparison
+
+        Sign-in uses the `VITE_CLIENT_ID` / `VITE_TENANT_ID` **baked into the running
+        build** (Vite inlines env vars at build time). Confirm they match the app you
+        edited in the portal's **Overview** blade. If you changed `.env`, you must
+        **rebuild** for it to take effect.
+  - type: input
+    id: env-client-id
+    attributes:
+      label: "`VITE_CLIENT_ID` in the sample's `.env`"
+      description: From the scaffolded sample's `.env` (or `.env.local`).
+    validations:
+      required: true
+  - type: input
+    id: env-tenant-id
+    attributes:
+      label: "`VITE_TENANT_ID` in the sample's `.env`"
+    validations:
+      required: true
+  - type: input
+    id: portal-client-id
+    attributes:
+      label: Application (client) ID shown in the portal Overview
+      description: Entra portal → App registrations → your app → Overview. Should equal `VITE_CLIENT_ID`.
+    validations:
+      required: true
+  - type: input
+    id: portal-tenant-id
+    attributes:
+      label: Directory (tenant) ID shown in the portal Overview
+      description: Should equal `VITE_TENANT_ID`.
+    validations:
+      required: true
+  - type: dropdown
+    id: rebuilt
+    attributes:
+      label: Did you rebuild the sample after the most recent `.env` change?
+      options:
+        - "Yes — rebuilt after editing .env"
+        - "No / not sure"
+        - "Did not edit .env"
+    validations:
+      required: true
+  - type: textarea
+    id: spa-redirects
+    attributes:
+      label: The signing-in app's SPA redirect URIs
+      description: |
+        Run this against the **client id from `.env`** and paste the output:
+        ```bash
+        az rest --method GET \
+          --url "https://graph.microsoft.com/v1.0/applications?\$filter=appId eq '<VITE_CLIENT_ID>'&\$select=appId,spa" \
+          -o json
+        ```
+      render: json
+    validations:
+      required: true
+  - type: dropdown
+    id: guest
+    attributes:
+      label: Is the signed-in user a guest/external (B2B) user in this tenant?
+      options:
+        - "No — member of the tenant"
+        - "Yes — guest/external user"
+        - "Not sure"
+  - type: dropdown
+    id: mcp-client
+    attributes:
+      label: MCP client used to scaffold/run
+      options:
+        - VS Code (Copilot)
+        - Cursor
+        - Claude Desktop
+        - Azure AI Foundry
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: server-version
+    attributes:
+      label: Server version
+      description: "`@microsoft/spe-mcp` version or commit SHA."
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I confirmed `VITE_CLIENT_ID` / `VITE_TENANT_ID` against the portal Overview and rebuilt after any `.env` change.
+          required: true
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: I did **not** paste any tokens or secrets.
+          required: true
diff --git a/.github/skills/report-spe-mcp-issue/SKILL.md b/.github/skills/report-spe-mcp-issue/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: Report an SPE MCP issue
+description: >-
+  Help a user file a high-quality, triage-ready issue for the SharePoint
+  Embedded MCP server (microsoft/SharePoint-Embedded-MCP-Server). Use whenever
+  someone hits a problem with the server or a scaffolded sample — a failing MCP
+  tool call, a scaffolding / build / deploy error, an install or packaging
+  problem, wrong or confusing output, a docs gap, or a sign-in / Entra "AADSTS…"
+  failure — and wants to report it, or asks "how do I file an issue / bug".
+  Picks the right issue-form template, gathers the diagnostics it expects,
+  redacts secrets, and drafts a ready-to-submit GitHub issue.
+---
+
+# Report an SPE MCP issue
+
+Turn a vague "it's broken" into a triage-ready issue for
+`microsoft/SharePoint-Embedded-MCP-Server`, using the repository's issue-form
+templates. This works for **any** kind of problem — a failing MCP tool call, a
+scaffolding / build / deploy error, an install or packaging issue, unexpected
+output, or a docs gap. Most reports use the general **Bug report** form;
+**sign-in / `AADSTS…` errors** have a dedicated form because they need a few
+extra auth-specific diagnostics.
+
+## 0. Try to resolve it first
+
+Many problems are self-fixable. Before drafting an issue, check
+[`docs/TROUBLESHOOTING.md`](../../../docs/TROUBLESHOOTING.md) and the relevant
+`README` / `docs` section for whatever is failing — container-type registration
+delays, deploy/config, and sign-in all have known fixes there.
+
+The most common self-fix is for **sign-in / `AADSTS…`** errors, which are almost
+always a **config mismatch**: the running build signs in with the
+`VITE_CLIENT_ID` / `VITE_TENANT_ID` baked into its `.env` at build time, which
+points at a *different* app/tenant than the one the user edited in the portal.
+Confirm those two values match the app's **Overview** blade and that the sample
+was **rebuilt** after any `.env` change (see
+["React SPA sign-in fails with AADSTS9002326"](../../../docs/TROUBLESHOOTING.md#react-spa-sign-in-fails-with-aadsts9002326-redirect-uri-already-registered)).
+If a known fix resolves it, no issue is needed.
+
+## 1. Classify the issue
+
+Pick the template that fits. Everything except sign-in uses the general **Bug
+report** form (`bug_report.yml`):
+
+- A failing **MCP tool call** (error text or a client-facing `correlationId`).
+- A **scaffolding / build / local-run** problem in a generated sample.
+- A **deployment** problem (e.g. Static Web Apps / Azure).
+- An **install / packaging** problem (`npx` / `npm i -g @microsoft/spe-mcp`).
+- **Unexpected or confusing output**, or a **documentation** gap.
+
+Use the dedicated **Sign-in / AADSTS** form (`signin_issue.yml`) only when the
+symptom is an auth failure — the error text contains `AADSTS`, "sign in",
+"redirect URI", or "token", or the failing request is to
+`login.microsoftonline.com`.
+
+## 2. Gather diagnostics
+
+Ask for only what's missing; don't re-request what the user already provided.
+
+**For any issue — collect:** what happened (include any client-facing
+`correlationId`), steps to reproduce (the prompt / tool calls), expected
+behavior, MCP client (e.g. VS Code Copilot), `@microsoft/spe-mcp` version or
+commit, OS + Node version, the tool name(s) involved, and the server stderr
+lines for the correlation id (`grep <id> spe-mcp.log`).
+
+**If it's a sign-in / AADSTS issue — also collect:**
+
+| Field | How to get it |
+|-------|---------------|
+| Exact `AADSTS` code + full error text | From the app UI / browser console |
+| Token request URL | Browser DevTools → Network → the failing `…/oauth2/v2.0/token` call |
+| `VITE_CLIENT_ID`, `VITE_TENANT_ID` | The scaffolded sample's `.env` (or `.env.local`) |
+| Portal **client id** + **tenant id** | Entra portal → App registrations → the app → **Overview** |
+| Rebuilt after `.env` change? | Ask directly (Vite inlines env at build time) |
+| SPA redirect URIs on the `.env` app | `az rest --method GET --url "https://graph.microsoft.com/v1.0/applications?\$filter=appId eq '<VITE_CLIENT_ID>'&\$select=appId,spa" -o json` |
+| Guest/member user? | Ask whether they signed in as a guest/external (B2B) user |
+
+## 3. Redact secrets — always
+
+Before drafting anything, strip: client secrets, refresh/access tokens, `az`
+output containing credentials, cookies, and authorization headers. Client IDs,
+tenant IDs, and redirect URIs are **not** secrets and are needed for triage
+(offer to mask the middle of GUIDs if the user considers them sensitive).
+
+## 4. Draft and submit
+
+Prefer opening the prefilled web form so the template's required checkboxes are
+honored:
+
+```bash
+gh issue create --repo microsoft/SharePoint-Embedded-MCP-Server \
+  --web --template bug_report.yml   # or signin_issue.yml for auth errors
+```
+
+For a fully non-interactive draft, write the body to a file and run:
+
+```bash
+gh issue create --repo microsoft/SharePoint-Embedded-MCP-Server \
+  --title "[Bug]: <one-line summary>" \
+  --body-file issue.md
+```
+
+Structure the body to mirror the chosen template's sections (what happened,
+repro steps, expected behavior, versions; for a sign-in issue, add the `.env`
+vs. portal comparison). Show the user the drafted title + body and get
+confirmation before creating. If `gh` isn't available or auth is restricted,
+output the same content and point the user to
+[**New issue**](https://github.com/microsoft/SharePoint-Embedded-MCP-Server/issues/new/choose).
+
+## 5. Search for duplicates first
+
+```bash
+gh issue list --repo microsoft/SharePoint-Embedded-MCP-Server \
+  --search "<key error text or tool name> in:title,body" --state all
+```
+
+Search on a distinctive fragment — the tool name, a `correlationId`, or the
+`AADSTS` code for sign-in issues. If a matching issue exists, add the new
+diagnostics as a comment instead of opening a duplicate.