Skip to content

Add SharePoint file content tool and Sites.Selected setup - #1817

Merged
helpcodeai merged 1 commit into
mainfrom
feat/sharepoint-selected-sites
Nov 21, 2026
Merged

helpcodeai merged 1 commit into
mainfrom
feat/sharepoint-selected-sites

Conversation

@helpcodeai

Copy link
Copy Markdown
Contributor

Summary

Some organisations want the SharePoint connector to see only a few sites, not every site the signed-in user can open. Microsoft Graph supports this with the delegated Sites.Selected permission plus a per-site grant for the app. This PR documents that setup and removes the one thing that broke under it (the connection test called /sites/root, which returns 403 unless the root site is granted).

The AI also could not read a file's content at all, only metadata and webUrl. The new sharepoint_get_file_content tool uses the existing binary response handling (as the Word, PowerPoint and Moss adapters already do), so this is now possible with the 10 MB cap the old note said was missing.

Behaviour is identical on Cloud and self-hosted: the change is adapter JSON only, and the binary response handling, response limits and redirect handling are shared code with no deployment-mode branch.

Changes

  • New read tool sharepoint_get_file_content: GET /drives/{drive_id}/items/{item_id}/content, optional format (enum pdf, Graph's conversion for Office and other formats, files up to 2 MB per the Graph docs). responseMapping.binary.maxBytes 10485760 (PDFs, images, other files are attached), plus transform { expression: "@", maxBytes: 200000 }, which only applies to text bodies (txt/csv/md/json...) so a large text file is cut and marked _truncated instead of filling the context. Binary bodies skip the transform (dynamic-mcp-tools.ts). Read-only via the derived GET annotation, enabled at install.
  • connector.healthcheckPath: /sites/root changed to /me (works with User.Read under any scope set).
  • probe is left on sharepoint_get_root_site. A probe must name a tool, and there is no /me tool. It is also never run for this adapter: for an OAUTH2 connector authorized in the browser, runImportProbe returns null and verifyCredentials returns skipped: 'authorization' (adapters.service.ts). So changing it would mean adding a tool without changing any behaviour.
  • Instructions: new section "Restrict the AI to selected sites (Sites.Selected)". It covers a dedicated app with only offline_access User.Read Sites.Selected (not the shared Outlook app, because the token carries every consented Graph scope), admin consent, the per-site grant via Graph POST /v1.0/sites/{siteId}/permissions or PnP Grant-PnPEntraIDAppSitePermission, write grants for write tools, setting OAuth Scopes and re-authorizing, disabling sharepoint_get_root_site / sharepoint_search_sites / sharepoint_search, entering sites with sharepoint_get_site_by_path, and that effective access is the intersection of the user's rights and the site grant. Also updated: the sentence that said the connector does not download file content, the out-of-scope paragraph, the 403 error line, the 403 verify hint, and the adapter description ("read files").
  • Spec: static assertions for the new tool (method, path, format query param only when given, binary and transform mapping, read-only, enabled), healthcheckPath /me, the Sites.Selected section, and the /content method guard now allows the one GET.

Redirect handling (verified in code): Graph answers /content with a 302 to a pre-authenticated download URL on another host. The REST engine sends through outboundRequest (common/outbound-http.ts), which follows redirects itself (maxRedirects: 0 on the client, up to 5 hops, SSRF check on every hop). In redirectedConfig, when the target origin differs (keepsCredentials false), it deletes Authorization, Cookie, Proxy-Authorization, Basic auth, any credential-named header and the engine's credentialHeaders. So the bearer token is not forwarded to the download host. This is covered by the existing tests in outbound-http.spec.ts ("drops credential headers and Basic auth when the redirect leaves the origin"). maxContentLength (tool response limit, default 10 MB) applies to every hop.

Type

  • Bug fix
  • New feature
  • Documentation
  • Refactoring
  • Performance improvement
  • Other (describe below)

Testing

  • Added/updated unit tests
  • Tested manually (describe steps below)
  • No tests needed (explain why)

Commands and results (macOS, Node 22):

Directory Command Result
repo root node scripts/validate-adapters.mjs --warn exit 0, 975 passed, 0 failed, 1436 warnings. One new warning: tool-prefix for sharepoint_get_file_content (not prefixed microsoft_sharepoint_). It is the same rule all 29 existing SharePoint tools already hit; the adapter uses sharepoint_ and its spec pins that prefix.
repo root node scripts/regenerate-catalog.mjs regenerated, no diff in catalog.ts
repo root node scripts/adapter-count.mjs --check OK: every quoted count equals 957 adapters (51 keyless, 20016 tools); tool counts are not quoted in checked files
packages/backend npx prisma generate (dummy DATABASE_URL) generated
packages/backend npx jest --maxWorkers=4 src/adapters/intl/microsoft-sharepoint src/adapters/catalog 5 suites passed; 23445 passed, 3 skipped (live tests, no token)
packages/backend npx jest --maxWorkers=4 'src/adapters/[^/]+\.spec\.ts$' 31 suites passed, 24307 tests passed
packages/backend npx tsc --noEmit -p tsconfig.json exit 0
packages/backend npm run lint 0 errors, 11 warnings, all in files this PR does not touch; no files rewritten

Not verified (no tenant available): no live call against a real Microsoft 365 tenant. Specifically untested:

  • /content and ?format=pdf end to end through the 302.
  • That delegated Sites.Selected covers /drives/{id}/items/{id}/content. The conversion docs list Files.Read and Sites.Read.All, not Sites.Selected.
  • That sharepoint_search_sites and sharepoint_search fail under Sites.Selected.
  • That pages and permissions tools work under it.
  • The content type SharePoint sends for .md / .csv. Non-text-typed UTF-8 bodies are still decoded as text by decodeResponseBody.

The live block of the spec (MS_GRAPH_ACCESS_TOKEN=...) was not run.

Checklist

  • My code follows the existing code style
  • I have tested my changes locally
  • I have updated documentation (if applicable)
  • All existing tests pass (npm test): the adapter and catalog suites above; full suite runs in CI
  • This PR has a descriptive title

Related Issues

None.

Add sharepoint_get_file_content (GET /drives/{drive_id}/items/{item_id}/content,
optional format=pdf): text files come back as text capped at 200 KB, other
files as an attachment up to 10 MB through the binary response mapping.

Document how to restrict the connector to selected sites with the delegated
Sites.Selected permission, and test the connection with /me, which answers
under every scope set, instead of /sites/root.
@helpcodeai
helpcodeai requested a review from D3nisty as a code owner November 21, 2026 13:33
@helpcodeai
helpcodeai merged commit 775680c into main Nov 21, 2026
17 checks passed
@helpcodeai
helpcodeai deleted the feat/sharepoint-selected-sites branch November 21, 2026 14:07
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 21, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant