Add MCP server for LLM integration with multi-student support by Copilot · Pull Request #55 · zmoog/classeviva

Copilot · 2025-10-18T07:08:12Z

Overview

This PR implements a Model Context Protocol (MCP) server that enables LLMs like Claude to interact with the Classeviva school portal API. The implementation integrates with the new profiles configuration system, allowing users to manage multiple student credentials through a unified YAML configuration file shared with the CLI.

Changes

Core Implementation

MCP Server (entrypoints/mcp/main.go)

Implements a complete MCP server using the mcp-go library
Provides 4 MCP tools for LLM interaction:
- list_profiles: Lists all configured student profiles
- list_grades: Retrieves grades for a specific profile with optional limit
- list_agenda: Shows homework and events with configurable date ranges
- list_noticeboards: Displays school announcements and circulars
Reuses existing Spaggiari API adapters for reliability
Communicates via stdio following the MCP protocol specification
Integrated with the profiles system (uses YAML-based configuration)

Configuration System Integration

Uses the shared YAML-based profiles configuration (~/.classeviva/config.yaml)
Leverages the adapters/config package with koanf-based configuration loading
Supports multiple student profiles with secure 0600 file permissions
Compatible with CLI profile management commands (classeviva profile add/remove/list)

User Experience

Installation & Setup

Automated installation script (install.sh) that builds and installs the binary
Example YAML configuration file (config.yaml.example) with clear placeholders
Comprehensive user documentation with step-by-step setup instructions
Users can manage profiles using existing CLI commands or manual YAML editing

Documentation

User README: Setup instructions with YAML format, tool descriptions, and example workflows
Development guide: Architecture overview and extension guidelines
Updated main README with MCP server overview and CLI profile commands
Deprecated old JSON format with clear migration instructions

Use Cases

With this MCP server, users can now ask Claude to:

"Compare the grades between my two students and identify areas where each needs support"
"What homework assignments are due this week for both students?"
"Summarize all noticeboard announcements from the past month"
"Show me which subjects each student is excelling in"

Security

CodeQL Analysis: Passed with 0 security alerts
Credential Protection: Passwords stored locally, never exposed to LLM
File Permissions: Configuration file created with 0600 (owner read/write only)
Authentication: Reuses existing identity token management and caching
No Logging: Credentials never logged or included in responses

Testing

All existing tests pass (3 test suites)
Configuration loading verified with profiles system
Server startup tested successfully
Both CLI and MCP server build without errors
Integration with profiles system confirmed
go vet reports no issues

Example Configuration

Users can manage profiles using the CLI:

classeviva profile add student1 --username YOUR_USERNAME --password YOUR_PASSWORD
classeviva profile add student2 --username YOUR_USERNAME --password YOUR_PASSWORD
classeviva profile set-default student1

Or manually create ~/.classeviva/config.yaml:

profiles:
  student1:
    username: "YOUR_CLASSEVIVA_USERNAME"
    password: "YOUR_CLASSEVIVA_PASSWORD"
  student2:
    username: "YOUR_CLASSEVIVA_USERNAME"
    password: "YOUR_CLASSEVIVA_PASSWORD"
default_profile: "student1"

Claude Desktop Integration

To use with Claude Desktop, add to your configuration file:

{
  "mcpServers": {
    "classeviva": {
      "command": "/path/to/classeviva-mcp"
    }
  }
}

Integration with Profiles System

This PR integrates seamlessly with the existing profiles feature:

Shares the same config.yaml configuration file as the CLI
Uses profile names for identification
Compatible with all profile management commands
Provides a consistent configuration experience across all entry points

Fixes #52

Original prompt

This section details on the original issue you should resolve

<issue_title>MCP server</issue_title>
<issue_description>## Context

The classeviva project allows users to interact with the Classeviva application via CLI and a Go.

Goal

Write an MCP server to allow LLMs to perform the following actions:

List students: I have two kids, so the MCP server should start with a list of students allowing the LLM to access grades/agenda/noticeboards for each student. The MCP server should store each student credentials safely to access the Classeviva API.

List student grades

List student agenda

List student noticeboard

Impact

With an MCP server, I can use LLMs like Claude to automate workflow like:

List and analyze grades

Verify the agenda looking for lessons' topics, tests, and homework assignments.

Analyze the noticeboards, download attachments, and summarize their content.</issue_description>

<agent_instructions>Prototype an MCP server that fulfils the goals in the issue description.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes #52

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

zmoog · 2025-10-29T21:59:33Z

@copilot can you rebase on main and sync with the new changes?

Copilot · 2025-10-29T22:18:02Z

@copilot can you rebase on main and sync with the new changes?

I've successfully rebased the MCP server branch on main and updated it to work with the new profiles system (commit 68eeb0f and later).

Key Changes

Integration with Profiles System:

Updated MCP server to use the YAML-based config package from feat: add profiles #61
Changed from students.json to config.yaml format
Renamed list_students to list_profiles and student_id to profile parameter
Now shares the same configuration file as the CLI

What This Means:

Single config file (~/.classeviva/config.yaml) for both CLI and MCP server
Users can manage profiles with classeviva profile add/remove commands
MCP tools now use profile names instead of custom student IDs

The branch is ready but requires a force push since the rebase rewrote history. The changes are in commits 68eeb0f through 50007ab. All tests pass and both binaries build successfully.

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Rebased the branch with main and updated the MCP server implementation to work with the new YAML-based configuration system that was introduced in main. The new config uses profiles instead of students and YAML format instead of JSON. Changes: - Updated MCP server to use config.Load() and new config.Config structure - Changed from Students to Profiles throughout the codebase - Updated tool names: list_students → list_profiles - Changed parameter names: student_id → profile - Updated spaggiari.New() call to include profile name parameter - Updated README.md with new YAML config format and examples - Updated go.mod/go.sum with proper dependencies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

zmoog · 2025-10-30T06:50:03Z

@copilot can you review the PR description to see if it's aligned with the PR content?

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Copilot · 2025-10-30T06:55:20Z

@copilot can you review the PR description to see if it's aligned with the PR content?

I've reviewed and updated the PR to align the documentation with the actual implementation (commit 97bca81).

Issues Found:

Main README still referenced old students.json format instead of config.yaml
Missing config.yaml.example file
Old students.json.example didn't indicate deprecation

Fixed:

Updated main README Quick Start section to show YAML configuration format
Added config.yaml.example with proper YAML profiles structure
Updated students.json.example to clearly indicate it's deprecated with migration instructions
Updated PR description to accurately reflect the profiles-based implementation

The PR now correctly documents that it uses YAML-based profiles configuration shared with the CLI, not the old JSON students format.

zmoog · 2025-10-30T06:51:46Z

+
+### API Authentication
+- Uses existing identity management from Spaggiari adapter
+- Tokens cached in `~/.classeviva/identity.json`


Suggested change

- Tokens cached in `~/.classeviva/identity.json`

- Tokens cached in `~/.classeviva/identity-*.json`

Fixed in commit e93505b. Updated to identity-*.json pattern.

zmoog · 2025-10-30T06:53:19Z

+1. **Configuration file not found**
+   - Ensure `~/.classeviva/students.json` exists
+   - Check file permissions


Suggested change

1. **Configuration file not found**

- Ensure `~/.classeviva/students.json` exists

- Check file permissions

1. **Profiles not found**

- Ensure `~/.classeviva/config.json` exists and contains at least on student

- Check file permissions

Fixed in commit e93505b. Updated to reference config.yaml and corrected the typo "on" → "one".

zmoog · 2025-10-30T06:56:39Z

+2. Create configuration file at `~/.classeviva/config.yaml`:
+   ```yaml
+   profiles:
+     student1:
+       username: "your_username"
+       password: "your_password"
+     student2:
+       username: "your_username"
+       password: "your_password"
+   default_profile: "student1"
+   ```


@copilot we can replace this with the equivalent profiles commands.

Replaced with CLI profile commands in commit e93505b. Now shows how to add profiles using classeviva profile add commands.

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Copilot AI assigned Copilot and zmoog Oct 18, 2025

Copilot started work on behalf of zmoog October 18, 2025 07:08 View session

Copilot AI changed the title ~~[WIP] Add MCP server for student data access~~ Add MCP server for LLM integration with multi-student support Oct 18, 2025

Copilot AI requested a review from zmoog October 18, 2025 07:27

Copilot finished work on behalf of zmoog October 18, 2025 07:27

Copilot started work on behalf of zmoog October 29, 2025 21:59 View session

Copilot AI and others added 5 commits October 30, 2025 06:42

Initial plan

8a93602

Add MCP server implementation with multi-student support

3f288b4

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Add installation script and example config for MCP server

0317dd7

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Add development guide for MCP server

7aa505e

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

zmoog force-pushed the copilot/implement-mcp-server-features branch from de3a147 to df7ba3a Compare October 30, 2025 06:45

Copilot started work on behalf of zmoog October 30, 2025 06:50 View session

Fix PR to align documentation with actual profiles-based implementation

97bca81

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Copilot finished work on behalf of zmoog October 30, 2025 06:56

zmoog reviewed Oct 30, 2025

View reviewed changes

zmoog marked this pull request as ready for review October 30, 2025 06:57

Copilot started work on behalf of zmoog October 30, 2025 06:57 View session

Fix outdated references in documentation to use profiles system

e93505b

Co-authored-by: zmoog <25941+zmoog@users.noreply.github.com>

Copilot AI requested a review from zmoog October 30, 2025 07:02

Copilot finished work on behalf of zmoog October 30, 2025 07:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add MCP server for LLM integration with multi-student support#55

Add MCP server for LLM integration with multi-student support#55
Copilot wants to merge 7 commits intomainfrom
copilot/implement-mcp-server-features

Copilot AI commented Oct 18, 2025 •

edited

Loading

Uh oh!

zmoog commented Oct 29, 2025

Uh oh!

Copilot AI commented Oct 29, 2025

Uh oh!

zmoog commented Oct 30, 2025

Uh oh!

Copilot AI commented Oct 30, 2025

Uh oh!

zmoog Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

zmoog Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

zmoog Oct 30, 2025

Uh oh!

Copilot AI Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Tokens cached in `~/.classeviva/identity.json`
	- Tokens cached in `~/.classeviva/identity-*.json`

Conversation

Copilot AI commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Changes

Core Implementation

User Experience

Use Cases

Security

Testing

Example Configuration

Claude Desktop Integration

Integration with Profiles System

Goal

Impact

Comments on the Issue (you are @copilot in this section)

Uh oh!

zmoog commented Oct 29, 2025

Uh oh!

Copilot AI commented Oct 29, 2025

Key Changes

Uh oh!

zmoog commented Oct 30, 2025

Uh oh!

Copilot AI commented Oct 30, 2025

Uh oh!

zmoog Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

zmoog Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

zmoog Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Oct 18, 2025 •

edited

Loading