@eduware/oneroster 1.0.1 → 1.2.0

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];

package/src/mcp-server/server.ts

@@ -0,0 +1,330 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import { OneRosterCore } from '../core.js';
+import { OneRosterVersion, SDKOptions } from '../lib/config.js';
+import type { ConsoleLogger } from './console-logger.js';
+import { ClientProfile } from './profiles.js';
+import { createRegisterPrompt } from './prompts.js';
+import { createRegisterResource, createRegisterResourceTemplate } from './resources.js';
+import { MCPScope } from './scopes.js';
+import { createRegisterTool } from './tools.js';
+import { tool$academicSessionsManagementDeleteAcademicSession } from './tools/academicSessionsManagementDeleteAcademicSession.js';
+import { tool$academicSessionsManagementGetAcademicSession } from './tools/academicSessionsManagementGetAcademicSession.js';
+import { tool$academicSessionsManagementGetAllAcademicSessions } from './tools/academicSessionsManagementGetAllAcademicSessions.js';
+import { tool$academicSessionsManagementPostAcademicSession } from './tools/academicSessionsManagementPostAcademicSession.js';
+import { tool$academicSessionsManagementPutAcademicSession } from './tools/academicSessionsManagementPutAcademicSession.js';
+import { tool$assessmentLineItemsManagementCreateAssessmentLineItem } from './tools/assessmentLineItemsManagementCreateAssessmentLineItem.js';
+import { tool$assessmentLineItemsManagementDeleteAssessmentLineItem } from './tools/assessmentLineItemsManagementDeleteAssessmentLineItem.js';
+import { tool$assessmentLineItemsManagementGetAllAssessmentLineItems } from './tools/assessmentLineItemsManagementGetAllAssessmentLineItems.js';
+import { tool$assessmentLineItemsManagementGetAssessmentLineItem } from './tools/assessmentLineItemsManagementGetAssessmentLineItem.js';
+import { tool$assessmentLineItemsManagementUpdateAssessmentLineItem } from './tools/assessmentLineItemsManagementUpdateAssessmentLineItem.js';
+import { tool$assessmentResultsManagementCreateAssessmentResult } from './tools/assessmentResultsManagementCreateAssessmentResult.js';
+import { tool$assessmentResultsManagementDeleteAssessmentResult } from './tools/assessmentResultsManagementDeleteAssessmentResult.js';
+import { tool$assessmentResultsManagementGetAllAssessmentResults } from './tools/assessmentResultsManagementGetAllAssessmentResults.js';
+import { tool$assessmentResultsManagementGetAssessmentResult } from './tools/assessmentResultsManagementGetAssessmentResult.js';
+import { tool$assessmentResultsManagementUpdateAssessmentResult } from './tools/assessmentResultsManagementUpdateAssessmentResult.js';
+import { tool$categoriesManagementCreateCategory } from './tools/categoriesManagementCreateCategory.js';
+import { tool$categoriesManagementDeleteCategory } from './tools/categoriesManagementDeleteCategory.js';
+import { tool$categoriesManagementGetAllCategories } from './tools/categoriesManagementGetAllCategories.js';
+import { tool$categoriesManagementGetCategory } from './tools/categoriesManagementGetCategory.js';
+import { tool$categoriesManagementUpdateCategory } from './tools/categoriesManagementUpdateCategory.js';
+import { tool$classesManagementAddStudentToClass } from './tools/classesManagementAddStudentToClass.js';
+import { tool$classesManagementAddTeacherToClass } from './tools/classesManagementAddTeacherToClass.js';
+import { tool$classesManagementCreateClass } from './tools/classesManagementCreateClass.js';
+import { tool$classesManagementDeleteClass } from './tools/classesManagementDeleteClass.js';
+import { tool$classesManagementGetAllClasses } from './tools/classesManagementGetAllClasses.js';
+import { tool$classesManagementGetCategoriesForClass } from './tools/classesManagementGetCategoriesForClass.js';
+import { tool$classesManagementGetClass } from './tools/classesManagementGetClass.js';
+import { tool$classesManagementGetClassesForStudent } from './tools/classesManagementGetClassesForStudent.js';
+import { tool$classesManagementGetClassesForTeacher } from './tools/classesManagementGetClassesForTeacher.js';
+import { tool$classesManagementGetClassesForTerm } from './tools/classesManagementGetClassesForTerm.js';
+import { tool$classesManagementGetClassesForUser } from './tools/classesManagementGetClassesForUser.js';
+import { tool$classesManagementGetLineItemsForClass } from './tools/classesManagementGetLineItemsForClass.js';
+import { tool$classesManagementGetResultsForClass } from './tools/classesManagementGetResultsForClass.js';
+import { tool$classesManagementGetResultsForLineItemForClass } from './tools/classesManagementGetResultsForLineItemForClass.js';
+import { tool$classesManagementGetResultsForStudentForClass } from './tools/classesManagementGetResultsForStudentForClass.js';
+import { tool$classesManagementGetScoreScalesForClass } from './tools/classesManagementGetScoreScalesForClass.js';
+import { tool$classesManagementGetStudentsForClass } from './tools/classesManagementGetStudentsForClass.js';
+import { tool$classesManagementGetTeachersForClass } from './tools/classesManagementGetTeachersForClass.js';
+import { tool$classesManagementPostResultsForAcademicSessionForClass } from './tools/classesManagementPostResultsForAcademicSessionForClass.js';
+import { tool$classesManagementUpdateClass } from './tools/classesManagementUpdateClass.js';
+import { tool$coursesManagementCreateComponentResource } from './tools/coursesManagementCreateComponentResource.js';
+import { tool$coursesManagementCreateCourse } from './tools/coursesManagementCreateCourse.js';
+import { tool$coursesManagementCreateCourseComponent } from './tools/coursesManagementCreateCourseComponent.js';
+import { tool$coursesManagementDeleteComponentResource } from './tools/coursesManagementDeleteComponentResource.js';
+import { tool$coursesManagementDeleteCourse } from './tools/coursesManagementDeleteCourse.js';
+import { tool$coursesManagementDeleteCourseComponent } from './tools/coursesManagementDeleteCourseComponent.js';
+import { tool$coursesManagementGetAllComponentResources } from './tools/coursesManagementGetAllComponentResources.js';
+import { tool$coursesManagementGetAllCourseComponents } from './tools/coursesManagementGetAllCourseComponents.js';
+import { tool$coursesManagementGetAllCourses } from './tools/coursesManagementGetAllCourses.js';
+import { tool$coursesManagementGetClassesForCourse } from './tools/coursesManagementGetClassesForCourse.js';
+import { tool$coursesManagementGetComponentResource } from './tools/coursesManagementGetComponentResource.js';
+import { tool$coursesManagementGetCourse } from './tools/coursesManagementGetCourse.js';
+import { tool$coursesManagementGetCourseComponent } from './tools/coursesManagementGetCourseComponent.js';
+import { tool$coursesManagementPutComponentResource } from './tools/coursesManagementPutComponentResource.js';
+import { tool$coursesManagementPutCourse } from './tools/coursesManagementPutCourse.js';
+import { tool$coursesManagementPutCourseComponent } from './tools/coursesManagementPutCourseComponent.js';
+import { tool$demographicsManagementDeleteDemographics } from './tools/demographicsManagementDeleteDemographics.js';
+import { tool$demographicsManagementGetAllDemographics } from './tools/demographicsManagementGetAllDemographics.js';
+import { tool$demographicsManagementGetDemographics } from './tools/demographicsManagementGetDemographics.js';
+import { tool$demographicsManagementPostDemographics } from './tools/demographicsManagementPostDemographics.js';
+import { tool$demographicsManagementPutDemographics } from './tools/demographicsManagementPutDemographics.js';
+import { tool$enrollmentsManagementCreateEnrollment } from './tools/enrollmentsManagementCreateEnrollment.js';
+import { tool$enrollmentsManagementDeleteEnrollment } from './tools/enrollmentsManagementDeleteEnrollment.js';
+import { tool$enrollmentsManagementGetAllEnrollments } from './tools/enrollmentsManagementGetAllEnrollments.js';
+import { tool$enrollmentsManagementGetEnrollment } from './tools/enrollmentsManagementGetEnrollment.js';
+import { tool$enrollmentsManagementUpdateEnrollment } from './tools/enrollmentsManagementUpdateEnrollment.js';
+import { tool$gradingPeriodsManagementCreateGradingPeriod } from './tools/gradingPeriodsManagementCreateGradingPeriod.js';
+import { tool$gradingPeriodsManagementDeleteGradingPeriod } from './tools/gradingPeriodsManagementDeleteGradingPeriod.js';
+import { tool$gradingPeriodsManagementGetAllGradingPeriods } from './tools/gradingPeriodsManagementGetAllGradingPeriods.js';
+import { tool$gradingPeriodsManagementGetGradingPeriod } from './tools/gradingPeriodsManagementGetGradingPeriod.js';
+import { tool$gradingPeriodsManagementUpdateGradingPeriod } from './tools/gradingPeriodsManagementUpdateGradingPeriod.js';
+import { tool$lineItemsManagementCreateLineItem } from './tools/lineItemsManagementCreateLineItem.js';
+import { tool$lineItemsManagementCreateResultForLineItem } from './tools/lineItemsManagementCreateResultForLineItem.js';
+import { tool$lineItemsManagementDeleteLineItem } from './tools/lineItemsManagementDeleteLineItem.js';
+import { tool$lineItemsManagementGetAllLineItems } from './tools/lineItemsManagementGetAllLineItems.js';
+import { tool$lineItemsManagementGetLineItem } from './tools/lineItemsManagementGetLineItem.js';
+import { tool$lineItemsManagementUpdateLineItem } from './tools/lineItemsManagementUpdateLineItem.js';
+import { tool$organizationsManagementCreateOrg } from './tools/organizationsManagementCreateOrg.js';
+import { tool$organizationsManagementDeleteOrg } from './tools/organizationsManagementDeleteOrg.js';
+import { tool$organizationsManagementGetAllOrgs } from './tools/organizationsManagementGetAllOrgs.js';
+import { tool$organizationsManagementGetOrg } from './tools/organizationsManagementGetOrg.js';
+import { tool$organizationsManagementUpdateOrg } from './tools/organizationsManagementUpdateOrg.js';
+import { tool$resourcesManagementCreateResource } from './tools/resourcesManagementCreateResource.js';
+import { tool$resourcesManagementDeleteResource } from './tools/resourcesManagementDeleteResource.js';
+import { tool$resourcesManagementExportResourceToCommonCartridge } from './tools/resourcesManagementExportResourceToCommonCartridge.js';
+import { tool$resourcesManagementGetAllResources } from './tools/resourcesManagementGetAllResources.js';
+import { tool$resourcesManagementGetResource } from './tools/resourcesManagementGetResource.js';
+import { tool$resourcesManagementGetResourcesForClass } from './tools/resourcesManagementGetResourcesForClass.js';
+import { tool$resourcesManagementGetResourcesForCourse } from './tools/resourcesManagementGetResourcesForCourse.js';
+import { tool$resourcesManagementGetResourcesForUser } from './tools/resourcesManagementGetResourcesForUser.js';
+import { tool$resourcesManagementUpdateResource } from './tools/resourcesManagementUpdateResource.js';
+import { tool$resultsManagementCreateResult } from './tools/resultsManagementCreateResult.js';
+import { tool$resultsManagementDeleteResult } from './tools/resultsManagementDeleteResult.js';
+import { tool$resultsManagementGetAllResults } from './tools/resultsManagementGetAllResults.js';
+import { tool$resultsManagementGetResult } from './tools/resultsManagementGetResult.js';
+import { tool$resultsManagementUpdateResult } from './tools/resultsManagementUpdateResult.js';
+import { tool$schoolsManagementCreateLineItemsForSchool } from './tools/schoolsManagementCreateLineItemsForSchool.js';
+import { tool$schoolsManagementCreateSchool } from './tools/schoolsManagementCreateSchool.js';
+import { tool$schoolsManagementDeleteSchool } from './tools/schoolsManagementDeleteSchool.js';
+import { tool$schoolsManagementGetAllSchools } from './tools/schoolsManagementGetAllSchools.js';
+import { tool$schoolsManagementGetClassesForSchool } from './tools/schoolsManagementGetClassesForSchool.js';
+import { tool$schoolsManagementGetCoursesForSchool } from './tools/schoolsManagementGetCoursesForSchool.js';
+import { tool$schoolsManagementGetEnrollmentsForClassInSchool } from './tools/schoolsManagementGetEnrollmentsForClassInSchool.js';
+import { tool$schoolsManagementGetEnrollmentsForSchool } from './tools/schoolsManagementGetEnrollmentsForSchool.js';
+import { tool$schoolsManagementGetLineItemsForSchool } from './tools/schoolsManagementGetLineItemsForSchool.js';
+import { tool$schoolsManagementGetSchool } from './tools/schoolsManagementGetSchool.js';
+import { tool$schoolsManagementGetStudentsForClassInSchool } from './tools/schoolsManagementGetStudentsForClassInSchool.js';
+import { tool$schoolsManagementGetStudentsForSchool } from './tools/schoolsManagementGetStudentsForSchool.js';
+import { tool$schoolsManagementGetTeachersForClassInSchool } from './tools/schoolsManagementGetTeachersForClassInSchool.js';
+import { tool$schoolsManagementGetTeachersForSchool } from './tools/schoolsManagementGetTeachersForSchool.js';
+import { tool$schoolsManagementGetTermsForSchool } from './tools/schoolsManagementGetTermsForSchool.js';
+import { tool$schoolsManagementUpdateSchool } from './tools/schoolsManagementUpdateSchool.js';
+import { tool$scoreScalesManagementCreateScoreScale } from './tools/scoreScalesManagementCreateScoreScale.js';
+import { tool$scoreScalesManagementDeleteScoreScale } from './tools/scoreScalesManagementDeleteScoreScale.js';
+import { tool$scoreScalesManagementGetAllScoreScales } from './tools/scoreScalesManagementGetAllScoreScales.js';
+import { tool$scoreScalesManagementGetScoreScale } from './tools/scoreScalesManagementGetScoreScale.js';
+import { tool$scoreScalesManagementGetScoreScalesForSchool } from './tools/scoreScalesManagementGetScoreScalesForSchool.js';
+import { tool$scoreScalesManagementUpdateScoreScale } from './tools/scoreScalesManagementUpdateScoreScale.js';
+import { tool$studentsManagementGetAllStudents } from './tools/studentsManagementGetAllStudents.js';
+import { tool$studentsManagementGetStudent } from './tools/studentsManagementGetStudent.js';
+import { tool$teachersManagementGetAllTeachers } from './tools/teachersManagementGetAllTeachers.js';
+import { tool$teachersManagementGetTeacher } from './tools/teachersManagementGetTeacher.js';
+import { tool$termsManagementCreateGradingPeriodForTerm } from './tools/termsManagementCreateGradingPeriodForTerm.js';
+import { tool$termsManagementGetAllTerms } from './tools/termsManagementGetAllTerms.js';
+import { tool$termsManagementGetGradingPeriodsForTerm } from './tools/termsManagementGetGradingPeriodsForTerm.js';
+import { tool$termsManagementGetTerm } from './tools/termsManagementGetTerm.js';
+import { tool$usersManagementCreateUser } from './tools/usersManagementCreateUser.js';
+import { tool$usersManagementDeleteUser } from './tools/usersManagementDeleteUser.js';
+import { tool$usersManagementGetAllUsers } from './tools/usersManagementGetAllUsers.js';
+import { tool$usersManagementGetUser } from './tools/usersManagementGetUser.js';
+import { tool$usersManagementGetUserWithDemographics } from './tools/usersManagementGetUserWithDemographics.js';
+import { tool$usersManagementUpdateUser } from './tools/usersManagementUpdateUser.js';
+
+export function createMCPServer(deps: {
+    logger: ConsoleLogger;
+    allowedTools?: string[] | undefined;
+    scopes?: MCPScope[] | undefined;
+    serverURL?: string | undefined;
+    security?: SDKOptions['security'] | undefined;
+    serverIdx?: SDKOptions['serverIdx'] | undefined;
+    /** Client profile for filtering available tools */
+    clientProfile?: ClientProfile | undefined;
+    /** Profile-specific tool allowlist (from getProfileTools) */
+    profileTools?: ReadonlySet<string> | undefined;
+    /** OneRoster API version */
+    oneRosterVersion?: OneRosterVersion | undefined;
+}) {
+    const server = new McpServer({
+        name: 'OneRoster',
+        version: '0.7.0',
+    });
+
+    const client = new OneRosterCore({
+        security: deps.security,
+        serverURL: deps.serverURL,
+        serverIdx: deps.serverIdx,
+        oneRosterVersion: deps.oneRosterVersion,
+    });
+
+    const scopes = new Set(deps.scopes);
+
+    // Combine allowedTools with profileTools for filtering
+    // If profileTools is set, tools must be in profileTools AND allowedTools (if specified)
+    let effectiveAllowedTools: ReadonlySet<string> | undefined;
+    if (deps.profileTools) {
+        if (deps.allowedTools) {
+            // Intersection: tool must be in both profileTools and allowedTools
+            effectiveAllowedTools = new Set(
+                deps.allowedTools.filter((t) => deps.profileTools!.has(t))
+            );
+        } else {
+            // Just use profileTools
+            effectiveAllowedTools = deps.profileTools;
+        }
+    } else if (deps.allowedTools) {
+        effectiveAllowedTools = new Set(deps.allowedTools);
+    }
+
+    const tool = createRegisterTool(deps.logger, server, client, scopes, effectiveAllowedTools);
+    const resource = createRegisterResource(deps.logger, server, client, scopes);
+    const resourceTemplate = createRegisterResourceTemplate(deps.logger, server, client, scopes);
+    const prompt = createRegisterPrompt(deps.logger, server, client, scopes);
+    const register = { tool, resource, resourceTemplate, prompt };
+    void register; // suppress unused warnings
+
+    tool(tool$scoreScalesManagementGetAllScoreScales);
+    tool(tool$scoreScalesManagementCreateScoreScale);
+    tool(tool$scoreScalesManagementGetScoreScale);
+    tool(tool$scoreScalesManagementUpdateScoreScale);
+    tool(tool$scoreScalesManagementDeleteScoreScale);
+    tool(tool$scoreScalesManagementGetScoreScalesForSchool);
+    tool(tool$schoolsManagementGetAllSchools);
+    tool(tool$schoolsManagementCreateSchool);
+    tool(tool$schoolsManagementGetSchool);
+    tool(tool$schoolsManagementUpdateSchool);
+    tool(tool$schoolsManagementDeleteSchool);
+    tool(tool$schoolsManagementGetLineItemsForSchool);
+    tool(tool$schoolsManagementCreateLineItemsForSchool);
+    tool(tool$schoolsManagementGetClassesForSchool);
+    tool(tool$schoolsManagementGetTermsForSchool);
+    tool(tool$schoolsManagementGetTeachersForClassInSchool);
+    tool(tool$schoolsManagementGetTeachersForSchool);
+    tool(tool$schoolsManagementGetStudentsForClassInSchool);
+    tool(tool$schoolsManagementGetStudentsForSchool);
+    tool(tool$schoolsManagementGetEnrollmentsForClassInSchool);
+    tool(tool$schoolsManagementGetEnrollmentsForSchool);
+    tool(tool$schoolsManagementGetCoursesForSchool);
+    tool(tool$resultsManagementGetAllResults);
+    tool(tool$resultsManagementCreateResult);
+    tool(tool$resultsManagementGetResult);
+    tool(tool$resultsManagementUpdateResult);
+    tool(tool$resultsManagementDeleteResult);
+    tool(tool$lineItemsManagementGetAllLineItems);
+    tool(tool$lineItemsManagementCreateLineItem);
+    tool(tool$lineItemsManagementGetLineItem);
+    tool(tool$lineItemsManagementUpdateLineItem);
+    tool(tool$lineItemsManagementDeleteLineItem);
+    tool(tool$lineItemsManagementCreateResultForLineItem);
+    tool(tool$classesManagementPostResultsForAcademicSessionForClass);
+    tool(tool$classesManagementGetResultsForLineItemForClass);
+    tool(tool$classesManagementGetResultsForStudentForClass);
+    tool(tool$classesManagementGetCategoriesForClass);
+    tool(tool$classesManagementGetLineItemsForClass);
+    tool(tool$classesManagementGetResultsForClass);
+    tool(tool$classesManagementGetScoreScalesForClass);
+    tool(tool$classesManagementGetAllClasses);
+    tool(tool$classesManagementCreateClass);
+    tool(tool$classesManagementGetClass);
+    tool(tool$classesManagementUpdateClass);
+    tool(tool$classesManagementDeleteClass);
+    tool(tool$classesManagementGetClassesForUser);
+    tool(tool$classesManagementGetClassesForTerm);
+    tool(tool$classesManagementGetTeachersForClass);
+    tool(tool$classesManagementAddTeacherToClass);
+    tool(tool$classesManagementGetClassesForTeacher);
+    tool(tool$classesManagementGetStudentsForClass);
+    tool(tool$classesManagementAddStudentToClass);
+    tool(tool$classesManagementGetClassesForStudent);
+    tool(tool$categoriesManagementGetAllCategories);
+    tool(tool$categoriesManagementCreateCategory);
+    tool(tool$categoriesManagementGetCategory);
+    tool(tool$categoriesManagementUpdateCategory);
+    tool(tool$categoriesManagementDeleteCategory);
+    tool(tool$assessmentResultsManagementGetAllAssessmentResults);
+    tool(tool$assessmentResultsManagementCreateAssessmentResult);
+    tool(tool$assessmentResultsManagementGetAssessmentResult);
+    tool(tool$assessmentResultsManagementUpdateAssessmentResult);
+    tool(tool$assessmentResultsManagementDeleteAssessmentResult);
+    tool(tool$assessmentLineItemsManagementGetAllAssessmentLineItems);
+    tool(tool$assessmentLineItemsManagementCreateAssessmentLineItem);
+    tool(tool$assessmentLineItemsManagementGetAssessmentLineItem);
+    tool(tool$assessmentLineItemsManagementUpdateAssessmentLineItem);
+    tool(tool$assessmentLineItemsManagementDeleteAssessmentLineItem);
+    tool(tool$resourcesManagementGetAllResources);
+    tool(tool$resourcesManagementCreateResource);
+    tool(tool$resourcesManagementGetResource);
+    tool(tool$resourcesManagementUpdateResource);
+    tool(tool$resourcesManagementDeleteResource);
+    tool(tool$resourcesManagementGetResourcesForClass);
+    tool(tool$resourcesManagementGetResourcesForCourse);
+    tool(tool$resourcesManagementExportResourceToCommonCartridge);
+    tool(tool$resourcesManagementGetResourcesForUser);
+    tool(tool$usersManagementGetAllUsers);
+    tool(tool$usersManagementCreateUser);
+    tool(tool$usersManagementGetUser);
+    tool(tool$usersManagementUpdateUser);
+    tool(tool$usersManagementDeleteUser);
+    tool(tool$usersManagementGetUserWithDemographics);
+    tool(tool$termsManagementGetAllTerms);
+    tool(tool$termsManagementGetTerm);
+    tool(tool$termsManagementGetGradingPeriodsForTerm);
+    tool(tool$termsManagementCreateGradingPeriodForTerm);
+    tool(tool$teachersManagementGetAllTeachers);
+    tool(tool$teachersManagementGetTeacher);
+    tool(tool$studentsManagementGetAllStudents);
+    tool(tool$studentsManagementGetStudent);
+    tool(tool$organizationsManagementGetAllOrgs);
+    tool(tool$organizationsManagementCreateOrg);
+    tool(tool$organizationsManagementGetOrg);
+    tool(tool$organizationsManagementUpdateOrg);
+    tool(tool$organizationsManagementDeleteOrg);
+    tool(tool$gradingPeriodsManagementGetAllGradingPeriods);
+    tool(tool$gradingPeriodsManagementCreateGradingPeriod);
+    tool(tool$gradingPeriodsManagementGetGradingPeriod);
+    tool(tool$gradingPeriodsManagementUpdateGradingPeriod);
+    tool(tool$gradingPeriodsManagementDeleteGradingPeriod);
+    tool(tool$enrollmentsManagementGetAllEnrollments);
+    tool(tool$enrollmentsManagementCreateEnrollment);
+    tool(tool$enrollmentsManagementGetEnrollment);
+    tool(tool$enrollmentsManagementUpdateEnrollment);
+    tool(tool$enrollmentsManagementDeleteEnrollment);
+    tool(tool$demographicsManagementGetAllDemographics);
+    tool(tool$demographicsManagementPostDemographics);
+    tool(tool$demographicsManagementGetDemographics);
+    tool(tool$demographicsManagementPutDemographics);
+    tool(tool$demographicsManagementDeleteDemographics);
+    tool(tool$coursesManagementGetAllCourses);
+    tool(tool$coursesManagementCreateCourse);
+    tool(tool$coursesManagementGetClassesForCourse);
+    tool(tool$coursesManagementGetCourse);
+    tool(tool$coursesManagementPutCourse);
+    tool(tool$coursesManagementDeleteCourse);
+    tool(tool$coursesManagementCreateComponentResource);
+    tool(tool$coursesManagementGetAllComponentResources);
+    tool(tool$coursesManagementGetComponentResource);
+    tool(tool$coursesManagementPutComponentResource);
+    tool(tool$coursesManagementDeleteComponentResource);
+    tool(tool$coursesManagementCreateCourseComponent);
+    tool(tool$coursesManagementGetAllCourseComponents);
+    tool(tool$coursesManagementGetCourseComponent);
+    tool(tool$coursesManagementPutCourseComponent);
+    tool(tool$coursesManagementDeleteCourseComponent);
+    tool(tool$academicSessionsManagementGetAllAcademicSessions);
+    tool(tool$academicSessionsManagementPostAcademicSession);
+    tool(tool$academicSessionsManagementGetAcademicSession);
+    tool(tool$academicSessionsManagementPutAcademicSession);
+    tool(tool$academicSessionsManagementDeleteAcademicSession);
+
+    return server;
+}

package/src/mcp-server/shared.ts

@@ -0,0 +1,58 @@
+import * as z from 'zod';
+
+import { bytesToBase64 } from '../lib/base64.js';
+
+type BinaryData = Uint8Array | ArrayBuffer | Blob | ReadableStream | Response | string;
+
+export async function consumeStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+    const reader = stream.getReader();
+    const chunks: Uint8Array[] = [];
+
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (value != null) chunks.push(value);
+            if (done) break;
+        }
+    } finally {
+        reader.releaseLock();
+    }
+
+    return new Uint8Array(await new Blob(chunks).arrayBuffer());
+}
+
+export function isAsyncIterable(value: unknown): value is AsyncIterable<string> {
+    return typeof value === 'object' && value != null && Symbol.asyncIterator in value;
+}
+
+export function isBinaryData(value: unknown): value is BinaryData {
+    return (
+        value instanceof Uint8Array ||
+        value instanceof ArrayBuffer ||
+        value instanceof Blob ||
+        value instanceof ReadableStream ||
+        value instanceof Response ||
+        typeof value === 'string'
+    );
+}
+
+const base64Schema = z.string().base64();
+
+export async function valueToBase64(value: BinaryData | null | undefined): Promise<string | null> {
+    if (value == null) {
+        return null;
+    } else if (value instanceof Uint8Array) {
+        return bytesToBase64(value);
+    } else if (value instanceof ArrayBuffer) {
+        return bytesToBase64(new Uint8Array(value));
+    } else if (value instanceof Response || value instanceof Blob) {
+        return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
+    } else if (value instanceof ReadableStream) {
+        return bytesToBase64(await consumeStream(value));
+    } else if (typeof value === 'string') {
+        return base64Schema.parse(value);
+    } else {
+        value satisfies never;
+        throw new Error(`Unsupported image value type: ${typeof value}`);
+    }
+}