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

npm install

2. Environment Variables

Create a .env file in the root directory:

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

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:

npm run start:dev

Production mode:

npm run build
npm run start:prod

Start (default):

npm run start

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:

{
  "name": "mark_attendance",
  "arguments": {
    "studentId": "12345",
    "date": "2024-01-15",
    "status": "present"
  }
}

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:

{
  "name": "commit_changes",
  "arguments": {
    "repoOwner": "username",
    "repoName": "my-repo",
    "branchName": "main",
    "commitMessage": "Add new file",
    "filesToCommit": [
      {
        "path": "test.txt",
        "content": "Hello World"
      }
    ]
  }
}

3. get_repo_info

Get information about a GitHub repository.

Parameters:

• repoOwner (string): GitHub username/organization
• repoName (string): Repository name

Example:

{
  "name": "get_repo_info",
  "arguments": {
    "repoOwner": "username",
    "repoName": "my-repo"
  }
}

Connecting to Codex/Cursor

Configuration

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "school-attendance-mcp": {
      "url": "http://localhost:3001/mcp",
      "requestInit": {
        "headers": {
          "Content-Type": "application/json"
        }
      }
    }
  }
}

Testing Connection

curl http://localhost:3001/mcp/status

Expected response:

{
  "status": "OK",
  "tools": [
    "mark_attendance",
    "commit_changes",
    "get_repo_info",
    "create_branch",
    "list_branches",
    "get_file_contents",
    "list_commits"
  ]
}

Implementation Details

Architecture

Codex/Cursor
    ↓
MCP Protocol (JSON-RPC over HTTP)
    ↓
NestJS Application
    ↓
MCP Controller → Services (Attendance, GitHub)
    ↓
GitHub API (via @octokit/rest SDK)

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:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { ... }
  },
  "id": 1
}

Response Format

All responses follow MCP protocol format:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Result message"
      }
    ]
  },
  "id": 1
}

Testing

See TESTING.md for detailed testing instructions.

Quick test:

# Check server status
curl http://localhost:3001/mcp/status

# List tools
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Project Structure

school-attendance-mcp/
├── src/
│   ├── main.ts                # Application entry point
│   ├── app.module.ts          # Root application module
│   ├── mcp/
│   │   └── mcp.controller.ts  # MCP protocol controller
│   └── services/
│       ├── attendance.service.ts # Attendance service
│       └── github.service.ts     # GitHub service
├── .env                       # Environment variables
├── nest-cli.json              # NestJS CLI configuration
├── tsconfig.json              # TypeScript configuration
├── package.json               # Dependencies
├── README.md                  # This file
└── TESTING.md                 # Testing guide

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