librus-mcp 0.1.0__tar.gz

librus_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint and format check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv pip install -e . --system
+
+      - name: Ruff check
+        run: uvx ruff check src/
+
+      - name: Ruff format check
+        run: uvx ruff format --check src/
+
+      - name: Bandit security check
+        run: uvx bandit -c pyproject.toml -r src/

librus_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/librus-mcp
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

librus_mcp-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.pytest_cache/
+coverage.xml
+
+# mypy / Pyre type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+
+# pyenv
+.python-version
+
+# Secrets
+secrets.json
+
+# IDE settings
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# AI coding assistants
+.claude/              # Claude Code
+.gemini/              # Gemini CLI
+.codex/               # OpenAI Codex CLI
+.cursor/              # Cursor
+.windsurf/            # Windsurf
+.aider*               # Aider
+.continue/            # Continue.dev
+.codeium/             # Codeium
+.copilot/             # GitHub Copilot
+.augment/             # Augment Code
+.junie/               # JetBrains Junie
+
+# Linter / formatter cache
+.ruff_cache/
+
+# Logs
+*.log

librus_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+repos:
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Prevent committing large files (default 500KB)
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      # Prevent committing files with credentials or secrets patterns
+      - id: detect-private-key
+      # Ensure JSON files are valid
+      - id: check-json
+      # Ensure TOML files are valid
+      - id: check-toml
+      # Ensure YAML files are valid
+      - id: check-yaml
+      # Prevent committing directly to main/master
+      - id: no-commit-to-branch
+        args: ['--branch', 'main', '--branch', 'master']
+      # Ensure files end with a newline
+      - id: end-of-file-fixer
+      # Remove trailing whitespace
+      - id: trailing-whitespace
+      # Catch common merge conflict markers
+      - id: check-merge-conflict
+      # Prevent adding symlinks that point nowhere
+      - id: check-symlinks
+
+  # Block secrets from being committed
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: (uv\.lock|\.secrets\.baseline)$
+
+  # Python linting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.11
+    hooks:
+      - id: ruff
+        args: ['--fix']
+      - id: ruff-format
+
+  # Security checks for Python code
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.3
+    hooks:
+      - id: bandit
+        args: ['-c', 'pyproject.toml']
+        additional_dependencies: ['bandit[toml]']

librus_mcp-0.1.0/.secrets.baseline

@@ -0,0 +1,143 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        "(uv\\.lock|\\.secrets\\.baseline|secrets\\.json)$"
+      ]
+    }
+  ],
+  "results": {
+    "secrets.json.template": [
+      {
+        "type": "Secret Keyword",
+        "filename": "secrets.json.template",
+        "hashed_secret": "cf109a70a9c73fd9a8061796eedc0d6a8a1d9add",
+        "is_verified": false,
+        "line_number": 6
+      }
+    ]
+  },
+  "generated_at": "2026-03-10T12:19:41Z"
+}

librus_mcp-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a positive experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal attacks
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, including issues,
+pull requests, and discussions.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainer
+at [contact@datacraze.io](mailto:contact@datacraze.io). All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

librus_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to librus-mcp
+
+Thank you for your interest in contributing! This document provides guidelines to make the process smooth for everyone.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork and set up the development environment:
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/librus-mcp.git
+    cd librus-mcp
+    uv venv && uv pip install -e .
+    ```
+3. Create a branch for your change:
+    ```bash
+    git checkout -b your-branch-name
+    ```
+
+## Development Workflow
+
+### Code Style
+
+The key rules:
+
+- **Safety first:** Validate inputs and outputs with assertions (~2 per function)
+- **Split assertions:** `assert a; assert b` — never `assert a and b`
+- **Functions <= 70 lines**
+- **No abbreviations** in variable names
+- **Comments explain "why"**, not "what"
+- **Lines <= 100 columns**
+
+### Linting and Formatting
+
+Before submitting, ensure your code passes:
+
+```bash
+uvx ruff check src/
+uvx ruff format src/
+```
+
+### Testing
+
+Run the verification script to confirm basic connectivity works:
+
+```bash
+python verify_connection.py
+```
+
+When adding new functionality, ensure you test it manually against a real Librus account.
+
+## Submitting Changes
+
+1. Commit your changes with a clear, descriptive message
+2. Push to your fork
+3. Open a Pull Request against `main`
+4. Describe what your change does and why
+
+### What Makes a Good PR
+
+- **Focused:** One logical change per PR
+- **Documented:** Update README.md if you add/change tools
+- **Linted:** All ruff checks pass with zero warnings
+- **Tested:** You have verified the change works
+
+## Adding a New MCP Tool
+
+See [SPEC.md](SPEC.md) for the step-by-step process of adding a new tool.
+
+## Reporting Bugs
+
+Open a GitHub issue with:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Your Python version and OS
+
+## Security Issues
+
+**Do not open public issues for security vulnerabilities.** See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
+
+## Questions?
+
+Open a GitHub issue or reach out at [contact@datacraze.io](mailto:contact@datacraze.io).

librus_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krzysztof Bury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

librus_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: librus-mcp
+Version: 0.1.0
+Summary: MCP server for Librus Synergia — access grades, messages, attendance, homework, timetables, and announcements from AI assistants
+Project-URL: Homepage, https://github.com/krzysztoofbury/librus-mcp
+Project-URL: Repository, https://github.com/krzysztoofbury/librus-mcp
+Project-URL: Issues, https://github.com/krzysztoofbury/librus-mcp/issues
+Author-email: Krzysztof Bury <contact@datacraze.io>
+License: MIT
+License-File: LICENSE
+Keywords: claude,gemini,gradebook,librus,llm,mcp,synergia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: librus-apix>=0.1.0
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# Librus MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/librus-mcp)](https://pypi.org/project/librus-mcp/)
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that provides AI assistants with access to the **Librus Synergia** electronic gradebook. It supports multiple student accounts simultaneously and exposes tools for grades, messages, attendance, homework, schedules, timetables, and announcements.
+
+## Acknowledgments
+
+This project is built on top of the excellent [**librus-apix**](https://github.com/RustySnek/librus-apix) library by [**RustySnek**](https://github.com/RustySnek). Their work on reverse-engineering and maintaining a Python client for the Librus Synergia platform made this MCP server possible. If you find this project useful, please consider starring their repository as well.
+
+## Quick Start
+
+### 1. Add to your AI assistant
+
+Pick your client. Credentials are passed directly via the `env` block — no files or cloning needed.
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "librus": {
+      "command": "uvx",
+      "args": ["librus-mcp"],
+      "env": {
+        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Via the `/mcp` command or in `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "librus": {
+      "command": "uvx",
+      "args": ["librus-mcp"],
+      "env": {
+        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
+      }
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project-level):
+
+```json
+{
+  "mcpServers": {
+    "librus": {
+      "command": "uvx",
+      "args": ["librus-mcp"],
+      "env": {
+        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
+      }
+    }
+  }
+}
+```
+
+#### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-level):
+
+```toml
+[mcp_servers.librus]
+command = "uvx"
+args = ["librus-mcp"]
+
+[mcp_servers.librus.env]
+LIBRUS_ACCOUNTS = '[{"alias":"daughter","username":"12345","password":"..."}]'
+```
+
+> **Note:** `uvx` automatically downloads and runs the package from PyPI — no cloning or virtual environments needed. You only need [uv](https://github.com/astral-sh/uv) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
+
+### Providing credentials
+
+Each account represents a **parent's login** to Librus Synergia for a specific child. In the Polish school system, parents receive separate Librus login credentials for each of their children. The `alias` is a friendly name you choose to identify which child's data you're accessing. The `username` and `password` are the parent portal credentials you use to log in at [synergia.librus.pl](https://synergia.librus.pl/).
+
+There are three ways to provide credentials (checked in this order):
+
+| Method | Best for | Example |
+|--------|----------|---------|
+| `LIBRUS_ACCOUNTS` env var | `uvx` users, CI | JSON array of account objects (see examples above) |
+| `LIBRUS_CONFIG` env var | Custom file location | Path to your `secrets.json`, e.g. `~/.config/librus/secrets.json` |
+| `secrets.json` in working dir | Local development | Create from `secrets.json.template` |
+
+#### Multiple children
+
+Add multiple accounts to the JSON array:
+
+```
+[{"alias":"daughter","username":"12345","password":"..."},{"alias":"son","username":"67890","password":"..."}]
+```
+
+#### Using a config file with `uvx`
+
+If you prefer a file over inline JSON:
+
+```json
+{
+  "mcpServers": {
+    "librus": {
+      "command": "uvx",
+      "args": ["librus-mcp"],
+      "env": {
+        "LIBRUS_CONFIG": "/Users/you/.config/librus/secrets.json"
+      }
+    }
+  }
+}
+```
+
+### Alternative: Install from source
+
+If you prefer to run from a local clone:
+
+```bash
+git clone https://github.com/krzysztoofbury/librus-mcp.git
+cd librus-mcp
+uv venv && uv pip install -e .
+cp secrets.json.template secrets.json   # Then fill in credentials
+```
+
+Then use the full path in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "librus": {
+      "command": "/path/to/librus-mcp/.venv/bin/librus-mcp"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_students()` | List configured student aliases |
+| `get_grades(student_alias)` | Get grades for a student |
+| `get_messages(student_alias)` | Get received messages |
+| `get_message_content(student_alias, message_id)` | Get the body of a specific message |
+| `get_attendance(student_alias)` | Get attendance records |
+| `get_homework(student_alias)` | Get homework for the next 2 weeks |
+| `get_schedule(student_alias, year, month)` | Get calendar events/exams for a month |
+| `get_timetable(student_alias)` | Get current week's timetable |
+| `get_announcements(student_alias)` | Get school announcements |
+
+## Project Structure
+
+```
+src/
+  server.py          # MCP server with tool definitions and entry point
+  librus_client.py   # Librus API client wrapper with caching and retry
+  config.py          # Configuration loader (reads secrets.json)
+  patches.py         # Runtime patches for librus-apix bugs
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Security
+
+To report vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.