@eduware/oneroster 1.1.0 → 1.2.1

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
+    }
+}

package/src/mcp-server/prompts.ts

@@ -0,0 +1,94 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import { objectOutputType, ZodOptional, ZodType, ZodTypeAny, ZodTypeDef } from 'zod';
+
+import { OneRosterCore } from '../core.js';
+import { ConsoleLogger } from './console-logger.js';
+import { MCPScope } from './scopes.js';
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+    [k: string]:
+        | ZodType<string, ZodTypeDef, string>
+        | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<Args extends undefined | PromptArgsRawShape = undefined> =
+    Args extends PromptArgsRawShape
+        ? {
+              name: string;
+              description?: string;
+              scopes?: MCPScope[];
+              args: Args;
+              prompt: (
+                  client: OneRosterCore,
+                  args: objectOutputType<Args, ZodTypeAny>,
+                  extra: RequestHandlerExtra
+              ) => GetPromptResult | Promise<GetPromptResult>;
+          }
+        : {
+              name: string;
+              description?: string;
+              scopes?: MCPScope[];
+              args?: undefined;
+              prompt: (
+                  client: OneRosterCore,
+                  extra: RequestHandlerExtra
+              ) => GetPromptResult | Promise<GetPromptResult>;
+          };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+    return {
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: value,
+                },
+            },
+        ],
+    };
+}
+
+export function createRegisterPrompt(
+    logger: ConsoleLogger,
+    server: McpServer,
+    sdk: OneRosterCore,
+    allowedScopes: Set<MCPScope>
+): <A extends PromptArgsRawShape | undefined>(prompt: PromptDefinition<A>) => void {
+    return <A extends PromptArgsRawShape | undefined>(prompt: PromptDefinition<A>): void => {
+        const scopes = prompt.scopes ?? [];
+        if (allowedScopes.size > 0 && scopes.length === 0) {
+            return;
+        }
+
+        if (allowedScopes.size > 0 && !scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+            return;
+        }
+
+        if (prompt.args) {
+            if (prompt.description) {
+                server.prompt(prompt.name, prompt.description, prompt.args, async (args, ctx) =>
+                    prompt.prompt(sdk, args, ctx)
+                );
+            } else {
+                server.prompt(prompt.name, prompt.args, async (args, ctx) =>
+                    prompt.prompt(sdk, args, ctx)
+                );
+            }
+        } else {
+            if (prompt.description) {
+                server.prompt(prompt.name, prompt.description, async (ctx) =>
+                    prompt.prompt(sdk, ctx)
+                );
+            } else {
+                server.prompt(prompt.name, async (ctx) => prompt.prompt(sdk, ctx));
+            }
+        }
+
+        logger.debug('Registered prompt', { name: prompt.name });
+    };
+}

package/src/mcp-server/resources.ts

@@ -0,0 +1,151 @@
+import {
+    McpServer,
+    ResourceMetadata,
+    ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+
+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 ReadResourceCallback = (
+    client: OneRosterCore,
+    uri: URL,
+    extra: RequestHandlerExtra
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceDefinition = {
+    name: string;
+    description?: string;
+    metadata?: ResourceMetadata;
+    scopes?: MCPScope[];
+    resource: string;
+    read: ReadResourceCallback;
+};
+
+export type ReadResourceTemplateCallback = (
+    client: OneRosterCore,
+    uri: URL,
+    vars: Variables,
+    extra: RequestHandlerExtra
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceTemplateDefinition = {
+    name: string;
+    description: string;
+    metadata?: ResourceMetadata;
+    scopes?: MCPScope[];
+    resource: ResourceTemplate;
+    read: ReadResourceTemplateCallback;
+};
+
+// Optional function to assist with formatting resource results
+export async function formatResult(
+    value: unknown,
+    uri: URL,
+    init: { mimeType?: string | undefined; response?: Response | undefined }
+): Promise<ReadResourceResult> {
+    if (typeof value === 'undefined') {
+        return { contents: [] };
+    }
+
+    let contents: ReadResourceResult['contents'] = [];
+
+    const mimeType = init.mimeType ?? init.response?.headers.get('content-type') ?? '';
+
+    if (mimeType.search(/\bjson\b/g) !== -1) {
+        contents = [{ uri: uri.toString(), mimeType, text: JSON.stringify(value) }];
+    } else if (mimeType.startsWith('text/event-stream') && isAsyncIterable(value)) {
+        contents = [
+            {
+                uri: uri.toString(),
+                mimeType: 'application/json',
+                text: await stringifySSEToJSON(value),
+            },
+        ];
+    } else if (
+        (mimeType.startsWith('text/') || mimeType.startsWith('application/')) &&
+        typeof value === 'string'
+    ) {
+        contents = [{ uri: uri.toString(), mimeType, text: value }];
+    } else if (isBinaryData(value)) {
+        const blob = await valueToBase64(value);
+        contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
+    } else {
+        throw new Error(`Unsupported content type: "${mimeType}"`);
+    }
+
+    return { contents };
+}
+
+async function stringifySSEToJSON(value: AsyncIterable<unknown>): Promise<string> {
+    const payloads = [];
+
+    for await (const chunk of value) {
+        payloads.push(chunk);
+    }
+
+    return JSON.stringify(payloads);
+}
+
+export function createRegisterResource(
+    logger: ConsoleLogger,
+    server: McpServer,
+    sdk: OneRosterCore,
+    allowedScopes: Set<MCPScope>
+): (resource: ResourceDefinition) => void {
+    return (resource: ResourceDefinition): void => {
+        const scopes = resource.scopes ?? [];
+        if (allowedScopes.size > 0 && scopes.length === 0) {
+            return;
+        }
+
+        if (allowedScopes.size > 0 && !scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+            return;
+        }
+
+        const metadata: ResourceMetadata = {
+            ...resource.metadata,
+            description: resource.description,
+        };
+
+        server.resource(resource.name, resource.resource, metadata, async (uri, ctx) =>
+            resource.read(sdk, uri, ctx)
+        );
+
+        logger.debug('Registered resource', { name: resource.name });
+    };
+}
+
+export function createRegisterResourceTemplate(
+    logger: ConsoleLogger,
+    server: McpServer,
+    sdk: OneRosterCore,
+    allowedScopes: Set<MCPScope>
+): (resource: ResourceTemplateDefinition) => void {
+    return (resource: ResourceTemplateDefinition): void => {
+        const scopes = resource.scopes ?? [];
+        if (allowedScopes.size > 0 && scopes.length === 0) {
+            return;
+        }
+
+        if (allowedScopes.size > 0 && !scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+            return;
+        }
+
+        const metadata: ResourceMetadata = {
+            ...resource.metadata,
+            description: resource.description,
+        };
+
+        server.resource(resource.name, resource.resource, metadata, async (uri, vars, ctx) =>
+            resource.read(sdk, uri, vars, ctx)
+        );
+
+        logger.debug('Registered resource template', { name: resource.name });
+    };
+}

package/src/mcp-server/scopes.ts

@@ -0,0 +1,3 @@
+export const mcpScopes = [] as const;
+
+export type MCPScope = (typeof mcpScopes)[number];