README.md•6.39 kB
# 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
```bash
npm install
```
### 2. Environment Variables
Create a `.env` file in the root directory:
```bash
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:**
```bash
npm run start:dev
```
**Production mode:**
```bash
npm run build
npm run start:prod
```
**Start (default):**
```bash
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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"name": "get_repo_info",
"arguments": {
"repoOwner": "username",
"repoName": "my-repo"
}
}
```
## Connecting to Codex/Cursor
### Configuration
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"school-attendance-mcp": {
"url": "http://localhost:3001/mcp",
"requestInit": {
"headers": {
"Content-Type": "application/json"
}
}
}
}
}
```
### Testing Connection
```bash
curl http://localhost:3001/mcp/status
```
Expected response:
```json
{
"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:
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": { ... }
},
"id": 1
}
```
### Response Format
All responses follow MCP protocol format:
```json
{
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "Result message"
}
]
},
"id": 1
}
```
## Testing
See [TESTING.md](./TESTING.md) for detailed testing instructions.
Quick test:
```bash
# 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