@eduware/oneroster 1.0.1 → 1.2.0

package/src/lib/pagination.ts

@@ -0,0 +1,26 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+/**
+ * Pagination metadata extracted from HTTP response headers.
+ */
+export type PaginationMeta = {
+    totalCount?: number | undefined;
+};
+
+/**
+ * Extracts pagination metadata from HTTP response headers.
+ *
+ * The OneRoster API returns the total count of records in the X-Total-Count header.
+ * This function extracts that value for use in paginated responses.
+ *
+ * @param response - The HTTP Response object containing headers
+ * @returns An object containing the totalCount if present, undefined otherwise
+ */
+export function extractPaginationMeta(response: Response): PaginationMeta {
+    const totalCountHeader = response.headers.get('X-Total-Count');
+    return {
+        totalCount: totalCountHeader ? parseInt(totalCountHeader, 10) : undefined,
+    };
+}

package/src/mcp-server/cli/start/command.ts

@@ -0,0 +1,168 @@
+import { buildCommand } from '@stricli/core';
+import { numberParser } from '@stricli/core';
+import * as z from 'zod';
+
+import { consoleLoggerLevels } from '../../console-logger.js';
+import { clientProfiles } from '../../profiles.js';
+import { mcpScopes } from '../../scopes.js';
+
+/**
+ * Authentication types supported by the MCP server:
+ * - oauth1: OAuth 1.0a (HMAC-SHA256 signature) - for OneRoster v1.1
+ * - oauth2: OAuth 2.0 Client Credentials flow (default)
+ * - bearer: Pre-authenticated Bearer token (e.g., ClassLink Proxy mode)
+ */
+export const authTypes = ['oauth1', 'oauth2', 'bearer'] as const;
+export type AuthType = (typeof authTypes)[number];
+
+/**
+ * OneRoster API versions:
+ * - 1.1: Uses URL path /ims/oneroster/v1p1/
+ * - 1.2: Uses URL path /ims/oneroster/rostering/v1p2/ (default)
+ */
+export const oneRosterVersions = ['1.1', '1.2'] as const;
+export type OneRosterVersion = (typeof oneRosterVersions)[number];
+
+export const startCommand = buildCommand({
+    loader: async () => {
+        const { main } = await import('./impl.js');
+        return main;
+    },
+    parameters: {
+        flags: {
+            transport: {
+                kind: 'enum',
+                brief: 'The transport to use for communicating with the server',
+                default: 'stdio',
+                values: ['stdio', 'sse'],
+            },
+            port: {
+                kind: 'parsed',
+                brief: 'The port to use when the SSE transport is enabled',
+                default: '2718',
+                parse: (val: string) => z.coerce.number().int().gte(0).lt(65536).parse(val),
+            },
+            tool: {
+                kind: 'parsed',
+                brief: 'Specify tools to mount on the server',
+                optional: true,
+                variadic: true,
+                parse: (value: string) => {
+                    return z.string().parse(value);
+                },
+            },
+            ...(mcpScopes.length
+                ? {
+                      scope: {
+                          kind: 'enum',
+                          brief: 'Mount tools/resources that match given scope (repeatable flag)',
+                          values: mcpScopes,
+                          variadic: true,
+                          optional: true,
+                      },
+                  }
+                : {}),
+            'auth-type': {
+                kind: 'enum',
+                brief: 'Authentication type: oauth1 (v1.1 only), oauth2 (default), or bearer (pre-authenticated token)',
+                default: 'oauth2',
+                values: authTypes,
+            },
+            'client-id': {
+                kind: 'parsed',
+                brief: 'Sets the clientID auth field for the API (required for oauth1/oauth2)',
+                optional: true,
+                parse: (value: string) => {
+                    return z.string().parse(value);
+                },
+            },
+            'client-secret': {
+                kind: 'parsed',
+                brief: 'Sets the clientSecret auth field for the API (required for oauth1/oauth2)',
+                optional: true,
+                parse: (value: string) => {
+                    return z.string().parse(value);
+                },
+            },
+            'token-url': {
+                kind: 'parsed',
+                brief: 'Sets the tokenURL auth field for the API (required for oauth2)',
+                optional: true,
+                parse: (value: string) => {
+                    return z.string().parse(value);
+                },
+            },
+            'bearer-token': {
+                kind: 'parsed',
+                brief: 'Pre-authenticated bearer token (required when auth-type is bearer)',
+                optional: true,
+                parse: (value: string) => {
+                    return z.string().parse(value);
+                },
+            },
+            'client-profile': {
+                kind: 'enum',
+                brief: 'Client profile determining available tools: full (all tools) or classlink (read-only)',
+                default: 'full',
+                values: clientProfiles,
+            },
+            'oneroster-version': {
+                kind: 'enum',
+                brief: 'OneRoster API version: 1.1 or 1.2 (default)',
+                default: '1.2',
+                values: oneRosterVersions,
+            },
+            'server-url': {
+                kind: 'parsed',
+                brief: 'Overrides the default server URL used by the SDK',
+                optional: true,
+                parse: (value: string) => new URL(value).toString(),
+            },
+            'server-index': {
+                kind: 'parsed',
+                brief: 'Selects a predefined server used by the SDK',
+                optional: true,
+                parse: numberParser,
+            },
+            'log-level': {
+                kind: 'enum',
+                brief: 'The log level to use for the server',
+                default: 'info',
+                values: consoleLoggerLevels,
+            },
+            env: {
+                kind: 'parsed',
+                brief: 'Environment variables made available to the server',
+                optional: true,
+                variadic: true,
+                parse: (val: string) => {
+                    const sepIdx = val.indexOf('=');
+                    if (sepIdx === -1) {
+                        throw new Error('Invalid environment variable format');
+                    }
+
+                    const key = val.slice(0, sepIdx);
+                    const value = val.slice(sepIdx + 1);
+
+                    return [
+                        z
+                            .string()
+                            .nonempty({
+                                message: 'Environment variable key must be a non-empty string',
+                            })
+                            .parse(key),
+                        z
+                            .string()
+                            .nonempty({
+                                message: 'Environment variable value must be a non-empty string',
+                            })
+                            .parse(value),
+                    ] satisfies [string, string];
+                },
+            },
+        },
+    },
+    docs: {
+        brief: 'Run the Model Context Protocol server',
+    },
+});

package/src/mcp-server/cli/start/impl.ts

@@ -0,0 +1,223 @@
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import express from 'express';
+
+import { SDKOptions } from '../../../lib/config.js';
+import { AuthType, Security } from '../../../models/components/security.js';
+import { LocalContext } from '../../cli.js';
+import { ConsoleLoggerLevel, createConsoleLogger } from '../../console-logger.js';
+import { ClientProfile, getProfileTools } from '../../profiles.js';
+import { MCPScope } from '../../scopes.js';
+import { createMCPServer } from '../../server.js';
+
+interface StartCommandFlags {
+    readonly transport: 'stdio' | 'sse';
+    readonly port: number;
+    readonly tool?: string[];
+    readonly scope?: MCPScope[];
+    readonly 'client-id'?: string | undefined;
+    readonly 'client-secret'?: string | undefined;
+    readonly 'token-url'?: string | undefined;
+    readonly 'server-url'?: string;
+    readonly 'server-index'?: SDKOptions['serverIdx'];
+    readonly 'log-level': ConsoleLoggerLevel;
+    readonly env?: [string, string][];
+    // New flags for authentication and profiles
+    readonly 'auth-type': AuthType;
+    readonly 'bearer-token'?: string | undefined;
+    readonly 'client-profile': ClientProfile;
+    readonly 'oneroster-version': '1.1' | '1.2';
+}
+
+/**
+ * Validates flag combinations and throws an error if invalid.
+ */
+function validateFlags(flags: StartCommandFlags): void {
+    const authType = flags['auth-type'];
+
+    // Bearer auth requires bearer-token
+    if (authType === 'bearer') {
+        if (!flags['bearer-token']) {
+            throw new Error('The --bearer-token flag is required when --auth-type is "bearer"');
+        }
+    }
+
+    // OAuth1 and OAuth2 require client-id and client-secret
+    if (authType === 'oauth1' || authType === 'oauth2') {
+        if (!flags['client-id'] || !flags['client-secret']) {
+            throw new Error(
+                `The --client-id and --client-secret flags are required when --auth-type is "${authType}"`
+            );
+        }
+    }
+
+    // OAuth2 requires token-url
+    if (authType === 'oauth2') {
+        if (!flags['token-url']) {
+            throw new Error('The --token-url flag is required when --auth-type is "oauth2"');
+        }
+    }
+
+    // OAuth1 typically uses v1.1, warn if using v1.2
+    if (authType === 'oauth1' && flags['oneroster-version'] === '1.2') {
+        console.warn(
+            'Warning: OAuth 1.0a is typically used with OneRoster v1.1. ' +
+                'Consider using --oneroster-version 1.1 or switching to OAuth 2.0.'
+        );
+    }
+}
+
+/**
+ * Builds the security configuration based on the auth type and flags.
+ */
+function buildSecurityConfig(flags: StartCommandFlags): Security {
+    const authType = flags['auth-type'];
+
+    switch (authType) {
+        case 'bearer':
+            return {
+                authType: 'bearer',
+                bearerToken: flags['bearer-token'],
+            };
+
+        case 'oauth1':
+            return {
+                authType: 'oauth1',
+                clientID: flags['client-id'],
+                clientSecret: flags['client-secret'],
+            };
+
+        case 'oauth2':
+        default:
+            return {
+                authType: 'oauth2',
+                clientID: flags['client-id'],
+                clientSecret: flags['client-secret'],
+                tokenURL: flags['token-url'],
+            };
+    }
+}
+
+export async function main(this: LocalContext, flags: StartCommandFlags) {
+    // Validate flag combinations
+    validateFlags(flags);
+
+    flags.env?.forEach(([key, value]) => {
+        process.env[key] = value;
+    });
+
+    switch (flags.transport) {
+        case 'stdio':
+            await startStdio(flags);
+            break;
+        case 'sse':
+            await startSSE(flags);
+            break;
+        default:
+            throw new Error(`Invalid transport: ${flags.transport}`);
+    }
+}
+
+async function startStdio(flags: StartCommandFlags) {
+    const logger = createConsoleLogger(flags['log-level']);
+    const transport = new StdioServerTransport();
+
+    // Get profile-specific tools
+    const profileTools = getProfileTools(flags['client-profile']);
+
+    const server = createMCPServer({
+        logger,
+        allowedTools: flags.tool,
+        scopes: flags.scope,
+        security: buildSecurityConfig(flags),
+        serverURL: flags['server-url'],
+        serverIdx: flags['server-index'],
+        clientProfile: flags['client-profile'],
+        profileTools,
+        oneRosterVersion: flags['oneroster-version'],
+    });
+    await server.connect(transport);
+
+    const abort = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGTERM', abort);
+    process.on('SIGINT', abort);
+}
+
+async function startSSE(flags: StartCommandFlags) {
+    const logger = createConsoleLogger(flags['log-level']);
+    const app = express();
+
+    // Get profile-specific tools
+    const profileTools = getProfileTools(flags['client-profile']);
+
+    const mcpServer = createMCPServer({
+        logger,
+        allowedTools: flags.tool,
+        scopes: flags.scope,
+        security: buildSecurityConfig(flags),
+        serverURL: flags['server-url'],
+        serverIdx: flags['server-index'],
+        clientProfile: flags['client-profile'],
+        profileTools,
+        oneRosterVersion: flags['oneroster-version'],
+    });
+    let transport: SSEServerTransport | undefined;
+    const controller = new AbortController();
+
+    app.get('/sse', async (_req, res) => {
+        transport = new SSEServerTransport('/message', res);
+
+        await mcpServer.connect(transport);
+
+        mcpServer.server.onclose = async () => {
+            res.end();
+        };
+    });
+
+    app.post('/message', async (req, res) => {
+        if (!transport) {
+            throw new Error('Server transport not initialized');
+        }
+
+        await transport.handlePostMessage(req, res);
+    });
+
+    const httpServer = app.listen(flags.port, '0.0.0.0', () => {
+        const ha = httpServer.address();
+        const host = typeof ha === 'string' ? ha : `${ha?.address}:${ha?.port}`;
+        logger.info('MCP HTTP server started', { host });
+    });
+
+    let closing = false;
+    controller.signal.addEventListener('abort', async () => {
+        if (closing) {
+            logger.info('Received second signal. Forcing shutdown.');
+            process.exit(1);
+        }
+        closing = true;
+
+        logger.info('Shutting down MCP server');
+
+        await mcpServer.close();
+
+        logger.info('Shutting down HTTP server');
+
+        const timer = setTimeout(() => {
+            logger.info('Forcing shutdown');
+            process.exit(1);
+        }, 5000);
+
+        httpServer.close(() => {
+            clearTimeout(timer);
+            logger.info('Graceful shutdown complete');
+            process.exit(0);
+        });
+    });
+
+    const abort = () => controller.abort();
+    process.on('SIGTERM', abort);
+    process.on('SIGINT', abort);
+}

package/src/mcp-server/cli.ts

@@ -0,0 +1,9 @@
+import { CommandContext, StricliProcess } from '@stricli/core';
+
+export interface LocalContext extends CommandContext {
+    readonly process: StricliProcess;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+    return { process: process as StricliProcess };
+}

package/src/mcp-server/console-logger.ts

@@ -0,0 +1,55 @@
+export const consoleLoggerLevels = ['debug', 'warning', 'info', 'error'] as const;
+
+export type ConsoleLoggerLevel = (typeof consoleLoggerLevels)[number];
+
+export type ConsoleLogger = {
+    [key in ConsoleLoggerLevel]: (message: string, data?: Record<string, unknown>) => void;
+};
+
+export function createConsoleLogger(level: ConsoleLoggerLevel): ConsoleLogger {
+    const min = consoleLoggerLevels.indexOf(level);
+    const noop = () => {};
+
+    const logger: ConsoleLogger = {
+        debug: noop,
+        warning: noop,
+        info: noop,
+        error: noop,
+    };
+
+    return consoleLoggerLevels.reduce((logger, level, i) => {
+        if (i < min) {
+            return logger;
+        }
+
+        logger[level] = log.bind(null, level);
+
+        return logger;
+    }, logger);
+}
+
+function log(level: ConsoleLoggerLevel, message: string, data?: Record<string, unknown>) {
+    let line = '';
+    const allData = [{ msg: message, l: level }, data];
+
+    for (const ctx of allData) {
+        for (const [key, value] of Object.entries(ctx || {})) {
+            if (value == null) {
+                line += ` ${key}=<${value}>`;
+            } else if (typeof value === 'function') {
+                line += ` ${key}=<function>`;
+            } else if (typeof value === 'symbol') {
+                line += ` ${key}=${value.toString()}`;
+            } else if (typeof value === 'string') {
+                const v = value.search(/\s/g) >= 0 ? JSON.stringify(value) : value;
+                line += ` ${key}=${v}`;
+            } else if (typeof value !== 'object') {
+                line += ` ${key}=${value}`;
+            } else {
+                line += ` ${key}="${JSON.stringify(value)}"`;
+            }
+        }
+    }
+
+    console.error(line);
+}

package/src/mcp-server/extensions.ts

@@ -0,0 +1,12 @@
+import { ZodRawShape } from 'zod';
+
+import { PromptArgsRawShape, PromptDefinition } from './prompts.js';
+import { ResourceDefinition, ResourceTemplateDefinition } from './resources.js';
+import { ToolDefinition } from './tools.js';
+
+export type Register = {
+    tool: <A extends ZodRawShape | undefined>(def: ToolDefinition<A>) => void;
+    resource: (def: ResourceDefinition) => void;
+    resourceTemplate: (def: ResourceTemplateDefinition) => void;
+    prompt: <A extends PromptArgsRawShape | undefined>(prompt: PromptDefinition<A>) => void;
+};

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

@@ -0,0 +1,24 @@
+import process from 'node:process';
+
+import { buildApplication, buildRouteMap, run } from '@stricli/core';
+
+import { buildContext } from './cli.js';
+import { startCommand } from './cli/start/command.js';
+
+const routes = buildRouteMap({
+    routes: {
+        start: startCommand,
+    },
+    docs: {
+        brief: 'MCP server CLI',
+    },
+});
+
+export const app = buildApplication(routes, {
+    name: 'mcp',
+    versionInfo: {
+        currentVersion: '0.7.0',
+    },
+});
+
+run(app, process.argv.slice(2), buildContext(process));

package/src/mcp-server/profiles.ts

@@ -0,0 +1,104 @@
+/**
+ * MCP Server Profile Definitions
+ *
+ * Maps client profiles to the tools they can access.
+ * Based on the profile interfaces defined in src/clients/profiles.ts
+ */
+
+/**
+ * Available client profiles for the MCP server.
+ */
+export const clientProfiles = ['full', 'classlink'] as const;
+export type ClientProfile = (typeof clientProfiles)[number];
+
+/**
+ * Tools available in the ClassLink profile (read-only rostering).
+ * Based on IClassLinkProfile in src/clients/profiles.ts
+ *
+ * ClassLink does NOT support:
+ * - Demographics
+ * - Line Items / Results / Categories / Score Scales (gradebook)
+ * - Course Components / Component Resources
+ * - Assessment Line Items / Assessment Results
+ * - Resources
+ * - Any create/update/delete operations
+ */
+export const CLASSLINK_TOOLS: ReadonlySet<string> = new Set([
+    // Academic Sessions - read only
+    'acad-sessions-get-all-sessions',
+    'acad-sessions-get-session',
+
+    // Classes - read only
+    'classes-get-all-classes',
+    'classes-get-class',
+    'classes-get-students-class',
+    'classes-get-teachers-class',
+    'classes-get-classes-user',
+    'classes-get-classes-term',
+    'classes-get-classes-teacher',
+    'classes-get-classes-student',
+
+    // Courses - read only
+    'courses-get-all-courses',
+    'courses-get-course',
+    'courses-get-classes-course',
+
+    // Enrollments - read only
+    'enrollments-get-all-enrolls',
+    'enrollments-get-enroll',
+
+    // Grading Periods - read only
+    'grading-periods-get-all-gps',
+    'grading-periods-get-gp',
+
+    // Organizations - read only
+    'organizations-get-all-orgs',
+    'organizations-get-org',
+
+    // Schools - read only
+    'schools-get-all-schools',
+    'schools-get-school',
+    'schools-get-classes-school',
+    'schools-get-courses-school',
+    'schools-get-enrolls-school',
+    'schools-get-enrolls-class-school',
+    'schools-get-students-school',
+    'schools-get-students-class-school',
+    'schools-get-teachers-school',
+    'schools-get-teachers-class-school',
+    'schools-get-terms-school',
+
+    // Students - read only
+    'students-get-all-students',
+    'students-get-student',
+
+    // Teachers - read only
+    'teachers-get-all-teachers',
+    'teachers-get-teacher',
+
+    // Terms - read only
+    'terms-get-all-terms',
+    'terms-get-term',
+    'terms-get-gps-term',
+
+    // Users - read only
+    'users-get-all-users',
+    'users-get-user',
+]);
+
+/**
+ * Get the set of allowed tools for a given profile.
+ * Returns undefined for 'full' profile (all tools allowed).
+ *
+ * @param profile - The client profile to get tools for
+ * @returns A set of tool names allowed for the profile, or undefined if all tools are allowed
+ */
+export function getProfileTools(profile: ClientProfile): ReadonlySet<string> | undefined {
+    switch (profile) {
+        case 'classlink':
+            return CLASSLINK_TOOLS;
+        case 'full':
+        default:
+            return undefined; // All tools allowed
+    }
+}