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:
- Go to https://github.com/settings/tokens
- Generate a new token (classic)
- Select
reposcope (for full repository access) - Copy the token to your
.envfile
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 IDdate(string): Date in YYYY-MM-DD formatstatus(string):present,absent, orlate
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/organizationrepoName(string): Repository namebranchName(string): Branch name (e.g.,main,master)commitMessage(string): Commit messagefilesToCommit(array): Array of files withpathandcontent
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/organizationrepoName(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
-
MCP Controller (
src/mcp/mcp.controller.ts):- Custom MCP protocol implementation
- Handles
initialize,tools/list,tools/callmethods - JSON-RPC 2.0 message format
- CORS enabled for codex connectivity
-
Services (
src/services/):attendance.service.ts: Attendance managementgithub.service.ts: GitHub operations using@octokit/rest
-
App Module (
src/app.module.ts):- Main application module
- Configures NestJS modules and dependencies
- Uses
@nestjs/configfor environment variables
-
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 negotiationtools/list: Returns list of available tools with schemastools/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/restSDK - Server binds to
0.0.0.0for external accessibility - CORS is enabled to allow codex connections
- Uses dependency injection for better testability and modularity