m365connector 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# m365connector
+
+MCP server that lets AI agents search and read your Microsoft 365 data (emails, files, Teams chats, calendar events, people, and external connectors).
+
+Works with any MCP-compatible client: Claude Code, Claude Desktop, etc.
+
+## How it works
+
+```
+MCP Client          m365connector              Browser Extension
+(Claude Code)       (this package)             (Chrome/Edge MV3)
+
+  HTTP :52366         WebSocket :52365
+  ───────────►  ◄──────────────────►
+  Streamable HTTP     IPC bridge              Captures tokens,
+  transport           (localhost)             executes API calls
+```
+
+The MCP server runs as a long-lived process. A companion browser extension connects over WebSocket and handles all M365 API calls using tokens captured from the browser.
+
+## Prerequisites
+
+- Node.js 18+
+- The [M365 Connector browser extension](https://github.com/anthropics/m365-connector-extension) loaded in Chrome or Edge
+- An M365 account (work or school)
+
+## Quick start
+
+```bash
+npx m365connector
+```
+
+You should see:
+
+```
+[workiq/ws] listening on ws://127.0.0.1:52365
+[workiq] MCP HTTP listening on http://127.0.0.1:52366/mcp
+```
+
+Then add to your MCP client config (e.g. `~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "m365-connector": {
+      "type": "http",
+      "url": "http://127.0.0.1:52366/mcp"
+    }
+  }
+}
+```
+
+## Global install
+
+```bash
+npm install -g m365connector
+m365connector
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WORKIQ_MCP_PORT` | 52366 | HTTP port for MCP clients |
+| `WORKIQ_WS_PORT` | 52365 | WebSocket port for extension IPC |
+
+## Tools
+
+### search
+
+Search across M365 data sources.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| query | string | yes | | Search query |
+| conversation_id | string | yes | | Conversation identifier for grouping requests |
+| source | string | no | `"all"` | `all`, `email`, `files`, `chat`, `events`, `people`, `external` |
+| connector | string | no | | External connector name (when source=`external`) |
+| size | integer | no | 10 | Results per page (1--25) |
+| from | integer | no | 0 | Pagination offset |
+
+### open
+
+Read the content of a search result.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| read_handle | string | yes | Opaque handle from a search result's `_readHandle` field |
+| conversation_id | string | yes | Conversation identifier |
+
+Returns content with a `completeness` field: `full`, `partial`, or `snippet`.
+
+## Security
+
+- Both servers bind to `127.0.0.1` only (not accessible from the network)
+- WebSocket accepts connections only from `chrome-extension://` origins
+- Read handles are server-issued opaque UUIDs with 30-minute TTL
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/index.js";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "m365connector",
+  "version": "0.1.0",
+  "description": "MCP server for M365 Connector browser extension",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "m365connector": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "microsoft365",
+    "m365",
+    "search"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "ws": "^8.18.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,303 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { WsServer } from "./ws-server.js";
+
+const SERVER_INFO = {
+  name: "workiq-lite",
+  version: "0.1.0"
+};
+
+const DEFAULT_MCP_PORT = 52366;
+const DEFAULT_WS_PORT = 52365;
+const SESSION_IDLE_TTL_MS = 30 * 60 * 1000;
+const SESSION_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+class ToolRegistry {
+  constructor() {
+    this.tools = [];
+    this.handlers = new Map();
+  }
+
+  addTool(definition, handler) {
+    if (!definition?.name) {
+      throw new Error("Tool definition must include name");
+    }
+    if (this.handlers.has(definition.name)) {
+      throw new Error(`Duplicate tool name: ${definition.name}`);
+    }
+
+    this.tools.push(definition);
+    this.handlers.set(definition.name, handler);
+  }
+
+  list() {
+    return this.tools;
+  }
+
+  getHandler(name) {
+    return this.handlers.get(name);
+  }
+}
+
+function createReadHandleCache() {
+  const cache = new Map();
+
+  const interval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, value] of cache.entries()) {
+      if (value.expiresAt < now) {
+        cache.delete(key);
+      }
+    }
+  }, 60_000);
+
+  interval.unref();
+
+  return cache;
+}
+
+async function loadToolModules(toolRegistry, context) {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  const toolsDir = path.resolve(currentDir, "tools");
+  const files = fs
+    .readdirSync(toolsDir)
+    .filter((name) => name.endsWith(".js"))
+    .sort((a, b) => a.localeCompare(b));
+
+  for (const fileName of files) {
+    const fullPath = path.join(toolsDir, fileName);
+    const moduleUrl = pathToFileURL(fullPath).href;
+    const mod = await import(moduleUrl);
+
+    if (typeof mod.registerTools !== "function") {
+      continue;
+    }
+
+    mod.registerTools(toolRegistry, context);
+  }
+}
+
+function toToolSuccessResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ],
+    structuredContent: payload
+  };
+}
+
+function toToolErrorResult(message) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Error: ${message}`
+      }
+    ],
+    isError: true
+  };
+}
+
+function createSessionServer(toolRegistry, _context) {
+  const server = new Server(SERVER_INFO, {
+    capabilities: {
+      tools: {}
+    }
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolRegistry.list()
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const handler = toolRegistry.getHandler(toolName);
+
+    if (!handler) {
+      return toToolErrorResult(`Unknown tool: ${toolName}`);
+    }
+
+    try {
+      const args = request.params.arguments || {};
+      const result = await handler(args);
+      return toToolSuccessResult(result);
+    } catch (err) {
+      return toToolErrorResult(String(err?.message || err));
+    }
+  });
+
+  return server;
+}
+
+function parsePort(value, envName, defaultPort) {
+  const port = Number(value || defaultPort);
+  if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
+    throw new Error(`${envName} must be a valid TCP port number`);
+  }
+  return port;
+}
+
+function sendJsonRpcError(res, status, code, message) {
+  res.status(status).json({
+    jsonrpc: "2.0",
+    error: {
+      code,
+      message
+    },
+    id: null
+  });
+}
+
+async function main() {
+  const mcpPort = parsePort(process.env.WORKIQ_MCP_PORT, "WORKIQ_MCP_PORT", DEFAULT_MCP_PORT);
+  const wsPort = parsePort(process.env.WORKIQ_WS_PORT, "WORKIQ_WS_PORT", DEFAULT_WS_PORT);
+
+  // MCP responses are returned over HTTP; operational logs must go to stderr only.
+  const stderrLogger = {
+    info: (...args) => console.error(...args),
+    warn: (...args) => console.warn(...args),
+    error: (...args) => console.error(...args)
+  };
+
+  const readHandleCache = createReadHandleCache();
+
+  const ws = new WsServer({
+    host: "127.0.0.1",
+    port: wsPort,
+    logger: stderrLogger
+  });
+  await ws.start();
+
+  const toolRegistry = new ToolRegistry();
+  const toolContext = { ws, readHandleCache };
+  await loadToolModules(toolRegistry, toolContext);
+
+  const sessions = new Map();
+  const app = createMcpExpressApp({ host: "127.0.0.1" });
+
+  app.all("/mcp", async (req, res) => {
+    const sessionId = req.get("mcp-session-id");
+
+    try {
+      if (req.method === "POST" && !sessionId) {
+        let initializedSessionId;
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => crypto.randomUUID(),
+          onsessioninitialized: async (newSessionId) => {
+            const server = createSessionServer(toolRegistry, toolContext);
+            await server.connect(transport);
+            initializedSessionId = newSessionId;
+            sessions.set(newSessionId, {
+              server,
+              transport,
+              lastActivity: Date.now()
+            });
+          }
+        });
+
+        transport.onerror = (err) => {
+          stderrLogger.warn("[workiq] MCP transport error:", err);
+        };
+
+        transport.onclose = () => {
+          const closedSessionId = initializedSessionId || transport.sessionId;
+          if (!closedSessionId) {
+            return;
+          }
+          sessions.delete(closedSessionId);
+        };
+
+        await transport.handleRequest(req, res, req.body);
+        return;
+      }
+
+      if (!sessionId) {
+        sendJsonRpcError(res, 400, -32000, "Bad Request: Mcp-Session-Id header is required");
+        return;
+      }
+
+      const session = sessions.get(sessionId);
+      if (!session) {
+        sendJsonRpcError(res, 404, -32001, "Session not found");
+        return;
+      }
+
+      session.lastActivity = Date.now();
+      await session.transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      stderrLogger.error("[workiq] failed to handle MCP request:", err);
+      if (!res.headersSent) {
+        sendJsonRpcError(res, 500, -32603, "Internal error");
+      }
+    }
+  });
+
+  const sessionSweepInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [sessionId, session] of sessions.entries()) {
+      if (now - session.lastActivity <= SESSION_IDLE_TTL_MS) {
+        continue;
+      }
+
+      session.server.close().catch((err) => {
+        stderrLogger.warn(`[workiq] failed to close idle session ${sessionId}:`, err);
+      });
+    }
+  }, SESSION_SWEEP_INTERVAL_MS);
+  sessionSweepInterval.unref();
+
+  const httpServer = await new Promise((resolve, reject) => {
+    const server = app.listen(mcpPort, "127.0.0.1");
+    server.once("listening", () => resolve(server));
+    server.once("error", reject);
+  });
+
+  stderrLogger.error(`[workiq] MCP HTTP listening on http://127.0.0.1:${mcpPort}/mcp`);
+
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+
+    clearInterval(sessionSweepInterval);
+
+    for (const session of sessions.values()) {
+      try {
+        await session.server.close();
+      } catch (err) {
+        stderrLogger.warn("[workiq] failed to close session during shutdown:", err);
+      }
+    }
+
+    try {
+      await ws.stop();
+    } catch (err) {
+      stderrLogger.warn("[workiq] failed to stop WebSocket server:", err);
+    }
+
+    await new Promise((resolve) => {
+      httpServer.close(() => resolve());
+    });
+
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => {
+  console.error("[workiq] MCP server failed to start:", err);
+  process.exit(1);
+});

package/src/tools/search.js

@@ -0,0 +1,201 @@
+import crypto from "node:crypto";
+
+const SEARCH_TOOL = {
+  name: "search",
+  description:
+    "Search across Microsoft 365 data including emails, files, Teams chats, calendar events, people, and external connectors.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      conversation_id: {
+        type: "string",
+        description: "Client-provided conversation identifier for grouping related requests"
+      },
+      query: {
+        type: "string",
+        description: "Search query string"
+      },
+      source: {
+        type: "string",
+        enum: ["all", "email", "files", "chat", "events", "people", "external"],
+        description: "Data source to search",
+        default: "all"
+      },
+      connector: {
+        type: "string",
+        description: "Specific external connector name when source='external'"
+      },
+      size: {
+        type: "integer",
+        minimum: 1,
+        maximum: 25,
+        description: "Number of results to return",
+        default: 10
+      },
+      from: {
+        type: "integer",
+        minimum: 0,
+        description: "Pagination offset",
+        default: 0
+      }
+    },
+    required: ["query", "conversation_id"]
+  }
+};
+
+const OPEN_TOOL = {
+  name: "open",
+  description:
+    "Open and read best-effort content for a prior search result using its read handle. Returns completeness metadata: full, partial, or snippet.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      conversation_id: {
+        type: "string",
+        description: "Client-provided conversation identifier for grouping related requests"
+      },
+      read_handle: {
+        type: "string",
+        description: "Opaque read handle from search result"
+      }
+    },
+    required: ["read_handle", "conversation_id"]
+  }
+};
+
+function asObject(value) {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+  return value;
+}
+
+function makeReadHandle(cache, readContext) {
+  const id = crypto.randomUUID();
+  cache.set(id, {
+    value: readContext,
+    expiresAt: Date.now() + 30 * 60 * 1000
+  });
+  return id;
+}
+
+function getReadContext(cache, handle) {
+  const record = cache.get(handle);
+  if (!record) {
+    return null;
+  }
+
+  if (record.expiresAt < Date.now()) {
+    cache.delete(handle);
+    return null;
+  }
+
+  return record.value;
+}
+
+export function registerTools(registry, context) {
+  registry.addTool(SEARCH_TOOL, async (args) => {
+    const conversationId = String(args.conversation_id || "").trim();
+    if (!conversationId) {
+      throw new Error("conversation_id is required");
+    }
+
+    const query = String(args.query || "").trim();
+    if (!query) {
+      throw new Error("query is required");
+    }
+
+    const source = args.source || "all";
+    const connector = args.connector ? String(args.connector).trim() : undefined;
+    const size = Number.isInteger(args.size) ? args.size : 10;
+    const from = Number.isInteger(args.from) ? args.from : 0;
+
+    const wsResult = await context.ws.sendRequest(
+      "search",
+      { conversation_id: conversationId, query, source, connector, size, from },
+      { timeoutMs: 30000 }
+    );
+
+    const resultObject = asObject(wsResult);
+    const incomingResults = Array.isArray(resultObject.results) ? resultObject.results : [];
+
+    const transformedResults = incomingResults.map((result, index) => {
+      const row = asObject(result);
+      const { _readContext: readContextFromRow, ...publicRow } = row;
+      const readContext = readContextFromRow || {
+        type: publicRow.type,
+        id: publicRow.id,
+        title: publicRow.title,
+        url: publicRow.url,
+        snippet: publicRow.snippet,
+        metadata: {}
+      };
+
+      const readHandle = makeReadHandle(context.readHandleCache, readContext);
+
+      // Only expose the opaque handle to agents; never return internal read context.
+      return {
+        index: Number.isInteger(publicRow.index) ? publicRow.index : index,
+        type: publicRow.type || "",
+        title: publicRow.title || "",
+        url: publicRow.url || "",
+        contentSource: publicRow.contentSource || "",
+        snippet: publicRow.snippet || "",
+        date: publicRow.date || "",
+        from: publicRow.from,
+        to: publicRow.to,
+        subject: publicRow.subject,
+        teamName: publicRow.teamName,
+        channelName: publicRow.channelName,
+        preview: publicRow.preview,
+        author: publicRow.author,
+        fileType: publicRow.fileType,
+        location: publicRow.location,
+        startTime: publicRow.startTime,
+        endTime: publicRow.endTime,
+        attendees: publicRow.attendees,
+        organizer: publicRow.organizer,
+        jobTitle: publicRow.jobTitle,
+        department: publicRow.department,
+        email: publicRow.email,
+        _readHandle: readHandle
+      };
+    });
+
+    return {
+      results: transformedResults,
+      totalEstimatedMatches: Number(resultObject.totalEstimatedMatches || 0),
+      moreAvailable: Boolean(resultObject.moreAvailable),
+      nextFrom:
+        Number.isInteger(resultObject.nextFrom)
+          ? resultObject.nextFrom
+          : from + transformedResults.length,
+      warnings: Array.isArray(resultObject.warnings) ? resultObject.warnings : []
+    };
+  });
+
+  registry.addTool(OPEN_TOOL, async (args) => {
+    const conversationId = String(args.conversation_id || "").trim();
+    if (!conversationId) {
+      throw new Error("conversation_id is required");
+    }
+
+    const readHandle = String(args.read_handle || "").trim();
+    if (!readHandle) {
+      throw new Error("read_handle is required");
+    }
+
+    const readContext = getReadContext(context.readHandleCache, readHandle);
+    if (!readContext) {
+      throw new Error("Invalid or expired read_handle. Run search again.");
+    }
+
+    const wsResult = await context.ws.sendRequest(
+      "open",
+      { conversation_id: conversationId, context: readContext },
+      { timeoutMs: 60000 }
+    );
+
+    return asObject(wsResult);
+  });
+}

package/src/ws-server.js

@@ -0,0 +1,202 @@
+import crypto from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+
+export class WsServer {
+  constructor(options = {}) {
+    const stderrLogger = {
+      info: (...args) => console.error(...args),
+      warn: (...args) => console.warn(...args),
+      error: (...args) => console.error(...args)
+    };
+
+    this.host = options.host || "127.0.0.1";
+    this.port = Number(options.port || 52365);
+    this.logger = options.logger || stderrLogger;
+
+    this.wss = null;
+    this.client = null;
+    this.pending = new Map();
+  }
+
+  async start() {
+    if (this.wss) {
+      return;
+    }
+
+    this.wss = new WebSocketServer({
+      host: this.host,
+      port: this.port
+    });
+
+    this.wss.on("connection", (socket, req) => {
+      this.handleConnection(socket, req).catch((err) => {
+        this.logger.error("[workiq/ws] connection handling failed:", err);
+        try {
+          socket.close(1011, "internal error");
+        } catch (_err) {
+          // ignored
+        }
+      });
+    });
+
+    await new Promise((resolve, reject) => {
+      this.wss.once("listening", resolve);
+      this.wss.once("error", reject);
+    });
+
+    this.logger.error(`[workiq/ws] listening on ws://${this.host}:${this.port}`);
+  }
+
+  async stop() {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("WebSocket server stopped"));
+    }
+    this.pending.clear();
+
+    if (this.client) {
+      try {
+        this.client.close(1001, "server stopping");
+      } catch (_err) {
+        // ignored
+      }
+      this.client = null;
+    }
+
+    if (!this.wss) {
+      return;
+    }
+
+    const wss = this.wss;
+    this.wss = null;
+    await new Promise((resolve) => wss.close(resolve));
+  }
+
+  isReady() {
+    return Boolean(this.client && this.client.readyState === WebSocket.OPEN);
+  }
+
+  getStatus() {
+    return {
+      host: this.host,
+      port: this.port,
+      connected: this.isReady()
+    };
+  }
+
+  async sendRequest(type, params, options = {}) {
+    const timeoutMs = Number(options.timeoutMs || 30000);
+
+    if (!this.isReady()) {
+      throw new Error("M365 Connector extension is not connected");
+    }
+
+    const id = crypto.randomUUID();
+    const payload = { id, type, params: params || {} };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`WebSocket request timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timeout });
+
+      try {
+        this.client.send(JSON.stringify(payload));
+      } catch (err) {
+        clearTimeout(timeout);
+        this.pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  async handleConnection(socket, req) {
+    const origin = req.headers.origin;
+
+    if (!origin) {
+      this.logger.warn("[workiq/ws] rejected connection: missing origin header");
+      socket.close(1008, "origin required");
+      return;
+    }
+
+    if (!origin.startsWith("chrome-extension://")) {
+      this.logger.warn(`[workiq/ws] rejected connection from origin: ${origin}`);
+      socket.close(1008, "origin not allowed");
+      return;
+    }
+
+    if (this.client && this.client.readyState === WebSocket.OPEN) {
+      // MV3 service workers can die silently without sending a close frame.
+      // When the extension reconnects, replace the stale connection.
+      this.logger.error("[workiq/ws] replacing existing connection with new one");
+      try { this.client.terminate(); } catch (_e) { /* ignored */ }
+      this.handleClose(this.client);
+    }
+
+    // Clean up if client ref exists but is no longer OPEN
+    if (this.client && this.client.readyState !== WebSocket.OPEN) {
+      this.client = null;
+    }
+
+    this.client = socket;
+
+    socket.on("message", async (rawData) => {
+      await this.handleMessage(socket, rawData);
+    });
+
+    socket.on("close", (code, reason) => {
+      this.logger.error(`[workiq/ws] socket close: code=${code}, reason=${String(reason)}`);
+      this.handleClose(socket);
+    });
+
+    socket.on("error", (err) => {
+      this.logger.warn("[workiq/ws] client socket error:", err.message);
+    });
+    this.logger.error("[workiq/ws] extension connected");
+  }
+
+  async handleMessage(socket, rawData) {
+    let message;
+    try {
+      message = JSON.parse(String(rawData));
+    } catch (_err) {
+      socket.close(4002, "invalid json");
+      return;
+    }
+
+    if (!message?.id) {
+      return;
+    }
+
+    const pending = this.pending.get(message.id);
+    if (!pending) {
+      return;
+    }
+
+    clearTimeout(pending.timeout);
+    this.pending.delete(message.id);
+
+    if (!message.success) {
+      pending.reject(new Error(message.error || "Unknown extension error"));
+      return;
+    }
+
+    pending.resolve(message.data);
+  }
+
+  handleClose(socket) {
+    if (this.client === socket) {
+      this.client = null;
+    }
+
+    for (const [id, pending] of this.pending.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Extension disconnected"));
+      this.pending.delete(id);
+    }
+
+    this.logger.error("[workiq/ws] extension disconnected");
+  }
+}