# SkillOps MCP

> **AI-powered operations automation for EdTech teams.** Five [Model Context Protocol](https://modelcontextprotocol.io/) 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.

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](#license)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io/)
[![Powered by Gemini](https://img.shields.io/badge/engine-Gemini%20(free%20tier)-4285F4.svg)](https://aistudio.google.com/)
[![Tests](https://img.shields.io/badge/tests-22%20passing-success.svg)](#testing)

---

## Table of Contents

1. [What is SkillOps MCP?](#what-is-skillops-mcp)
2. [What is MCP? (60-second primer)](#what-is-mcp-60-second-primer)
3. [The five tools](#the-five-tools)
4. [Architecture](#architecture)
5. [How a request flows (step by step)](#how-a-request-flows-step-by-step)
6. [Tech stack](#tech-stack)
7. [Project structure](#project-structure)
8. [Prerequisites](#prerequisites)
9. [Installation](#installation)
10. [Getting your free Gemini API key](#getting-your-free-gemini-api-key)
11. [Configuration](#configuration)
12. [How to use it — three ways](#how-to-use-it--three-ways)
13. [Tool reference (inputs, prompts, outputs)](#tool-reference)
14. [Error handling](#error-handling)
15. [Testing](#testing)
16. [Engineering highlights](#engineering-highlights)
17. [Extending it — add your own tool](#extending-it--add-your-own-tool)
18. [Troubleshooting](#troubleshooting)
19. [FAQ](#faq)
20. [Why I built this](#why-i-built-this)
21. [License](#license)

---

## 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](https://aistudio.google.com/apikey) — **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

| # | Tool | What it does | Example you'd type |
|---|------|--------------|--------------------|
| 1 | `triage_support_query` | Classifies a support ticket (category + urgency), drafts an empathetic reply, and flags whether a human is needed. | *"Triage: 'I paid but can't open the videos!'"* |
| 2 | `generate_reengagement_message` | Writes a personalized **email + WhatsApp** win-back message for an inactive student. | *"Re-engage Priya — 12 days inactive, 45% through Web Dev."* |
| 3 | `analyze_course_feedback` | Turns a batch of raw feedback into sentiment scores, themes, complaints, praises, and prioritized fixes. | *"Analyze these 40 reviews for the Python course."* |
| 4 | `batch_generate_reports` | Computes cohort metrics **in Python**, then has the model write the weekly narrative report. | *"Weekly report from students.csv for the Spring cohort."* |
| 5 | `create_course_outline` | Produces a full course outline: modules, lessons, durations, projects, assessments. | *"Outline an 8-week beginner 'Intro to SQL' course."* |

Full input/output details for each are in the [Tool reference](#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**

| Layer | File(s) | Responsibility |
|-------|---------|----------------|
| **Server** | `server.py` | Speaks MCP. Registers the 5 tools, each as a thin adapter whose docstring is shown to the AI as the tool's description. Logs to **stderr** (never stdout — that would corrupt the stdio transport). |
| **Tools** | `tools/*.py` | The actual work. Each follows the same shape: **validate → prompt → call → format**. `reports.py` additionally computes cohort statistics in pure Python. |
| **Models** | `models/schemas.py` | Pydantic v2 models enforce every tool's input contract (required fields, enums, numeric bounds) *before* any API call. Bad input becomes a friendly `Error: …` string, never a crash. |
| **Gemini client** | `utils/gemini_client.py` | One place for all LLM calls: exponential-backoff retries on 429/5xx, **fails fast on 4xx**, Gemini-native JSON mode, strict parsing, and structured logging on every call. |
| **Formatters** | `utils/formatters.py` | Turns structured data into the clean, plain-text reports you see in chat. |

**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

| Concern | Choice | Why |
|---------|--------|-----|
| Language | **Python 3.11+** | Modern typing, broad availability |
| MCP framework | **FastMCP** | Minimal, decorator-based MCP servers |
| LLM | **Google Gemini** (`gemini-2.5-flash`) via `google-genai` | **Free tier**, fast, native JSON output |
| Validation | **Pydantic v2** | Declarative input contracts, great errors |
| Config | **python-dotenv** | `.env`-based secrets, never hardcoded |
| Data | Built-in **csv** / **json** | No heavy deps for parsing |
| Logging | Built-in **logging** | Structured, stderr-safe |
| Testing | **pytest** + **pytest-asyncio** | Fast, fully mocked, offline |

---

## 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](#getting-your-free-gemini-api-key))
- *(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

```bash
# 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`):

| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `GEMINI_API_KEY` | Yes | — | Your free Google AI Studio key |
| `GEMINI_MODEL` | No | `gemini-2.5-flash` | Which Gemini model to use (any free-tier Flash model works) |
| `SKILLOPS_LOG_LEVEL` | No | `INFO` | `DEBUG` · `INFO` · `WARNING` · `ERROR` |
| `SKILLOPS_MAX_RETRIES` | No | `3` | Retry attempts on rate-limit / server errors |

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:

```bash
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`](.mcp.json):

```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`):

```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.

| Parameter | Type | Required | Default | Notes |
|-----------|------|----------|---------|-------|
| `query` | string | Yes | — | The raw support message |
| `student_name` | string | | `"Student"` | For personalizing the reply |
| `course_name` | string | | `null` | The course they're enrolled in |

**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.

| Parameter | Type | Required | Default | Notes |
|-----------|------|----------|---------|-------|
| `student_name` | string | Yes | — | First name |
| `course_name` | string | Yes | — | Course they enrolled in |
| `days_inactive` | int | Yes | — | Days since last activity |
| `last_completed_module` | string | | `null` | Last module they finished |
| `completion_percentage` | float | | `null` | e.g. `45.5` |
| `channel` | string | | `"email"` | `email` · `whatsapp` · `both` |

**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).

| Parameter | Type | Required | Default | Notes |
|-----------|------|----------|---------|-------|
| `feedback_list` | list[str] | Yes | — | 1–50 items (extras truncated with a note) |
| `course_name` | string | | `null` | For context |
| `analysis_focus` | string | | `"balanced"` | `balanced` · `complaints_only` · `praises_only` · `actionable_only` |

**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: positive 6 | neutral 1 | negative 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.**

| Parameter | Type | Required | Default | Notes |
|-----------|------|----------|---------|-------|
| `data_source` | string | Yes | — | `"inline"` or `"csv"` |
| `students_data` | list[dict] | conditionally | `null` | Required when `inline` |
| `csv_path` | string | conditionally | `null` | Required when `csv` |
| `report_week` | string | | `null` | e.g. `"Jun 16–22, 2026"` |
| `cohort_name` | string | | `null` | e.g. `"Spring Cohort"` |

**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.

| Parameter | Type | Required | Default | Notes |
|-----------|------|----------|---------|-------|
| `topic` | string | Yes | — | e.g. `"Python for Data Science"` |
| `audience_level` | string | Yes | — | `absolute_beginner` · `beginner` · `intermediate` · `advanced` |
| `duration_weeks` | int | | `8` | Total weeks |
| `hours_per_week` | float | | `5.0` | Study hours/week |
| `delivery_format` | string | | `"self_paced"` | `self_paced` · `live_cohort` · `hybrid` |
| `include_projects` | bool | | `true` | Include hands-on projects |

**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:

| Situation | What you see |
|-----------|--------------|
| Missing API key | `Error: GEMINI_API_KEY not set. Add it to your .env file.` |
| API down after retries | `Error: Gemini API unavailable after 3 retries. Check your API key and network.` |
| Non-retryable API error (e.g. 400) | `Error: Gemini API error (400): <message>` — fails fast, no wasted retries |
| Un-parseable model output | `Error: Could not parse Gemini's response as JSON. Raw response: …` |
| Invalid input (empty feedback, bad enum, etc.) | `Error: <specific validation message>` |
| CSV file not found | `Error: CSV file not found at path: <path>` |
| CSV missing columns | `Error: CSV missing required columns: <list>` |

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.

```bash
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`:
   ```python
   class MyToolInput(BaseModel):
       text: str = Field(..., min_length=1)
   ```
2. **Write the tool** in `tools/mytool.py` following the standard shape:
   ```python
   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`:
   ```python
   @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

| Symptom | Fix |
|---------|-----|
| `Error: GEMINI_API_KEY not set` | Add the key to `.env`, or to the `env` block of your MCP client config. |
| `/mcp` doesn't list `skillops` | Run `pip install -e .`, then reload your editor. Or add it explicitly: `claude mcp add skillops python -m skillops_mcp.server`. |
| `No module named skillops_mcp` | You skipped `pip install -e .` (or you're in a different Python env / venv than the one the client launches). |
| Gemini `429` errors | Free-tier rate limit — wait a moment and retry; the client already backs off automatically. |
| Server "hangs" when run directly | That's correct — `python -m skillops_mcp.server` waits silently for an MCP client over stdio. Use `demo.py` to interact directly. |
| Claude Desktop on Windows can't find Python in WSL | Use `"command": "wsl"`, `"args": ["python", "-m", "skillops_mcp.server"]`. |

---

## 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`](LICENSE) (or the badge above) for details.