D2L Brightspace MCP Server

Instructions

Implementation Reference

• src/tools/grades.ts:21-25 (handler)

  The handler function that executes the get_my_grades tool logic: resolves orgUnitId, fetches raw grades using the D2L client, marshals them to a friendly format, and returns as formatted JSON string.

  handler: async (args: { orgUnitId?: number }): Promise<string> => {
    const orgUnitId = getOrgUnitId(args.orgUnitId);
    const grades = await client.getMyGradeValues(orgUnitId) as RawGrade[];
    return JSON.stringify(marshalGrades(grades), null, 2);
  },

• src/tools/grades.ts:18-20 (schema)

  Zod schema defining the optional orgUnitId input parameter for the tool.

  schema: {
    orgUnitId: z.number().optional().describe('The course ID. Optional if D2L_COURSE_ID env var is set.'),
  },

• src/index.ts:103-111 (registration)

  Registers the get_my_grades tool with the MCP server, providing name, description, schema, and a wrapper handler that formats the response as MCP content.

  server.tool(
    'get_my_grades',
    gradeTools.get_my_grades.description,
    { orgUnitId: gradeTools.get_my_grades.schema.orgUnitId },
    async (args) => {
      const result = await gradeTools.get_my_grades.handler(args as { orgUnitId?: number });
      return { content: [{ type: 'text', text: result }] };
    }
  );

• src/tools/grades.ts:7-13 (helper)

  Helper function to determine the course orgUnitId from the input argument or the D2L_COURSE_ID environment variable.

  function getOrgUnitId(provided?: number): number {
    const orgUnitId = provided ?? DEFAULT_COURSE_ID;
    if (!orgUnitId) {
      throw new Error('orgUnitId is required. Either provide it or set D2L_COURSE_ID environment variable.');
    }
    return orgUnitId;
  }

• src/utils/marshal.ts:87-97 (helper)

  Helper utility that transforms raw grades from the D2L API into a structured, LLM-friendly format including name, score (points earned/possible), percentage, feedback, and formatted last modified date.

  export function marshalGrades(grades: RawGrade[]): MarshalledGrade[] {
    return grades.map((g) => removeEmpty({
      name: g.GradeObjectName,
      score: g.PointsNumerator !== null && g.PointsDenominator !== null
        ? `${g.PointsNumerator}/${g.PointsDenominator}`
        : null,
      percentage: g.DisplayedGrade?.trim() || null,
      feedback: g.Comments?.Text?.trim() || null,
      lastModified: formatDate(g.LastModified),
    })) as MarshalledGrade[];
  }