@eduware/oneroster 1.1.0 → 1.2.0

package/src/mcp-server/tools/usersManagementDeleteUser.ts

@@ -0,0 +1,29 @@
+import { usersManagementDeleteUser } from '../../funcs/usersManagementDeleteUser.js';
+import * as operations from '../../models/operations/index.js';
+import { formatResult, ToolDefinition } from '../tools.js';
+
+const args = {
+    request: operations.DeleteUserRequest$inboundSchema,
+};
+
+export const tool$usersManagementDeleteUser: ToolDefinition<typeof args> = {
+    name: 'users-delete-user',
+    description: `Delete a User
+
+Perform a soft delete on a specific User on the service provider. This operation changes the status of the User to 'tobedeleted'.`,
+    args,
+    tool: async (client, args, ctx) => {
+        const [result, apiCall] = await usersManagementDeleteUser(client, args.request, {
+            fetchOptions: { signal: ctx.signal },
+        }).$inspect();
+
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error.message }],
+                isError: true,
+            };
+        }
+
+        return formatResult(void 0, apiCall);
+    },
+};

package/src/mcp-server/tools/usersManagementGetAllUsers.ts

@@ -0,0 +1,31 @@
+import { usersManagementGetAllUsers } from '../../funcs/usersManagementGetAllUsers.js';
+import * as operations from '../../models/operations/index.js';
+import { formatResult, ToolDefinition } from '../tools.js';
+
+const args = {
+    request: operations.GetAllUsersRequest$inboundSchema,
+};
+
+export const tool$usersManagementGetAllUsers: ToolDefinition<typeof args> = {
+    name: 'users-get-all-users',
+    description: `Get all Users
+
+To get all Users on the service provider.`,
+    args,
+    tool: async (client, args, ctx) => {
+        const [result, apiCall] = await usersManagementGetAllUsers(client, args.request, {
+            fetchOptions: { signal: ctx.signal },
+        }).$inspect();
+
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error.message }],
+                isError: true,
+            };
+        }
+
+        const value = result.value.result;
+
+        return formatResult(value, apiCall);
+    },
+};

package/src/mcp-server/tools/usersManagementGetUser.ts

@@ -0,0 +1,31 @@
+import { usersManagementGetUser } from '../../funcs/usersManagementGetUser.js';
+import * as operations from '../../models/operations/index.js';
+import { formatResult, ToolDefinition } from '../tools.js';
+
+const args = {
+    request: operations.GetUserRequest$inboundSchema,
+};
+
+export const tool$usersManagementGetUser: ToolDefinition<typeof args> = {
+    name: 'users-get-user',
+    description: `Get a specific User
+
+To get a specific User on the service provider.`,
+    args,
+    tool: async (client, args, ctx) => {
+        const [result, apiCall] = await usersManagementGetUser(client, args.request, {
+            fetchOptions: { signal: ctx.signal },
+        }).$inspect();
+
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error.message }],
+                isError: true,
+            };
+        }
+
+        const value = result.value;
+
+        return formatResult(value, apiCall);
+    },
+};

package/src/mcp-server/tools/usersManagementGetUserWithDemographics.ts

@@ -0,0 +1,33 @@
+import { usersManagementGetUserWithDemographics } from '../../funcs/usersManagementGetUserWithDemographics.js';
+import * as operations from '../../models/operations/index.js';
+import { formatResult, ToolDefinition } from '../tools.js';
+
+const args = {
+    request: operations.GetUserWithDemographicsRequest$inboundSchema,
+};
+
+export const tool$usersManagementGetUserWithDemographics: ToolDefinition<typeof args> = {
+    name: 'users-get-user-with-demo',
+    description: `Get a specific User with demographics
+
+To get a specific User with demographics on the service provider. If the corresponding record cannot be located, the api will return a 404 error code and message 'User not found.'`,
+    args,
+    tool: async (client, args, ctx) => {
+        const [result, apiCall] = await usersManagementGetUserWithDemographics(
+            client,
+            args.request,
+            { fetchOptions: { signal: ctx.signal } }
+        ).$inspect();
+
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error.message }],
+                isError: true,
+            };
+        }
+
+        const value = result.value;
+
+        return formatResult(value, apiCall);
+    },
+};

package/src/mcp-server/tools/usersManagementUpdateUser.ts

@@ -0,0 +1,31 @@
+import { usersManagementUpdateUser } from '../../funcs/usersManagementUpdateUser.js';
+import * as operations from '../../models/operations/index.js';
+import { formatResult, ToolDefinition } from '../tools.js';
+
+const args = {
+    request: operations.UpdateUserRequest$inboundSchema,
+};
+
+export const tool$usersManagementUpdateUser: ToolDefinition<typeof args> = {
+    name: 'users-update-user',
+    description: `Update an existing User
+
+To update an existing User on the service provider. The sourcedId for the record to be updated is supplied by the requesting system.`,
+    args,
+    tool: async (client, args, ctx) => {
+        const [result, apiCall] = await usersManagementUpdateUser(client, args.request, {
+            fetchOptions: { signal: ctx.signal },
+        }).$inspect();
+
+        if (!result.ok) {
+            return {
+                content: [{ type: 'text', text: result.error.message }],
+                isError: true,
+            };
+        }
+
+        const value = result.value;
+
+        return formatResult(value, apiCall);
+    },
+};

package/src/mcp-server/tools.ts

@@ -0,0 +1,119 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { objectOutputType, ZodRawShape, ZodTypeAny } from 'zod';
+
+import { OneRosterCore } from '../core.js';
+import { ConsoleLogger } from './console-logger.js';
+import { MCPScope } from './scopes.js';
+import { isAsyncIterable, isBinaryData, valueToBase64 } from './shared.js';
+
+export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
+    Args extends ZodRawShape
+        ? {
+              name: string;
+              description: string;
+              scopes?: MCPScope[];
+              args: Args;
+              tool: (
+                  client: OneRosterCore,
+                  args: objectOutputType<Args, ZodTypeAny>,
+                  extra: RequestHandlerExtra
+              ) => CallToolResult | Promise<CallToolResult>;
+          }
+        : {
+              name: string;
+              description: string;
+              scopes?: MCPScope[];
+              args?: undefined;
+              tool: (
+                  client: OneRosterCore,
+                  extra: RequestHandlerExtra
+              ) => CallToolResult | Promise<CallToolResult>;
+          };
+
+// Optional function to assist with formatting tool results
+export async function formatResult(
+    value: unknown,
+    init: { response?: Response | undefined }
+): Promise<CallToolResult> {
+    if (typeof value === 'undefined') {
+        return { content: [] };
+    }
+
+    const { response } = init;
+    const contentType = response?.headers.get('content-type') ?? '';
+    let content: CallToolResult['content'] = [];
+
+    if (contentType.search(/\bjson\b/g)) {
+        content = [{ type: 'text', text: JSON.stringify(value) }];
+    } else if (contentType.startsWith('text/event-stream') && isAsyncIterable(value)) {
+        content = await consumeSSE(value);
+    } else if (contentType.startsWith('text/') && typeof value === 'string') {
+        content = [{ type: 'text', text: value }];
+    } else if (isBinaryData(value) && contentType.startsWith('image/')) {
+        const data = await valueToBase64(value);
+        content = data == null ? [] : [{ type: 'image', data, mimeType: contentType }];
+    } else {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Unsupported content type: "${contentType}"`,
+                },
+            ],
+            isError: true,
+        };
+    }
+
+    return { content };
+}
+
+async function consumeSSE(value: AsyncIterable<unknown>): Promise<CallToolResult['content']> {
+    const content: CallToolResult['content'] = [];
+
+    for await (const chunk of value) {
+        if (typeof chunk === 'string') {
+            content.push({ type: 'text', text: chunk });
+        } else {
+            content.push({ type: 'text', text: JSON.stringify(chunk) });
+        }
+    }
+
+    return content;
+}
+
+export function createRegisterTool(
+    logger: ConsoleLogger,
+    server: McpServer,
+    sdk: OneRosterCore,
+    allowedScopes: Set<MCPScope>,
+    allowedTools?: ReadonlySet<string>
+): <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>) => void {
+    return <A extends ZodRawShape | undefined>(tool: ToolDefinition<A>): void => {
+        if (allowedTools && !allowedTools.has(tool.name)) {
+            return;
+        }
+
+        const scopes = tool.scopes ?? [];
+        if (allowedScopes.size > 0 && scopes.length === 0) {
+            return;
+        }
+
+        if (allowedScopes.size > 0 && !scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+            return;
+        }
+
+        if (tool.args) {
+            server.tool(tool.name, tool.description, tool.args, async (args, ctx) => {
+                return tool.tool(sdk, args, ctx);
+            });
+        } else {
+            server.tool(tool.name, tool.description, async (ctx) => {
+                return tool.tool(sdk, ctx);
+            });
+        }
+
+        logger.debug('Registered tool', { name: tool.name });
+    };
+}