sentra-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,18 @@
+name: publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

sentra_mcp-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+.venv/
+dist/
+build/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# Student materials — never commit private PDFs
+OS-Course/**/*.pdf
+OS-Course/**/*.PDF
+
+# Frontend
+landing/node_modules/
+landing/dist/
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

sentra_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

sentra_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mo22zy2
+
+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.

sentra_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: sentra-mcp
+Version: 0.1.0
+Summary: Sentra — local-first MCP server for mock exam generation
+Project-URL: Homepage, https://github.com/mo22zy2/Sentra-MCP
+Project-URL: Issues, https://github.com/mo22zy2/Sentra-MCP/issues
+Author: mo22zy2
+License: MIT
+License-File: LICENSE
+Keywords: education,mcp,mock-exam,opencode,study
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: anyio>=4.9
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic>=2.12
+Requires-Dist: pymupdf>=1.26
+Description-Content-Type: text/markdown
+
+# Sentra — AI-Powered Mock Exam Generator (local-first MCP server)
+
+Sentra is a local-first **MCP server** for university students. It lets you
+generate realistic mock exams from your lecture PDFs and previous exams.
+
+**OpenCode is the AI client, Sentra is the tool it calls.** The MCP server
+does document extraction, validation, analysis prep, and local file
+operations. Your configured AI model (via OpenCode) does the reasoning and
+writes the questions. Model inference costs depend on your chosen provider —
+Sentra itself makes no model calls and costs nothing.
+
+No hosted backend, no cloud database, no file storage, no auth service.
+Everything runs on your machine. Nothing you study is uploaded anywhere
+by Sentra.
+
+Bilingual product site + docs: [`landing/`](landing/) (English / Egyptian Arabic).
+
+## Fastest start: two commands, OpenCode does the rest
+
+Prerequisite (once): install `uv` — Windows: `winget install -e --id astral-sh.uv`,
+macOS/Linux or any Python: `pip install uv`.
+
+```bash
+uvx sentra-mcp init
+```
+
+`init` creates your course folder, adds Sentra to your `opencode.json`
+(backing it up first, never deleting your other settings), and tells you
+where to drop PDFs — in plain words. Then open OpenCode and paste:
+
+```text
+Verify the 5 sentra tools work, then analyze my past exams and summarize the professor's question patterns.
+```
+
+Or skip the terminal entirely: paste this into OpenCode and the agent will
+run the setup for you:
+
+```text
+Install Sentra on this computer: make sure `uv` is installed (install it if missing), then run `uvx sentra-mcp init` to configure OpenCode and create my course folder. Verify the 5 sentra tools are available, then tell me where to drop my lecture PDFs and past exams, in simple words. Never upload my files anywhere.
+```
+
+Then drop lecture PDFs into `lectures/`, past exams into `past_exams/`, and ask:
+
+- "Analyze the previous exams and summarize the professor's question patterns."
+- "Generate a two-hour Operating Systems mock exam with an answer key."
+
+You get `output/<name>_exam.md` + `output/<name>_answers.md`, saved locally.
+
+## Manual install (developers)
+
+Requires: Miniconda/Anaconda, Python 3.11.
+
+```bash
+git clone https://github.com/mo22zy2/Sentra-MCP.git
+cd Sentra-MCP
+conda create -n mcp python=3.11 -y
+conda activate mcp
+pip install uv
+uv sync --python "$CONDA_PREFIX/bin/python"   # Windows: uv sync --python %CONDA_PREFIX%\python.exe
+```
+
+Verify (tested on Python 3.11.17, MCP SDK 2.3.0, PyMuPDF 1.28.2):
+
+```bash
+uv run python -c "from mcp.server import MCPServer; import pymupdf; print('ok')"
+uv run pytest -q               # expect: 30 passed
+```
+
+### OpenCode configuration
+
+1. Install OpenCode per https://opencode.ai/docs and configure any
+   compatible provider/model. That provider bills you if paid.
+2. Copy `opencode.jsonc.example` into your OpenCode config (`opencode.json`),
+   replacing `<ABSOLUTE_PATH_TO_SENTRA_REPO>` and
+   `<ABSOLUTE_PATH_TO_COURSE_FOLDER>` with real absolute paths:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sentra": {
+      "type": "local",
+      "command": ["uvx", "sentra-mcp"],
+      "environment": { "SENTRA_COURSE_DIR": "<ABSOLUTE_PATH_TO_COURSE_FOLDER>" },
+      "enabled": true,
+      "timeout": 30000
+    }
+  }
+}
+```
+
+(`uvx` fetches `sentra-mcp` from PyPI on first run — no clone needed.
+Developers running from source can use
+`["uv", "--directory", "<ABSOLUTE_PATH_TO_SENTRA_REPO>", "run", "sentra"]`
+instead.)
+
+Verified against https://opencode.ai/docs/mcp-servers: `type: "local"`
++ `command[]` array, absolute `--directory`, `environment` for the course dir
+(not secrets), `enabled`, `timeout`. Never put API keys here.
+
+### Course folder
+
+```
+OS-Course/
+├── lectures/     # lecture PDFs (primary content source)
+├── past_exams/   # previous exam PDFs (style evidence)
+└── output/       # generated *_exam.md + *_answers.md (auto-created)
+```
+
+Flat subfolders only — no reorganization needed. Supported format:
+**PDF only** in this version (`.txt`/`.docx` are rejected with a clear error).
+
+## Tools (5, all local)
+
+| Tool | What it does |
+|---|---|
+| `list_course_pdfs` | Lists `lectures/` + `past_exams/` PDFs, reports unreadable files. Never leaves the course dir. |
+| `extract_pdf_text` | Page-preserving text extraction (50 pages / 60k chars per call). Flags scanned PDFs instead of returning silent empties. No OCR. |
+| `analyze_past_exams` | Question types, wording templates, approx difficulty, marks — every finding cites `file:page`. Past patterns only; never claims to predict the real exam. |
+| `prepare_exam_brief` | Validates your exam spec, returns a grounded brief + warnings for unsupported topics. The agent writes the questions. |
+| `save_exam_files` | Validates exam/answer-key separation and saves `output/<name>_exam.md` + `<name>_answers.md`. Refuses silent overwrites. |
+
+`prompts/` holds the 5 agent workflow prompts (extract → knowledge base →
+professor DNA → targets → predicted exam).
+
+## Privacy
+
+- Sentra processes and saves everything on your machine and uploads nothing.
+- If your OpenCode model is cloud-hosted, the content you ask about is sent
+  to that provider — local processing does not guarantee content stays local.
+- Scanned/image PDFs are flagged `insufficient_text: true`. OCR is out of scope.
+
+## Limits & safety
+
+- 50 MB per file; 50 pages / 60 000 chars per `extract_pdf_text` call;
+  12 000-char lecture budget per brief.
+- All paths resolve inside the course dir (`../` escapes rejected).
+- PDFs are treated as untrusted data (never executed). Corrupt/empty PDFs
+  return clear errors. No secrets in logs or config.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Course directory does not exist` | Create it or set `SENTRA_COURSE_DIR` to an existing absolute folder. |
+| `Access denied ... escapes the course directory` | Use `lectures/x.pdf`-style relative paths only. |
+| Tools missing in OpenCode | `opencode mcp list`; check absolute `--directory`; re-run `uv sync`; restart OpenCode; bump `timeout` to 30000. |
+| `... must sum to 100` | Difficulty `{easy,medium,hard}` must total exactly 100. |
+| `Refusing to overwrite` | New `basename` or `overwrite: true`. |
+| `Unsupported file type` | This version reads PDFs only. |
+| `insufficient_text: true` | Scanned PDF — use a text-based export. |
+| `Unknown question types` | Allowed: MCQ, True/False, Short Answer, Essay, Numerical, Comparison, Diagram, Case Study, Application, Analysis, Problem Solving. |
+
+## Tests
+
+```bash
+conda activate mcp
+uv run pytest -q
+```
+
+Covers extraction, empty/corrupt PDFs, page refs, dir validation, traversal
+blocks, input/spec/output validation, key separation, filename collisions,
+`init` config merge + backups, and MCP registration via in-memory `Client(mcp)`.
+Fixtures are synthetic — never commit private materials (see `.gitignore`:
+course PDFs are excluded).
+
+## Contributing
+
+Open an issue or pull request at
+https://github.com/mo22zy2/Sentra-MCP with your OS, Python version, the
+command you ran, and the full error message. Never attach private course
+materials.

sentra_mcp-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Sentra — AI-Powered Mock Exam Generator (local-first MCP server)
+
+Sentra is a local-first **MCP server** for university students. It lets you
+generate realistic mock exams from your lecture PDFs and previous exams.
+
+**OpenCode is the AI client, Sentra is the tool it calls.** The MCP server
+does document extraction, validation, analysis prep, and local file
+operations. Your configured AI model (via OpenCode) does the reasoning and
+writes the questions. Model inference costs depend on your chosen provider —
+Sentra itself makes no model calls and costs nothing.
+
+No hosted backend, no cloud database, no file storage, no auth service.
+Everything runs on your machine. Nothing you study is uploaded anywhere
+by Sentra.
+
+Bilingual product site + docs: [`landing/`](landing/) (English / Egyptian Arabic).
+
+## Fastest start: two commands, OpenCode does the rest
+
+Prerequisite (once): install `uv` — Windows: `winget install -e --id astral-sh.uv`,
+macOS/Linux or any Python: `pip install uv`.
+
+```bash
+uvx sentra-mcp init
+```
+
+`init` creates your course folder, adds Sentra to your `opencode.json`
+(backing it up first, never deleting your other settings), and tells you
+where to drop PDFs — in plain words. Then open OpenCode and paste:
+
+```text
+Verify the 5 sentra tools work, then analyze my past exams and summarize the professor's question patterns.
+```
+
+Or skip the terminal entirely: paste this into OpenCode and the agent will
+run the setup for you:
+
+```text
+Install Sentra on this computer: make sure `uv` is installed (install it if missing), then run `uvx sentra-mcp init` to configure OpenCode and create my course folder. Verify the 5 sentra tools are available, then tell me where to drop my lecture PDFs and past exams, in simple words. Never upload my files anywhere.
+```
+
+Then drop lecture PDFs into `lectures/`, past exams into `past_exams/`, and ask:
+
+- "Analyze the previous exams and summarize the professor's question patterns."
+- "Generate a two-hour Operating Systems mock exam with an answer key."
+
+You get `output/<name>_exam.md` + `output/<name>_answers.md`, saved locally.
+
+## Manual install (developers)
+
+Requires: Miniconda/Anaconda, Python 3.11.
+
+```bash
+git clone https://github.com/mo22zy2/Sentra-MCP.git
+cd Sentra-MCP
+conda create -n mcp python=3.11 -y
+conda activate mcp
+pip install uv
+uv sync --python "$CONDA_PREFIX/bin/python"   # Windows: uv sync --python %CONDA_PREFIX%\python.exe
+```
+
+Verify (tested on Python 3.11.17, MCP SDK 2.3.0, PyMuPDF 1.28.2):
+
+```bash
+uv run python -c "from mcp.server import MCPServer; import pymupdf; print('ok')"
+uv run pytest -q               # expect: 30 passed
+```
+
+### OpenCode configuration
+
+1. Install OpenCode per https://opencode.ai/docs and configure any
+   compatible provider/model. That provider bills you if paid.
+2. Copy `opencode.jsonc.example` into your OpenCode config (`opencode.json`),
+   replacing `<ABSOLUTE_PATH_TO_SENTRA_REPO>` and
+   `<ABSOLUTE_PATH_TO_COURSE_FOLDER>` with real absolute paths:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sentra": {
+      "type": "local",
+      "command": ["uvx", "sentra-mcp"],
+      "environment": { "SENTRA_COURSE_DIR": "<ABSOLUTE_PATH_TO_COURSE_FOLDER>" },
+      "enabled": true,
+      "timeout": 30000
+    }
+  }
+}
+```
+
+(`uvx` fetches `sentra-mcp` from PyPI on first run — no clone needed.
+Developers running from source can use
+`["uv", "--directory", "<ABSOLUTE_PATH_TO_SENTRA_REPO>", "run", "sentra"]`
+instead.)
+
+Verified against https://opencode.ai/docs/mcp-servers: `type: "local"`
++ `command[]` array, absolute `--directory`, `environment` for the course dir
+(not secrets), `enabled`, `timeout`. Never put API keys here.
+
+### Course folder
+
+```
+OS-Course/
+├── lectures/     # lecture PDFs (primary content source)
+├── past_exams/   # previous exam PDFs (style evidence)
+└── output/       # generated *_exam.md + *_answers.md (auto-created)
+```
+
+Flat subfolders only — no reorganization needed. Supported format:
+**PDF only** in this version (`.txt`/`.docx` are rejected with a clear error).
+
+## Tools (5, all local)
+
+| Tool | What it does |
+|---|---|
+| `list_course_pdfs` | Lists `lectures/` + `past_exams/` PDFs, reports unreadable files. Never leaves the course dir. |
+| `extract_pdf_text` | Page-preserving text extraction (50 pages / 60k chars per call). Flags scanned PDFs instead of returning silent empties. No OCR. |
+| `analyze_past_exams` | Question types, wording templates, approx difficulty, marks — every finding cites `file:page`. Past patterns only; never claims to predict the real exam. |
+| `prepare_exam_brief` | Validates your exam spec, returns a grounded brief + warnings for unsupported topics. The agent writes the questions. |
+| `save_exam_files` | Validates exam/answer-key separation and saves `output/<name>_exam.md` + `<name>_answers.md`. Refuses silent overwrites. |
+
+`prompts/` holds the 5 agent workflow prompts (extract → knowledge base →
+professor DNA → targets → predicted exam).
+
+## Privacy
+
+- Sentra processes and saves everything on your machine and uploads nothing.
+- If your OpenCode model is cloud-hosted, the content you ask about is sent
+  to that provider — local processing does not guarantee content stays local.
+- Scanned/image PDFs are flagged `insufficient_text: true`. OCR is out of scope.
+
+## Limits & safety
+
+- 50 MB per file; 50 pages / 60 000 chars per `extract_pdf_text` call;
+  12 000-char lecture budget per brief.
+- All paths resolve inside the course dir (`../` escapes rejected).
+- PDFs are treated as untrusted data (never executed). Corrupt/empty PDFs
+  return clear errors. No secrets in logs or config.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Course directory does not exist` | Create it or set `SENTRA_COURSE_DIR` to an existing absolute folder. |
+| `Access denied ... escapes the course directory` | Use `lectures/x.pdf`-style relative paths only. |
+| Tools missing in OpenCode | `opencode mcp list`; check absolute `--directory`; re-run `uv sync`; restart OpenCode; bump `timeout` to 30000. |
+| `... must sum to 100` | Difficulty `{easy,medium,hard}` must total exactly 100. |
+| `Refusing to overwrite` | New `basename` or `overwrite: true`. |
+| `Unsupported file type` | This version reads PDFs only. |
+| `insufficient_text: true` | Scanned PDF — use a text-based export. |
+| `Unknown question types` | Allowed: MCQ, True/False, Short Answer, Essay, Numerical, Comparison, Diagram, Case Study, Application, Analysis, Problem Solving. |
+
+## Tests
+
+```bash
+conda activate mcp
+uv run pytest -q
+```
+
+Covers extraction, empty/corrupt PDFs, page refs, dir validation, traversal
+blocks, input/spec/output validation, key separation, filename collisions,
+`init` config merge + backups, and MCP registration via in-memory `Client(mcp)`.
+Fixtures are synthetic — never commit private materials (see `.gitignore`:
+course PDFs are excluded).
+
+## Contributing
+
+Open an issue or pull request at
+https://github.com/mo22zy2/Sentra-MCP with your OS, Python version, the
+command you ran, and the full error message. Never attach private course
+materials.

sentra_mcp-0.1.0/landing/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

sentra_mcp-0.1.0/landing/README.md

@@ -0,0 +1,24 @@
+# Sentra landing page (public site, not the exam app)
+
+Bilingual (EN / Egyptian Arabic) product + docs site for the Sentra MCP server.
+Lives in `landing/` so the Python MCP project at the repo root stays untouched.
+
+## Run
+
+```bash
+cd landing
+npm install
+npm run dev      # local preview
+npm run build    # production build → dist/
+```
+
+## Notes
+
+- `src/config.ts` — `GITHUB_URL` is the single source of truth for the repo
+  link (currently `https://github.com/mo22zy2/Sentra-MCP`). The bootstrap
+  prompt (`BOOTSTRAP_PROMPT`) injects it automatically. Never hardcode the
+  URL elsewhere.
+- Install commands and the OpenCode JSON mirror the root `README.md` and
+  `opencode.jsonc.example` verbatim. If those change, update `src/config.ts`.
+- Stack: React + TypeScript + Tailwind v4 (`@tailwindcss/vite`) + motion +
+  lucide-react. No router (anchor navigation, single page).

sentra_mcp-0.1.0/landing/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Sentra — Study smarter. Practice with purpose.</title>
+    <meta
+      name="description"
+      content="Sentra is a local-first MCP server that turns your lecture PDFs and previous exams into focused mock exams through AI agents like OpenCode."
+    />
+    <meta property="og:title" content="Sentra — Study smarter. Practice with purpose." />
+    <meta
+      property="og:description"
+      content="Turn lecture PDFs and past exams into focused practice with a local-first MCP server built for AI-powered studying."
+    />
+    <meta property="og:type" content="website" />
+    <meta name="twitter:card" content="summary" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>