School Attendance MCP Server

考勤MCP服务器

MCP（模型上下文协议）服务器，提供管理出勤和与GitHub存储库交互的工具。

特性

• MCP协议实现：使用NestJS定制MCP服务器
• GitHub集成：用于提交文件和获取存储库信息的工具
• 考勤管理：标记学生出勤率的工具
• Codex兼容：适用于Cursor/codex和其他MCP客户端

设置

1.安装依赖项

npm install

2.环境变量

创建一个 .env 根目录中的文件：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

获取GitHub代币：

1. 首选https://github.com/settings/tokens
2. 生成新令牌（经典）
3. 选择 repo 范围（用于完全访问存储库）
4. 将令牌复制到您的 .env 文件

3.运行服务器

开发模式：

npm run start:dev

生产方式：

npm run build
npm run start:prod

启动（默认）：

npm run start

服务器启动于 http://localhost:3001 并暴露：

• MCP端点: http://localhost:3001/mcp
• 状态端点: http://localhost:3001/mcp/status

可用工具

1. mark_attendance

用日期和状态标记学生的出勤情况。

参数：

• studentId （string）：学生ID
• date （字符串）：YYYY-MM-DD格式的日期
• status （字符串）： present, absent，或 late

例子：

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

2. commit_changes

将文件提交到GitHub存储库。

参数：

• repoOwner （string）：GitHub用户名/组织
• repoName （string）：存储库名称
• branchName （string）：分支名称（例如。， main, master)
• commitMessage （string）：提交消息
• filesToCommit （array）：包含以下内容的文件数组 path 和 content

例子：

{
  "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

获取有关GitHub存储库的信息。

参数：

• repoOwner （string）：GitHub用户名/组织
• repoName （string）：存储库名称

例子：

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

连接到Codex/Cursor

配置

增添 ~/.cursor/mcp.json:

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

测试连接

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

预期响应：

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

实现细节

建筑

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

关键组件

1. MCP控制器 (src/mcp/mcp.controller.ts):

- 自定义MCP协议实现 - 手柄 initialize, tools/list, tools/call 方法 - JSON-RPC 2.0消息格式 - 为codex连接启用CORS

1. 服务 (src/services/):

- attendance.service.ts：考勤管理 - github.service.ts：GitHub操作使用 @octokit/rest

1. 应用模块 (src/app.module.ts):

- 主要应用模块 - 配置NestJS模块和依赖关系 - 用途 @nestjs/config 对于环境变量

1. 依赖项:

- @nestjs/core, @nestjs/common：NestJS框架 - @nestjs/platform-express：NestJS的快速适配器 - @nestjs/config：配置管理 - @octokit/rest：GitHub API SDK

MCP协议方法

服务器实现以下MCP协议方法：

• initialize：服务器初始化和能力协商
• tools/list：返回具有模式的可用工具列表
• tools/call：使用提供的参数执行工具

请求格式

所有请求均遵循JSON-RPC 2.0格式：

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

响应格式

所有响应均遵循MCP协议格式：

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

测试

看 测试.md 详细的测试说明。

快速测试：

# 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}'

项目结构

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

备注

• 采用NestJS框架构建，具有更好的结构和可维护性
• MCP协议是手动实现的（未使用MCP SDK）
• GitHub操作使用 @octokit/rest 软件开发工具包
• 服务器绑定到 0.0.0.0 外部可访问性
• CORS已启用以允许codex连接
• 使用依赖注入实现更好的可测试性和模块化