msloop-mcp: Instructions file for Codex

Agent Guidelines for Loop MCP

This document captures project knowledge to help AI agents work effectively with this codebase.

Repository

• Repository: https://github.com/shayanline/msloop-mcp
• Package: msloop-mcp
• Install: npx -y msloop-mcp@latest, or clone the repo, npm install && npm run build, then point your MCP client to dist/index.js.
• Sibling projects: msteams-mcp and msoutlook-mcp. This project follows the same auth and session pattern; msoutlook-mcp is the closest template.

Project Overview

An MCP server that gives AI assistants read and discovery access to Microsoft Loop. Microsoft publishes no Loop API, so this reuses the Loop web app's own first party client ID and the internal APIs the web client calls, with tokens extracted from a browser session. The browser is only used for initial login and silent refresh fallback, everything else is direct HTTP.

The central constraint

Loop is not a REST resource model like mail or calendar. Workspaces are SharePoint Embedded containers, and pages are Fluid Framework documents (ops plus snapshots). There is no public content-write API and content cannot be materialised over plain HTTP without the Fluid client runtime.

So this server is read and discovery only:

• Metadata (workspaces, pages) comes from the Substrate Loop API.
• Page content is read by asking SharePoint to render the Fluid document to HTML on demand (?format=html), then converting to Markdown. Lossy for rich components.
• Writing or editing page content is out of scope and not achievable here.

Architecture

src/
  index.ts              Entry point, runs the MCP server on stdio
  server.ts             createServer() — registers all tool groups
  constants.ts          Client ID, endpoints, scopes, timeouts
  auth/
    index.ts            getSubstrateToken / getSharePointToken / getGraphToken, status
    session-store.ts    AES-256-GCM encrypted token + session storage in ~/.msloop-mcp-server/
    token-extractor.ts  Pure: select Substrate/SharePoint/Graph tokens from MSAL entries by audience
    token-refresh.ts    HTTP refresh, one OAuth2 call per resource
    browser-login.ts    Playwright login at loop.cloud.microsoft (headless first)
  browser/
    cookie-import.ts    Cross-platform SSO cookie import (Keychain / libsecret / DPAPI)
  api/
    client.ts           substrateGet/Post, graphGet/Post, sharePointGetText
    loop.ts             discover() (merge /workspaces + /recent + /deltasync), listPages, createWorkspace
    pages.ts            getPageContent — HTML export then htmlToMarkdown
    search.ts           Graph /search/query for .loop / .fluid files
  utils/
    http.ts             Bearer headers, retry, the SharePoint multipart "GET via POST" builder
    parsers.ts          Pure: decodePodId, itemIdFromPageId, hostFromSiteUrl, slugify, htmlToMarkdown
    logger.ts           stderr logger (MSLOOP_DEBUG=true)
  types/loop.ts         Substrate API shapes