decocms
diff --git a/‎.github/workflows/deploy-microsoft-teams.yml‎
Lines changed: 44 additions & 0 deletions b/‎.github/workflows/deploy-microsoft-teams.yml‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎bun.lock‎
Lines changed: 37 additions & 0 deletions b/‎bun.lock‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎microsoft-teams/.gitignore‎
Lines changed: 11 additions & 0 deletions b/‎microsoft-teams/.gitignore‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎microsoft-teams/README.md‎
Lines changed: 89 additions & 0 deletions b/‎microsoft-teams/README.md‎
Lines changed: 89 additions & 0 deletions
diff --git a/‎microsoft-teams/app.json‎
Lines changed: 19 additions & 0 deletions b/‎microsoft-teams/app.json‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎microsoft-teams/package.json‎
Lines changed: 32 additions & 0 deletions b/‎microsoft-teams/package.json‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎microsoft-teams/server/lib/auth.ts‎
Lines changed: 59 additions & 0 deletions b/‎microsoft-teams/server/lib/auth.ts‎
Lines changed: 59 additions & 0 deletions
diff --git a/‎microsoft-teams/server/lib/dedup.ts‎
Lines changed: 44 additions & 0 deletions b/‎microsoft-teams/server/lib/dedup.ts‎
Lines changed: 44 additions & 0 deletions
@@ -0,0 +1,44 @@
+name: Deploy Microsoft Teams MCP
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "microsoft-teams/**"
+      - ".github/workflows/deploy-microsoft-teams.yml"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: microsoft-teams
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-microsoft-teams-${{ hashFiles('microsoft-teams/bun.lock', 'microsoft-teams/package.json') }}
+          restore-keys: ${{ runner.os }}-bun-microsoft-teams-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run check
+        continue-on-error: true
+
+      - name: Deploy to Cloudflare Workers
+        run: bunx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
@@ -0,0 +1,11 @@
+node_modules
+dist
+.env
+.env.*
+!.env.example
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+.secrets.json
+.wrangler/
+*.log
@@ -0,0 +1,89 @@
+# Microsoft Teams MCP
+
+Microsoft Teams integration via the Microsoft Graph API — channel and private
+chat messaging, meeting management, and a message-received trigger. Authenticates
+with Azure AD delegated OAuth (Authorization Code + PKCE); all actions run on
+behalf of the connected Microsoft 365 user.
+
+## Features
+
+- **Channel messaging** — list teams/channels, send & reply, read history &
+  threads, edit, react
+- **Private chats** — find/search users (by email or name), open 1-on-1 & group
+  chats, send & quote-reply, read history
+- **Meetings** — create Teams meetings with join links, list, get, update,
+  reschedule, cancel, and respond (accept / decline / tentative)
+- **OAuth Authentication** — connect your Microsoft 365 account with one click
+- **Trigger System** — `teams.message.received` fires when a new message is
+  posted in a subscribed channel (Graph change notifications)
+
+## Trigger Events
+
+- `teams.message.received` — a new message was posted in a subscribed channel.
+  Manage subscriptions with `SUBSCRIBE_TO_CHANNEL`, `REFRESH_SUBSCRIPTIONS`,
+  `LIST_SUBSCRIPTIONS`, `UNSUBSCRIBE_FROM_CHANNEL`. Inspect delivered events
+  with `GET_RECENT_EVENTS`.
+
+## Architecture
+
+```
+Client → MCP runtime (this Worker) → graph.microsoft.com
+Graph change notifications → /teams/notifications/:connectionId → trigger matching
+```
+
+State (trigger subscriptions, cached tokens, dedup, event log) is persisted in
+a Cloudflare Workers KV namespace because Workers isolates are ephemeral.
+
+> Note: Microsoft Teams APIs require a Microsoft 365 work or school account.
+> Personal Microsoft accounts (Outlook/Hotmail) are not supported.
+
+---
+
+## Development
+
+### Prerequisites
+
+An **Azure AD app registration** (multi-tenant) with delegated Microsoft Graph
+permissions and admin consent:
+
+- `User.Read`, `User.ReadBasic.All`
+- `ChannelMessage.Send`, `ChannelMessage.Read.All`, `ChannelMessage.ReadWrite`
+- `Channel.ReadBasic.All`, `Team.ReadBasic.All`
+- `Chat.ReadWrite`, `ChatMessage.Send`
+- `Calendars.ReadWrite`
+- `offline_access`
+
+Register the OAuth redirect URI (`/oauth/callback`) under
+Authentication → Web in the app registration.
+
+### Environment Variables
+
+Set as Worker secrets (`wrangler secret put`) or, for local dev, in `.dev.vars`:
+
+```bash
+MICROSOFT_TENANT_ID=organizations   # or your specific tenant id
+MICROSOFT_CLIENT_ID=<azure-app-client-id>
+MICROSOFT_CLIENT_SECRET=<azure-app-client-secret>
+```
+
+### Running locally
+
+```bash
+bun install
+bunx wrangler dev   # local Worker at http://localhost:8787 (KV simulated)
+bun run check       # type check
+bun run build       # production bundle (wrangler dry-run)
+```
+
+Expose the local Worker with a tunnel (e.g. `ngrok http 8787`) and register the
+public `/mcp` URL as a custom connection in deco Studio.
+
+### Deploy (Cloudflare Workers)
+
+```bash
+bunx wrangler kv namespace create TEAMS_KV   # paste the id into wrangler.toml
+bunx wrangler secret put MICROSOFT_TENANT_ID
+bunx wrangler secret put MICROSOFT_CLIENT_ID
+bunx wrangler secret put MICROSOFT_CLIENT_SECRET
+bun run deploy
+```
@@ -0,0 +1,19 @@
+{
+  "scopeName": "deco",
+  "name": "microsoft-teams",
+  "friendlyName": "Microsoft Teams",
+  "connection": {
+    "type": "HTTP",
+    "url": "https://microsoft-teams-mcp.decocms.com/mcp"
+  },
+  "description": "Microsoft Teams integration — send channel and private chat messages, manage meetings, and trigger agents on new Teams messages via the Microsoft Graph API.",
+  "icon": "https://upload.wikimedia.org/wikipedia/commons/9/94/Microsoft_Office_Teams_%282019%E2%80%932025%29.svg",
+  "unlisted": false,
+  "metadata": {
+    "categories": ["Communication", "Automation"],
+    "official": false,
+    "tags": ["teams", "microsoft", "bot", "messaging", "ai-agent", "webhooks", "automation", "channels", "chats", "meetings", "calendar", "azure"],
+    "short_description": "Microsoft Teams bot — channel & private messages, meetings, and message-received triggers via Microsoft Graph.",
+    "mesh_description": "The Microsoft Teams MCP integrates with Microsoft Teams through the Microsoft Graph API. Authentication uses Azure AD delegated OAuth (Authorization Code flow with PKCE) — users sign in with the 'Connect to Microsoft' button in deco Studio, and all actions run on behalf of that work or school account (Microsoft 365). Capabilities include: channel messaging (list teams and channels, send and reply to messages, read channel history and threads, edit and react to messages); private chats (find or search users by email or name, open 1-on-1 and group chats, send and quote-reply to chat messages, read chat history); and meeting management (create Teams meetings with join links, list, get, update, reschedule, cancel, and respond to invitations with accept/decline/tentative). A trigger system delivers the 'teams.message.received' event whenever a new message is posted in a subscribed channel via Graph change notifications, giving the agent full context (sender, text, thread, web link) so it can respond. Note: Teams APIs require a Microsoft 365 work or school account; personal Microsoft accounts are not supported."
+  }
+}
@@ -0,0 +1,32 @@
+{
+  "name": "microsoft-teams-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "description": "Microsoft Teams MCP — send messages, manage meetings and react to Teams events via Microsoft Graph API",
+  "scripts": {
+    "dev": "bunx wrangler dev",
+    "check": "tsc --noEmit",
+    "build": "bunx wrangler deploy --dry-run --outdir=dist",
+    "deploy": "bunx wrangler deploy"
+  },
+  "dependencies": {
+    "@decocms/bindings": "^1.4.0",
+    "@decocms/runtime": "^1.6.0",
+    "hono": "^4.7.4",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20251014.0",
+    "@decocms/mcps-shared": "1.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.2",
+    "wrangler": "^4.28.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "overrides": {
+    "zod": "^4.0.0"
+  }
+}
@@ -0,0 +1,59 @@
+/**
+ * Token accessor for the Microsoft Teams MCP.
+ *
+ * The deco runtime handles the entire OAuth flow (authorize, exchange,
+ * refresh) — the per-request bearer token arrives in
+ * `env.MESH_REQUEST_CONTEXT.authorization`. We just pull it out here.
+ *
+ * For webhook handlers that run *outside* a tool request (no MESH context),
+ * use getDelegatedTokenForConnection() with a stored refresh token.
+ */
+
+import type { Env } from "../types/env.ts";
+import { getKvStore } from "./kv.ts";
+
+/** Pull the user's bearer token off the per-request mesh context. */
+export function getAccessToken(env: Env): string {
+  const auth = env.MESH_REQUEST_CONTEXT?.authorization;
+  if (!auth) {
+    throw new Error(
+      "Missing authorization. Click 'Connect to Microsoft' in deco Studio first.",
+    );
+  }
+  // Authorization header may come as "Bearer <token>" or just "<token>"
+  return auth.startsWith("Bearer ") ? auth.slice(7) : auth;
+}
+
+/**
+ * For webhook handlers (no MESH request context, so we can't read
+ * MESH_REQUEST_CONTEXT.authorization). Reads an access token cached by
+ * SUBSCRIBE_TO_CHANNEL / REFRESH_SUBSCRIPTIONS.
+ *
+ * Throws if the cache is missing or expired — the agent must call
+ * REFRESH_SUBSCRIPTIONS to reseed the cache (and renew the Graph
+ * subscription itself, which expires every ~60 min anyway).
+ */
+export async function getDelegatedTokenForConnection(
+  connectionId: string,
+): Promise<string> {
+  const kv = getKvStore();
+  const cached = await kv.get<{ accessToken: string; expiresAt: number }>(
+    `webhook-token:${connectionId}`,
+  );
+
+  if (!cached) {
+    throw new Error(
+      `No cached webhook token for connection ${connectionId}. ` +
+        `Call SUBSCRIBE_TO_CHANNEL or REFRESH_SUBSCRIPTIONS to seed it.`,
+    );
+  }
+
+  if (Date.now() > cached.expiresAt - 60_000) {
+    throw new Error(
+      `Webhook token for connection ${connectionId} is expired. ` +
+        `Call REFRESH_SUBSCRIPTIONS to renew.`,
+    );
+  }
+
+  return cached.accessToken;
+}
@@ -0,0 +1,44 @@
+/**
+ * Event deduplication for Microsoft Graph notifications, backed by KV.
+ *
+ * Graph occasionally redelivers the same change notification (network blips,
+ * subscription renewals, isolate restarts). Without dedup the agent would
+ * receive the trigger twice and reply twice. We fingerprint each notification
+ * and skip duplicates seen within a TTL window.
+ *
+ * Backed by Workers KV (not an in-memory Map) so dedup survives across the
+ * ephemeral isolates that handle webhook deliveries.
+ */
+
+import { getKvStore } from "./kv.ts";
+
+const PREFIX = "dedup:";
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1h — Graph retries within minutes
+
+/** Build a fingerprint for a single Graph notification. */
+export function fingerprintNotification(notification: {
+  subscriptionId: string;
+  changeType: string;
+  resourceData?: { id?: string };
+  resource?: string;
+}): string {
+  const resourceId =
+    notification.resourceData?.id ?? notification.resource ?? "";
+  return `${notification.subscriptionId}|${notification.changeType}|${resourceId}`;
+}
+
+/**
+ * Returns true if this fingerprint was already seen within the TTL window.
+ * If new, records it (with TTL) and returns false so the caller processes it.
+ */
+export async function isDuplicateNotification(
+  fingerprint: string,
+  ttlMs: number = DEFAULT_TTL_MS,
+): Promise<boolean> {
+  const kv = getKvStore();
+  const key = `${PREFIX}${fingerprint}`;
+  const seen = await kv.get<number>(key);
+  if (seen) return true;
+  await kv.set(key, Date.now(), ttlMs);
+  return false;
+}