🎯 SkillOps MCP

AI-powered operations automation for EdTech teams. Five Model Context Protocol tools that turn hours of repetitive weekly busywork — support triage, re-engagement outreach, feedback analysis, progress reporting, and course design — into a single sentence typed into any MCP client.

📑 Table of Contents

1. What is SkillOps MCP?

2. What is MCP? (60-second primer)

3. The five tools

4. Architecture

5. How a request flows (step by step)

6. Tech stack

7. Project structure

8. Prerequisites

9. Installation

10. Getting your free Gemini API key

11. Configuration

12. How to use it — three ways

13. Tool reference (inputs, prompts, outputs)

14. Error handling

15. Testing

16. Engineering highlights

17. Extending it — add your own tool

18. Troubleshooting

19. FAQ

20. Why I built this

21. License

Related MCP server: Educhain MCP Server

🧭 What is SkillOps MCP?

EdTech operations, growth, and product teams spend hours every week on repetitive, judgment-light work:

• 📨 Reading and categorizing every incoming support ticket

• ✍️ Hand-writing re-engagement emails for students who went quiet

• 🔍 Skimming hundreds of feedback comments to find what to fix

• 📊 Assembling the weekly cohort progress report

• 🗂️ Drafting course outlines from a blank page

It's necessary work, but it scales linearly with headcount and quietly burns people out.

SkillOps MCP turns each of those into a single command. It's a server that exposes five purpose-built tools to any MCP client (Claude Desktop, Claude Code, or others). A support lead pastes a ticket and gets an instant triage with a ready-to-send reply. A growth manager generates a personalized win-back message in seconds. A product manager drops in a batch of feedback and gets a structured, prioritized analysis.

The design principle is "deterministic work in code, language work in the model." Anything that must be correct — cohort averages, at-risk thresholds, CSV parsing, input validation — is computed in plain Python so the numbers are never hallucinated. Only the genuinely language-shaped work (writing, classifying, summarizing) is delegated to the LLM. That LLM is Google's Gemini, running free on gemini-2.5-flash via the Google AI Studio free tier — no credit card required.

🔌 What is MCP? (60-second primer)

The Model Context Protocol (MCP) is an open standard (created by Anthropic) that lets AI assistants call external tools in a uniform way — think of it as "USB-C for AI tools." Instead of every app inventing its own plugin format, a single MCP server exposes tools that any MCP client can discover and call.

   You ──talk──▶  MCP CLIENT  ──MCP protocol──▶  MCP SERVER  ──▶  your code
 (English)      (Claude Desktop,   (JSON-RPC over     (this project)
                 Claude Code…)       stdio)

• You type plain English into the client.

• The client (an AI assistant) decides which tool to call and with what arguments.

• The server (this project) runs the tool and returns a result.

You never speak the protocol yourself — the client translates your English into a tool call for you. SkillOps MCP is the server half: it provides the five EdTech tools; you bring any MCP client to drive them.

🛠️ The five tools

Full input/output details for each are in the Tool reference.

🏗️ Architecture

SkillOps MCP is built in clean, testable layers. Each layer has one job and is independently verifiable.

┌──────────────────────────────────────────────────────────────────┐
│  MCP CLIENT   (Claude Desktop · Claude Code · any MCP client)     │
│  You type plain English here. The client picks the tool + args.   │
└───────────────────────────────┬──────────────────────────────────┘
                                 │  MCP protocol (JSON-RPC over stdio)
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│  SERVER LAYER     src/skillops_mcp/server.py                      │
│  • FastMCP app, name = "SkillOps MCP"                             │
│  • 5 thin @mcp.tool adapters (docstrings become tool descriptions)│
│  • Loads .env, configures stderr logging, then mcp.run()          │
└───────────────────────────────┬──────────────────────────────────┘
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│  TOOL LAYER       src/skillops_mcp/tools/*.py                     │
│  Each tool: validate input → build prompt → call model → format   │
│  • support · outreach · feedback · reports · curriculum           │
│  • reports.py computes all metrics in PURE PYTHON (no LLM math)   │
└──────────────┬───────────────────────────────┬───────────────────┘
               ▼                                ▼
┌──────────────────────────┐    ┌──────────────────────────────────┐
│  MODELS    models/        │    │  UTILS    utils/                 │
│  schemas.py               │    │  gemini_client.py — API wrapper  │
│  Pydantic v2 input models │    │    (retries, JSON mode, logging) │
│  + enums (urgency, etc.)  │    │  formatters.py — text rendering  │
└──────────────────────────┘    └───────────────┬──────────────────┘
                                                 │  Google Gemini API (free tier)
                                                 ▼
                                          gemini-2.5-flash

Layer responsibilities

Key design choices

• 🧮 Numbers are computed, not generated. In batch_generate_reports, averages, at-risk lists, top performers, and assignment rates are calculated in Python. The model only writes the narrative around those facts — so a report can never invent a statistic.

• 🛡️ Validation before spend. Pydantic rejects bad input before a single token is sent, saving API calls and returning precise error messages.

• 🗄️ No database. Everything is in-memory; reports read from inline data or a CSV path. Zero infrastructure to run.

• 🔁 One client, one retry policy. Every tool calls the same GeminiClient, so resilience and logging are uniform.

🔄 How a request flows (step by step)

Take "Triage this ticket: 'I paid but can't open the videos!'"

1. You type that into your MCP client (e.g. Claude Code).

2. The client recognizes it matches the triage_support_query tool and calls the server over stdio with { "query": "I paid but can't open the videos!" }.

3. server.py receives the call and forwards it to tools/support.py.

4. support.py validates the input with the SupportQueryInput Pydantic model. (Blank/empty → instant Error: string, no API call.)

5. It builds a system + user prompt and calls GeminiClient.call_json(...).

6. gemini_client.py sends the request to Gemini in JSON mode, retrying on rate limits / server errors, and parses the JSON reply into a dict.

7. support.py formats that dict into the readable triage report via formatters.py.

8. The string travels back through the server → client → and appears in your chat.

Total time: a couple of seconds. Total cost on the free tier: $0.

🧰 Tech stack

📁 Project structure

skillops-mcp/
├── src/
│   └── skillops_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP entry point — registers all 5 tools
│       ├── tools/
│       │   ├── support.py         # triage_support_query
│       │   ├── outreach.py        # generate_reengagement_message
│       │   ├── feedback.py        # analyze_course_feedback
│       │   ├── reports.py         # batch_generate_reports (Python metrics + narrative)
│       │   └── curriculum.py      # create_course_outline
│       ├── models/
│       │   └── schemas.py         # Pydantic v2 input models + enums
│       └── utils/
│           ├── gemini_client.py   # Gemini API wrapper: retries, JSON mode, logging
│           └── formatters.py      # Plain-text output rendering helpers
├── tests/
│   ├── conftest.py                # mock_client fixture; API-key isolation
│   ├── test_support.py
│   ├── test_outreach.py
│   ├── test_feedback.py
│   ├── test_reports.py
│   └── test_curriculum.py
├── examples/
│   ├── sample_feedback.json       # 10 feedback strings for the feedback tool
│   ├── sample_students.csv        # 7 student rows for the reports tool
│   └── sample_queries.txt         # 3 support tickets for the triage tool
├── demo.py                        # interactive terminal demo (no MCP client needed)
├── .mcp.json                      # MCP client config (Claude Code auto-detects it)
├── .env.example                   # copy to .env and add your free Gemini key
├── .gitignore                     # ignores .env (your secret stays local)
├── pyproject.toml                 # package metadata + `skillops-mcp` entry point
├── requirements.txt               # runtime dependencies
├── requirements-dev.txt           # + pytest
└── README.md

✅ Prerequisites

• Python 3.11 or newer (python --version)

• pip

• A free Google Gemini API key (how to get one)

• (Optional) An MCP client — Claude Code or Claude Desktop — to use the tools conversationally. You can also try everything with the bundled demo.py and no client at all.

📦 Installation

# 1. Clone
git clone https://github.com/<your-username>/skillops-mcp.git
cd skillops-mcp

# 2. (Recommended) create a virtual environment
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate

# 3. Install the package (editable) — this also installs all dependencies
pip install -e .
#    For development/tests, also: pip install -r requirements-dev.txt

# 4. Configure your free Gemini key
cp .env.example .env
#    then open .env and set GEMINI_API_KEY=...

# 5. Smoke-test it (no API call, fully offline)
pytest

pip install -e . registers the package so it's importable from anywhere and creates a skillops-mcp console command. (You can also pip install -r requirements.txt if you prefer not to install the package itself.)

🔑 Getting your free Gemini API key

The default engine is Gemini's free tier — no credit card, no UPI, no billing of any kind.

1. Go to https://aistudio.google.com/apikey

2. Sign in with any Google account

3. Click Create API key → choose "Create API key in a new project" (Google makes the free project for you)

4. Copy the key (looks like AIzaSy...)

5. Paste it into your .env:

   GEMINI_API_KEY=AIzaSy...your-key...

Free-tier note: Google AI Studio's free tier has generous per-minute/day rate limits — plenty for personal use and demos — and (on the free tier) Google may use prompts to improve its products. For production traffic, enable paid usage in Google Cloud.

⚙️ Configuration

All configuration is via environment variables (loaded from .env):

The server loads .env from the project root regardless of the directory it's launched from, so MCP clients can start it from anywhere.

🚀 How to use it — three ways

Way 1 — Quick demo in the terminal (no MCP client needed)

The fastest way to see all five tools working:

python demo.py

This opens a friendly menu that calls the same tool functions an MCP client would, and prints the output. Great for a first look or a screen-share. (Requires GEMINI_API_KEY in .env.)

Way 2 — Inside Claude Code (recommended for daily use)

Claude Code auto-detects the committed .mcp.json:

{
  "mcpServers": {
    "skillops": {
      "command": "python",
      "args": ["-m", "skillops_mcp.server"]
    }
  }
}

1. Make sure you ran pip install -e . (so python -m skillops_mcp.server resolves).

2. Reload the editor window so Claude Code re-reads .mcp.json.

3. Type /mcp — you should see skillops with its 5 tools. Approve/trust it if prompted.

4. Now just chat in plain English:

   "Use the skillops tools to triage this ticket: 'I paid but can't open the videos!'"

Way 3 — Inside Claude Desktop

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "skillops": {
      "command": "python",
      "args": ["-m", "skillops_mcp.server"],
      "env": {
        "GEMINI_API_KEY": "your-free-gemini-key-here"
      }
    }
  }
}

Restart Claude Desktop. The five tools appear and you talk to them in plain English.

WSL note: if your Python lives in WSL but Claude Desktop runs on Windows, set "command": "wsl" and "args": ["python", "-m", "skillops_mcp.server"].

📚 Tool reference

Each tool returns a clean, human-readable string (with a 📋 RAW JSON appendix for power users). You can call them by describing what you want — the client maps your words to the right tool and arguments.

1. triage_support_query

Analyze a student support message and return a structured triage.

You type:

Triage this ticket: "I paid but can't open the videos, it's been 2 days!"

You get back (real output):

✅ SUPPORT TRIAGE COMPLETE
──────────────────────────────────────────────────
Category: technical_issue
Urgency: high — Student has paid but is fully blocked from content for two days.
Escalate to Human: Yes — Payment + access issues need a human to check backend systems.
Estimated Resolution: 1-2 business days
Tags: access_issue, payment_verification, video_access, content_lock

📧 SUGGESTED RESPONSE:
"Dear Student, I'm very sorry to hear you're having trouble accessing the course
videos despite having paid, especially after two days. Our team is actively
investigating to get you access as quickly as possible, and we'll reach out
shortly with an update. Thank you for your patience."

Output fields: category (one of technical_issue, billing, course_content, mentor_support, certificate, refund, general), urgency (critical/high/medium/low), urgency_reason, suggested_response, escalate_to_human, escalation_reason, estimated_resolution_time, tags.

2. generate_reengagement_message

Write a personalized win-back message for an inactive student.

You type:

Generate a re-engagement message for Priya — 12 days inactive in Web Development, last finished "CSS Basics", 45% complete. Channel: both.

You get back (illustrative):

💬 RE-ENGAGEMENT MESSAGE READY
──────────────────────────────────────────────────

📧 EMAIL
Subject: You're closer than you think, Priya 🚀

Hi Priya, you crushed CSS Basics and you're already 45% through Web Development —
real momentum, still right where you left it. The next module is where the fun
starts. It takes ~20 minutes to get back in the flow. Want to pick up where you
stopped?  → Resume Module 6: JavaScript Foundations

📱 WHATSAPP
Hey Priya! 👋 You're 45% through Web Dev and CSS Basics is behind you. The next
module is a fun one — jump back in? Takes ~20 mins 🚀

🎯 PERSONALIZATION HOOKS:
  • Referenced her 45% progress
  • Named her last completed module (CSS Basics)
  • Lowered the barrier with a "20 minutes" framing

⏰ Recommended send time: Tuesday 10am or Thursday 6pm

3. analyze_course_feedback

Analyze a batch of raw feedback in a single model call (not one per item).

You type:

Analyze this feedback for Python Basics: [paste the 10 lines from examples/sample_feedback.json]

You get back (illustrative):

📊 COURSE FEEDBACK ANALYSIS
──────────────────────────────────────────────────
Items analyzed: 10
Overall sentiment: positive (score: 0.45)
Breakdown: 👍 6 | 😐 1 | 👎 3

🧵 TOP THEMES:
  • Video length & pacing (×3, negative) — "Videos are too long…"
  • Mentor support (×2, positive) — "got a response within hours"

❗ KEY COMPLAINTS:  • Videos too long  • Need more practice problems
🌟 KEY PRAISES:     • Clear instruction  • Real career outcomes
🛠️  IMPROVEMENT SUGGESTIONS:
  • [high / medium] Split long videos into 5–8 min segments
  • [high / low] Add a solutions bank for practice problems

📝 EXECUTIVE SUMMARY:
Net-positive sentiment driven by instruction and mentor support; clearest win is
shorter videos and more solved practice problems.

4. batch_generate_reports

Generate a weekly cohort report. Metrics are computed in Python; only the narrative comes from the model.

CSV columns: name, course, completion_pct, last_active_days_ago, quiz_avg_score, assignments_submitted, total_assignments (missing columns are reported clearly; a sample is in examples/sample_students.csv).

You type:

Generate this week's report from examples/sample_students.csv for the "Spring Cohort", week "Jun 16–22, 2026".

You get back (illustrative):

📈 Spring Cohort — Weekly Progress Report
──────────────────────────────────────────────────
Cohort: Spring Cohort | Week: Jun 16–22, 2026 | Students: 7

📊 COHORT METRICS
  Average completion:     58.4%      ← computed in Python
  Average quiz score:     68.9
  Assignment completion:  57.1%
  At-risk students:       3
  Top performers:         2

✅ RECOMMENDED ACTIONS:
  • [urgent] Personal outreach to Divya Patel (25 days inactive) — Success Team
  • [this_week] Nudge sequence for Sneha & Priya — Growth

At-risk = inactive > 7 days or completion < 30%. Top performer = completion > 80% and quiz avg > 75. These thresholds are pure Python — never the model's guess.

5. create_course_outline

Generate a complete, structured course outline.

You type:

Outline an 8-week beginner course on "Intro to SQL", 5 hrs/week, self-paced, with projects.

You get back (illustrative):

🎓 Intro to SQL: Query Real Data with Confidence
──────────────────────────────────────────────────
⏱️  Total: ~40.0 hours

🏆 LEARNING OUTCOMES:
  • Write SELECT queries with filtering, sorting, and joins
  • Model a small relational database from scratch
  • Aggregate and report on real datasets

📚 MODULES:
  Module 1: SQL Foundations  (5.0h)
      1. [video] What is a Database? (15 min)
      2. [exercise] Your First SELECT (40 min)
      ⚙️  Project: Query a movie database
      ✅ Module quiz included
  ...
🚀 FINAL PROJECT: Build & query an e-commerce schema end-to-end

🛡️ Error handling

Every tool returns a clean Error: … string instead of crashing the server. The cases handled:

Validation runs before any API call, so bad input fails instantly and for free.

🧪 Testing

The suite is fully offline — every Gemini call is mocked, so no API key and no network are needed, and it costs nothing.

pip install -r requirements-dev.txt
pytest                 # 22 tests
pytest -v              # verbose
pytest tests/test_reports.py   # one file

Each tool is tested for: a valid call (mocked model response), invalid/empty input, and the missing-API-key path. reports.py additionally has tests proving the Python-computed metrics are correct and that CSV errors are handled.

tests/test_curriculum.py .....   tests/test_reports.py  ......
tests/test_feedback.py    ....   tests/test_support.py  ...
tests/test_outreach.py    ....   ===== 22 passed =====

💎 Engineering highlights

For reviewers, the parts worth a look:

• Deterministic-vs-generative split. tools/reports.py computes every statistic in Python and hands the model only the facts — a report can't hallucinate a number. This is the project's core design idea.

• Resilient API client. utils/gemini_client.py retries only what's worth retrying (429 + 5xx) with exponential backoff, fails fast on 4xx, uses Gemini's native JSON mode, and logs every call structurally.

• Validation as a first-class layer. models/schemas.py (Pydantic v2) enforces every contract before spend; errors are turned into friendly strings, never stack traces.

• Provider-swappable by design. The entire LLM dependency lives behind one small client class — the project started on Anthropic Claude and moved to free Gemini by changing one file.

• Stdio-safe logging. Logs go to stderr so they never corrupt the MCP stdout transport — a subtle but real correctness requirement for MCP servers.

• Tested, typed, documented. Type hints and docstrings on every function; 22 offline tests; no bare except; no print; no hardcoded secrets.

🧩 Extending it — add your own tool

Adding a sixth tool takes three steps:

1. Define the input model in models/schemas.py:

   class MyToolInput(BaseModel):
       text: str = Field(..., min_length=1)

2. Write the tool in tools/mytool.py following the standard shape:

   def run(text: str, client: GeminiClient | None = None) -> str:
       try:
           params = MyToolInput(text=text)
       except ValidationError as exc:
           return f"Error: {fmt.validation_message(exc)}"
       try:
           client = client or GeminiClient()
       except MissingAPIKeyError as exc:
           return f"Error: {exc}"
       data = client.call_json(SYSTEM_PROMPT, user_prompt, tool_name="my_tool")
       return _format_output(data)

3. Register it in server.py:

   @mcp.tool
   def my_tool(text: str) -> str:
       """One-line description the AI will read to decide when to call this."""
       return mytool.run(text=text)

Add a tests/test_mytool.py mirroring the existing tests and you're done.

🔧 Troubleshooting

❓ FAQ

Does this cost anything? No. It runs on Gemini's free tier — no credit card, no UPI. The test suite is free too (fully mocked).

Do I need Claude or Anthropic? No. SkillOps MCP is the server. Any MCP client can drive it — Claude Code, Claude Desktop, or others. The LLM doing the work inside is Gemini.

Why MCP instead of a REST API or a CLI? Because the value is being inside the tool the team already uses. With MCP, a support lead triages a ticket without leaving their AI chat — no new app, no copy-pasting into a separate service.

Can I use a different model? Yes — set GEMINI_MODEL in .env to any free-tier Gemini model. Swapping providers entirely is a one-file change in utils/gemini_client.py.

Is my .env safe to commit? No — and it's already in .gitignore. Your key stays on your machine.

💡 Why I built this

The highest-leverage AI automation isn't flashy — it's the quiet, repetitive operational work that consumes an EdTech team's week. Triaging tickets, chasing inactive learners, reading feedback, and assembling reports are tasks where human judgment matters at the edges but the bulk is mechanical. By packaging that work as MCP tools, it lives directly inside the assistant the team already uses, the deterministic parts stay deterministic, and the model only does the writing. The result turns "an afternoon of busywork" into "a single sentence" — backed by a clean, tested, provider-agnostic codebase that's easy to extend with the next workflow.

📄 License

Released under the MIT License. See LICENSE (or the badge above) for details.