@softeria/ms-365-mcp-server 0.79.5 → 0.79.6

package/README.md

@@ -589,6 +589,10 @@ The Key Vault integration uses `DefaultAzureCredential` from the Azure Identity
 
 The Azure Key Vault packages (`@azure/identity` and `@azure/keyvault-secrets`) are optional dependencies. They are only loaded when `MS365_MCP_KEYVAULT_URL` is configured. If you don't use Key Vault, these packages are not required.
 
+## Production Deployment
+
+See [docs/deployment.md](docs/deployment.md) for a full guide to hosting the server for organization-wide access, including Docker, Azure Container Apps, Azure App Service, Azure AD app registration, reverse proxy setup, client configuration, and exposed endpoints.
+
 ## Contributing
 
 We welcome contributions! Before submitting a pull request, please ensure your changes meet our quality standards.

package/dist/graph-tools.js

@@ -7,6 +7,8 @@ import { fileURLToPath } from "url";
 import { TOOL_CATEGORIES } from "./tool-categories.js";
 import { getRequestTokens } from "./request-context.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
+import { buildBM25Index, scoreQuery, tokenize } from "./lib/bm25.js";
+import { describeToolSchema } from "./lib/tool-schema.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
@@ -484,58 +486,109 @@ function buildToolsRegistry(readOnly, orgMode) {
   }
   return toolsMap;
 }
+function buildDiscoverySearchIndex(toolsRegistry) {
+  const TIP_EXCERPT_TOKENS = 12;
+  const DESC_CAP_TOKENS = 40;
+  const docs = [];
+  const nameTokens = /* @__PURE__ */ new Map();
+  for (const [name, { tool, config }] of toolsRegistry) {
+    const nt = tokenize(name);
+    nameTokens.set(name, new Set(nt));
+    const pathTokens = tokenize(tool.path);
+    const descTokens = tokenize(tool.description).slice(0, DESC_CAP_TOKENS);
+    const tipTokens = tokenize(config?.llmTip).slice(0, TIP_EXCERPT_TOKENS);
+    const tokens = [
+      ...nt,
+      ...nt,
+      ...nt,
+      ...nt,
+      ...nt,
+      ...pathTokens,
+      ...pathTokens,
+      ...tipTokens,
+      ...descTokens
+    ];
+    docs.push({ id: name, tokens });
+  }
+  return { bm25: buildBM25Index(docs), nameTokens };
+}
+function scoreDiscoveryQuery(query, index) {
+  const queryTokenSet = new Set(tokenize(query));
+  if (queryTokenSet.size === 0) return [];
+  const ranked = scoreQuery(query, index.bm25);
+  const NAME_BONUS_WEIGHT = 2;
+  for (const r of ranked) {
+    const nt = index.nameTokens.get(r.id);
+    if (!nt || nt.size === 0) continue;
+    let matchedIdf = 0;
+    let matchedCount = 0;
+    for (const qt of queryTokenSet) {
+      if (nt.has(qt)) {
+        matchedCount++;
+        matchedIdf += index.bm25.idf.get(qt) ?? 0;
+      }
+    }
+    if (matchedCount === 0) continue;
+    const precision = matchedCount / nt.size;
+    r.score += precision * matchedIdf * NAME_BONUS_WEIGHT;
+  }
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked;
+}
 function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, _multiAccount = false) {
   const toolsRegistry = buildToolsRegistry(readOnly, orgMode);
+  const searchIndex = buildDiscoverySearchIndex(toolsRegistry);
   logger.info(`Discovery mode: ${toolsRegistry.size} tools available in registry`);
+  const categoryNames = Object.keys(TOOL_CATEGORIES).join(", ");
+  const toResultEntry = (name) => {
+    const entry = toolsRegistry.get(name);
+    if (!entry) return null;
+    const { tool, config } = entry;
+    return {
+      name,
+      method: tool.method.toUpperCase(),
+      path: tool.path,
+      description: tool.description || `${tool.method.toUpperCase()} ${tool.path}`,
+      ...config?.llmTip ? { llmTip: config.llmTip } : {}
+    };
+  };
   server.tool(
     "search-tools",
-    `Search through ${toolsRegistry.size} available Microsoft Graph API tools. Use this to find tools by name, path, or description before executing them.`,
+    `Search through ${toolsRegistry.size} Microsoft Graph API tools. Ranks results by BM25 over tool name, llmTip, description, and path (tokenized on hyphens, camelCase, and whitespace). After picking a tool, call get-tool-schema to see its parameters, then execute-tool to invoke it.`,
     {
-      query: z.string().describe("Search query to filter tools (searches name, path, and description)").optional(),
-      category: z.string().describe(
-        "Filter by category: mail, calendar, files, contacts, tasks, onenote, search, users, excel"
+      query: z.string().describe(
+        'Natural-language query. Tokenized and BM25-ranked. E.g. "send email", "create calendar event", "list unread messages".'
       ).optional(),
-      limit: z.number().describe("Maximum results to return (default: 20, max: 50)").optional()
+      category: z.string().describe(`Optional pre-filter by category: ${categoryNames}`).optional(),
+      limit: z.number().describe("Maximum results (default: 10, max: 50)").optional()
     },
     {
       title: "search-tools",
       readOnlyHint: true,
       openWorldHint: true
-      // Searches Microsoft Graph API tools
     },
-    async ({ query, category, limit = 20 }) => {
-      const maxLimit = Math.min(limit, 50);
-      const results = [];
-      const queryLower = query?.toLowerCase();
+    async ({ query, category, limit = 10 }) => {
+      const maxLimit = Math.min(Math.max(limit, 1), 50);
       const categoryDef = category ? TOOL_CATEGORIES[category] : void 0;
-      for (const [name, { tool, config }] of toolsRegistry) {
-        if (categoryDef && !categoryDef.pattern.test(name)) {
-          continue;
-        }
-        if (queryLower) {
-          const searchText = `${name} ${tool.path} ${tool.description || ""} ${config?.llmTip || ""}`.toLowerCase();
-          if (!searchText.includes(queryLower)) {
-            continue;
-          }
-        }
-        results.push({
-          name,
-          method: tool.method.toUpperCase(),
-          path: tool.path,
-          description: tool.description || `${tool.method.toUpperCase()} ${tool.path}`
-        });
-        if (results.length >= maxLimit) break;
+      const categoryFilter = (name) => !categoryDef || categoryDef.pattern.test(name);
+      let orderedNames;
+      if (query && query.trim().length > 0) {
+        const ranked = scoreDiscoveryQuery(query, searchIndex);
+        orderedNames = ranked.map((r) => r.id).filter(categoryFilter);
+      } else {
+        orderedNames = [...toolsRegistry.keys()].filter(categoryFilter);
       }
+      const tools = orderedNames.slice(0, maxLimit).map(toResultEntry).filter(Boolean);
       return {
         content: [
           {
             type: "text",
             text: JSON.stringify(
               {
-                found: results.length,
+                found: tools.length,
                 total: toolsRegistry.size,
-                tools: results,
-                tip: "Use execute-tool with the tool name and required parameters to call any of these tools."
+                tools,
+                tip: "Call get-tool-schema(tool_name) to see parameters before invoking execute-tool."
               },
               null,
               2
@@ -545,20 +598,53 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
       };
     }
   );
+  server.tool(
+    "get-tool-schema",
+    "Returns the full parameter schema (name, placement, required, JSON Schema) for a tool discovered via search-tools. Call this before execute-tool so you know what parameters to pass and what enum values are valid.",
+    {
+      tool_name: z.string().describe('Exact tool name from search-tools (e.g. "send-mail")')
+    },
+    {
+      title: "get-tool-schema",
+      readOnlyHint: true,
+      openWorldHint: false
+    },
+    async ({ tool_name }) => {
+      const entry = toolsRegistry.get(tool_name);
+      if (!entry) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `Tool not found: ${tool_name}`,
+                tip: "Use search-tools to find available tools."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const schema = describeToolSchema(entry.tool, entry.config?.llmTip);
+      return {
+        content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
+      };
+    }
+  );
   server.tool(
     "execute-tool",
-    "Execute a Microsoft Graph API tool by name. Use search-tools first to find available tools and their parameters. For list endpoints, pass a small $top (or top) first and use $select to limit fields\u2014avoid large page sizes unless the user needs them.",
+    "Execute a Microsoft Graph API tool by name. Workflow: search-tools \u2192 get-tool-schema \u2192 execute-tool. Call get-tool-schema first for any tool you have not seen before \u2014 passing the wrong shape to parameters will fail validation or return a Graph 400. For list endpoints, prefer modest $top plus $select.",
     {
       tool_name: z.string().describe('Name of the tool to execute (e.g., "list-mail-messages")'),
-      parameters: z.record(z.any()).describe("Parameters to pass to the tool as key-value pairs").optional()
+      parameters: z.record(z.any()).describe(
+        'Parameters shaped per get-tool-schema. Path/query/header params go at the top level; request bodies go under "body".'
+      ).optional()
     },
     {
       title: "execute-tool",
       readOnlyHint: false,
       destructiveHint: true,
-      // Can execute any tool, including write operations
       openWorldHint: true
-      // Executes against Microsoft Graph API
     },
     async ({ tool_name, parameters = {} }) => {
       const toolData = toolsRegistry.get(tool_name);
@@ -581,6 +667,9 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
   );
 }
 export {
+  buildDiscoverySearchIndex,
+  buildToolsRegistry,
   registerDiscoveryTools,
-  registerGraphTools
+  registerGraphTools,
+  scoreDiscoveryQuery
 };

package/dist/lib/bm25.js

@@ -0,0 +1,53 @@
+function tokenize(text) {
+  if (!text) return [];
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[\s\-_/.,;:(){}[\]'"!?@#$]+/).filter((t) => t.length > 0);
+}
+function buildBM25Index(documents, k1 = 1.2, b = 0.75) {
+  const docs = /* @__PURE__ */ new Map();
+  const df = /* @__PURE__ */ new Map();
+  let totalLen = 0;
+  for (const { id, tokens } of documents) {
+    const termFreq = /* @__PURE__ */ new Map();
+    for (const tok of tokens) {
+      termFreq.set(tok, (termFreq.get(tok) ?? 0) + 1);
+    }
+    for (const tok of termFreq.keys()) {
+      df.set(tok, (df.get(tok) ?? 0) + 1);
+    }
+    docs.set(id, { id, length: tokens.length, termFreq });
+    totalLen += tokens.length;
+  }
+  const N = docs.size;
+  const avgdl = N > 0 ? totalLen / N : 0;
+  const idf = /* @__PURE__ */ new Map();
+  for (const [term, n] of df) {
+    idf.set(term, Math.log((N - n + 0.5) / (n + 0.5) + 1));
+  }
+  return { docs, idf, avgdl, k1, b };
+}
+function scoreQuery(query, index) {
+  const queryTokens = [...new Set(tokenize(query))];
+  if (queryTokens.length === 0) return [];
+  const results = [];
+  for (const [id, doc] of index.docs) {
+    let score = 0;
+    let matched = false;
+    for (const qt of queryTokens) {
+      const tf = doc.termFreq.get(qt);
+      if (!tf) continue;
+      matched = true;
+      const idf = index.idf.get(qt) ?? 0;
+      const num = tf * (index.k1 + 1);
+      const den = tf + index.k1 * (1 - index.b + index.b * doc.length / (index.avgdl || 1));
+      score += idf * (num / den);
+    }
+    if (matched) results.push({ id, score });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+export {
+  buildBM25Index,
+  scoreQuery,
+  tokenize
+};

package/dist/lib/tool-schema.js

@@ -0,0 +1,35 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+function unwrapOptional(schema) {
+  const def = schema._def;
+  const typeName = def?.typeName;
+  if (typeName === "ZodOptional" || typeName === "ZodDefault" || typeName === "ZodNullable") {
+    return { inner: def.innerType, optional: true };
+  }
+  return { inner: schema, optional: false };
+}
+function describeToolSchema(tool, llmTip) {
+  const params = (tool.parameters ?? []).map((p) => {
+    const { inner, optional } = unwrapOptional(p.schema);
+    const isPath = p.type === "Path";
+    const jsonSchema = zodToJsonSchema(inner, { target: "jsonSchema7", $refStrategy: "none" });
+    const { $schema: _s, ...schema } = jsonSchema;
+    return {
+      name: p.name,
+      in: p.type,
+      required: isPath || !optional,
+      description: p.description,
+      schema
+    };
+  });
+  return {
+    name: tool.alias,
+    method: tool.method.toUpperCase(),
+    path: tool.path,
+    description: tool.description ?? "",
+    ...llmTip ? { llmTip } : {},
+    parameters: params
+  };
+}
+export {
+  describeToolSchema
+};

package/dist/mcp-instructions.js

@@ -14,7 +14,7 @@ function buildGeneralMcpInstructions(opts) {
     parts.push("Work/school-only tools require starting the server with --org-mode.");
   return parts.join(" ");
 }
-const DISCOVERY_MODE_INSTRUCTIONS_ADDON = "DISCOVERY MODE ADD-ON: Graph is reached via search-tools then execute-tool (plus auth helpers). Call search-tools with short keywords, then execute-tool with tool_name exactly as returned; put Graph parameters in the parameters object. If search-tools returns no matches, retry with shorter or different keywords.";
+const DISCOVERY_MODE_INSTRUCTIONS_ADDON = "DISCOVERY MODE ADD-ON: Graph is reached via search-tools \u2192 get-tool-schema \u2192 execute-tool (plus auth helpers). Workflow: (1) call search-tools with short natural-language keywords (BM25-ranked); (2) call get-tool-schema(tool_name) to see the parameters, required fields, and enum values; (3) call execute-tool with tool_name exactly as returned and parameters shaped per the schema. Skipping get-tool-schema is the leading cause of Graph 400 errors here. If search-tools returns no matches, retry with shorter or different keywords.";
 function buildMcpServerInstructions(opts) {
   const general = buildGeneralMcpInstructions(opts);
   if (!opts.discovery) return general;

package/docs/deployment.md

@@ -0,0 +1,189 @@
+# Production Deployment
+
+The server can be hosted centrally so that multiple users in an organization share a single MCP endpoint. Each user
+authenticates with their own Microsoft account via OAuth — the server is stateless and does not store tokens.
+
+## Architecture
+
+```
+MCP Clients (Claude Desktop, Claude Code, Open WebUI, ...)
+         │  Streamable HTTP + OAuth 2.1
+         ▼
+   ┌─────────────────────────────┐
+   │  ms-365-mcp-server --http   │  Azure Container Apps / App Service / Docker
+   │  (stateless, no token store)│
+   └─────────────┬───────────────┘
+                 │  Bearer token (per-user)
+                 ▼
+         Microsoft Graph API
+```
+
+## Docker
+
+A `Dockerfile` is included for containerized deployments:
+
+```bash
+# Build the image
+docker build -t ms-365-mcp-server .
+
+# Run with environment variables
+docker run -p 3000:3000 \
+  -e MS365_MCP_CLIENT_ID=your-client-id \
+  -e MS365_MCP_TENANT_ID=your-tenant-id \
+  -e MS365_MCP_CLIENT_SECRET=your-secret \
+  -e MS365_MCP_ORG_MODE=true \
+  ms-365-mcp-server \
+  --http 3000 --org-mode
+```
+
+For production, use Azure Key Vault instead of environment variables for secrets (see [Azure Key Vault Integration](../README.md#azure-key-vault-integration)):
+
+```bash
+docker run -p 3000:3000 \
+  -e MS365_MCP_KEYVAULT_URL=https://your-keyvault.vault.azure.net \
+  -e MS365_MCP_ORG_MODE=true \
+  -e MS365_MCP_BASE_URL=https://mcp.example.com \
+  ms-365-mcp-server \
+  --http 3000 --org-mode
+```
+
+## Azure Container Apps
+
+1. **Push the image** to Azure Container Registry:
+
+   ```bash
+   az acr build --registry yourregistry --image ms365-mcp-server:latest .
+   ```
+
+2. **Create the Container App** with system-assigned managed identity:
+
+   ```bash
+   az containerapp create \
+     --name mcp-server \
+     --resource-group your-rg \
+     --environment your-cae \
+     --image yourregistry.azurecr.io/ms365-mcp-server:latest \
+     --target-port 3000 \
+     --ingress external \
+     --min-replicas 1 \
+     --max-replicas 3 \
+     --cpu 0.5 --memory 1Gi \
+     --system-assigned \
+     --env-vars \
+       "MS365_MCP_KEYVAULT_URL=https://your-keyvault.vault.azure.net" \
+       "MS365_MCP_ORG_MODE=true" \
+       "MS365_MCP_BASE_URL=https://mcp.example.com" \
+     --command "node" "dist/index.js" "--http" "3000" "--org-mode"
+   ```
+
+3. **Grant Key Vault access** to the managed identity:
+
+   ```bash
+   PRINCIPAL_ID=$(az containerapp show --name mcp-server --resource-group your-rg \
+     --query identity.principalId -o tsv)
+   az keyvault set-policy --name your-keyvault --object-id $PRINCIPAL_ID \
+     --secret-permissions get list
+   ```
+
+## Azure App Service
+
+```bash
+az webapp create \
+  --name mcp-server \
+  --resource-group your-rg \
+  --plan your-plan \
+  --runtime "NODE:20-lts" \
+  --assign-identity
+
+az webapp config appsettings set --name mcp-server --resource-group your-rg \
+  --settings \
+    MS365_MCP_KEYVAULT_URL="https://your-keyvault.vault.azure.net" \
+    MS365_MCP_ORG_MODE="true" \
+    MS365_MCP_BASE_URL="https://mcp-server.azurewebsites.net" \
+    WEBSITES_PORT="3000"
+
+az webapp config set --name mcp-server --resource-group your-rg \
+  --startup-file "node dist/index.js --http 3000 --org-mode"
+```
+
+## Azure AD App Registration (for organizations)
+
+When deploying for an organization, create a dedicated app registration instead of using the built-in client ID:
+
+1. **Create the app** in [Azure Portal](https://portal.azure.com) > App registrations > New registration
+   - Name: `MS365 MCP Server`
+   - Supported account types: **Accounts in this organizational directory only** (single tenant)
+   - Redirect URI: your server's callback URL
+
+2. **Add API permissions** > Microsoft Graph > Delegated permissions
+   Run `npx @softeria/ms-365-mcp-server --org-mode --list-permissions` to print the exact list of permissions required for your enabled tools.
+
+3. **Grant admin consent** to skip per-user consent prompts:
+
+   ```bash
+   az ad app permission admin-consent --id your-app-client-id
+   ```
+
+4. **Create a client secret** under Certificates & secrets, then store it in Key Vault
+
+5. **Store credentials** in Key Vault (see [Azure Key Vault Integration](../README.md#azure-key-vault-integration))
+
+## Reverse Proxy / Custom Domain
+
+When running behind a reverse proxy or custom domain, set `MS365_MCP_BASE_URL` so OAuth discovery endpoints return the correct public URL:
+
+```bash
+# Via environment variable
+MS365_MCP_BASE_URL=https://mcp.example.com
+
+# Or via CLI flag
+--base-url https://mcp.example.com
+```
+
+Without this, `/.well-known/oauth-authorization-server` would advertise `http://localhost:3000` as the authorization endpoint.
+
+## Client Configuration
+
+Once deployed, users connect by pointing their MCP client to the server URL:
+
+**Claude Desktop:**
+
+```json
+{
+  "mcpServers": {
+    "ms365": {
+      "type": "streamable-http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add ms365 --transport http https://mcp.example.com/mcp
+```
+
+The client automatically discovers OAuth endpoints and opens a browser for authentication on first use.
+
+## Security Considerations
+
+- **Stateless**: the server does not store tokens — each request carries the user's Bearer token
+- **Admin consent**: grant tenant-wide consent to avoid per-user consent prompts
+- **Managed identity**: use managed identity for Key Vault access (no secrets in environment variables)
+- **Read-only mode**: use `--read-only` to disable all write operations (send, delete, update, create)
+- **Tool filtering**: use `--enabled-tools <regex>` or `--preset <names>` to restrict available tools
+- **CORS**: configure `MS365_MCP_CORS_ORIGIN` to restrict allowed origins (defaults to `http://localhost:3000`); set explicitly when clients run on a different origin
+
+## Exposed Endpoints
+
+| Path                                      | Method   | Description                     | Auth Required |
+| ----------------------------------------- | -------- | ------------------------------- | ------------- |
+| `/`                                       | GET      | Health check                    | No            |
+| `/mcp`                                    | GET/POST | MCP protocol endpoint           | Bearer token  |
+| `/authorize`                              | GET      | OAuth — redirect to Microsoft   | No            |
+| `/token`                                  | POST     | OAuth — code exchange / refresh | No            |
+| `/register`                               | POST     | OAuth — dynamic registration    | No            |
+| `/.well-known/oauth-authorization-server` | GET      | OAuth server metadata           | No            |
+| `/.well-known/oauth-protected-resource`   | GET      | Protected resource metadata     | No            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.79.5",
+  "version": "0.79.6",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,8 @@
     "js-yaml": "^4.1.0",
     "open": "^11.0.0",
     "winston": "^3.17.0",
-    "zod": "^3.24.2"
+    "zod": "^3.24.2",
+    "zod-to-json-schema": "^3.25.1"
   },
   "optionalDependencies": {
     "@azure/identity": "^4.5.0",