@teamnetwork-nz/m365-mcp-server 1.0.5 → 1.0.7

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/README.md CHANGED
@@ -199,6 +199,22 @@ Operations always target exactly one mailbox per request, either the default or
199
199
  | `create_event` | Create a new event (non-readonly mailboxes only) |
200
200
  | `update_event` | Update an existing event (non-readonly mailboxes only) |
201
201
 
202
+ ### To Do
203
+
204
+ | Tool | Description |
205
+ |---|---|
206
+ | `list_todo_lists` | List all To Do lists for a mailbox. The default list has `wellknownListName: "defaultList"` |
207
+ | `list_todo_tasks` | List tasks in a To Do list with optional `status` and `importance` filters |
208
+ | `get_todo_task` | Get full details of a specific task |
209
+ | `create_todo_task` | Create a new task (non-readonly mailboxes only) |
210
+ | `update_todo_task` | Update a task — title, body, status, importance, due date, reminder (non-readonly mailboxes only) |
211
+ | `delete_todo_task` | Permanently delete a task (non-readonly mailboxes only) |
212
+ | `list_linked_resources` | List all linked resources (external back-references) attached to a task |
213
+ | `get_linked_resource` | Get a specific linked resource |
214
+ | `create_linked_resource` | Attach a linked resource to a task — set `externalId` for reverse lookup, `webUrl` for a one-click link back to the source item |
215
+ | `update_linked_resource` | Update a linked resource (non-readonly mailboxes only) |
216
+ | `delete_linked_resource` | Remove a linked resource from a task (non-readonly mailboxes only) |
217
+
202
218
  ---
203
219
 
204
220
  ## Admin Setup
@@ -222,6 +238,7 @@ Grant the following **Application permissions** (not Delegated) and click **Gran
222
238
  | `Mail.Send` | Sending and replying |
223
239
  | `Calendars.Read` | Reading calendar events |
224
240
  | `Calendars.ReadWrite` | Creating and updating events |
241
+ | `Tasks.ReadWrite.All` | Reading and writing To Do lists and tasks |
225
242
 
226
243
  ### 2. Restrict Mailbox Access (Recommended)
227
244
 
@@ -0,0 +1,192 @@
1
+ import { mapGraphError } from '../utils/errors.js';
2
+ const TASK_SELECT = [
3
+ 'id',
4
+ 'title',
5
+ 'status',
6
+ 'importance',
7
+ 'dueDateTime',
8
+ 'reminderDateTime',
9
+ 'completedDateTime',
10
+ 'body',
11
+ 'createdDateTime',
12
+ 'lastModifiedDateTime',
13
+ ].join(',');
14
+ export async function listTodoLists(client, email) {
15
+ try {
16
+ // Note: the To Do lists endpoint has limited $select support with app-only auth.
17
+ // Fetch without $select to get all available fields rather than risk a 400.
18
+ return await client
19
+ .api(`/users/${email}/todo/lists`)
20
+ .get();
21
+ }
22
+ catch (err) {
23
+ throw mapGraphError(err, 'list_todo_lists');
24
+ }
25
+ }
26
+ export async function listTodoTasks(client, email, listId, params) {
27
+ try {
28
+ const filters = [];
29
+ if (params.status !== undefined)
30
+ filters.push(`status eq '${params.status}'`);
31
+ if (params.importance !== undefined)
32
+ filters.push(`importance eq '${params.importance}'`);
33
+ // Note: the To Do tasks endpoint has limited $select support with app-only auth.
34
+ // Fetch without $select to avoid a 400, same as listTodoLists.
35
+ // $orderby is also unsupported with app-only auth.
36
+ let req = client
37
+ .api(`/users/${email}/todo/lists/${listId}/tasks`)
38
+ .top(params.maxResults);
39
+ if (filters.length > 0) {
40
+ req = req.filter(filters.join(' and '));
41
+ }
42
+ return await req.get();
43
+ }
44
+ catch (err) {
45
+ throw mapGraphError(err, 'list_todo_tasks');
46
+ }
47
+ }
48
+ export async function getTodoTask(client, email, listId, taskId) {
49
+ try {
50
+ return await client
51
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}`)
52
+ .select(TASK_SELECT)
53
+ .get();
54
+ }
55
+ catch (err) {
56
+ throw mapGraphError(err, 'get_todo_task');
57
+ }
58
+ }
59
+ export async function createTodoTask(client, email, listId, params) {
60
+ try {
61
+ const body = {
62
+ title: params.title,
63
+ status: params.status,
64
+ importance: params.importance,
65
+ };
66
+ if (params.body !== undefined) {
67
+ body['body'] = {
68
+ content: params.body,
69
+ contentType: params.bodyType === 'html' ? 'html' : 'text',
70
+ };
71
+ }
72
+ if (params.dueDateTime !== undefined) {
73
+ body['dueDateTime'] = params.dueDateTime;
74
+ }
75
+ if (params.reminderDateTime !== undefined) {
76
+ body['reminderDateTime'] = params.reminderDateTime;
77
+ body['isReminderOn'] = true;
78
+ }
79
+ return await client.api(`/users/${email}/todo/lists/${listId}/tasks`).post(body);
80
+ }
81
+ catch (err) {
82
+ throw mapGraphError(err, 'create_todo_task');
83
+ }
84
+ }
85
+ export async function updateTodoTask(client, email, listId, taskId, params) {
86
+ try {
87
+ const patch = {};
88
+ if (params.title !== undefined)
89
+ patch['title'] = params.title;
90
+ if (params.status !== undefined)
91
+ patch['status'] = params.status;
92
+ if (params.importance !== undefined)
93
+ patch['importance'] = params.importance;
94
+ if (params.body !== undefined) {
95
+ patch['body'] = {
96
+ content: params.body,
97
+ contentType: (params.bodyType ?? 'text') === 'html' ? 'html' : 'text',
98
+ };
99
+ }
100
+ // null means "clear the due date"; an object means "set it"
101
+ if (params.dueDateTime !== undefined) {
102
+ patch['dueDateTime'] = params.dueDateTime; // may be null
103
+ }
104
+ if (params.reminderDateTime !== undefined) {
105
+ patch['reminderDateTime'] = params.reminderDateTime;
106
+ patch['isReminderOn'] = true;
107
+ }
108
+ return await client.api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}`).patch(patch);
109
+ }
110
+ catch (err) {
111
+ throw mapGraphError(err, 'update_todo_task');
112
+ }
113
+ }
114
+ export async function deleteTodoTask(client, email, listId, taskId) {
115
+ try {
116
+ await client.api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}`).delete();
117
+ }
118
+ catch (err) {
119
+ throw mapGraphError(err, 'delete_todo_task');
120
+ }
121
+ }
122
+ const LINKED_RESOURCE_SELECT = 'id,webUrl,applicationName,displayName,externalId';
123
+ export async function listLinkedResources(client, email, listId, taskId) {
124
+ try {
125
+ return await client
126
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}/linkedResources`)
127
+ .select(LINKED_RESOURCE_SELECT)
128
+ .get();
129
+ }
130
+ catch (err) {
131
+ throw mapGraphError(err, 'list_linked_resources');
132
+ }
133
+ }
134
+ export async function getLinkedResource(client, email, listId, taskId, linkedResourceId) {
135
+ try {
136
+ return await client
137
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}/linkedResources/${linkedResourceId}`)
138
+ .select(LINKED_RESOURCE_SELECT)
139
+ .get();
140
+ }
141
+ catch (err) {
142
+ throw mapGraphError(err, 'get_linked_resource');
143
+ }
144
+ }
145
+ export async function createLinkedResource(client, email, listId, taskId, params) {
146
+ try {
147
+ const body = {
148
+ applicationName: params.applicationName,
149
+ };
150
+ if (params.webUrl !== undefined)
151
+ body['webUrl'] = params.webUrl;
152
+ if (params.displayName !== undefined)
153
+ body['displayName'] = params.displayName;
154
+ if (params.externalId !== undefined)
155
+ body['externalId'] = params.externalId;
156
+ return await client
157
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}/linkedResources`)
158
+ .post(body);
159
+ }
160
+ catch (err) {
161
+ throw mapGraphError(err, 'create_linked_resource');
162
+ }
163
+ }
164
+ export async function updateLinkedResource(client, email, listId, taskId, linkedResourceId, params) {
165
+ try {
166
+ const patch = {};
167
+ if (params.applicationName !== undefined)
168
+ patch['applicationName'] = params.applicationName;
169
+ if (params.webUrl !== undefined)
170
+ patch['webUrl'] = params.webUrl;
171
+ if (params.displayName !== undefined)
172
+ patch['displayName'] = params.displayName;
173
+ if (params.externalId !== undefined)
174
+ patch['externalId'] = params.externalId;
175
+ return await client
176
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}/linkedResources/${linkedResourceId}`)
177
+ .patch(patch);
178
+ }
179
+ catch (err) {
180
+ throw mapGraphError(err, 'update_linked_resource');
181
+ }
182
+ }
183
+ export async function deleteLinkedResource(client, email, listId, taskId, linkedResourceId) {
184
+ try {
185
+ await client
186
+ .api(`/users/${email}/todo/lists/${listId}/tasks/${taskId}/linkedResources/${linkedResourceId}`)
187
+ .delete();
188
+ }
189
+ catch (err) {
190
+ throw mapGraphError(err, 'delete_linked_resource');
191
+ }
192
+ }
package/dist/index.js CHANGED
@@ -16,7 +16,36 @@ async function main() {
16
16
  // 3. Create MCP server and register all tools
17
17
  const server = new McpServer({
18
18
  name: '@teamnetwork/m365-mcp-server',
19
- version: '1.0.0',
19
+ version: '1.0.7',
20
+ }, {
21
+ instructions: `
22
+ Microsoft 365 MCP server — email, calendar, and To Do via the Microsoft Graph API.
23
+
24
+ ## Accounts and mailboxes
25
+ - Most tools accept optional accountId and mailbox parameters. Omit both to use the first configured account and its first mailbox.
26
+ - Call list_mailboxes once at the start of a session if you need to work with a specific account or mailbox, or if a tool returns a CONFIG_ERROR.
27
+ - Some mailboxes are marked read-only in config. Write tools (send_message, create_event, create_todo_task, etc.) will fail with READONLY_VIOLATION on those mailboxes — do not retry, report the error to the user.
28
+
29
+ ## Datetime handling
30
+ - All datetime inputs accept naive local time ("2026-05-11T09:00:00") or explicit offset ("2026-05-11T09:00:00+12:00").
31
+ - Naive strings are interpreted as the server's configured timezone (DATETIME_FORMAT env var — typically the user's local timezone). Do not convert to UTC before passing.
32
+ - All datetime values in responses are already expressed in the configured local timezone with offset (e.g. "2026-05-11T09:00:00+12:00"). Present these to the user as-is.
33
+
34
+ ## Email
35
+ - list_messages returns metadata only (subject, sender, preview). Call get_message with the messageId to retrieve the full body.
36
+ - The bodySearch parameter performs a full-text search but cannot be combined with server-side filters (startDate, endDate, sender). When bodySearch is used, those filters are applied client-side after retrieval.
37
+ - Use list_folders to discover folder IDs. Well-known names ("Inbox", "SentItems", "Drafts", "DeletedItems", "JunkEmail") work without a lookup.
38
+
39
+ ## Calendar
40
+ - list_events requires both startDate and endDate and expands recurring events within that window.
41
+ - Call list_calendars to discover calendarId values. Omit calendarId to use the default calendar.
42
+
43
+ ## To Do
44
+ - All To Do task operations require a listId. Always call list_todo_lists first to discover available lists and their IDs.
45
+ - list_todo_tasks defaults to returning all statuses. Pass status="notStarted" to see only open tasks.
46
+ - Linked resources (list_linked_resources, create_linked_resource, etc.) are external URL attachments on a task — they are not subtasks. Subtasks appear as checklistItems inside the task body.
47
+ - delete_todo_task is permanent and irreversible. Confirm with the user before calling it.
48
+ `.trim(),
20
49
  });
21
50
  registerAllTools(server, config, auth);
22
51
  // 4. Connect via stdio transport (Claude Desktop / Claude Code)
@@ -14,6 +14,18 @@ import { registerListEvents } from './calendar/listEvents.js';
14
14
  import { registerGetEvent } from './calendar/getEvent.js';
15
15
  import { registerCreateEvent } from './calendar/createEvent.js';
16
16
  import { registerUpdateEvent } from './calendar/updateEvent.js';
17
+ // Todo tools
18
+ import { registerListTodoLists } from './todo/listTodoLists.js';
19
+ import { registerListTodoTasks } from './todo/listTodoTasks.js';
20
+ import { registerGetTodoTask } from './todo/getTodoTask.js';
21
+ import { registerCreateTodoTask } from './todo/createTodoTask.js';
22
+ import { registerUpdateTodoTask } from './todo/updateTodoTask.js';
23
+ import { registerDeleteTodoTask } from './todo/deleteTodoTask.js';
24
+ import { registerListLinkedResources } from './todo/listLinkedResources.js';
25
+ import { registerGetLinkedResource } from './todo/getLinkedResource.js';
26
+ import { registerCreateLinkedResource } from './todo/createLinkedResource.js';
27
+ import { registerUpdateLinkedResource } from './todo/updateLinkedResource.js';
28
+ import { registerDeleteLinkedResource } from './todo/deleteLinkedResource.js';
17
29
  function registerEmailTools(server, config, auth) {
18
30
  registerListMailboxes(server, config);
19
31
  registerListFolders(server, config, auth);
@@ -32,8 +44,22 @@ function registerCalendarTools(server, config, auth) {
32
44
  registerCreateEvent(server, config, auth);
33
45
  registerUpdateEvent(server, config, auth);
34
46
  }
47
+ function registerTodoTools(server, config, auth) {
48
+ registerListTodoLists(server, config, auth);
49
+ registerListTodoTasks(server, config, auth);
50
+ registerGetTodoTask(server, config, auth);
51
+ registerCreateTodoTask(server, config, auth);
52
+ registerUpdateTodoTask(server, config, auth);
53
+ registerDeleteTodoTask(server, config, auth);
54
+ registerListLinkedResources(server, config, auth);
55
+ registerGetLinkedResource(server, config, auth);
56
+ registerCreateLinkedResource(server, config, auth);
57
+ registerUpdateLinkedResource(server, config, auth);
58
+ registerDeleteLinkedResource(server, config, auth);
59
+ }
35
60
  export function registerAllTools(server, config, auth) {
36
61
  registerEmailTools(server, config, auth);
37
62
  registerCalendarTools(server, config, auth);
63
+ registerTodoTools(server, config, auth);
38
64
  // Future: registerTeamsTools(server, config, auth);
39
65
  }
@@ -89,3 +89,65 @@ export const UpdateEventSchema = AccountMailbox.extend({
89
89
  location: z.string().optional(),
90
90
  attendees: z.array(z.string().email()).optional(),
91
91
  });
92
+ // ── Todo tools ─────────────────────────────────────────────────────────────
93
+ const TodoBase = AccountMailbox.extend({
94
+ listId: z.string().describe('The To Do list ID. Use list_todo_lists to find available list IDs.'),
95
+ });
96
+ export const ListTodoListsSchema = AccountMailbox;
97
+ export const ListTodoTasksSchema = TodoBase.extend({
98
+ status: z.enum(['notStarted', 'inProgress', 'completed', 'waitingOnOthers', 'deferred'])
99
+ .optional().describe('Filter tasks by status. Omit to return all statuses.'),
100
+ importance: z.enum(['low', 'normal', 'high'])
101
+ .optional().describe('Filter tasks by importance. Omit to return all importance levels.'),
102
+ maxResults: z.number().int().min(1).max(100).default(25).describe('Maximum number of tasks to return (1–100)'),
103
+ });
104
+ export const GetTodoTaskSchema = TodoBase.extend({
105
+ taskId: z.string().describe('The task ID'),
106
+ });
107
+ export const CreateTodoTaskSchema = TodoBase.extend({
108
+ title: z.string().min(1).describe('Task title'),
109
+ body: z.string().optional().describe('Task notes / body'),
110
+ bodyType: z.enum(['text', 'html']).default('text'),
111
+ status: z.enum(['notStarted', 'inProgress', 'waitingOnOthers', 'deferred'])
112
+ .default('notStarted').describe('Initial task status'),
113
+ importance: z.enum(['low', 'normal', 'high']).default('normal'),
114
+ dueDateTime: z.string().optional().describe('Due date/time. Naive format ("2024-01-15T09:00:00") is interpreted as the configured local timezone (DATETIME_FORMAT).'),
115
+ reminderDateTime: z.string().optional().describe('Reminder date/time. Naive format is interpreted as the configured local timezone (DATETIME_FORMAT).'),
116
+ });
117
+ export const UpdateTodoTaskSchema = TodoBase.extend({
118
+ taskId: z.string().describe('The task ID to update'),
119
+ title: z.string().optional(),
120
+ body: z.string().optional(),
121
+ bodyType: z.enum(['text', 'html']).optional(),
122
+ status: z.enum(['notStarted', 'inProgress', 'completed', 'waitingOnOthers', 'deferred']).optional(),
123
+ importance: z.enum(['low', 'normal', 'high']).optional(),
124
+ dueDateTime: z.string().optional().describe('New due date/time. Naive format is interpreted as the configured local timezone (DATETIME_FORMAT). Pass an empty string to clear the due date.'),
125
+ reminderDateTime: z.string().optional().describe('New reminder date/time. Naive format is interpreted as the configured local timezone (DATETIME_FORMAT).'),
126
+ });
127
+ export const DeleteTodoTaskSchema = TodoBase.extend({
128
+ taskId: z.string().describe('The task ID to delete'),
129
+ });
130
+ // ── Linked Resource tools ──────────────────────────────────────────────────
131
+ const TaskBase = TodoBase.extend({
132
+ taskId: z.string().describe('The task ID'),
133
+ });
134
+ export const ListLinkedResourcesSchema = TaskBase;
135
+ export const GetLinkedResourceSchema = TaskBase.extend({
136
+ linkedResourceId: z.string().describe('The linked resource ID'),
137
+ });
138
+ export const CreateLinkedResourceSchema = TaskBase.extend({
139
+ applicationName: z.string().min(1).describe('Display name of the source application (e.g. "Xero", "My App"). Identifies which system created the link.'),
140
+ webUrl: z.string().url().optional().describe('Deep-link URL back to the source item. Shown as a tappable link in the To Do UI.'),
141
+ displayName: z.string().optional().describe('Human-readable label for the linked item (e.g. "Invoice #INV-2026-042").'),
142
+ externalId: z.string().optional().describe('Your identifier for the source object — free-form string. Useful for reverse lookup ("which task is linked to this record in my system?").'),
143
+ });
144
+ export const UpdateLinkedResourceSchema = TaskBase.extend({
145
+ linkedResourceId: z.string().describe('The linked resource ID to update'),
146
+ applicationName: z.string().optional(),
147
+ webUrl: z.string().url().optional().describe('Updated deep-link URL back to the source item.'),
148
+ displayName: z.string().optional(),
149
+ externalId: z.string().optional(),
150
+ });
151
+ export const DeleteLinkedResourceSchema = TaskBase.extend({
152
+ linkedResourceId: z.string().describe('The linked resource ID to delete'),
153
+ });
@@ -0,0 +1,29 @@
1
+ import { CreateLinkedResourceSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { createLinkedResource } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ export function registerCreateLinkedResource(server, config, auth) {
9
+ server.tool('create_linked_resource', 'Attach a linked resource to a Microsoft To Do task. A linked resource is a back-reference to an external item — for example, a Xero invoice, a support ticket, or any record in an external system. Set externalId to your system\'s record identifier for reverse lookup. Set webUrl to give users a one-click link back to the source item from within To Do. A task may have multiple linked resources. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', CreateLinkedResourceSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('create_linked_resource', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId });
13
+ assertWritable(config, resolved.accountId, resolved.mailbox);
14
+ const token = await auth.getAccessToken(resolved.accountId);
15
+ const client = createGraphClient(token);
16
+ const result = await createLinkedResource(client, resolved.mailbox, params.listId, params.taskId, {
17
+ applicationName: params.applicationName,
18
+ ...(params.webUrl !== undefined && { webUrl: params.webUrl }),
19
+ ...(params.displayName !== undefined && { displayName: params.displayName }),
20
+ ...(params.externalId !== undefined && { externalId: params.externalId }),
21
+ });
22
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
23
+ }
24
+ catch (err) {
25
+ logger.error('create_linked_resource failed', { accountId: params.accountId, mailbox: params.mailbox });
26
+ return errorResponse(err);
27
+ }
28
+ });
29
+ }
@@ -0,0 +1,33 @@
1
+ import { CreateTodoTaskSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { createTodoTask } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ import { toCalendarDatetime, localizeResponseDates } from '../../utils/datetime.js';
9
+ export function registerCreateTodoTask(server, config, auth) {
10
+ server.tool('create_todo_task', 'Create a new task in a Microsoft To Do list. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', CreateTodoTaskSchema.shape, async (params) => {
11
+ try {
12
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
13
+ logger.info('create_todo_task', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId });
14
+ assertWritable(config, resolved.accountId, resolved.mailbox);
15
+ const token = await auth.getAccessToken(resolved.accountId);
16
+ const client = createGraphClient(token);
17
+ const result = await createTodoTask(client, resolved.mailbox, params.listId, {
18
+ title: params.title,
19
+ ...(params.body !== undefined && { body: params.body }),
20
+ bodyType: params.bodyType,
21
+ status: params.status,
22
+ importance: params.importance,
23
+ ...(params.dueDateTime !== undefined && { dueDateTime: toCalendarDatetime(params.dueDateTime) }),
24
+ ...(params.reminderDateTime !== undefined && { reminderDateTime: toCalendarDatetime(params.reminderDateTime) }),
25
+ });
26
+ return { content: [{ type: 'text', text: JSON.stringify(localizeResponseDates(result), null, 2) }] };
27
+ }
28
+ catch (err) {
29
+ logger.error('create_todo_task failed', { accountId: params.accountId, mailbox: params.mailbox });
30
+ return errorResponse(err);
31
+ }
32
+ });
33
+ }
@@ -0,0 +1,24 @@
1
+ import { DeleteLinkedResourceSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { deleteLinkedResource } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ export function registerDeleteLinkedResource(server, config, auth) {
9
+ server.tool('delete_linked_resource', 'Remove a linked resource from a Microsoft To Do task. This detaches the external reference but does not affect the task itself or the source item. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', DeleteLinkedResourceSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('delete_linked_resource', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId, linkedResourceId: params.linkedResourceId });
13
+ assertWritable(config, resolved.accountId, resolved.mailbox);
14
+ const token = await auth.getAccessToken(resolved.accountId);
15
+ const client = createGraphClient(token);
16
+ await deleteLinkedResource(client, resolved.mailbox, params.listId, params.taskId, params.linkedResourceId);
17
+ return { content: [{ type: 'text', text: JSON.stringify({ success: true, message: 'Linked resource removed successfully.' }) }] };
18
+ }
19
+ catch (err) {
20
+ logger.error('delete_linked_resource failed', { accountId: params.accountId, mailbox: params.mailbox });
21
+ return errorResponse(err);
22
+ }
23
+ });
24
+ }
@@ -0,0 +1,24 @@
1
+ import { DeleteTodoTaskSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { deleteTodoTask } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ export function registerDeleteTodoTask(server, config, auth) {
9
+ server.tool('delete_todo_task', 'Permanently delete a Microsoft To Do task. This action cannot be undone. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', DeleteTodoTaskSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('delete_todo_task', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId });
13
+ assertWritable(config, resolved.accountId, resolved.mailbox);
14
+ const token = await auth.getAccessToken(resolved.accountId);
15
+ const client = createGraphClient(token);
16
+ await deleteTodoTask(client, resolved.mailbox, params.listId, params.taskId);
17
+ return { content: [{ type: 'text', text: JSON.stringify({ success: true, message: 'Task deleted successfully.' }) }] };
18
+ }
19
+ catch (err) {
20
+ logger.error('delete_todo_task failed', { accountId: params.accountId, mailbox: params.mailbox });
21
+ return errorResponse(err);
22
+ }
23
+ });
24
+ }
@@ -0,0 +1,22 @@
1
+ import { GetLinkedResourceSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { getLinkedResource } from '../../graph/todo.js';
4
+ import { errorResponse } from '../../utils/errors.js';
5
+ import { logger } from '../../utils/logger.js';
6
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
7
+ export function registerGetLinkedResource(server, config, auth) {
8
+ server.tool('get_linked_resource', 'Get a specific linked resource attached to a Microsoft To Do task. Omit accountId/mailbox to use the first configured account and mailbox.', GetLinkedResourceSchema.shape, async (params) => {
9
+ try {
10
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
11
+ logger.info('get_linked_resource', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId, linkedResourceId: params.linkedResourceId });
12
+ const token = await auth.getAccessToken(resolved.accountId);
13
+ const client = createGraphClient(token);
14
+ const result = await getLinkedResource(client, resolved.mailbox, params.listId, params.taskId, params.linkedResourceId);
15
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
16
+ }
17
+ catch (err) {
18
+ logger.error('get_linked_resource failed', { accountId: params.accountId, mailbox: params.mailbox });
19
+ return errorResponse(err);
20
+ }
21
+ });
22
+ }
@@ -0,0 +1,23 @@
1
+ import { GetTodoTaskSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { getTodoTask } from '../../graph/todo.js';
4
+ import { errorResponse } from '../../utils/errors.js';
5
+ import { logger } from '../../utils/logger.js';
6
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
7
+ import { localizeResponseDates } from '../../utils/datetime.js';
8
+ export function registerGetTodoTask(server, config, auth) {
9
+ server.tool('get_todo_task', 'Get full details of a specific Microsoft To Do task. Omit accountId/mailbox to use the first configured account and mailbox.', GetTodoTaskSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('get_todo_task', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId });
13
+ const token = await auth.getAccessToken(resolved.accountId);
14
+ const client = createGraphClient(token);
15
+ const result = await getTodoTask(client, resolved.mailbox, params.listId, params.taskId);
16
+ return { content: [{ type: 'text', text: JSON.stringify(localizeResponseDates(result), null, 2) }] };
17
+ }
18
+ catch (err) {
19
+ logger.error('get_todo_task failed', { accountId: params.accountId, mailbox: params.mailbox });
20
+ return errorResponse(err);
21
+ }
22
+ });
23
+ }
@@ -0,0 +1,22 @@
1
+ import { ListLinkedResourcesSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { listLinkedResources } from '../../graph/todo.js';
4
+ import { errorResponse } from '../../utils/errors.js';
5
+ import { logger } from '../../utils/logger.js';
6
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
7
+ export function registerListLinkedResources(server, config, auth) {
8
+ server.tool('list_linked_resources', 'List all linked resources attached to a Microsoft To Do task. Linked resources are back-references to external items (e.g. a Xero invoice, a ticket, an email) that the task originated from or is associated with. Returns id, applicationName, displayName, webUrl, and externalId for each. Omit accountId/mailbox to use the first configured account and mailbox.', ListLinkedResourcesSchema.shape, async (params) => {
9
+ try {
10
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
11
+ logger.info('list_linked_resources', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId });
12
+ const token = await auth.getAccessToken(resolved.accountId);
13
+ const client = createGraphClient(token);
14
+ const result = await listLinkedResources(client, resolved.mailbox, params.listId, params.taskId);
15
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
16
+ }
17
+ catch (err) {
18
+ logger.error('list_linked_resources failed', { accountId: params.accountId, mailbox: params.mailbox });
19
+ return errorResponse(err);
20
+ }
21
+ });
22
+ }
@@ -0,0 +1,22 @@
1
+ import { ListTodoListsSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { listTodoLists } from '../../graph/todo.js';
4
+ import { errorResponse } from '../../utils/errors.js';
5
+ import { logger } from '../../utils/logger.js';
6
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
7
+ export function registerListTodoLists(server, config, auth) {
8
+ server.tool('list_todo_lists', 'List all Microsoft To Do lists for a mailbox. Returns list IDs, display names, and whether each list is the default (wellknownListName: "defaultList"). Use the returned listId with other To Do tools. Omit accountId/mailbox to use the first configured account and mailbox.', ListTodoListsSchema.shape, async (params) => {
9
+ try {
10
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
11
+ logger.info('list_todo_lists', { accountId: resolved.accountId, mailbox: resolved.mailbox });
12
+ const token = await auth.getAccessToken(resolved.accountId);
13
+ const client = createGraphClient(token);
14
+ const result = await listTodoLists(client, resolved.mailbox);
15
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
16
+ }
17
+ catch (err) {
18
+ logger.error('list_todo_lists failed', { accountId: params.accountId, mailbox: params.mailbox });
19
+ return errorResponse(err);
20
+ }
21
+ });
22
+ }
@@ -0,0 +1,27 @@
1
+ import { ListTodoTasksSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { listTodoTasks } from '../../graph/todo.js';
4
+ import { errorResponse } from '../../utils/errors.js';
5
+ import { logger } from '../../utils/logger.js';
6
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
7
+ import { localizeResponseDates } from '../../utils/datetime.js';
8
+ export function registerListTodoTasks(server, config, auth) {
9
+ server.tool('list_todo_tasks', 'List tasks in a Microsoft To Do list. Optionally filter by status and/or importance. Returns up to maxResults tasks ordered by last modified date. Omit accountId/mailbox to use the first configured account and mailbox.', ListTodoTasksSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('list_todo_tasks', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId });
13
+ const token = await auth.getAccessToken(resolved.accountId);
14
+ const client = createGraphClient(token);
15
+ const result = await listTodoTasks(client, resolved.mailbox, params.listId, {
16
+ ...(params.status !== undefined && { status: params.status }),
17
+ ...(params.importance !== undefined && { importance: params.importance }),
18
+ maxResults: params.maxResults,
19
+ });
20
+ return { content: [{ type: 'text', text: JSON.stringify(localizeResponseDates(result), null, 2) }] };
21
+ }
22
+ catch (err) {
23
+ logger.error('list_todo_tasks failed', { accountId: params.accountId, mailbox: params.mailbox });
24
+ return errorResponse(err);
25
+ }
26
+ });
27
+ }
@@ -0,0 +1,29 @@
1
+ import { UpdateLinkedResourceSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { updateLinkedResource } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ export function registerUpdateLinkedResource(server, config, auth) {
9
+ server.tool('update_linked_resource', 'Update an existing linked resource on a Microsoft To Do task. Only provided fields are changed. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', UpdateLinkedResourceSchema.shape, async (params) => {
10
+ try {
11
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
12
+ logger.info('update_linked_resource', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId, linkedResourceId: params.linkedResourceId });
13
+ assertWritable(config, resolved.accountId, resolved.mailbox);
14
+ const token = await auth.getAccessToken(resolved.accountId);
15
+ const client = createGraphClient(token);
16
+ const result = await updateLinkedResource(client, resolved.mailbox, params.listId, params.taskId, params.linkedResourceId, {
17
+ ...(params.applicationName !== undefined && { applicationName: params.applicationName }),
18
+ ...(params.webUrl !== undefined && { webUrl: params.webUrl }),
19
+ ...(params.displayName !== undefined && { displayName: params.displayName }),
20
+ ...(params.externalId !== undefined && { externalId: params.externalId }),
21
+ });
22
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
23
+ }
24
+ catch (err) {
25
+ logger.error('update_linked_resource failed', { accountId: params.accountId, mailbox: params.mailbox });
26
+ return errorResponse(err);
27
+ }
28
+ });
29
+ }
@@ -0,0 +1,43 @@
1
+ import { UpdateTodoTaskSchema } from '../schemas.js';
2
+ import { createGraphClient } from '../../graph/clientFactory.js';
3
+ import { updateTodoTask } from '../../graph/todo.js';
4
+ import { assertWritable } from '../../middleware/readonlyGuard.js';
5
+ import { errorResponse } from '../../utils/errors.js';
6
+ import { logger } from '../../utils/logger.js';
7
+ import { resolveMailbox } from '../../utils/resolveMailbox.js';
8
+ import { toCalendarDatetime, localizeResponseDates } from '../../utils/datetime.js';
9
+ export function registerUpdateTodoTask(server, config, auth) {
10
+ server.tool('update_todo_task', 'Update an existing Microsoft To Do task. Only provided fields are changed. Set status to "completed" to mark the task done. To clear dueDateTime, pass an empty string. Requires the mailbox to be non-readonly. Omit accountId/mailbox to use the first configured account and mailbox.', UpdateTodoTaskSchema.shape, async (params) => {
11
+ try {
12
+ const resolved = resolveMailbox(config, params.accountId, params.mailbox);
13
+ logger.info('update_todo_task', { accountId: resolved.accountId, mailbox: resolved.mailbox, listId: params.listId, taskId: params.taskId });
14
+ assertWritable(config, resolved.accountId, resolved.mailbox);
15
+ const token = await auth.getAccessToken(resolved.accountId);
16
+ const client = createGraphClient(token);
17
+ // Resolve dueDateTime: empty string or 'null' literal → clear (null); otherwise convert
18
+ let resolvedDueDateTime;
19
+ if (params.dueDateTime !== undefined) {
20
+ if (params.dueDateTime === '' || params.dueDateTime === 'null') {
21
+ resolvedDueDateTime = null;
22
+ }
23
+ else {
24
+ resolvedDueDateTime = toCalendarDatetime(params.dueDateTime);
25
+ }
26
+ }
27
+ const result = await updateTodoTask(client, resolved.mailbox, params.listId, params.taskId, {
28
+ ...(params.title !== undefined && { title: params.title }),
29
+ ...(params.body !== undefined && { body: params.body }),
30
+ ...(params.bodyType !== undefined && { bodyType: params.bodyType }),
31
+ ...(params.status !== undefined && { status: params.status }),
32
+ ...(params.importance !== undefined && { importance: params.importance }),
33
+ ...(resolvedDueDateTime !== undefined && { dueDateTime: resolvedDueDateTime }),
34
+ ...(params.reminderDateTime !== undefined && { reminderDateTime: toCalendarDatetime(params.reminderDateTime) }),
35
+ });
36
+ return { content: [{ type: 'text', text: JSON.stringify(localizeResponseDates(result), null, 2) }] };
37
+ }
38
+ catch (err) {
39
+ logger.error('update_todo_task failed', { accountId: params.accountId, mailbox: params.mailbox });
40
+ return errorResponse(err);
41
+ }
42
+ });
43
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@teamnetwork-nz/m365-mcp-server",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "description": "MCP server for Microsoft 365 Email and Calendar access using client credentials (app-only auth). Supports multiple accounts, shared mailboxes, per-mailbox read-only access, folder navigation, and date/content filtering.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",