academy-pages-mcp (prototype)

Een kleine MCP-server waarmee Claude rechtstreeks concept-pagina's op de HTJZ Academy (SharePoint) kan maken, bijwerken en publiceren, via de Microsoft Graph API. Dus zonder de PowerShell-omweg die we nu gebruiken.

Dit is een prototype om te laten zien dat het werkt en om IT te laten beoordelen voor uitrol. Het gaat om schrijftoegang tot het kennissysteem van de firma, dus de uiteindelijke keuze (welke rechten, welke app) ligt bij Edgar en IT.

Waarom

Nu bouwt Claude Academy-pagina's via PowerShell op één Mac met een gecachete verbinding. Dat werkt, maar alleen daar, en collega's zonder die opstelling kunnen niet zelf bijdragen. Met deze tool als connector in de Cowork-omgeving kan iedereen met toegang concept-pagina's laten bouwen, net zoals de bestaande file-tools (uploaden, verplaatsen) werken.

Wat het doet

Vier tools voor Claude:

Tool	Wat het doet
academy_create_concept_page	Maakt een nieuwe pagina als concept (draft, niet live). Argumenten: name, title, bodyHtml.
academy_update_page_text	Werkt de tekst van een pagina bij (blijft concept tot publiceren). Argumenten: id, bodyHtml.
academy_publish_page	Publiceert een pagina. Argument: id.
academy_list_pages	Lijst de pagina's op (id, naam, titel, url).
academy_list_menu	Toont het menu (QuickLaunch) met de id's, om een parent te kiezen.
academy_add_menu_item	Zet een gepubliceerde pagina in het menu (optioneel onder een sectie).

Nieuwe pagina's zijn standaard concept. Dat sluit aan bij het model "iedereen levert, de eigenaar publiceert": Claude bouwt het concept, de eigenaar publiceert (of vraagt Claude dat te doen).

De echte beslissing: rechten

De tool heeft schrijftoegang tot de Academy nodig (Graph-scope Sites.ReadWrite.All). Twee smaken:

• Delegated (namens de ingelogde gebruiker). Veilig en simpel. De gebruiker logt één keer in (device-code), en de tool doet alleen wat die gebruiker zelf mag. Nadeel: de gebruiker moet al bewerkrechten op de Academy hebben.
• App-only (namens de app zelf). De tool kan altijd schrijven, ongeacht wie hem gebruikt. Krachtiger en echt "iedereen kan bijdragen", maar dan moet de omgeving zelf bewaken wie de tool mag aanroepen. Vraagt om governance.

Dit is de knoop die IT doorhakt. De code werkt met allebei; standaard staat delegated.

Demo draaien (zonder dat IT iets registreert)

Voor een snelle demo gebruikt de tool standaard de publieke Microsoft Graph CLI-app, zodat je geen eigen app-registratie nodig hebt. Je logt één keer in met je eigen account.

cd ~/Developer/academy-pages-mcp
npm install
npm run demo            # maakt een concept-testpagina ZZ-MCP-demo.aspx
npm run demo -- publish # maakt hem en publiceert hem

Bij de eerste run verschijnt een device-code login (ga naar de getoonde URL, voer de code in, log in met je HTJZ-account). Daarna is het token gecached en gaat het stil.

Let op: sommige tenants vragen admin-goedkeuring voor Sites.ReadWrite.All. Als de login zegt dat goedkeuring nodig is, moet een Entra-beheerder dat één keer goedkeuren. Dat is precies de IT-stap hieronder.

Toevoegen aan Claude (Desktop/Cowork)

Zet dit in de MCP-configuratie (bij Claude Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "academy-pages": {
      "command": "node",
      "args": ["/Users/edgarstam/Developer/academy-pages-mcp/src/index.mjs"],
      "env": {
        "SP_SITE_URL": "https://stamadvocaten.sharepoint.com/sites/Academy",
        "GRAPH_TENANT": "stamadvocaten.onmicrosoft.com",
        "GRAPH_CLIENT_ID": "646a6353-f18d-4566-84a9-73b2a8d9f23d",
        "GRAPH_SCOPES": "Sites.ReadWrite.All"
      }
    }
  }
}

Daarna heeft Claude de vier tools hierboven.

Voor productie (de nette versie, IT-taak)

1. Registreer een eigen Entra-app "Academy Pages" (in plaats van de Graph CLI-app).
2. Kies de rechtenvorm:
   • Delegated: Graph-permissie Sites.ReadWrite.All (delegated) + "Allow public client flows" aan (voor device-code). Gebruikers hebben eigen bewerkrechten nodig.
   • App-only: Graph-permissie Sites.ReadWrite.All (application) + admin consent, en een client secret of certificaat. Zet dan een gate op wie de tool mag gebruiken.
3. Overweeg de scope te beperken tot alleen de Academy-site met Sites.Selected in plaats van Sites.ReadWrite.All (schrijftoegang tot precies één site, niet alle sites). Netter en veiliger.
4. Zet de client-id (en bij app-only de auth-gegevens) in de env van de connector.

Menu-beheer (extra permissie nodig)

De Graph-API kan geen SharePoint-menu (QuickLaunch) aanpassen, dus academy_list_menu en academy_add_menu_item praten met de SharePoint REST-API. Dat vereist een SharePoint-token, en dus een extra delegated permissie op de app: SharePoint > AllSites.Manage (naast de Graph-permissie), met admin consent. De page-acties (tekst, banner, byline, publiceren) werken op Graph; alleen het menu gebruikt SharePoint.

Beperkingen van dit prototype

• Delegated device-code is bedoeld voor persoonlijk gebruik per persoon; voor de hele firma zonder per-persoon login is app-only met een gate of Sites.Selected de nette route.
• De banner verwijst naar een bestaande afbeelding in SiteAssets (de tool uploadt zelf geen banners).

Bestanden

• src/index.mjs - de MCP-server en de tools.
• src/graph.mjs - de Graph Pages-API-aanroepen (maken/bijwerken/publiceren, banner + byline).
• src/sharepoint.mjs - de SharePoint REST-aanroepen voor het menu.
• src/auth.mjs - device-code login met tokencache (Graph- en SharePoint-scope).
• src/canvas.mjs - zet een HTML-fragment om in een tekst-webpart.
• bin/demo.mjs - losse demo buiten Claude om.