@frustrated/ms-graph-mcp 0.1.10 → 0.1.11

package/README.md

@@ -20,6 +20,7 @@ A TypeScript MCP (Model Context Protocol) package for personal Microsoft Graph a
 - **Secure Token Storage:** Stores the MSAL token cache at `~/.config/ms-graph-mcp/msal_cache.json` with restricted file permissions (`0600`).
 - **User Control:** Provides CLI commands for permission management and revocation.
 - **MCP Standard:** Adheres to the Model Context Protocol for broad agent compatibility.
+- **OneDrive Support:** Lists, inspects, searches, and creates OneDrive files and folders.
 
 ## Usage with Manus Agents
 
@@ -54,6 +55,7 @@ The Microsoft Graph MCP CLI exposes the following tools:
 
 - **`mail`**: Manage email communications (e.g., list messages).
 - **`calendar`**: Organize calendar events (e.g., create events).
+- **`onedrive`**: Work with OneDrive files and folders.
 
 For detailed information on specific tools and their functionalities, refer to the [Tools Documentation](./docs/tools/README.md).
 
@@ -78,6 +80,7 @@ bunx --bun @frustrated/ms-graph-mcp revoke
 - [Ideation Document](./docs/ms_graph_mcp_ideation.md) - Conceptual design and motivation.
 - [Technical Specification](./docs/ms_graph_mcp_spec.md) - Detailed implementation guide.
 - [Tools Documentation](./docs/tools/README.md) - Comprehensive guide to all available MCP tools.
+- [MCP Smoke Test](./docs/mcp-smoke-test.md) - How to test the server directly over stdio with the MCP SDK.
 
 ## Security Considerations
 

package/docs/mcp-smoke-test.md

@@ -0,0 +1,89 @@
+# MCP smoke testing
+
+This guide shows how to test `ms-graph-mcp` as a raw MCP server over `stdio`, without wiring it into another AI app first.
+
+The goal is to verify three things:
+
+1. The process starts cleanly.
+2. The MCP handshake succeeds.
+3. `tools/list` and at least one `tools/call` work end to end.
+
+## What to expect
+
+When the server runs in MCP mode, `stdout` must remain reserved for protocol messages only. Human-readable logs should go to `stderr`.
+
+If you see plain text on `stdout`, the MCP framing is broken.
+
+## Prerequisites
+
+1. Authenticate once:
+
+```bash
+bun run src/index.ts init
+```
+
+2. Confirm the server can start:
+
+```bash
+bun run src/index.ts run
+```
+
+## Manual smoke test with the MCP SDK
+
+The easiest direct test is to use the official MCP SDK from a short Bun script.
+
+Create a temporary file such as `scripts/mcp-smoke-test.ts` with the following contents:
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({
+  command: 'bun',
+  args: ['run', 'src/index.ts', 'run'],
+});
+
+const client = new Client(
+  {
+    name: 'mcp-smoke-test',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {},
+  },
+);
+
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log(JSON.stringify(tools, null, 2));
+
+// Pick one tool that is enabled in your config.
+// Example: mail.list_messages
+const result = await client.callTool({
+  name: 'mail.list_messages',
+  arguments: { top: 1 },
+});
+
+console.log(JSON.stringify(result, null, 2));
+await client.close();
+```
+
+Run it with:
+
+```bash
+bun run scripts/mcp-smoke-test.ts
+```
+
+## What to verify
+
+- `listTools()` returns the registered tools you expect.
+- `callTool()` returns a successful result object.
+- The server does not print protocol text to `stderr` or `stdout` outside the MCP response stream.
+- A bad input should fail with a clear validation or Graph error instead of an opaque transport error.
+
+## Quick debug checks
+
+- If `listTools()` is empty, confirm tool gating in `~/.ms-graph-mcp/config.json`.
+- If a tool call returns `401`, re-run `bun run src/index.ts init`.
+- If a tool call returns `400`, inspect the request payload for invalid dates, missing required fields, or malformed OneDrive paths.

package/docs/tools/README.md

@@ -6,7 +6,7 @@ This document provides an overview of the top-level tools available in the Micro
 
 *   **[Mail](./mail.md)**: Interact with email messages, folders, and other mail-related functionalities.
 *   **[Calendar](./calendar.md)**: Manage calendar events, schedules, and attendees.
-*   **OneDrive (Coming Soon)**: Interact with files and folders in OneDrive.
+*   **[OneDrive](./onedrive.md)**: List, inspect, search, and create files and folders in OneDrive.
 
 ## How to Discover Sub-Tools
 

package/docs/tools/onedrive.md

@@ -0,0 +1,44 @@
+# OneDrive Tools
+
+This document details the sub-tools available under the `onedrive` top-level tool.
+
+## `onedrive.list_items`
+
+Lists files and folders from OneDrive root or a specific folder.
+
+### Parameters
+
+* `folderPath` (string, optional): A folder path relative to OneDrive root, such as `/Projects`.
+* `itemId` (string, optional): A drive item ID whose children should be listed.
+* `top` (number, optional): Maximum number of items to return.
+* `select` (string, optional): Optional OData `$select` clause.
+
+## `onedrive.get_item`
+
+Gets metadata for a OneDrive file or folder.
+
+### Parameters
+
+* `path` (string, optional): Item path relative to OneDrive root, such as `/Projects/report.docx`.
+* `itemId` (string, optional): Drive item ID.
+* `select` (string, optional): Optional OData `$select` clause.
+
+## `onedrive.search_items`
+
+Searches OneDrive for files and folders.
+
+### Parameters
+
+* `query` (string, required): Search query.
+* `top` (number, optional): Maximum number of items to return.
+* `select` (string, optional): Optional OData `$select` clause.
+
+## `onedrive.create_folder`
+
+Creates a folder in OneDrive root or under a specific parent folder.
+
+### Parameters
+
+* `name` (string, required): Folder name.
+* `parentPath` (string, optional): Parent folder path relative to OneDrive root.
+* `parentItemId` (string, optional): Parent drive item ID.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frustrated/ms-graph-mcp",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "A JSR-based TypeScript MCP package for personal Microsoft Graph access via CLI",
   "type": "module",
   "main": "./src/index.ts",
@@ -21,6 +21,8 @@
     "@microsoft/microsoft-graph-client": "npm:@microsoft/microsoft-graph-client@^3.0.0",
     "@commander-js/extra-typings": "npm:@commander-js/extra-typings@^14.0.0",
     "@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@^1.28.0",
+    "zod/v3": "./src/vendor/zod-v3.ts",
+    "zod/v4": "./src/vendor/zod-v4.ts",
     "zod": "npm:zod@^3.24.2"
   },
   "dependencies": {

package/src/auth.ts

@@ -18,7 +18,9 @@ const MSAL_CONFIG: Configuration = {
   system: {
     loggerOptions: {
       loggerCallback(loglevel, message, containsPii) {
-        console.log(message);
+        if (!containsPii) {
+          process.stderr.write(`${message}\n`);
+        }
       },
       piiLoggingEnabled: false,
       logLevel: LogLevel.Verbose,

package/src/index.ts

@@ -9,7 +9,7 @@ const program = new Command();
 program
   .name("ms-graph-mcp")
   .description("CLI for JSR-based Microsoft Graph MCP package")
-  .version("0.1.0");
+  .version("0.1.11");
 
 program
   .command("init")

package/src/mcp-interface.ts

@@ -7,6 +7,7 @@ import { log } from './utils.ts';
 import { Client } from '@microsoft/microsoft-graph-client';
 import * as mail from './tools/mail.ts';
 import * as calendar from './tools/calendar.ts';
+import * as onedrive from './tools/onedrive.ts';
 
 function buildGraphClient(accessToken: string): Client {
   return Client.init({
@@ -17,7 +18,7 @@ function buildGraphClient(accessToken: string): Client {
 export async function startMcpServer(): Promise<void> {
   const server = new McpServer({
     name: 'ms-graph-mcp',
-    version: '0.1.10',
+    version: '0.1.11',
   });
 
   if (isToolEnabled('mail.list_messages')) {
@@ -66,6 +67,75 @@ export async function startMcpServer(): Promise<void> {
     );
   }
 
+  if (isToolEnabled('onedrive.list_items')) {
+    server.tool(
+      'onedrive.list_items',
+      'List files and folders from OneDrive root or a specific folder',
+      {
+        folderPath: z.string().trim().optional().describe('Folder path relative to OneDrive root, e.g. /Projects'),
+        itemId: z.string().trim().optional().describe('Drive item ID to list children from'),
+        top: z.number().int().min(1).max(999).optional().describe('Maximum number of items to return'),
+        select: z.string().trim().optional().describe('Optional OData $select clause'),
+      },
+      async (input) => {
+        const token = await getAccessToken();
+        const result = await onedrive.listItems(buildGraphClient(token), input);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      },
+    );
+  }
+
+  if (isToolEnabled('onedrive.get_item')) {
+    server.tool(
+      'onedrive.get_item',
+      'Get metadata for a OneDrive file or folder by path or item ID',
+      {
+        path: z.string().trim().optional().describe('Item path relative to OneDrive root, e.g. /Projects/report.docx'),
+        itemId: z.string().trim().optional().describe('Drive item ID'),
+        select: z.string().trim().optional().describe('Optional OData $select clause'),
+      },
+      async (input) => {
+        const token = await getAccessToken();
+        const result = await onedrive.getItem(buildGraphClient(token), input);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      },
+    );
+  }
+
+  if (isToolEnabled('onedrive.search_items')) {
+    server.tool(
+      'onedrive.search_items',
+      'Search OneDrive for files and folders',
+      {
+        query: z.string().trim().min(1).describe('Search query'),
+        top: z.number().int().min(1).max(999).optional().describe('Maximum number of items to return'),
+        select: z.string().trim().optional().describe('Optional OData $select clause'),
+      },
+      async (input) => {
+        const token = await getAccessToken();
+        const result = await onedrive.searchItems(buildGraphClient(token), input);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      },
+    );
+  }
+
+  if (isToolEnabled('onedrive.create_folder')) {
+    server.tool(
+      'onedrive.create_folder',
+      'Create a folder in OneDrive root or under a specific parent',
+      {
+        name: z.string().trim().min(1).describe('Folder name'),
+        parentPath: z.string().trim().optional().describe('Parent folder path relative to OneDrive root'),
+        parentItemId: z.string().trim().optional().describe('Parent drive item ID'),
+      },
+      async (input) => {
+        const token = await getAccessToken();
+        const result = await onedrive.createFolder(buildGraphClient(token), input);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      },
+    );
+  }
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   log('MCP server started (JSON-RPC 2.0 over stdio). Listening for commands...');

package/src/tools/calendar.ts

@@ -1,5 +1,23 @@
 import { Client } from '@microsoft/microsoft-graph-client';
-import { log, error } from '../utils.ts';
+import { log, error, describeGraphError } from '../utils.ts';
+
+function assertValidEventTimeRange(start: { dateTime: string; timeZone: string }, end: { dateTime: string; timeZone: string }): void {
+  const startDate = new Date(start.dateTime);
+  const endDate = new Date(end.dateTime);
+
+  if (Number.isNaN(startDate.getTime())) {
+    throw new Error(`Invalid start.dateTime value: ${start.dateTime}`);
+  }
+  if (Number.isNaN(endDate.getTime())) {
+    throw new Error(`Invalid end.dateTime value: ${end.dateTime}`);
+  }
+  if (endDate.getTime() <= startDate.getTime()) {
+    throw new Error('Event end time must be after the start time.');
+  }
+  if (!start.timeZone.trim() || !end.timeZone.trim()) {
+    throw new Error('Both start.timeZone and end.timeZone are required.');
+  }
+}
 
 export async function createEvent(graphClient: Client, input: {
   subject: string;
@@ -10,6 +28,8 @@ export async function createEvent(graphClient: Client, input: {
   location?: string;
 }): Promise<any> {
   try {
+    assertValidEventTimeRange(input.start, input.end);
+
     const event = {
       subject: input.subject,
       start: input.start,
@@ -31,11 +51,6 @@ export async function createEvent(graphClient: Client, input: {
     };
   } catch (err: any) {
     error('Error creating calendar event:', err);
-    return {
-      id: null,
-      webLink: null,
-      status: 'failed',
-      errorMessage: err.message,
-    };
+    throw new Error(`Failed to create calendar event: ${describeGraphError(err)}`);
   }
 }

package/src/tools/index.ts

@@ -1,9 +1,12 @@
 import * as mail from './mail.ts';
 import * as calendar from './calendar.ts';
-// import * as onedrive from './onedrive'; // Placeholder for future tools
+import * as onedrive from './onedrive.ts';
 
 export const tools = {
   'mail.list_messages': mail.listMessages,
   'calendar.create_event': calendar.createEvent,
-  // 'onedrive.list_files': onedrive.listFiles,
+  'onedrive.list_items': onedrive.listItems,
+  'onedrive.get_item': onedrive.getItem,
+  'onedrive.search_items': onedrive.searchItems,
+  'onedrive.create_folder': onedrive.createFolder,
 };

package/src/tools/mail.ts

@@ -1,10 +1,36 @@
 import { Client } from '@microsoft/microsoft-graph-client';
-import { log, error } from '../utils.ts';
+import { log, error, describeGraphError } from '../utils.ts';
+
+const WELL_KNOWN_FOLDERS = new Map<string, string>([
+  ['inbox', 'inbox'],
+  ['sent', 'sentitems'],
+  ['sentitems', 'sentitems'],
+  ['drafts', 'drafts'],
+  ['deleted', 'deleteditems'],
+  ['deleteditems', 'deleteditems'],
+  ['archive', 'archive'],
+  ['junk', 'junkemail'],
+  ['junkemail', 'junkemail'],
+  ['outbox', 'outbox'],
+]);
+
+function normalizeFolderId(folderId?: string): string | undefined {
+  if (!folderId) {
+    return undefined;
+  }
+
+  const trimmed = folderId.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return WELL_KNOWN_FOLDERS.get(trimmed.toLowerCase()) ?? trimmed;
+}
 
 export async function listMessages(graphClient: Client, input: { folderId?: string; top?: number; filter?: string }): Promise<any> {
   try {
-    let request = graphClient.api(input.folderId ? `/me/mailFolders/${input.folderId}/messages` : 
-'/me/messages');
+    const folderId = normalizeFolderId(input.folderId);
+    let request = graphClient.api(folderId ? `/me/mailFolders/${folderId}/messages` : '/me/messages');
 
     if (input.top) {
       request = request.top(input.top);
@@ -29,6 +55,6 @@ export async function listMessages(graphClient: Client, input: { folderId?: stri
     };
   } catch (err: any) {
     error('Error listing messages:', err);
-    throw err;
+    throw new Error(`Failed to list messages: ${describeGraphError(err)}`);
   }
 }

package/src/tools/onedrive.ts

@@ -0,0 +1,145 @@
+import { Client } from '@microsoft/microsoft-graph-client';
+import { error, log, describeGraphError } from '../utils.ts';
+
+type DriveItem = {
+  id: string;
+  name: string;
+  webUrl?: string;
+  size?: number;
+  createdDateTime?: string;
+  lastModifiedDateTime?: string;
+  folder?: unknown;
+  file?: unknown;
+};
+
+function trimLeadingSlash(value: string): string {
+  return value.replace(/^\/+/, '');
+}
+
+function toRootPath(path: string): string {
+  const normalized = trimLeadingSlash(path.trim());
+  const segments = normalized
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map((segment) => encodeURIComponent(segment));
+  return `/${segments.join('/')}`;
+}
+
+function buildItemPath(itemId?: string, folderPath?: string): string {
+  if (itemId) {
+    return `/me/drive/items/${itemId}`;
+  }
+
+  if (folderPath) {
+    return `/me/drive/root:${toRootPath(folderPath)}:`;
+  }
+
+  return '/me/drive/root';
+}
+
+function simplifyItem(item: DriveItem): Record<string, unknown> {
+  return {
+    id: item.id,
+    name: item.name,
+    webUrl: item.webUrl,
+    size: item.size,
+    createdDateTime: item.createdDateTime,
+    lastModifiedDateTime: item.lastModifiedDateTime,
+    isFolder: Boolean(item.folder),
+    isFile: Boolean(item.file),
+  };
+}
+
+export async function listItems(
+  graphClient: Client,
+  input: { folderPath?: string; itemId?: string; top?: number; select?: string },
+): Promise<any> {
+  try {
+    const path = buildItemPath(input.itemId, input.folderPath);
+    let request = graphClient.api(`${path}/children`);
+
+    if (input.top) {
+      request = request.top(input.top);
+    }
+
+    const select = input.select?.trim();
+    const response = select
+      ? await request.select(select).get()
+      : await request.get();
+
+    log(`Listed ${response.value.length} OneDrive items.`);
+    return {
+      items: response.value.map((item: DriveItem) => simplifyItem(item)),
+      nextLink: response['@odata.nextLink'],
+    };
+  } catch (err: any) {
+    error('Error listing OneDrive items:', err);
+    throw new Error(`Failed to list OneDrive items: ${describeGraphError(err)}`);
+  }
+}
+
+export async function getItem(
+  graphClient: Client,
+  input: { itemId?: string; path?: string; select?: string },
+): Promise<any> {
+  try {
+    const path = buildItemPath(input.itemId, input.path);
+    const select = input.select?.trim();
+    const response = select
+      ? await graphClient.api(path).select(select).get()
+      : await graphClient.api(path).get();
+
+    log(`Fetched OneDrive item: ${response.name ?? response.id}`);
+    return simplifyItem(response);
+  } catch (err: any) {
+    error('Error retrieving OneDrive item:', err);
+    throw new Error(`Failed to retrieve OneDrive item: ${describeGraphError(err)}`);
+  }
+}
+
+export async function searchItems(
+  graphClient: Client,
+  input: { query: string; top?: number; select?: string },
+): Promise<any> {
+  try {
+    let request = graphClient.api(`/me/drive/root/search(q='${input.query.replace(/'/g, "''")}')`);
+
+    if (input.top) {
+      request = request.top(input.top);
+    }
+
+    const select = input.select?.trim();
+    const response = select
+      ? await request.select(select).get()
+      : await request.get();
+
+    log(`Search returned ${response.value.length} OneDrive items.`);
+    return {
+      items: response.value.map((item: DriveItem) => simplifyItem(item)),
+      nextLink: response['@odata.nextLink'],
+    };
+  } catch (err: any) {
+    error('Error searching OneDrive items:', err);
+    throw new Error(`Failed to search OneDrive items: ${describeGraphError(err)}`);
+  }
+}
+
+export async function createFolder(
+  graphClient: Client,
+  input: { name: string; parentPath?: string; parentItemId?: string },
+): Promise<any> {
+  try {
+    const parentPath = buildItemPath(input.parentItemId, input.parentPath);
+    const response = await graphClient.api(`${parentPath}/children`).post({
+      name: input.name,
+      folder: {},
+      '@microsoft.graph.conflictBehavior': 'rename',
+    });
+
+    log(`Created OneDrive folder: ${response.name} (ID: ${response.id})`);
+    return simplifyItem(response);
+  } catch (err: any) {
+    error('Error creating OneDrive folder:', err);
+    throw new Error(`Failed to create OneDrive folder: ${describeGraphError(err)}`);
+  }
+}

package/src/utils.ts

@@ -18,4 +18,32 @@ export function warn(message: string) {
   log(message, 'warn');
 }
 
-// Placeholder for future file-based logging or other utilities
+export function describeGraphError(err: unknown): string {
+  if (err instanceof Error) {
+    const parts: string[] = [err.message];
+    const graphErr = err as Error & {
+      code?: string;
+      statusCode?: number;
+      body?: { error?: { code?: string; message?: string } };
+      response?: { status?: number; body?: { error?: { code?: string; message?: string } } };
+    };
+
+    const status = graphErr.statusCode ?? graphErr.response?.status;
+    const code = graphErr.code ?? graphErr.body?.error?.code ?? graphErr.response?.body?.error?.code;
+    const message = graphErr.body?.error?.message ?? graphErr.response?.body?.error?.message;
+
+    if (status) {
+      parts.unshift(`HTTP ${status}`);
+    }
+    if (code) {
+      parts.push(`code=${code}`);
+    }
+    if (message && message !== err.message) {
+      parts.push(message);
+    }
+
+    return parts.join(' | ');
+  }
+
+  return String(err);
+}

package/src/vendor/zod-v3.ts

@@ -0,0 +1,4 @@
+import * as zod from 'zod';
+
+export * from 'zod';
+export default zod;

package/src/vendor/zod-v4.ts

@@ -0,0 +1,4 @@
+import * as zod from 'zod';
+
+export * from 'zod';
+export default zod;