365center-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+Business Source License 1.1
+
+Licensor: Cristian Bucioacă
+Licensed Work: 365center-mcp
+Change Date: 2030-04-08
+Change License: MIT
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work.
+
+Additional Use Grant: You may use the Licensed Work for internal business
+purposes, testing, development, and personal projects.
+
+You may NOT use the Licensed Work to provide a commercial product or service
+that competes with the Licensed Work without explicit written permission
+from the Licensor.
+
+On the Change Date, or the fourth anniversary of the first publicly available
+distribution of a specific version of the Licensed Work under this License,
+whichever comes first, the Licensor hereby grants you rights under the terms
+of the Change License, and the rights granted in the paragraph above terminate.
+
+Contact: info@cristianb.cz

package/README.md

@@ -0,0 +1,258 @@
+# 365center-mcp
+
+MCP server for Microsoft 365 and SharePoint. Gives Claude (and any MCP client) full read-write access to SharePoint sites, documents, pages, metadata, navigation, and permissions via Microsoft Graph API and SharePoint REST API.
+
+Built for manufacturing companies that manage factory documentation in SharePoint.
+
+## Features
+
+**32 tools** across 7 categories:
+
+### Sites
+- `list_sites` — List all SharePoint sites in the tenant
+- `get_site` — Get site by URL
+- `get_site_by_id` — Get site by ID
+
+### Documents
+- `list_document_libraries` — List document libraries (drives)
+- `list_documents` — List documents with both driveItemId and listItemId
+- `upload_document` — Upload files to SharePoint
+- `search_documents` — Search across documents
+- `delete_document` — Delete a document
+- `create_folder` — Create folders
+- `get_document_versions` — Version history (audit trail)
+
+### Metadata
+- `list_columns` — List custom metadata columns
+- `create_choice_column` — Create choice/dropdown columns
+- `create_text_column` — Create text columns
+- `get_document_metadata` — Read document metadata
+- `set_document_metadata` — Set metadata on documents
+
+### Pages
+- `list_pages` — List all pages
+- `create_page` — Create empty page
+- `create_page_with_content` — Create page with sections and HTML content
+- `add_quick_links` — Add Quick Links web part
+- `publish_page` — Publish a draft page
+- `delete_page` — Delete a page
+
+### Pages (REST API)
+- `list_site_pages` — List pages with numeric IDs
+- `get_page_canvas_content` — Read raw page content (CanvasContent1)
+- `set_page_canvas_content` — Write raw page content (supports Highlighted Content and any web part)
+- `copy_page` — Copy a page as template
+
+### Navigation
+- `get_navigation` — Read top navigation menu
+- `add_navigation_link` — Add link to navigation
+- `delete_navigation_link` — Remove link from navigation
+
+### Permissions
+- `get_permissions` — List SharePoint groups (Visitors, Members, Owners)
+- `get_group_members` — List members of a group
+- `add_user_to_group` — Add user to a group
+- `remove_user_from_group` — Remove user from a group
+
+## Authentication
+
+365center-mcp uses two authentication methods:
+
+- **App-only (Client Credentials)** — for Graph API operations (sites, documents, pages, metadata). Works automatically with Azure App Registration credentials.
+- **Delegated (Device Code Flow)** — for SharePoint REST API operations (navigation, permissions, Highlighted Content). On first use, you'll be prompted to sign in via https://login.microsoft.com/device with a one-time code. Token is cached and refreshed automatically.
+
+## Prerequisites
+
+- Microsoft 365 tenant with SharePoint
+- Azure App Registration with:
+  - **Application permissions:** Sites.ReadWrite.All, Sites.FullControl.All, Files.ReadWrite.All, Sites.Manage.All
+  - **Delegated permissions:** Sites.ReadWrite.All, Sites.FullControl.All, offline_access
+  - **SharePoint permissions:** Sites.FullControl.All
+  - **"Allow public client flows" enabled** (for device code auth)
+
+## Installation
+
+### Docker (recommended)
+
+```bash
+docker pull crscristi28/365center-mcp:latest
+
+# Claude Desktop config (claude_desktop_config.json):
+{
+  "mcpServers": {
+    "<your-server-name>": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "AZURE_TENANT_ID=your-tenant-id",
+        "-e", "AZURE_CLIENT_ID=your-client-id",
+        "-e", "AZURE_CLIENT_SECRET=your-client-secret",
+        "-e", "SHAREPOINT_DOMAIN=your-domain.sharepoint.com",
+        "-v", "~/.365center-mcp:/home/mcp/.365center-mcp",
+        "crscristi28/365center-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+### Node.js
+
+```bash
+git clone https://github.com/Crscristi28/365center-mcp.git
+cd 365center-mcp/mcp-server
+npm install
+npm run build
+
+# Create .env file:
+AZURE_TENANT_ID=your-tenant-id
+AZURE_CLIENT_ID=your-client-id
+AZURE_CLIENT_SECRET=your-client-secret
+SHAREPOINT_DOMAIN=your-domain.sharepoint.com
+
+# Run:
+node dist/index.js
+```
+
+### Claude Desktop config (Node.js)
+
+```json
+{
+  "mcpServers": {
+    "<your-server-name>": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/index.js"],
+      "env": {
+        "AZURE_TENANT_ID": "your-tenant-id",
+        "AZURE_CLIENT_ID": "your-client-id",
+        "AZURE_CLIENT_SECRET": "your-client-secret",
+        "SHAREPOINT_DOMAIN": "your-domain.sharepoint.com"
+      }
+    }
+  }
+}
+```
+
+## Page Layouts
+
+When using `create_page_with_content`, available section layouts:
+
+| Layout | Columns | Widths |
+|--------|---------|--------|
+| `oneColumn` | 1 | 12 |
+| `twoColumns` | 2 | 6 + 6 |
+| `threeColumns` | 3 | 4 + 4 + 4 |
+| `oneThirdLeftColumn` | 2 | 4 + 8 |
+| `oneThirdRightColumn` | 2 | 8 + 4 |
+| `fullWidth` | 1 | 12 |
+
+## Supported Web Parts
+
+When creating pages via Graph API, these standard web parts are supported:
+
+| Web Part | Type ID |
+|----------|---------|
+| Bing Maps | `e377ea37-9047-43b9-8cdb-a761be2f8e09` |
+| Button | `0f087d7f-520e-42b7-89c0-496aaf979d58` |
+| Call To Action | `df8e44e7-edd5-46d5-90da-aca1539313b8` |
+| Divider | `2161a1c6-db61-4731-b97c-3cdb303f7cbb` |
+| Document Embed | `b7dd04e1-19ce-4b24-9132-b60a1c2b910d` |
+| Image | `d1d91016-032f-456d-98a4-721247c305e8` |
+| Image Gallery | `af8be689-990e-492a-81f7-ba3e4cd3ed9c` |
+| Link Preview | `6410b3b6-d440-4663-8744-378976dc041e` |
+| Org Chart | `e84a8ca2-f63c-4fb9-bc0b-d8eef5ccb22b` |
+| People | `7f718435-ee4d-431c-bdbf-9c4ff326f46e` |
+| Quick Links | `c70391ea-0b10-4ee9-b2b4-006d3fcad0cd` |
+| Spacer | `8654b779-4886-46d4-8ffb-b5ed960ee986` |
+| YouTube Embed | `544dd15b-cf3c-441b-96da-004d5a8cea1d` |
+| Title Area | `cbe7b0a9-3504-44dd-a3a3-0e5cacd07788` |
+
+For **Highlighted Content** and other unsupported web parts, use the REST API tools (`get_page_canvas_content` / `set_page_canvas_content`).
+
+## Security
+
+365center-mcp is designed for enterprise environments:
+
+- **No data leaves your tenant** — all API calls go directly from the MCP server to Microsoft Graph API and SharePoint REST API. No third-party servers, no telemetry, no analytics.
+- **Azure AD authentication** — uses your organization's existing Azure App Registration with OAuth 2.0. Credentials are never stored in the codebase.
+- **Principle of least privilege** — app-only auth for read/write operations, delegated auth only when required (navigation, permissions). You control exactly which permissions are granted.
+- **Device Code Flow** — delegated auth uses Microsoft's standard device code flow (same as Azure CLI, GitHub CLI). No localhost servers, no open ports, no redirect URIs needed.
+- **Token security** — refresh tokens are stored locally in `~/.365center-mcp/token-cache.json` with filesystem permissions. Tokens are never transmitted to third parties.
+- **Docker isolation** — runs as non-root user (`mcp`) inside the container. Token cache is mounted as a volume, not baked into the image.
+- **No secrets in Docker image** — credentials are passed as environment variables at runtime, never included in the build.
+- **MCP stdio transport** — communicates via stdin/stdout only. No HTTP server, no exposed ports, no network attack surface.
+- **BSL license** — source code is fully auditable. Your security team can review every line before deployment.
+
+### Recommended deployment
+
+For production environments:
+
+1. Create a dedicated Azure App Registration for 365center-mcp
+2. Grant only the permissions your workflows need
+3. Use Docker with volume mount for token persistence
+4. Store credentials in your organization's secret manager (Azure Key Vault, HashiCorp Vault, etc.)
+5. Restrict App Registration to specific SharePoint sites if possible
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AZURE_TENANT_ID` | Yes | Azure AD tenant ID |
+| `AZURE_CLIENT_ID` | Yes | App registration client ID |
+| `AZURE_CLIENT_SECRET` | Yes | App registration client secret |
+| `SHAREPOINT_DOMAIN` | Yes | SharePoint domain (e.g. `contoso.sharepoint.com`) |
+
+## Architecture
+
+```
+Claude Desktop / Claude Code / API
+        │
+        │ stdio (stdin/stdout)
+        │
+  365center-mcp (MCP Server)
+        │
+        ├── Microsoft Graph API (v1.0)
+        │   └── Sites, Documents, Pages, Metadata
+        │
+        └── SharePoint REST API
+            └── Navigation, Permissions, CanvasContent1
+```
+
+- **Graph API** uses app-only auth (Client Credentials) — no user interaction needed
+- **REST API** uses delegated auth (Device Code Flow) — one-time login, then automatic token refresh
+
+## Docker Details
+
+The Docker image runs as non-root user `mcp` and communicates only via stdio.
+
+```bash
+# Build
+docker build -t 365center-mcp:latest ./mcp-server
+
+# Run standalone (for testing)
+docker run -i --rm \
+  -e AZURE_TENANT_ID=your-tenant-id \
+  -e AZURE_CLIENT_ID=your-client-id \
+  -e AZURE_CLIENT_SECRET=your-client-secret \
+  -e SHAREPOINT_DOMAIN=your-domain.sharepoint.com \
+  -v ~/.365center-mcp:/home/mcp/.365center-mcp \
+  crscristi28/365center-mcp:latest
+```
+
+The `-v` flag mounts the token cache directory so delegated auth tokens persist across container restarts. Without it, you'd need to re-authenticate every time the container starts.
+
+## Token Storage
+
+Delegated auth tokens are stored in `~/.365center-mcp/token-cache.json`. This file contains:
+- Access token (expires in ~1 hour, refreshed automatically)
+- Refresh token (long-lived, used to get new access tokens)
+
+For Docker, mount `~/.365center-mcp` as a volume. The token file has the same security sensitivity as your Azure credentials — protect it accordingly.
+
+## License
+
+[Business Source License 1.1](LICENSE) — Free for internal use, testing, and development. Commercial use that competes with 365center-mcp requires written permission. Converts to MIT on 2030-04-08.
+
+## Author
+
+Cristian Bucioacă — [cristianb.cz](https://cristianb.cz) — [info@cristianb.cz](mailto:info@cristianb.cz)

package/dist/auth.d.ts

@@ -0,0 +1,8 @@
+import { ClientSecretCredential } from "@azure/identity";
+import { Client } from "@microsoft/microsoft-graph-client";
+export declare const credential: ClientSecretCredential;
+export declare const graphClient: Client;
+export declare function getDelegatedToken(): Promise<string>;
+export declare function getSharePointToken(): Promise<string>;
+export declare function getSharePointDelegatedToken(): Promise<string>;
+export declare function callSharePointRest(siteUrl: string, apiPath: string, method?: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<unknown>;

package/dist/auth.js

@@ -0,0 +1,200 @@
+import { ClientSecretCredential } from "@azure/identity";
+import { Client } from "@microsoft/microsoft-graph-client";
+import { TokenCredentialAuthenticationProvider } from "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials/index.js";
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from "url";
+import fs from "fs";
+// Load .env — try parent directory first (local dev), fallback to env vars (Docker)
+const __dirname = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, "../../.env") });
+const tenantId = process.env.AZURE_TENANT_ID;
+const clientId = process.env.AZURE_CLIENT_ID;
+const clientSecret = process.env.AZURE_CLIENT_SECRET;
+// ============ APP-ONLY AUTH (Graph API) ============
+export const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
+const authProvider = new TokenCredentialAuthenticationProvider(credential, {
+    scopes: ["https://graph.microsoft.com/.default"],
+});
+export const graphClient = Client.initWithMiddleware({
+    authProvider,
+});
+// ============ DELEGATED AUTH (SharePoint REST API) ============
+// Store token in user's home directory — works for Node, Docker (with volume), and plugins
+const TOKEN_DIR = path.join(process.env.HOME || process.env.USERPROFILE || "/tmp", ".365center-mcp");
+if (!fs.existsSync(TOKEN_DIR))
+    fs.mkdirSync(TOKEN_DIR, { recursive: true });
+const TOKEN_CACHE_PATH = path.join(TOKEN_DIR, "token-cache.json");
+const SHAREPOINT_DOMAIN = process.env.SHAREPOINT_DOMAIN || "";
+const SP_SCOPES = `offline_access https://${SHAREPOINT_DOMAIN}/AllSites.FullControl`;
+function loadTokenCache() {
+    try {
+        if (fs.existsSync(TOKEN_CACHE_PATH)) {
+            return JSON.parse(fs.readFileSync(TOKEN_CACHE_PATH, "utf-8"));
+        }
+    }
+    catch { }
+    return null;
+}
+function saveTokenCache(cache) {
+    fs.writeFileSync(TOKEN_CACHE_PATH, JSON.stringify(cache, null, 2));
+}
+async function refreshAccessToken(refreshToken) {
+    const body = new URLSearchParams({
+        client_id: clientId,
+        client_secret: clientSecret,
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        scope: SP_SCOPES,
+    });
+    const response = await fetch(`https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body });
+    if (!response.ok) {
+        const err = await response.text();
+        throw new Error(`Token refresh failed: ${err}`);
+    }
+    const data = await response.json();
+    const cache = {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token || refreshToken,
+        expiresAt: Date.now() + data.expires_in * 1000,
+    };
+    saveTokenCache(cache);
+    return cache;
+}
+// Device code polling — runs in background after user gets instructions
+let deviceCodePollingPromise = null;
+function pollForDeviceCodeToken(deviceCode, interval, expiresIn) {
+    return new Promise(async (resolve, reject) => {
+        const pollInterval = (interval || 5) * 1000;
+        const deadline = Date.now() + expiresIn * 1000;
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, pollInterval));
+            const tokenResponse = await fetch(`https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: deviceCode,
+                }),
+            });
+            const tokenData = await tokenResponse.json();
+            if (tokenData.access_token) {
+                const cache = {
+                    accessToken: tokenData.access_token,
+                    refreshToken: tokenData.refresh_token,
+                    expiresAt: Date.now() + tokenData.expires_in * 1000,
+                };
+                saveTokenCache(cache);
+                deviceCodePollingPromise = null;
+                resolve(cache);
+                return;
+            }
+            if (tokenData.error === "authorization_pending")
+                continue;
+            if (tokenData.error === "slow_down") {
+                await new Promise(r => setTimeout(r, 5000));
+                continue;
+            }
+            deviceCodePollingPromise = null;
+            reject(new Error(`Device code auth failed: ${tokenData.error} — ${tokenData.error_description}`));
+            return;
+        }
+        deviceCodePollingPromise = null;
+        reject(new Error("Login timeout — user did not complete authentication in time"));
+    });
+}
+// Throws a user-facing error with login instructions, starts background polling
+async function startDeviceCodeFlow() {
+    if (!SHAREPOINT_DOMAIN) {
+        throw new Error("SHAREPOINT_DOMAIN environment variable is required for delegated auth");
+    }
+    const codeResponse = await fetch(`https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/devicecode`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            client_id: clientId,
+            scope: SP_SCOPES,
+        }),
+    });
+    if (!codeResponse.ok) {
+        const err = await codeResponse.text();
+        throw new Error(`Device code request failed: ${err}`);
+    }
+    const codeData = await codeResponse.json();
+    const { device_code, user_code, verification_uri, expires_in, interval, message } = codeData;
+    // Start polling in background
+    deviceCodePollingPromise = pollForDeviceCodeToken(device_code, interval, expires_in);
+    // Throw error with login instructions — Claude sees this and tells the user
+    throw new Error(`LOGIN REQUIRED: ${message}\n\n` +
+        `Go to: ${verification_uri}\n` +
+        `Enter code: ${user_code}\n\n` +
+        `After logging in, try your request again.`);
+}
+export async function getDelegatedToken() {
+    // 1. Check cache
+    const cache = loadTokenCache();
+    if (cache) {
+        if (cache.expiresAt > Date.now() + 300000) {
+            return cache.accessToken;
+        }
+        try {
+            const refreshed = await refreshAccessToken(cache.refreshToken);
+            return refreshed.accessToken;
+        }
+        catch {
+            // Refresh failed — need new login
+        }
+    }
+    // 2. If polling is already running, wait for it
+    if (deviceCodePollingPromise) {
+        const result = await deviceCodePollingPromise;
+        return result.accessToken;
+    }
+    // 3. No cache, no polling — start device code flow (throws with instructions)
+    await startDeviceCodeFlow();
+    throw new Error("unreachable"); // startDeviceCodeFlow always throws
+}
+// ============ SHAREPOINT REST API HELPERS ============
+// App-only token for SharePoint REST API (limited — doesn't work for navigation/permissions)
+export async function getSharePointToken() {
+    const domain = process.env.SHAREPOINT_DOMAIN;
+    if (!domain)
+        throw new Error("SHAREPOINT_DOMAIN environment variable is required");
+    const token = await credential.getToken(`https://${domain}/.default`);
+    return token.token;
+}
+// Delegated token for SharePoint REST API (full access — navigation, permissions, CanvasContent1)
+export async function getSharePointDelegatedToken() {
+    // Delegated token from Graph scopes also works for SharePoint REST API
+    // because Sites.FullControl.All grants access to SharePoint endpoints
+    return getDelegatedToken();
+}
+export async function callSharePointRest(siteUrl, apiPath, method = "GET", body, extraHeaders) {
+    const token = await getSharePointDelegatedToken();
+    const url = `${siteUrl}${apiPath}`;
+    const headers = {
+        "Authorization": `Bearer ${token}`,
+        "Accept": "application/json;odata=verbose",
+        "Content-Type": "application/json;odata=verbose",
+        ...extraHeaders,
+    };
+    // SharePoint REST API uses POST + X-HTTP-Method for MERGE/PUT/PATCH
+    let httpMethod = method;
+    if (method === "MERGE" || method === "PUT" || method === "PATCH") {
+        headers["X-HTTP-Method"] = method;
+        headers["IF-MATCH"] = "*";
+        httpMethod = "POST";
+    }
+    const options = { method: httpMethod, headers };
+    if (body) {
+        options.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, options);
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`SharePoint REST API error ${response.status}: ${errorText}`);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};