# 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