@teamsly/mcp 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# Teamsly MCP Server
+
+Exposes your Microsoft Teams as MCP tools — send DMs, read messages, list chats, channels, and teams.
+
+Works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, Zed, Windsurf, and others.
+
+## Install
+
+```bash
+claude mcp add teamsly -- npx -y @teamsly/mcp
+```
+
+That's it — no clone required. On first use you'll do a one-time Microsoft sign-in (see **Auth** below). For other clients, use the config blocks further down.
+
+## Auth (one-time setup)
+
+On first run, a sign-in prompt appears in your terminal:
+
+```
+╔══════════════════════════════════════════╗
+║       Sign in to Teamsly MCP             ║
+╠══════════════════════════════════════════╣
+║  1. Open: https://microsoft.com/devicelogin
+║  2. Enter code: XXXXXXXX                 ║
+╚══════════════════════════════════════════╝
+```
+
+Open the URL, enter the code, sign in with your Microsoft account. Done — tokens are saved to `~/.config/teamsly-mcp/tokens.json` and auto-refreshed.
+
+> **Azure app requirement:** the app registration behind `TEAMSLY_CLIENT_ID` must have **"Allow public client flows"** enabled (Entra ID → App registrations → *app* → Authentication → Advanced settings). The device-code flow is a public-client flow; without this, sign-in fails at the token step with `AADSTS7000218: ... must contain 'client_assertion' or 'client_secret'`.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `find_people` | Search contacts by name → returns `[{ id, displayName, email }]` |
+| `send_dm` | Send a DM given a user ID (use `find_people` first) |
+| `list_chats` | List recent DM and group chats |
+| `get_chat_messages` | Get recent messages from a chat |
+| `send_chat_message` | Send a message to a chat by ID |
+| `list_teams` | List your Teams |
+| `list_channels` | List channels in a team |
+| `get_channel_messages` | Get recent messages from a channel |
+| `send_channel_message` | Post a message to a channel |
+
+## Configuration
+
+---
+
+### Claude Code
+
+**Project-level** (auto-discovered for anyone who opens this repo — already configured via `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "teamsly": {
+      "command": "npx",
+      "args": ["-y", "@teamsly/mcp"]
+    }
+  }
+}
+```
+
+**User-level** (available in all your projects):
+
+```bash
+claude mcp add teamsly -- npx -y @teamsly/mcp
+```
+
+---
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "teamsly": {
+      "command": "npx",
+      "args": ["-y", "@teamsly/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (user-level) or `.cursor/mcp.json` in your project (project-level):
+
+```json
+{
+  "mcpServers": {
+    "teamsly": {
+      "command": "npx",
+      "args": ["-y", "@teamsly/mcp"]
+    }
+  }
+}
+```
+
+---
+
+### Zed
+
+Edit `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "teamsly": {
+      "command": { "path": "npx", "args": ["-y", "@teamsly/mcp"] }
+    }
+  }
+}
+```
+
+---
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "teamsly": {
+      "command": "npx",
+      "args": ["-y", "@teamsly/mcp"]
+    }
+  }
+}
+```
+
+---
+
+### Develop from source
+
+Working on the server itself? Run it straight from the repo with no build:
+
+```bash
+npx tsx mcp-server/index.ts
+```
+
+The repo's `.mcp.json` already points Claude Code at this for local development.
+
+---
+
+## Optional env vars
+
+| Variable | Default | Description |
+|---|---|---|
+| `TEAMSLY_CLIENT_ID` | teamsly.app's app ID | Azure AD app client ID |
+| `TEAMSLY_TENANT_ID` | `common` | Tenant ID (use your org's ID to restrict to one tenant) |
+| `TEAMSLY_TOKEN_DIR` | `~/.config/teamsly-mcp` | Token storage directory |

package/dist/index.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+// index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CLIENT_ID = process.env.TEAMSLY_CLIENT_ID ?? "377aa8a2-24d1-4d6e-8eca-e347864c9880";
+var TENANT_ID = process.env.TEAMSLY_TENANT_ID ?? "common";
+var TOKEN_DIR = process.env.TEAMSLY_TOKEN_DIR ?? join(homedir(), ".config", "teamsly-mcp");
+var TOKEN_FILE = join(TOKEN_DIR, "tokens.json");
+var SCOPE = [
+  "User.Read",
+  "User.ReadBasic.All",
+  "People.Read",
+  "Team.ReadBasic.All",
+  "Channel.ReadBasic.All",
+  "ChannelMessage.Read.All",
+  "ChannelMessage.Send",
+  "Chat.ReadWrite",
+  "Presence.Read.All",
+  "Files.Read.All",
+  "Calendars.Read",
+  "offline_access"
+].join(" ");
+var GRAPH = "https://graph.microsoft.com/v1.0";
+var TOKEN_URL = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`;
+function loadTokens() {
+  try {
+    return JSON.parse(readFileSync(TOKEN_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function saveTokens(t) {
+  mkdirSync(TOKEN_DIR, { recursive: true });
+  writeFileSync(TOKEN_FILE, JSON.stringify(t, null, 2), { mode: 384 });
+}
+async function deviceCodeAuth() {
+  const codeRes = await fetch(
+    `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/devicecode`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ client_id: CLIENT_ID, scope: SCOPE })
+    }
+  );
+  if (!codeRes.ok) throw new Error(`Device code request failed: ${await codeRes.text()}`);
+  const { device_code, user_code, verification_uri, interval, expires_in } = await codeRes.json();
+  process.stderr.write(
+    `
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551       Sign in to Teamsly MCP             \u2551
+\u2560\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2563
+\u2551  1. Open: ${verification_uri.padEnd(31)}\u2551
+\u2551  2. Enter code: ${user_code.padEnd(25)}\u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+
+Waiting for sign-in\u2026
+`
+  );
+  const deadline = Date.now() + expires_in * 1e3;
+  const poll = Math.max(interval, 5) * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, poll));
+    const res = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        client_id: CLIENT_ID,
+        device_code
+      })
+    });
+    const data = await res.json();
+    if (data.access_token) {
+      const tokens = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token ?? "",
+        expires_at: Date.now() + (data.expires_in ?? 3600) * 1e3
+      };
+      saveTokens(tokens);
+      process.stderr.write("\u2713 Signed in. Tokens saved.\n\n");
+      return tokens;
+    }
+    if (data.error && data.error !== "authorization_pending" && data.error !== "slow_down") {
+      throw new Error(`Auth error: ${data.error}`);
+    }
+  }
+  throw new Error("Device code expired \u2014 please restart and try again.");
+}
+async function refreshTokens(stored) {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: CLIENT_ID,
+      refresh_token: stored.refresh_token,
+      scope: SCOPE
+    })
+  });
+  const data = await res.json();
+  if (!data.access_token) throw new Error(`Refresh failed: ${data.error}`);
+  const tokens = {
+    access_token: data.access_token,
+    refresh_token: data.refresh_token ?? stored.refresh_token,
+    expires_at: Date.now() + (data.expires_in ?? 3600) * 1e3
+  };
+  saveTokens(tokens);
+  return tokens;
+}
+var _tokens = null;
+async function getAccessToken() {
+  if (!_tokens) {
+    _tokens = loadTokens();
+  }
+  if (!_tokens) {
+    _tokens = await deviceCodeAuth();
+  } else if (_tokens.expires_at < Date.now() + 6e4) {
+    try {
+      _tokens = await refreshTokens(_tokens);
+    } catch {
+      _tokens = await deviceCodeAuth();
+    }
+  }
+  return _tokens.access_token;
+}
+var _myId = null;
+async function getMyId() {
+  if (!_myId) {
+    const me = await graph("/me?$select=id");
+    _myId = me.id;
+  }
+  return _myId;
+}
+async function graph(path, options = {}) {
+  const token = await getAccessToken();
+  const res = await fetch(`${GRAPH}${path}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers ?? {}
+    }
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Graph ${path} \u2192 ${res.status}: ${text}`);
+  }
+  if (res.status === 204) return null;
+  return res.json();
+}
+var server = new McpServer({ name: "teamsly", version: "2.0.0" });
+server.tool(
+  "list_chats",
+  "List recent Microsoft Teams DM and group chat conversations",
+  {},
+  async () => {
+    const data = await graph("/me/chats?$expand=members&$top=50");
+    return { content: [{ type: "text", text: JSON.stringify(data?.value ?? data, null, 2) }] };
+  }
+);
+server.tool(
+  "get_chat_messages",
+  "Get recent messages from a Teams DM or group chat",
+  { chat_id: z.string().describe("The chat ID from list_chats") },
+  async ({ chat_id }) => {
+    const data = await graph(`/me/chats/${encodeURIComponent(chat_id)}/messages?$top=20`);
+    return { content: [{ type: "text", text: JSON.stringify(data?.value ?? data, null, 2) }] };
+  }
+);
+server.tool(
+  "send_chat_message",
+  "Send a message to a Teams DM or group chat",
+  {
+    chat_id: z.string().describe("The chat ID from list_chats"),
+    message: z.string().describe("Plain text message to send")
+  },
+  async ({ chat_id, message }) => {
+    await graph(`/me/chats/${encodeURIComponent(chat_id)}/messages`, {
+      method: "POST",
+      body: JSON.stringify({ body: { contentType: "text", content: message } })
+    });
+    return { content: [{ type: "text", text: "Message sent." }] };
+  }
+);
+server.tool(
+  "list_teams",
+  "List the Microsoft Teams the user has joined",
+  {},
+  async () => {
+    const data = await graph("/me/joinedTeams");
+    return { content: [{ type: "text", text: JSON.stringify(data?.value ?? data, null, 2) }] };
+  }
+);
+server.tool(
+  "list_channels",
+  "List channels in a Microsoft Teams team",
+  { team_id: z.string().describe("The team ID from list_teams") },
+  async ({ team_id }) => {
+    const data = await graph(`/teams/${team_id}/channels`);
+    return { content: [{ type: "text", text: JSON.stringify(data?.value ?? data, null, 2) }] };
+  }
+);
+server.tool(
+  "get_channel_messages",
+  "Get recent messages from a Teams channel",
+  {
+    team_id: z.string().describe("The team ID from list_teams"),
+    channel_id: z.string().describe("The channel ID from list_channels")
+  },
+  async ({ team_id, channel_id }) => {
+    const data = await graph(`/teams/${team_id}/channels/${channel_id}/messages?$top=20`);
+    return { content: [{ type: "text", text: JSON.stringify(data?.value ?? data, null, 2) }] };
+  }
+);
+server.tool(
+  "find_people",
+  "Search for a Microsoft Teams contact by name. Returns up to 5 matching users with their IDs, display names, and email addresses. Use the returned `id` with send_dm to send a message.",
+  {
+    query: z.string().describe("Name or partial name to search for, e.g. 'Priya' or 'Tom Baker'")
+  },
+  async ({ query }) => {
+    const encoded = encodeURIComponent(query);
+    const data = await graph(
+      `/me/people?$search=${encoded}&$select=id,displayName,userPrincipalName&$top=5`
+    );
+    const people = (data?.value ?? []).map((p) => ({
+      id: p.id,
+      displayName: p.displayName,
+      email: p.userPrincipalName ?? ""
+    }));
+    return {
+      content: [{ type: "text", text: JSON.stringify(people, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "send_dm",
+  "Send a direct message to a Teams user. Call find_people first to get their user ID. Creates a new 1:1 chat if one doesn't exist yet, or reuses the existing one.",
+  {
+    user_id: z.string().describe("AAD user ID from find_people"),
+    message: z.string().describe("Plain text message to send")
+  },
+  async ({ user_id, message }) => {
+    const myId = await getMyId();
+    const chat = await graph("/chats", {
+      method: "POST",
+      body: JSON.stringify({
+        chatType: "oneOnOne",
+        members: [
+          {
+            "@odata.type": "#microsoft.graph.aadUserConversationMember",
+            roles: ["owner"],
+            "user@odata.bind": `https://graph.microsoft.com/v1.0/users('${myId}')`
+          },
+          {
+            "@odata.type": "#microsoft.graph.aadUserConversationMember",
+            roles: ["owner"],
+            "user@odata.bind": `https://graph.microsoft.com/v1.0/users('${user_id}')`
+          }
+        ]
+      })
+    });
+    await graph(`/me/chats/${encodeURIComponent(chat.id)}/messages`, {
+      method: "POST",
+      body: JSON.stringify({ body: { contentType: "text", content: message } })
+    });
+    return { content: [{ type: "text", text: "Message sent." }] };
+  }
+);
+server.tool(
+  "send_channel_message",
+  "Post a message to a Teams channel",
+  {
+    team_id: z.string().describe("The team ID from list_teams"),
+    channel_id: z.string().describe("The channel ID from list_channels"),
+    message: z.string().describe("Plain text message to send")
+  },
+  async ({ team_id, channel_id, message }) => {
+    await graph(`/teams/${team_id}/channels/${channel_id}/messages`, {
+      method: "POST",
+      body: JSON.stringify({ body: { contentType: "text", content: message } })
+    });
+    return { content: [{ type: "text", text: "Message sent." }] };
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@teamsly/mcp",
+  "version": "0.1.0",
+  "description": "Microsoft Teams as MCP tools — DMs, channels, messages.",
+  "license": "AGPL-3.0",
+  "type": "module",
+  "bin": {
+    "teamsly-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8",
+    "typescript": "^6"
+  }
+}