School Attendance MCP Server

An MCP (Model Context Protocol) server that provides tools for managing school attendance and interacting with GitHub repositories.

Features

• MCP Protocol Implementation: Custom-built MCP server using NestJS

• GitHub Integration: Tools for committing files and fetching repository information

• Attendance Management: Tool for marking student attendance

• Codex Compatible: Works with Cursor/codex and other MCP clients

Setup

1. Install Dependencies

2. Environment Variables

Create a .env file in the root directory:

Getting a GitHub Token:

1. Go to https://github.com/settings/tokens

2. Generate a new token (classic)

3. Select repo scope (for full repository access)

4. Copy the token to your .env file

3. Running the Server

Development mode:

Production mode:

Start (default):

The server starts on http://localhost:3001 and exposes:

• MCP Endpoint: http://localhost:3001/mcp

• Status Endpoint: http://localhost:3001/mcp/status

Available Tools

1. mark_attendance

Mark attendance for a student with date and status.

Parameters:

• studentId (string): Student ID

• date (string): Date in YYYY-MM-DD format

• status (string): present, absent, or late

Example:

2. commit_changes

Commit files to a GitHub repository.

Parameters:

• repoOwner (string): GitHub username/organization

• repoName (string): Repository name

• branchName (string): Branch name (e.g., main, master)

• commitMessage (string): Commit message

• filesToCommit (array): Array of files with path and content

Example:

3. get_repo_info

Get information about a GitHub repository.

Parameters:

• repoOwner (string): GitHub username/organization

• repoName (string): Repository name

Example:

Connecting to Codex/Cursor

Configuration

Add to ~/.cursor/mcp.json:

Testing Connection

Expected response:

Implementation Details

Architecture

Key Components

1. MCP Controller (src/mcp/mcp.controller.ts):

   • Custom MCP protocol implementation

   • Handles initialize, tools/list, tools/call methods

   • JSON-RPC 2.0 message format

   • CORS enabled for codex connectivity

2. Services (src/services/):

   • attendance.service.ts: Attendance management

   • github.service.ts: GitHub operations using @octokit/rest

3. App Module (src/app.module.ts):

   • Main application module

   • Configures NestJS modules and dependencies

   • Uses @nestjs/config for environment variables

4. Dependencies:

   • @nestjs/core, @nestjs/common: NestJS framework

   • @nestjs/platform-express: Express adapter for NestJS

   • @nestjs/config: Configuration management

   • @octokit/rest: GitHub API SDK

MCP Protocol Methods

The server implements the following MCP protocol methods:

• initialize: Server initialization and capability negotiation

• tools/list: Returns list of available tools with schemas

• tools/call: Executes a tool with provided arguments

Request Format

All requests follow JSON-RPC 2.0 format:

Response Format

All responses follow MCP protocol format:

Testing

See TESTING.md for detailed testing instructions.

Quick test:

Project Structure

Notes

• Built with NestJS framework for better structure and maintainability

• The MCP protocol is implemented manually (no MCP SDK used)

• GitHub operations use @octokit/rest SDK

• Server binds to 0.0.0.0 for external accessibility

• CORS is enabled to allow codex connections

• Uses dependency injection for better testability and modularity