teams-api-mcp 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +406 -0
- package/SKILL.md +130 -0
- package/dist/actions.d.ts +49 -0
- package/dist/actions.d.ts.map +1 -0
- package/dist/actions.js +842 -0
- package/dist/actions.js.map +1 -0
- package/dist/api.d.ts +111 -0
- package/dist/api.d.ts.map +1 -0
- package/dist/api.js +630 -0
- package/dist/api.js.map +1 -0
- package/dist/auth.d.ts +53 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +479 -0
- package/dist/auth.js.map +1 -0
- package/dist/cli.d.ts +13 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +178 -0
- package/dist/cli.js.map +1 -0
- package/dist/mcp-server.d.ts +35 -0
- package/dist/mcp-server.d.ts.map +1 -0
- package/dist/mcp-server.js +144 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/teams-client.d.ts +197 -0
- package/dist/teams-client.d.ts.map +1 -0
- package/dist/teams-client.js +545 -0
- package/dist/teams-client.js.map +1 -0
- package/dist/token-store.d.ts +14 -0
- package/dist/token-store.d.ts.map +1 -0
- package/dist/token-store.js +79 -0
- package/dist/token-store.js.map +1 -0
- package/dist/types.d.ts +245 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +17 -0
- package/dist/types.js.map +1 -0
- package/package.json +69 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Maxim Mazurok
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
# teams-api
|
|
2
|
+
|
|
3
|
+
AI-native Microsoft Teams integration — read conversations, send messages, and manage members via the Teams Chat Service REST API.
|
|
4
|
+
|
|
5
|
+
Designed for autonomous AI agents that need to interact with Teams: read messages, reply to people, monitor conversations, and participate in team workflows.
|
|
6
|
+
|
|
7
|
+
> [!NOTE]
|
|
8
|
+
> This project was AI-generated using Claude Opus 4.6 with human guidance and review.
|
|
9
|
+
|
|
10
|
+
## Getting Started
|
|
11
|
+
|
|
12
|
+
`teams-api` can be used in three ways:
|
|
13
|
+
|
|
14
|
+
1. As an MCP server for editors and AI tools. This is the recommended path for most users.
|
|
15
|
+
2. As a CLI for direct terminal use.
|
|
16
|
+
3. As a programmatic Node.js library. This is the advanced path and is documented near the end.
|
|
17
|
+
|
|
18
|
+
### Recommended: MCP via `npx @latest`
|
|
19
|
+
|
|
20
|
+
Prefer running from `npx` so you always pick up the latest published version while the project is evolving quickly.
|
|
21
|
+
|
|
22
|
+
If you are on macOS and already use a platform authenticator / FIDO2 passkey, start with auto-login:
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"mcpServers": {
|
|
27
|
+
"teams": {
|
|
28
|
+
"command": "npx",
|
|
29
|
+
"args": ["-y", "teams-api-mcp@latest"],
|
|
30
|
+
"env": {
|
|
31
|
+
"TEAMS_AUTO": "true",
|
|
32
|
+
"TEAMS_EMAIL": "you@example.com"
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
If you are on Windows or Linux, or you want a visible browser login flow, use interactive login instead:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"mcpServers": {
|
|
44
|
+
"teams": {
|
|
45
|
+
"command": "npx",
|
|
46
|
+
"args": ["-y", "teams-api-mcp@latest"],
|
|
47
|
+
"env": {
|
|
48
|
+
"TEAMS_LOGIN": "true",
|
|
49
|
+
"TEAMS_EMAIL": "you@example.com",
|
|
50
|
+
"TEAMS_REGION": "emea"
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> [!TIP]
|
|
58
|
+
> In both recommended setups, `teams-api` captures the full token bundle automatically during login. Most users never need to copy tokens manually.
|
|
59
|
+
|
|
60
|
+
### CLI
|
|
61
|
+
|
|
62
|
+
You can also use the CLI directly without installing anything:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npx -y -p teams-api-mcp@latest teams-api auth --login --region emea
|
|
66
|
+
npx -y -p teams-api-mcp@latest teams-api list-conversations --login --region emea --limit 20
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
If you use the CLI often, a global install is optional:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npm install -g teams-api-mcp
|
|
73
|
+
teams-api auth --login --region emea
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Advanced Topics
|
|
77
|
+
|
|
78
|
+
Manual token usage, debug-session auth, and programmatic Node.js usage are covered later in this README.
|
|
79
|
+
|
|
80
|
+
## Platform support
|
|
81
|
+
|
|
82
|
+
| Feature | macOS | Windows / Linux |
|
|
83
|
+
| ---------------------- | -------------- | --------------- |
|
|
84
|
+
| **Interactive login** | Full support | Full support |
|
|
85
|
+
| **Auto-login (FIDO2)** | Full support | Not supported |
|
|
86
|
+
| **Debug session** | Full support | Full support |
|
|
87
|
+
| **Direct token** | Full support | Full support |
|
|
88
|
+
| **Token caching** | macOS Keychain | Not available |
|
|
89
|
+
| **CLI & MCP server** | Full support | Full support |
|
|
90
|
+
| **Programmatic API** | Full support | Full support |
|
|
91
|
+
|
|
92
|
+
## Authentication
|
|
93
|
+
|
|
94
|
+
Most users do not need to manage tokens manually.
|
|
95
|
+
|
|
96
|
+
If you use interactive login, auto-login, or a Chrome debug session, `teams-api` captures the full token bundle automatically from Teams web traffic. That includes the base `skypeToken` plus the extra bearer tokens used for profile resolution and reliable people/chat/channel search.
|
|
97
|
+
|
|
98
|
+
On macOS, prefer auto-login when you have a platform authenticator / FIDO2 passkey set up. On other platforms, use interactive login.
|
|
99
|
+
|
|
100
|
+
Direct token usage is the advanced/manual path.
|
|
101
|
+
|
|
102
|
+
| Method | Description | Automation | Platform |
|
|
103
|
+
| --------------------- | ---------------------------------------------------------------------------- | ---------------- | -------- |
|
|
104
|
+
| **Auto-login** | Playwright launches system Chrome and captures the full token bundle | Fully unattended | macOS |
|
|
105
|
+
| **Interactive login** | Opens a browser window and captures skype, middle-tier, and Substrate tokens | One-time manual | All |
|
|
106
|
+
| **Debug session** | Connects to a running Chrome instance and captures the full token bundle | Semi-manual | All |
|
|
107
|
+
| **Direct token** | Provide a previously captured token or token bundle explicitly | Manual | All |
|
|
108
|
+
|
|
109
|
+
### Auto-login (macOS only)
|
|
110
|
+
|
|
111
|
+
Requires macOS with a platform authenticator (e.g. Intune Company Portal) and a FIDO2 passkey enrolled. Fully unattended — no browser window appears.
|
|
112
|
+
|
|
113
|
+
### Interactive login (recommended for Windows / Linux)
|
|
114
|
+
|
|
115
|
+
The easiest cross-platform option. A browser window opens, you log in with any method your organization supports (password, MFA, passkey, etc.), and the token is captured automatically:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
teams-api auth --login --region emea
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Optionally pre-fill your email:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
teams-api auth --login --email you@example.com --region emea
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
> [!NOTE]
|
|
128
|
+
> Interactive login uses Playwright's bundled Chromium. No system Chrome installation is required.
|
|
129
|
+
|
|
130
|
+
### Advanced / manual methods
|
|
131
|
+
|
|
132
|
+
**Debug session** — start Chrome with `--remote-debugging-port=9222`, navigate to Teams and log in, then run:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
teams-api auth --debug-port 9222 --region emea
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**Direct token** — advanced/manual only. Extract `x-skypetoken` from browser DevTools (Network tab) and pass it directly:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
teams-api list-conversations --token "<paste-token-here>" --region emea
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
If you want reliable people/chat/channel lookup and profile resolution on the direct-token path, also pass the extra bearer tokens captured from Teams requests:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
teams-api find-people \
|
|
148
|
+
--token "<paste-skype-token-here>" \
|
|
149
|
+
--bearer-token "<paste-api-spaces-skype-bearer-token-here>" \
|
|
150
|
+
--substrate-token "<paste-substrate-bearer-token-here>" \
|
|
151
|
+
--region emea \
|
|
152
|
+
--query "Jane Doe"
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
> [!TIP]
|
|
156
|
+
> Skip this section if you are using `--login`, `--auto`, `TEAMS_LOGIN`, or `TEAMS_AUTO`. Those modes capture the full token bundle automatically.
|
|
157
|
+
|
|
158
|
+
> [!TIP]
|
|
159
|
+
> Replace `emea` with your region (`apac`, `emea`, or `amer`). See [API regions](#api-regions) below.
|
|
160
|
+
|
|
161
|
+
## CLI
|
|
162
|
+
|
|
163
|
+
Preferred without install:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
npx -y -p teams-api-mcp@latest teams-api <command> [options]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Optional global install for frequent use:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npm install -g teams-api-mcp
|
|
173
|
+
teams-api <command> [options]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The examples below use `teams-api` for readability. If you are not installing globally, replace it with `npx -y -p teams-api-mcp@latest teams-api`.
|
|
177
|
+
|
|
178
|
+
### Auth flags (available on all commands)
|
|
179
|
+
|
|
180
|
+
| Flag | Description |
|
|
181
|
+
| --------------------------- | ------------------------------------------------------------ |
|
|
182
|
+
| `--login` | Interactive browser login (all platforms) |
|
|
183
|
+
| `--auto` | Auto-acquire token via FIDO2 passkey (macOS) |
|
|
184
|
+
| `--email <email>` | Corporate email (required with `--auto`, optional otherwise) |
|
|
185
|
+
| `--token <token>` | Use an existing skype token (advanced/manual) |
|
|
186
|
+
| `--bearer-token <token>` | Optional middle-tier bearer token (advanced/manual) |
|
|
187
|
+
| `--substrate-token <token>` | Optional Substrate bearer token (advanced/manual) |
|
|
188
|
+
| `--debug-port <port>` | Chrome debug port (default: 9222) |
|
|
189
|
+
| `--region <region>` | API region (default: apac) |
|
|
190
|
+
| `--format <format>` | Output format: json, text, md, toon |
|
|
191
|
+
| `--output <file>` | Export output to file (default format: md) |
|
|
192
|
+
|
|
193
|
+
### Examples
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
# Acquire a token (interactive — all platforms)
|
|
197
|
+
teams-api auth --login --region emea
|
|
198
|
+
|
|
199
|
+
# Acquire a token (auto — macOS with FIDO2)
|
|
200
|
+
teams-api auth --auto --email you@example.com
|
|
201
|
+
|
|
202
|
+
# List conversations
|
|
203
|
+
teams-api list-conversations --login --region emea --limit 20 --format json
|
|
204
|
+
|
|
205
|
+
# Find a conversation by topic
|
|
206
|
+
teams-api find-conversation --auto --email you@example.com --query "Design Review"
|
|
207
|
+
|
|
208
|
+
# Find a 1:1 chat by person name
|
|
209
|
+
teams-api find-one-on-one --auto --email you@example.com --person-name "Jane Doe"
|
|
210
|
+
|
|
211
|
+
# Read messages (by topic name, person name, or direct ID)
|
|
212
|
+
teams-api get-messages --auto --email you@example.com --chat "Design Review"
|
|
213
|
+
teams-api get-messages --auto --email you@example.com --to "Jane Doe" --max-pages 5
|
|
214
|
+
teams-api get-messages --auto --email you@example.com --conversation-id "19:abc@thread.v2" --format json
|
|
215
|
+
|
|
216
|
+
# Newest-first order (API returns newest-first; default is oldest-first/chronological)
|
|
217
|
+
teams-api get-messages --auto --email you@example.com --chat "General" --order newest-first
|
|
218
|
+
|
|
219
|
+
# Send a message
|
|
220
|
+
teams-api send-message --auto --email you@example.com --to "Jane Doe" --content "Hello!"
|
|
221
|
+
teams-api send-message --auto --email you@example.com --chat "Design Review" --content "Status update"
|
|
222
|
+
|
|
223
|
+
# List members
|
|
224
|
+
teams-api get-members --auto --email you@example.com --chat "Design Review" --format md
|
|
225
|
+
|
|
226
|
+
# Get current user info
|
|
227
|
+
teams-api whoami --auto --email you@example.com
|
|
228
|
+
|
|
229
|
+
# Export messages to a file (default format: md)
|
|
230
|
+
teams-api get-messages --auto --email you@example.com --chat "General" --output exports/general.md
|
|
231
|
+
|
|
232
|
+
# Export as JSON to a file
|
|
233
|
+
teams-api get-messages --auto --email you@example.com --chat "General" --format json --output exports/general.json
|
|
234
|
+
|
|
235
|
+
# Toon format (fun ASCII art output)
|
|
236
|
+
teams-api list-conversations --auto --email you@example.com --format toon
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## MCP server
|
|
240
|
+
|
|
241
|
+
The MCP server exposes Teams operations as tools for AI agents via stdio transport.
|
|
242
|
+
|
|
243
|
+
### Recommended setup
|
|
244
|
+
|
|
245
|
+
For most users, use one of these login-based configs. No manual token extraction is required.
|
|
246
|
+
|
|
247
|
+
**macOS (auto-login with FIDO2):**
|
|
248
|
+
|
|
249
|
+
```json
|
|
250
|
+
{
|
|
251
|
+
"mcpServers": {
|
|
252
|
+
"teams": {
|
|
253
|
+
"command": "npx",
|
|
254
|
+
"args": ["-y", "teams-api-mcp@latest"],
|
|
255
|
+
"env": {
|
|
256
|
+
"TEAMS_AUTO": "true",
|
|
257
|
+
"TEAMS_EMAIL": "you@example.com"
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**All platforms (interactive login):**
|
|
265
|
+
|
|
266
|
+
```json
|
|
267
|
+
{
|
|
268
|
+
"mcpServers": {
|
|
269
|
+
"teams": {
|
|
270
|
+
"command": "npx",
|
|
271
|
+
"args": ["-y", "teams-api-mcp@latest"],
|
|
272
|
+
"env": {
|
|
273
|
+
"TEAMS_LOGIN": "true",
|
|
274
|
+
"TEAMS_EMAIL": "you@example.com",
|
|
275
|
+
"TEAMS_REGION": "emea"
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
> [!TIP]
|
|
283
|
+
> In the recommended configs above, `teams-api` captures the full token bundle automatically during login. You do not need to copy `skypeToken`, `bearerToken`, or `substrateToken` into the MCP config.
|
|
284
|
+
|
|
285
|
+
### Advanced: direct token configuration
|
|
286
|
+
|
|
287
|
+
Use this only if you already have tokens from another flow or need to avoid browser-based auth entirely.
|
|
288
|
+
|
|
289
|
+
**All platforms (direct token):**
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"mcpServers": {
|
|
294
|
+
"teams": {
|
|
295
|
+
"command": "npx",
|
|
296
|
+
"args": ["-y", "teams-api-mcp@latest"],
|
|
297
|
+
"env": {
|
|
298
|
+
"TEAMS_TOKEN": "<paste-skype-token-here>",
|
|
299
|
+
"TEAMS_BEARER_TOKEN": "<optional-api-spaces-skype-bearer-token>",
|
|
300
|
+
"TEAMS_SUBSTRATE_TOKEN": "<optional-substrate-bearer-token>",
|
|
301
|
+
"TEAMS_REGION": "emea"
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
> [!TIP]
|
|
309
|
+
> If you do use direct tokens, `teams-api auth --login --region emea` prints the full token object as JSON. For basic chat operations, `skypeToken` is enough. For reliable people/chat/channel search and profile resolution, also pass `bearerToken` and `substrateToken`.
|
|
310
|
+
|
|
311
|
+
### Environment variables
|
|
312
|
+
|
|
313
|
+
| Variable | Description |
|
|
314
|
+
| ----------------------- | --------------------------------------------------- |
|
|
315
|
+
| `TEAMS_TOKEN` | Pre-existing skype token |
|
|
316
|
+
| `TEAMS_BEARER_TOKEN` | Optional middle-tier bearer token |
|
|
317
|
+
| `TEAMS_SUBSTRATE_TOKEN` | Optional Substrate bearer token |
|
|
318
|
+
| `TEAMS_REGION` | API region (default: apac) |
|
|
319
|
+
| `TEAMS_EMAIL` | Corporate email for auto-login or interactive login |
|
|
320
|
+
| `TEAMS_AUTO` | Set to `true` to enable auto-login (macOS + FIDO2) |
|
|
321
|
+
| `TEAMS_LOGIN` | Set to `true` to enable interactive browser login |
|
|
322
|
+
| `TEAMS_DEBUG_PORT` | Chrome debug port (default: 9222) |
|
|
323
|
+
|
|
324
|
+
### Available tools
|
|
325
|
+
|
|
326
|
+
All MCP tools accept an optional `format` parameter (`json`, `text`, `md`, or `toon`). Default format is `toon`.
|
|
327
|
+
|
|
328
|
+
| Tool | Description |
|
|
329
|
+
| -------------------------- | ----------------------------------------------------- |
|
|
330
|
+
| `teams_list_conversations` | List available conversations |
|
|
331
|
+
| `teams_find_conversation` | Find a conversation by topic or member name |
|
|
332
|
+
| `teams_find_one_on_one` | Find a 1:1 chat with a person |
|
|
333
|
+
| `teams_find_people` | Search the organization directory |
|
|
334
|
+
| `teams_find_chats` | Search chats by name or member |
|
|
335
|
+
| `teams_get_messages` | Get messages from a conversation |
|
|
336
|
+
| `teams_send_message` | Send a message to a conversation |
|
|
337
|
+
| `teams_get_members` | List members of a conversation |
|
|
338
|
+
| `teams_get_transcript` | Get a meeting transcript from a recorded conversation |
|
|
339
|
+
| `teams_whoami` | Get the authenticated user's display name |
|
|
340
|
+
|
|
341
|
+
See [SKILL.md](SKILL.md) for detailed tool descriptions and typical agent workflows.
|
|
342
|
+
|
|
343
|
+
## API regions
|
|
344
|
+
|
|
345
|
+
The Teams Chat Service URL varies by region. Use the `region` parameter or `TEAMS_REGION` env var:
|
|
346
|
+
|
|
347
|
+
| Region | Base URL |
|
|
348
|
+
| ------ | -------------------------------------------- |
|
|
349
|
+
| `apac` | `https://apac.ng.msg.teams.microsoft.com/v1` |
|
|
350
|
+
| `emea` | `https://emea.ng.msg.teams.microsoft.com/v1` |
|
|
351
|
+
| `amer` | `https://amer.ng.msg.teams.microsoft.com/v1` |
|
|
352
|
+
|
|
353
|
+
## Known limitations
|
|
354
|
+
|
|
355
|
+
- Token lifetime is ~24 hours. After expiry, you must re-acquire.
|
|
356
|
+
- The Teams Chat Service REST API is undocumented and may change without notice.
|
|
357
|
+
- Auto-login requires macOS, system Chrome, a platform authenticator, and a FIDO2 passkey. On other platforms, use interactive login (`--login`) instead.
|
|
358
|
+
- Token caching (macOS Keychain) is only available on macOS. On other platforms, pass the token directly or re-run interactive login each time.
|
|
359
|
+
- The members API returns empty display names for 1:1 chat participants. Use `findOneOnOneConversation()` to resolve names from message history.
|
|
360
|
+
- Reaction actor identities come from the `emotions` field in message payloads. Parsing handles both JSON-string and array formats.
|
|
361
|
+
|
|
362
|
+
## Programmatic API
|
|
363
|
+
|
|
364
|
+
This is the advanced integration path. Most users should start with MCP or CLI instead.
|
|
365
|
+
|
|
366
|
+
Install the package in your project:
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
npm install teams-api-mcp
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Example:
|
|
373
|
+
|
|
374
|
+
```typescript
|
|
375
|
+
import { TeamsClient } from "teams-api-mcp";
|
|
376
|
+
|
|
377
|
+
// Interactive login — opens a browser, you log in manually (all platforms)
|
|
378
|
+
const client = await TeamsClient.fromInteractiveLogin({ region: "emea" });
|
|
379
|
+
|
|
380
|
+
// Or auto-login via platform authenticator (macOS + FIDO2 passkey)
|
|
381
|
+
const autoClient = await TeamsClient.fromAutoLogin({
|
|
382
|
+
email: "you@example.com",
|
|
383
|
+
});
|
|
384
|
+
|
|
385
|
+
// Advanced/manual: create a client from previously captured tokens
|
|
386
|
+
const manualClient = TeamsClient.fromToken("skype-token-here", "apac");
|
|
387
|
+
|
|
388
|
+
const conversations = await client.listConversations();
|
|
389
|
+
const messages = await client.getMessages(conversations[0].id, {
|
|
390
|
+
maxPages: 5,
|
|
391
|
+
onProgress: (count) => console.log(`Fetched ${count} messages`),
|
|
392
|
+
});
|
|
393
|
+
|
|
394
|
+
await client.sendMessage(conversations[0].id, "Hello from the API!");
|
|
395
|
+
|
|
396
|
+
const oneOnOne = await client.findOneOnOneConversation("Jane Doe");
|
|
397
|
+
const members = await client.getMembers(conversations[0].id);
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
## Contributing
|
|
401
|
+
|
|
402
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture, and implementation notes.
|
|
403
|
+
|
|
404
|
+
## License
|
|
405
|
+
|
|
406
|
+
MIT
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# teams-api MCP Skill
|
|
2
|
+
|
|
3
|
+
Use this skill when you need to interact with Microsoft Teams — reading messages, sending replies, listing conversations, or looking up team members.
|
|
4
|
+
|
|
5
|
+
All tools share a unified interface with the CLI and programmatic API. Tool definitions, parameters, and descriptions are generated from a single source (`src/actions.ts`).\n\nAll tools accept an optional `format` parameter (`json`, `text`, `md`, or `toon`). Default format is `toon`.
|
|
6
|
+
|
|
7
|
+
## When to use
|
|
8
|
+
|
|
9
|
+
- Reading unread messages from Teams chats
|
|
10
|
+
- Sending messages or replies to conversations
|
|
11
|
+
- Finding a specific conversation or 1:1 chat
|
|
12
|
+
- Looking up who is in a conversation
|
|
13
|
+
- Monitoring conversations for updates
|
|
14
|
+
- Acting on behalf of the user in Teams workflows
|
|
15
|
+
|
|
16
|
+
## Available MCP tools
|
|
17
|
+
|
|
18
|
+
### teams_list_conversations
|
|
19
|
+
|
|
20
|
+
List conversations (chats, group chats, meetings, channels). Returns conversation ID, topic, type, member count, and last message time.
|
|
21
|
+
|
|
22
|
+
Parameters:
|
|
23
|
+
|
|
24
|
+
- `limit` (optional, number): Maximum number of conversations to return. Default: 50.
|
|
25
|
+
|
|
26
|
+
### teams_find_conversation
|
|
27
|
+
|
|
28
|
+
Find a conversation by topic name (case-insensitive partial match). For 1:1 chats (which have no topic), use `teams_find_one_on_one` instead.
|
|
29
|
+
|
|
30
|
+
Parameters:
|
|
31
|
+
|
|
32
|
+
- `query` (required, string): Partial topic name to search for.
|
|
33
|
+
|
|
34
|
+
### teams_find_one_on_one
|
|
35
|
+
|
|
36
|
+
Find a 1:1 conversation with a person by name. Searches untitled chats by scanning recent message sender names. Also finds the self-chat if the name matches the current user.
|
|
37
|
+
|
|
38
|
+
Parameters:
|
|
39
|
+
|
|
40
|
+
- `personName` (required, string): Name of the person to find (case-insensitive partial match).
|
|
41
|
+
|
|
42
|
+
### teams_get_messages
|
|
43
|
+
|
|
44
|
+
Get messages from a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required.
|
|
45
|
+
|
|
46
|
+
Parameters:
|
|
47
|
+
|
|
48
|
+
- `chat` (optional, string): Find conversation by topic name (partial match).
|
|
49
|
+
- `to` (optional, string): Find 1:1 conversation by person name.
|
|
50
|
+
- `conversationId` (optional, string): Direct conversation thread ID.
|
|
51
|
+
- `maxPages` (optional, number): Maximum pagination pages to fetch. Default: 100.
|
|
52
|
+
- `pageSize` (optional, number): Messages per page. Default: 200.
|
|
53
|
+
- `textOnly` (optional, boolean): Only return text messages, excluding system events. Default: true.
|
|
54
|
+
- `order` (optional, string): Message order — `oldest-first` (chronological, default) or `newest-first`.
|
|
55
|
+
|
|
56
|
+
### teams_send_message
|
|
57
|
+
|
|
58
|
+
Send a plain-text message to a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required.
|
|
59
|
+
|
|
60
|
+
Parameters:
|
|
61
|
+
|
|
62
|
+
- `chat` (optional, string): Find conversation by topic name (partial match).
|
|
63
|
+
- `to` (optional, string): Find 1:1 conversation by person name.
|
|
64
|
+
- `conversationId` (optional, string): Direct conversation thread ID.
|
|
65
|
+
- `content` (required, string): Message text to send.
|
|
66
|
+
|
|
67
|
+
### teams_get_members
|
|
68
|
+
|
|
69
|
+
List members of a conversation. Identify the conversation by topic name, person name for 1:1 chats, or direct ID. At least one identifier is required. Note: 1:1 chat members may have empty display names.
|
|
70
|
+
|
|
71
|
+
Parameters:
|
|
72
|
+
|
|
73
|
+
- `chat` (optional, string): Find conversation by topic name (partial match).
|
|
74
|
+
- `to` (optional, string): Find 1:1 conversation by person name.
|
|
75
|
+
- `conversationId` (optional, string): Direct conversation thread ID.
|
|
76
|
+
|
|
77
|
+
### teams_whoami
|
|
78
|
+
|
|
79
|
+
Get the display name and region of the currently authenticated user.
|
|
80
|
+
|
|
81
|
+
No parameters.
|
|
82
|
+
|
|
83
|
+
## Typical workflows
|
|
84
|
+
|
|
85
|
+
### Read and summarize a conversation
|
|
86
|
+
|
|
87
|
+
1. Call `teams_get_messages` with `chat: "Chat Name"` — conversation resolution happens automatically
|
|
88
|
+
2. Summarize the messages
|
|
89
|
+
|
|
90
|
+
Or for 1:1 chats:
|
|
91
|
+
|
|
92
|
+
1. Call `teams_get_messages` with `to: "Person Name"`
|
|
93
|
+
2. Summarize the messages
|
|
94
|
+
|
|
95
|
+
### Reply to someone
|
|
96
|
+
|
|
97
|
+
1. Call `teams_send_message` with `to: "Person Name"` and `content: "Your reply"`
|
|
98
|
+
|
|
99
|
+
Or for group chats:
|
|
100
|
+
|
|
101
|
+
1. Call `teams_send_message` with `chat: "Chat Name"` and `content: "Your message"`
|
|
102
|
+
|
|
103
|
+
### Monitor a conversation
|
|
104
|
+
|
|
105
|
+
1. Call `teams_get_messages` with `chat: "Chat Name"` and `maxPages: 1` to check for new messages
|
|
106
|
+
|
|
107
|
+
### Find out who is in a chat
|
|
108
|
+
|
|
109
|
+
1. Call `teams_get_members` with `chat: "Chat Name"`
|
|
110
|
+
|
|
111
|
+
### Look up a conversation ID
|
|
112
|
+
|
|
113
|
+
1. Call `teams_find_conversation` with the topic name
|
|
114
|
+
2. Use the returned conversation ID for subsequent operations
|
|
115
|
+
|
|
116
|
+
## Authentication
|
|
117
|
+
|
|
118
|
+
The MCP server handles authentication automatically via environment variables. Common configurations:
|
|
119
|
+
|
|
120
|
+
- `TEAMS_TOKEN=<token>` — pre-acquired skype token (all platforms)
|
|
121
|
+
- `TEAMS_AUTO=true` and `TEAMS_EMAIL=user@company.com` — unattended FIDO2 login (macOS only)
|
|
122
|
+
- `TEAMS_LOGIN=true` — interactive browser login (all platforms, opens a visible browser window)
|
|
123
|
+
|
|
124
|
+
## Important notes
|
|
125
|
+
|
|
126
|
+
- Conversation IDs look like `19:abc123@thread.v2` for group chats or `48:notes` for self-chat
|
|
127
|
+
- 1:1 chats have no topic name — use `teams_find_one_on_one` or the `to` parameter to find them by person name
|
|
128
|
+
- Messages include reactions, mentions, and quoted message references
|
|
129
|
+
- Token lifetime is ~24 hours — the server re-authenticates automatically with auto-login
|
|
130
|
+
- All tools share the same parameters and behavior as the CLI commands and programmatic API
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Unified action definitions for the Teams API.
|
|
3
|
+
*
|
|
4
|
+
* This is the single source of truth for all operations. CLI commands,
|
|
5
|
+
* MCP tools, and programmatic usage all derive from these definitions.
|
|
6
|
+
*
|
|
7
|
+
* Each action declares:
|
|
8
|
+
* - name, title, description — shared help text and documentation
|
|
9
|
+
* - parameters — typed parameter definitions with descriptions and defaults
|
|
10
|
+
* - execute — the implementation, calling TeamsClient methods
|
|
11
|
+
* - formatResult — human-readable output formatter (CLI without --json)
|
|
12
|
+
*/
|
|
13
|
+
import type { TeamsClient } from "./teams-client.js";
|
|
14
|
+
export interface ActionParameter {
|
|
15
|
+
/** Parameter name in camelCase (CLI flags auto-converted to kebab-case). */
|
|
16
|
+
name: string;
|
|
17
|
+
/** Parameter type. Determines CLI flag syntax and MCP Zod schema. */
|
|
18
|
+
type: "string" | "number" | "boolean";
|
|
19
|
+
/** Description for CLI help, MCP tool description, and documentation. */
|
|
20
|
+
description: string;
|
|
21
|
+
/** Whether the parameter must be provided. */
|
|
22
|
+
required: boolean;
|
|
23
|
+
/** Default value when parameter is omitted. */
|
|
24
|
+
default?: string | number | boolean;
|
|
25
|
+
}
|
|
26
|
+
export interface ActionDefinition {
|
|
27
|
+
/** Kebab-case name. CLI command name; MCP tool name is `teams_` + snake_case. */
|
|
28
|
+
name: string;
|
|
29
|
+
/** Human-readable title (MCP tool title). */
|
|
30
|
+
title: string;
|
|
31
|
+
/** Full description shared across CLI help, MCP, and documentation. */
|
|
32
|
+
description: string;
|
|
33
|
+
/** Typed parameter definitions. */
|
|
34
|
+
parameters: ActionParameter[];
|
|
35
|
+
/** Execute the action against a TeamsClient. */
|
|
36
|
+
execute: (client: TeamsClient, parameters: Record<string, unknown>) => Promise<unknown>;
|
|
37
|
+
/** Format result as human-readable text (CLI output without --json). */
|
|
38
|
+
formatResult: (result: unknown) => string;
|
|
39
|
+
/** Format result as Markdown. */
|
|
40
|
+
formatMarkdown: (result: unknown) => string;
|
|
41
|
+
/** Format result as fun ASCII art with emojis. */
|
|
42
|
+
formatToon: (result: unknown) => string;
|
|
43
|
+
}
|
|
44
|
+
export type OutputFormat = "json" | "text" | "md" | "toon";
|
|
45
|
+
export type MessageOrder = "newest-first" | "oldest-first";
|
|
46
|
+
/** Format an action result in the specified output format. */
|
|
47
|
+
export declare function formatOutput(action: ActionDefinition, result: unknown, format?: OutputFormat): string;
|
|
48
|
+
export declare const actions: ActionDefinition[];
|
|
49
|
+
//# sourceMappingURL=actions.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAerD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,gDAAgD;IAChD,OAAO,EAAE,CACP,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,wEAAwE;IACxE,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC1C,iCAAiC;IACjC,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IAC5C,kDAAkD;IAClD,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;CACzC;AAID,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,cAAc,CAAC;AAE3D,8DAA8D;AAC9D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,GAAE,YAAqB,GAC5B,MAAM,CAWR;AAs6BD,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAWrC,CAAC"}
|