canvas-agent 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugh Koeze
+
+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 DELICT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -2,11 +2,25 @@
 
 MCP server that connects Claude AI to Instructure Canvas LMS. Manage courses, assignments, grades, and more through natural language.
 
-## Quick Setup
+## Setup
 
-Full setup guide: **[hughsibbele.github.io/Canvas-Agent](https://hughsibbele.github.io/Canvas-Agent)**
+**New to the terminal or don't have Node.js yet?** Follow the full step-by-step walkthrough at **[hughsibbele.github.io/Canvas-Agent](https://hughsibbele.github.io/Canvas-Agent)** — it explains every step.
 
-If you already have Claude Code and Node.js installed:
+### Prerequisites
+
+You need these installed before running Canvas Agent:
+
+1. **A Claude Pro subscription** ($20/month) — [sign up at claude.ai/pricing](https://claude.ai/pricing)
+2. **Node.js** — [download the LTS installer from nodejs.org](https://nodejs.org) and click through the defaults.
+3. **Claude Code and/or Claude Desktop** — Canvas Agent works in either, and if you install both the wizard will set up both:
+   - **Claude Code** (terminal-based): in a terminal, run
+     ```bash
+     npm install -g @anthropic-ai/claude-code
+     ```
+     Then type `claude` once to sign in with your Claude account.
+   - **Claude Desktop** (point-and-click app): [download from claude.ai/download](https://claude.ai/download)
+
+### Run the setup wizard
 
 ```bash
 npx -y canvas-agent setup
@@ -14,6 +28,18 @@ npx -y canvas-agent setup
 
 The wizard will walk you through connecting your Canvas account.
 
+### Alternative: install via Homebrew (macOS, developers)
+
+If you already use [Homebrew](https://brew.sh) and would rather manage these as casks and formulas, you can replace the prerequisites above with:
+
+```bash
+brew install node
+brew install --cask claude-code   # Claude Code (CLI)
+brew install --cask claude        # Claude Desktop (GUI app)
+```
+
+Skip the ones you don't want — Canvas Agent only needs one of `claude-code` or `claude` to function. Homebrew is entirely optional; the nodejs.org installer path above works without it.
+
 ## What It Does
 
 Canvas Agent gives Claude access to your Canvas LMS:

package/dist/setup.js

@@ -4,9 +4,9 @@
  * Uses only Node.js built-ins — no external dependencies.
  */
 import { createInterface } from "readline/promises";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { stdin, stdout, platform } from "process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, realpathSync, } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 // ANSI color helpers
@@ -26,7 +26,7 @@ function banner() {
     console.log("  You'll need about 3 minutes and access to your");
     console.log("  Canvas account.\n");
 }
-function isClaudeInstalled() {
+function isClaudeCodeInstalled() {
     try {
         execSync("claude --version", { stdio: "pipe" });
         return true;
@@ -35,17 +35,47 @@ function isClaudeInstalled() {
         return false;
     }
 }
-function openBrowser(url) {
+// Detects whether Claude Desktop is installed by looking for the app bundle
+// (macOS) or executable (Windows). No official Linux build exists, so Linux
+// always returns false. We intentionally DON'T check for the config file's
+// existence — a user might install Claude Desktop but never launch it, in
+// which case the config directory doesn't exist yet. Checking the app
+// itself is the authoritative signal.
+function isClaudeDesktopInstalled() {
+    if (platform === "darwin") {
+        return (existsSync("/Applications/Claude.app") ||
+            existsSync(join(homedir(), "Applications/Claude.app")));
+    }
+    if (platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData) {
+            // Known Claude Desktop install paths on Windows.
+            if (existsSync(join(localAppData, "AnthropicClaude", "claude.exe")))
+                return true;
+            if (existsSync(join(localAppData, "Programs", "Claude", "Claude.exe")))
+                return true;
+        }
+        return false;
+    }
+    return false;
+}
+// Opens a local folder in the OS file manager (Finder on macOS, Explorer on
+// Windows, default on Linux). Uses execFileSync with an argv array so paths
+// with spaces, quotes, or other special characters work correctly.
+function openInFileManager(path) {
     try {
-        const cmd = platform === "darwin"
-            ? "open"
-            : platform === "win32"
-                ? "start"
-                : "xdg-open";
-        execSync(`${cmd} "${url}"`, { stdio: "ignore" });
+        if (platform === "darwin") {
+            execFileSync("open", [path], { stdio: "ignore" });
+        }
+        else if (platform === "win32") {
+            execFileSync("explorer", [path], { stdio: "ignore" });
+        }
+        else {
+            execFileSync("xdg-open", [path], { stdio: "ignore" });
+        }
     }
     catch {
-        // Silently fail — we print the URL as fallback
+        // Nice-to-have, not critical — ignore if it fails.
     }
 }
 function normalizeCanvasUrl(raw) {
@@ -79,13 +109,316 @@ async function validateCredentials(apiUrl, token) {
         return { valid: false, error: e.message };
     }
 }
-function registerWithClaudeCode(apiUrl, token) {
+// Verifies that the URL the user typed actually points to a real Canvas
+// school BEFORE we tell them to visit the URL to generate a token. This
+// protects users from typo-squatters — e.g. someone who types
+// "instructure.org" instead of "instructure.com" would otherwise be steered
+// to a scam domain to generate a token, and their browser might pick up a
+// push-notification spam prompt in the process.
+//
+// Strategy: hit /api/v1/users/self without a token and check the response.
+// Canvas's actual unauthenticated response is 401 + the `x-canvas-meta`
+// header. A *nonexistent* school on instructure.com returns 404 + the same
+// header with a `"domain not found"` body — still instructure infrastructure,
+// but no such school. A typosquat like .org doesn't hit instructure at all
+// and fails at the socket layer. Each case gets a tailored error message.
+async function checkCanvasReachability(apiUrl) {
+    // Normalize the display URL for error messages — the host the user sees.
+    const displayHost = apiUrl.replace(/\/api\/v1\/?$/, "");
+    // Hit an API endpoint directly rather than the root. The root redirects
+    // to an SSO OAuth flow that returns 405 for unauthenticated HEAD requests,
+    // which is unhelpful. The /users/self endpoint is stable and returns a
+    // clear 401 for unauthenticated callers on every real Canvas instance.
+    const endpoint = apiUrl.replace(/\/$/, "") + "/users/self";
+    // Abort after 5 seconds so the wizard doesn't hang on a dead hostname
+    // or a slow link.
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
     try {
-        execSync(`claude mcp add -s user -e "CANVAS_API_URL=${apiUrl}" -e "CANVAS_API_TOKEN=${token}" canvas-agent -- npx -y canvas-agent`, { stdio: "inherit" });
-        return true;
+        const res = await fetch(endpoint, { signal: controller.signal });
+        const isCanvasInfra = res.headers.get("x-canvas-meta") !== null;
+        // The happy path: real Canvas school, no token → 401 + x-canvas-meta.
+        if (res.status === 401 && isCanvasInfra) {
+            return { ok: true };
+        }
+        // 404 + x-canvas-meta means "we're on instructure.com but this specific
+        // school subdomain doesn't exist" — usually a typo in the school name.
+        if (res.status === 404 && isCanvasInfra) {
+            return {
+                ok: false,
+                error: `Canvas couldn't find a school at "${displayHost}".\n` +
+                    `    Double-check the spelling of your school's subdomain.`,
+            };
+        }
+        // Anything else — unexpected status, or no x-canvas-meta header at all.
+        // This is the dangerous case: a URL that responds but isn't Canvas.
+        return {
+            ok: false,
+            error: `"${displayHost}" responded, but it doesn't look like a Canvas site.\n` +
+                `    Double-check the spelling. A common mistake is typing ".org" instead\n` +
+                `    of ".com" — that can send you to a lookalike scam domain.`,
+        };
+    }
+    catch (e) {
+        const cause = e.cause?.code || e.code || "";
+        // Any network-level failure — DNS NXDOMAIN, TLS error, socket refused,
+        // etc. Treat them all the same: the user's URL doesn't reach a real
+        // server, and a typo in the TLD is the most common cause.
+        if (cause === "ENOTFOUND" ||
+            cause === "UND_ERR_SOCKET" ||
+            cause === "ECONNREFUSED" ||
+            cause === "EAI_AGAIN") {
+            return {
+                ok: false,
+                error: `Could not reach "${displayHost}".\n` +
+                    `    Double-check the spelling — a common mistake is typing ".org" or ".net"\n` +
+                    `    instead of ".com".`,
+            };
+        }
+        if (e.name === "AbortError") {
+            return {
+                ok: false,
+                error: `"${displayHost}" didn't respond in time. Check your internet connection.`,
+            };
+        }
+        return {
+            ok: false,
+            error: `Could not reach "${displayHost}" — ${e.message || "unknown network error"}.`,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function registerWithClaudeCode(apiUrl, token, scopeChoice) {
+    // For local scope, run `claude` from inside the target folder so it writes
+    // the config under that folder's project key. For user scope, cwd doesn't
+    // matter — user-scope entries aren't tied to a directory.
+    const spawnOpts = { stdio: "pipe" };
+    if (scopeChoice.scope === "local") {
+        spawnOpts.cwd = scopeChoice.folderPath;
+    }
+    // If canvas-agent is already registered where we're about to write (e.g.
+    // the user re-runs setup after refreshing their token), remove the old
+    // entry first so add-json doesn't fail with "already exists" and we don't
+    // leave stale credentials on disk.
+    try {
+        execFileSync("claude", ["mcp", "get", "canvas-agent"], spawnOpts);
+        try {
+            execFileSync("claude", ["mcp", "remove", "canvas-agent"], spawnOpts);
+        }
+        catch {
+            // Best effort — if remove fails, add-json below will surface the real error.
+        }
     }
     catch {
-        return false;
+        // Not registered in this scope; nothing to remove.
+    }
+    // Use `claude mcp add-json` with an argv array (not a shell string) so that:
+    //  - Token characters never need shell escaping
+    //  - We sidestep the variadic `-e` parsing quirk in `claude mcp add` where
+    //    the server name can be swallowed as if it were another env var
+    const serverConfig = {
+        command: "npx",
+        args: ["-y", "canvas-agent"],
+        env: {
+            CANVAS_API_URL: apiUrl,
+            CANVAS_API_TOKEN: token,
+        },
+    };
+    try {
+        execFileSync("claude", [
+            "mcp",
+            "add-json",
+            "-s",
+            scopeChoice.scope,
+            "canvas-agent",
+            JSON.stringify(serverConfig),
+        ], spawnOpts);
+    }
+    catch (e) {
+        const stderr = (e.stderr?.toString() ||
+            e.stdout?.toString() ||
+            e.message ||
+            "unknown error").trim();
+        return { ok: false, error: stderr };
+    }
+    // Trust but verify — confirm the entry actually landed. This catches the
+    // rare case where `add-json` exits 0 but the config wasn't written (stale
+    // CLI version, file permission quirks, etc.).
+    try {
+        execFileSync("claude", ["mcp", "get", "canvas-agent"], spawnOpts);
+        return { ok: true };
+    }
+    catch {
+        return {
+            ok: false,
+            error: "Claude Code accepted the configuration but the server isn't showing up in 'claude mcp list'. Try re-running setup, or report this at https://github.com/hughsibbele/Canvas-Agent/issues",
+        };
+    }
+}
+// ── Scope selection helpers ───────────────────────────────────────────
+// These walk a non-technical user through choosing WHERE to install Canvas
+// Agent (globally vs. a specific folder) and, if needed, creating a folder
+// for them. Every prompt has a sensible default and plain-language guidance.
+async function chooseScope(rl, alsoInstallingInDesktop) {
+    // When Desktop is also a target, the heading and intro need to make clear
+    // that this scope question only affects Claude Code — in Claude Desktop,
+    // Canvas Agent is always globally available and we can't narrow that.
+    if (alsoInstallingInDesktop) {
+        console.log(bold("  Step 3: Where to Use Canvas Agent in Claude Code\n"));
+        console.log("  " +
+            dim("(This choice only affects Claude Code. In Claude Desktop,"));
+        console.log("  " + dim("Canvas Agent is always available globally.)") + "\n");
+        console.log("  Canvas Agent can be available every time you use Claude Code,");
+        console.log("  or only when you're working in a specific folder.\n");
+    }
+    else {
+        console.log(bold("  Step 3: Where to Use Canvas Agent\n"));
+        console.log("  Canvas Agent can be available every time you use Claude,");
+        console.log("  or only when you're working in a specific folder.\n");
+    }
+    console.log("  " + bold("1.") + " Everywhere " + dim("(recommended)"));
+    console.log("     " + dim("Canvas tools will load every time you run Claude."));
+    console.log("     " + dim("Pick this if you're not sure."));
+    console.log();
+    console.log("  " + bold("2.") + " Only in a specific folder");
+    console.log("     " + dim("Canvas tools will only load when you run Claude from"));
+    console.log("     " + dim("that folder. Good if you want to keep your Canvas"));
+    console.log("     " + dim("work separate from other projects."));
+    console.log();
+    while (true) {
+        const answer = (await rl.question("  Choose " + bold("1") + " or " + bold("2") + " (press Enter for 1): ")).trim();
+        if (answer === "" || answer === "1") {
+            console.log();
+            return { scope: "user" };
+        }
+        if (answer === "2") {
+            console.log();
+            const folderPath = await chooseOrCreateFolder(rl);
+            return { scope: "local", folderPath };
+        }
+        console.log(red("  ✗") + " Please type 1 or 2.\n");
+    }
+}
+async function chooseOrCreateFolder(rl) {
+    console.log(bold("  Pick a Folder for Canvas Agent\n"));
+    console.log("  " + bold("1.") + " Create a new folder for me " + dim("(recommended)"));
+    console.log("     " + dim('We\'ll make a "Canvas Work" folder inside your Documents.'));
+    console.log();
+    console.log("  " + bold("2.") + " I already have a folder I want to use");
+    console.log("     " + dim("You'll type the full path to it."));
+    console.log();
+    while (true) {
+        const answer = (await rl.question("  Choose " + bold("1") + " or " + bold("2") + " (press Enter for 1): ")).trim();
+        if (answer === "" || answer === "1") {
+            console.log();
+            return await createNewFolder(rl);
+        }
+        if (answer === "2") {
+            console.log();
+            return await pickExistingFolder(rl);
+        }
+        console.log(red("  ✗") + " Please type 1 or 2.\n");
+    }
+}
+async function createNewFolder(rl) {
+    const defaultName = "Canvas Work";
+    const parentDir = join(homedir(), "Documents");
+    console.log("  We'll create a folder inside your Documents folder:");
+    console.log("  " + dim(parentDir) + "\n");
+    let name = "";
+    while (true) {
+        const input = (await rl.question(`  Folder name (press Enter for "${defaultName}"): `)).trim();
+        name = input || defaultName;
+        // Basic sanity check — no path separators in the name, and not empty.
+        if (name.includes("/") || name.includes("\\")) {
+            console.log(red("  ✗") + ' Folder name cannot contain "/" or "\\\\". Try again.\n');
+            continue;
+        }
+        break;
+    }
+    // Ensure ~/Documents exists. On macOS/Windows it virtually always does,
+    // but on Linux or exotic setups it might not — recursive mkdir is safe.
+    try {
+        mkdirSync(parentDir, { recursive: true });
+    }
+    catch {
+        // If this fails the folder create below will also fail and surface the real error.
+    }
+    const folderPath = join(parentDir, name);
+    if (existsSync(folderPath)) {
+        console.log(green("  ✓") + " Folder already exists — we'll use it.");
+    }
+    else {
+        try {
+            mkdirSync(folderPath, { recursive: true });
+            console.log(green("  ✓") + " Created folder.");
+        }
+        catch (e) {
+            throw new Error(`Could not create folder "${folderPath}": ${e.message}`);
+        }
+    }
+    // Resolve symlinks so the path we use matches the key Claude Code will
+    // store (e.g. /tmp → /private/tmp on macOS). Otherwise the local-scope
+    // config lookup could miss our entry.
+    const canonical = realpathSync(folderPath);
+    console.log(dim(`    ${canonical}\n`));
+    // Nice touch: pop the folder open in Finder/Explorer so the user can
+    // literally see where it is. Fails silently if the OS command isn't available.
+    openInFileManager(canonical);
+    return canonical;
+}
+async function pickExistingFolder(rl) {
+    console.log("  Type the full path to the folder you want to use.");
+    console.log("  " + dim("You can use ~ to mean your home folder."));
+    console.log("  " + dim("Example: ~/Documents/My Canvas Courses") + "\n");
+    while (true) {
+        const rawPath = (await rl.question("  Folder path: ")).trim();
+        if (!rawPath) {
+            console.log(red("  ✗") + " Please type a folder path.\n");
+            continue;
+        }
+        // Expand ~ → home directory. Handles "~", "~/foo", and "~\foo".
+        let expanded = rawPath;
+        if (expanded === "~") {
+            expanded = homedir();
+        }
+        else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+            expanded = join(homedir(), expanded.slice(2));
+        }
+        if (!existsSync(expanded)) {
+            console.log(red("  ✗") + " That folder doesn't exist: " + dim(expanded));
+            const create = (await rl.question("  Create it? (y/n): ")).trim().toLowerCase();
+            if (create !== "y") {
+                console.log();
+                continue;
+            }
+            try {
+                mkdirSync(expanded, { recursive: true });
+                console.log(green("  ✓") + " Created folder.");
+            }
+            catch (e) {
+                console.log(red("  ✗") + ` Could not create: ${e.message}\n`);
+                continue;
+            }
+        }
+        // Make sure it's a directory, not a regular file.
+        try {
+            const stat = statSync(expanded);
+            if (!stat.isDirectory()) {
+                console.log(red("  ✗") + " That path is a file, not a folder. Try again.\n");
+                continue;
+            }
+        }
+        catch (e) {
+            console.log(red("  ✗") + ` Could not read folder: ${e.message}\n`);
+            continue;
+        }
+        const canonical = realpathSync(expanded);
+        console.log(green("  ✓") + " Using folder.");
+        console.log(dim(`    ${canonical}\n`));
+        return canonical;
     }
 }
 function getDesktopConfigPath() {
@@ -99,20 +432,34 @@ function getDesktopConfigPath() {
 }
 function registerWithDesktop(apiUrl, token) {
     const configPath = getDesktopConfigPath();
-    if (!configPath)
-        return false;
+    if (!configPath) {
+        return {
+            ok: false,
+            error: "No known Claude Desktop config path for this platform.",
+        };
+    }
     try {
-        // Read existing config or start fresh
+        // Read existing config or start fresh. We preserve every other field
+        // in the Desktop config (preferences, other MCP servers, etc.) — we
+        // only touch mcpServers["canvas-agent"].
         let config = {};
         if (existsSync(configPath)) {
-            config = JSON.parse(readFileSync(configPath, "utf-8"));
+            const raw = readFileSync(configPath, "utf-8");
+            try {
+                config = JSON.parse(raw);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    error: `Could not parse existing Claude Desktop config: ${e.message}. Fix or delete ${configPath} and try again.`,
+                };
+            }
         }
         else {
-            // Ensure parent directory exists
+            // Ensure parent directory exists (Claude Desktop installed but never launched)
             const dir = join(configPath, "..");
             mkdirSync(dir, { recursive: true });
         }
-        // Merge in our MCP server entry
         if (!config.mcpServers)
             config.mcpServers = {};
         config.mcpServers["canvas-agent"] = {
@@ -124,10 +471,10 @@ function registerWithDesktop(apiUrl, token) {
             },
         };
         writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-        return true;
+        return { ok: true };
     }
-    catch {
-        return false;
+    catch (e) {
+        return { ok: false, error: e.message || "unknown error writing Desktop config" };
     }
 }
 function printManualConfig(apiUrl, token) {
@@ -149,26 +496,42 @@ export async function runSetup() {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
         banner();
-        // ── Step 1: Check for Claude Code ──
-        const hasClaude = isClaudeInstalled();
-        let useDesktop = false;
-        if (hasClaude) {
-            console.log(green("  ✓") + " Claude Code is installed.\n");
-        }
-        else {
-            console.log(yellow("  ⚠") + " Claude Code not found.\n");
-            console.log("  Canvas Agent works best with Claude Code.");
-            console.log("  To install it, run:\n");
-            console.log(bold("    npm install -g @anthropic-ai/claude-code\n"));
-            console.log("  Then run this setup again.\n");
-            const answer = await rl.question("  Continue with Claude Desktop setup instead? (y/n): ");
-            if (answer.trim().toLowerCase() !== "y") {
-                console.log("\n  No problem! Install Claude Code and run this again:");
-                console.log(bold("    npx -y canvas-agent setup\n"));
-                return;
+        // ── Detection: Claude Code and Claude Desktop are independent targets ──
+        //
+        // We install into whichever are present — no fall-through logic, no
+        // "do you want Desktop instead" prompt. If the user has both, Canvas
+        // Agent gets set up in both automatically. If they have only one, we
+        // use that one. If they have neither, we bail out with a clear install
+        // guide.
+        const hasClaudeCode = isClaudeCodeInstalled();
+        const hasClaudeDesktop = isClaudeDesktopInstalled();
+        console.log("  Checking your Claude setup...\n");
+        console.log((hasClaudeCode ? green("  ✓") : dim("  ✗")) +
+            " Claude Code " +
+            (hasClaudeCode ? "" : dim("(not found)")));
+        console.log((hasClaudeDesktop ? green("  ✓") : dim("  ✗")) +
+            " Claude Desktop " +
+            (hasClaudeDesktop ? "" : dim("(not found)")));
+        console.log();
+        if (!hasClaudeCode && !hasClaudeDesktop) {
+            console.log(yellow("  ⚠") + " Canvas Agent needs either Claude Code or Claude Desktop.");
+            console.log();
+            console.log("  " + bold("Install one (or both) and then re-run this wizard:"));
+            console.log();
+            console.log("  " + bold("Claude Code") + dim(" — terminal-based, works in any folder"));
+            console.log("    " + bold("npm install -g @anthropic-ai/claude-code"));
+            if (platform === "darwin") {
+                console.log("    " + dim("or, with Homebrew:") + " " + bold("brew install --cask claude-code"));
             }
-            useDesktop = true;
             console.log();
+            console.log("  " + bold("Claude Desktop") + dim(" — point-and-click app"));
+            console.log("    Download at " + cyan("https://claude.ai/download"));
+            console.log();
+            console.log("  Full walkthrough: " + cyan("https://hughsibbele.github.io/Canvas-Agent"));
+            console.log();
+            console.log("  When you're ready, re-run:");
+            console.log(bold("    npx -y canvas-agent setup\n"));
+            return;
         }
         // ── Step 2: Get Canvas URL ──
         console.log(bold("  Step 1: Your School's Canvas\n"));
@@ -186,21 +549,38 @@ export async function runSetup() {
                 continue;
             }
             console.log(dim(`    → ${apiUrl}`));
+            console.log(dim("    Checking that this is a real Canvas site..."));
+            // Verify the URL actually points to a Canvas instance BEFORE we tell
+            // the user to visit it. This catches typos like .org instead of .com
+            // (which can send users to scam domains) before any browser navigation
+            // or token generation happens.
+            const reachability = await checkCanvasReachability(apiUrl);
+            if (!reachability.ok) {
+                console.log(red("  ✗") + ` ${reachability.error}\n`);
+                continue;
+            }
+            console.log(green("  ✓") + " Canvas found.");
             break;
         }
         // ── Step 3: Get Canvas API Token ──
         console.log(bold("\n  Step 2: Canvas API Token\n"));
         console.log("  We need an access token from Canvas. Here's how:\n");
-        console.log(`  1. Log in to Canvas at ${cyan(`https://${hostname}`)}`);
-        console.log("  2. Click your profile picture (top left) → " + bold("Settings"));
-        console.log("  3. Scroll down to " + bold('"Approved Integrations"'));
-        console.log("  4. Click " + bold('"+ New Access Token"'));
-        console.log("  5. For Purpose, type: " + dim("Canvas Agent"));
-        console.log("  6. Click " + bold('"Generate Token"') + " and copy the token shown\n");
         const settingsUrl = `https://${hostname}/profile/settings`;
-        console.log(`  Opening ${cyan(settingsUrl)} in your browser...`);
-        openBrowser(settingsUrl);
-        console.log();
+        // We intentionally DO NOT auto-open this URL in the user's browser.
+        // Auto-opening a URL the user just typed means a typo can steer their
+        // browser directly into a scam domain (push-notification spam, fake
+        // captchas, etc.) before they have a chance to notice. Instead, print
+        // the URL, let the user see it, and let them click or copy it. The
+        // reachability check above also guarantees this is really Canvas —
+        // but showing the URL gives the user a final visual confirmation.
+        console.log("  1. Open this link in your browser:");
+        console.log("       " + cyan(settingsUrl));
+        console.log("     " + dim("(Most terminals let you Cmd+click the link. Otherwise, copy and paste it.)"));
+        console.log("  2. Scroll down to " + bold('"Approved Integrations"'));
+        console.log("  3. Click " + bold('"+ New Access Token"'));
+        console.log("  4. For Purpose, type: " + dim("Canvas Agent"));
+        console.log("  5. Click " + bold('"Generate Token"') + " and copy the token shown");
+        console.log("  6. Come back here and paste the token below\n");
         let token = "";
         while (true) {
             token = (await rl.question("  Paste your token here: ")).trim();
@@ -233,51 +613,124 @@ export async function runSetup() {
                 console.log();
             }
         }
-        // ── Step 5: Register MCP server ──
-        console.log(bold("  Step 3: Connecting to Claude\n"));
-        let registered = false;
-        if (!useDesktop) {
-            // Try Claude Code first
-            console.log("  Registering Canvas Agent with Claude Code...\n");
-            registered = registerWithClaudeCode(apiUrl, token);
-            if (registered) {
-                console.log(green("\n  ✓") + " Registered with Claude Code!\n");
+        // ── Step 3: Choose scope (Claude Code targets only) ──
+        //
+        // Scope is a Claude Code concept — Claude Desktop's config is a single
+        // global file with no per-folder behavior. So we only ask when Claude
+        // Code is one of the install targets. When Desktop is *also* a target,
+        // chooseScope() shows an extra note so the user understands the choice
+        // only narrows Claude Code.
+        let scopeChoice = { scope: "user" };
+        if (hasClaudeCode) {
+            try {
+                scopeChoice = await chooseScope(rl, hasClaudeDesktop);
+            }
+            catch (e) {
+                console.log(red("  ✗") + ` ${e.message}\n`);
+                console.log("  Re-run this wizard when you're ready:");
+                console.log(bold("    npx -y canvas-agent setup\n"));
+                return;
+            }
+        }
+        // ── Step 4: Register MCP server in each detected target ──
+        // Step number depends on whether we asked about scope above. If we
+        // skipped scope (Desktop-only setup) this is Step 3; otherwise Step 4.
+        const connectStepNum = hasClaudeCode ? 4 : 3;
+        console.log(bold(`  Step ${connectStepNum}: Connecting to Claude\n`));
+        // Each target is attempted independently. A failure in one doesn't
+        // abort the other — users should get whatever we can successfully
+        // install for them, and we report per-target results so they can see
+        // exactly what happened.
+        let codeResult = null;
+        let desktopResult = null;
+        if (hasClaudeCode) {
+            console.log("  Registering with Claude Code...");
+            codeResult = registerWithClaudeCode(apiUrl, token, scopeChoice);
+            if (codeResult.ok) {
+                console.log(green("  ✓") + " Claude Code\n");
             }
             else {
-                console.log(yellow("\n  ⚠") + " Could not register automatically.\n");
-                // Fall through to Desktop or manual
-                useDesktop = true;
+                console.log(yellow("  ⚠") + " Claude Code — could not register.");
+                const detail = codeResult.error
+                    .split("\n")
+                    .map((l) => `    ${l}`)
+                    .join("\n");
+                console.log(dim(detail) + "\n");
             }
         }
-        if (useDesktop && !registered) {
-            console.log("  Setting up Claude Desktop...");
-            registered = registerWithDesktop(apiUrl, token);
-            if (registered) {
-                console.log(green("  ✓") + " Configured Claude Desktop!\n");
-                console.log(dim("    Restart Claude Desktop for changes to take effect.\n"));
+        if (hasClaudeDesktop) {
+            console.log("  Configuring Claude Desktop...");
+            desktopResult = registerWithDesktop(apiUrl, token);
+            if (desktopResult.ok) {
+                console.log(green("  ✓") + " Claude Desktop\n");
+            }
+            else {
+                console.log(yellow("  ⚠") + " Claude Desktop — could not configure.");
+                const detail = desktopResult.error
+                    .split("\n")
+                    .map((l) => `    ${l}`)
+                    .join("\n");
+                console.log(dim(detail) + "\n");
             }
         }
-        if (!registered) {
+        const codeOk = codeResult?.ok ?? false;
+        const desktopOk = desktopResult?.ok ?? false;
+        // If NOTHING succeeded, fall back to printing the config for manual install.
+        if (!codeOk && !desktopOk) {
+            console.log(red("  ✗") + " Canvas Agent could not be installed automatically.\n");
             printManualConfig(apiUrl, token);
             console.log("  Copy the JSON above and add it to your Claude configuration.");
             console.log("  For help, visit: " + cyan("https://hughsibbele.github.io/Canvas-Agent") + "\n");
+            return;
         }
         // ── Done ──
         console.log(cyan("  ╔══════════════════════════════════════╗"));
         console.log(cyan("  ║") + green("          Setup Complete!              ") + cyan("║"));
         console.log(cyan("  ╚══════════════════════════════════════╝"));
         console.log();
-        if (!useDesktop) {
-            console.log("  To start using Canvas Agent:");
-            console.log("  1. Open a terminal and type: " + bold("claude"));
-            console.log('  2. Try asking: ' + dim('"List my Canvas courses"'));
+        // Summary of where Canvas Agent ended up
+        if (codeOk && desktopOk) {
+            console.log(bold("  Canvas Agent is installed in both Claude Code and Claude Desktop."));
+        }
+        else if (codeOk) {
+            console.log(bold("  Canvas Agent is installed in Claude Code."));
         }
         else {
-            console.log("  To start using Canvas Agent:");
-            console.log("  1. Restart Claude Desktop");
-            console.log('  2. Try asking: ' + dim('"List my Canvas courses"'));
+            console.log(bold("  Canvas Agent is installed in Claude Desktop."));
         }
         console.log();
+        // Per-target launch instructions. We show every surface that succeeded
+        // so the user knows how to reach Canvas Agent from whichever tool they
+        // prefer to open first.
+        if (codeOk) {
+            console.log("  " + bold("To use it in Claude Code:"));
+            if (scopeChoice.scope === "user") {
+                console.log("    1. Open Terminal and type: " + bold("claude"));
+                console.log('    2. Try asking: ' + dim('"List my Canvas courses"'));
+            }
+            else {
+                // Local scope — user needs to launch claude from the registered folder.
+                const folderPath = scopeChoice.folderPath;
+                console.log("    Canvas Agent is installed in this folder:");
+                console.log("    " + cyan(folderPath));
+                console.log();
+                console.log("    1. Open Terminal");
+                console.log("    2. Go to your Canvas folder:");
+                console.log("       " + bold(`cd "${folderPath}"`));
+                console.log("    3. Type: " + bold("claude"));
+                console.log('    4. Try asking: ' + dim('"List my Canvas courses"'));
+                console.log();
+                console.log("    " + dim("Tip: copy-paste the whole thing —"));
+                console.log("    " + dim(`cd "${folderPath}" && claude`));
+            }
+            console.log();
+        }
+        if (desktopOk) {
+            console.log("  " + bold("To use it in Claude Desktop:"));
+            console.log("    1. Quit and restart Claude Desktop if it's running");
+            console.log('    2. Try asking: ' + dim('"List my Canvas courses"'));
+            console.log();
+        }
         console.log("  For help: " + cyan("https://hughsibbele.github.io/Canvas-Agent"));
         console.log();
     }

package/dist/tools/analytics.js

@@ -9,7 +9,7 @@ export function registerAnalyticsTools(server) {
             content: [{ type: "text", text: JSON.stringify(activity, null, 2) }],
         };
     });
-    server.tool("get_course_assignment_analytics", "Get aggregate statistical analytics per assignment: min/max/median scores, submission counts (on_time, late, missing). This returns statistics, not the assignments themselves — use list_assignments for that.", {
+    server.tool("get_course_assignment_analytics", "Get aggregate statistical analytics per assignment: min/max/median scores, submission counts (on_time, late, missing). This returns statistics, not the assignments themselves — use list_assignments for that. NOTE: this endpoint returns LIFETIME data and does NOT support grading_period_id — for semester-scoped data, fall back to fetching submissions directly via list_submissions.", {
         course_id: z.string().describe("Canvas course ID"),
     }, async ({ course_id }) => {
         const analytics = await canvas(`/courses/${course_id}/analytics/assignments`);
@@ -17,7 +17,7 @@ export function registerAnalyticsTools(server) {
             content: [{ type: "text", text: JSON.stringify(analytics, null, 2) }],
         };
     });
-    server.tool("get_student_summaries", "Get per-student engagement analytics for a course: page views, participations, and tardiness breakdown. For enrollment/roster data, use list_students instead.", {
+    server.tool("get_student_summaries", "Get per-student engagement analytics for a course: page views, participations, and tardiness breakdown (missing/late/on_time counts). For enrollment/roster data, use list_students instead. NOTE: this endpoint returns LIFETIME data and does NOT support grading_period_id — the tardiness counts include all assignments since the course began, not just the current semester. For per-semester counts, iterate course submissions with a grading_period_id filter.", {
         course_id: z.string().describe("Canvas course ID"),
         sort_column: z
             .enum([
@@ -48,7 +48,7 @@ export function registerAnalyticsTools(server) {
             content: [{ type: "text", text: JSON.stringify(activity, null, 2) }],
         };
     });
-    server.tool("get_student_assignment_data", "Get per-assignment scores, submission status, and timestamps for a specific student. This is analytics data — for actual submission details, use list_submissions.", {
+    server.tool("get_student_assignment_data", "Get per-assignment scores, submission status, and timestamps for a specific student. This is analytics data — for actual submission details, use list_submissions. NOTE: this endpoint returns LIFETIME data and does NOT support grading_period_id — it includes assignments from all grading periods.", {
         course_id: z.string().describe("Canvas course ID"),
         student_id: z.string().describe("Canvas user ID of the student"),
     }, async ({ course_id, student_id }) => {

package/dist/tools/courses.js

@@ -1,16 +1,29 @@
 import { z } from "zod";
-import { canvasAll } from "../canvas-client.js";
+import { canvas, canvasAll } from "../canvas-client.js";
 export function registerCourseTools(server) {
-    server.tool("list_courses", "List Canvas courses you have access to. Returns course IDs needed by all other tools. Shows active courses by default.", {
+    server.tool("list_courses", "List Canvas courses you have access to. Returns course IDs needed by all other tools. Shows active courses by default. Admins can use search_term to search all courses in the account.", {
         enrollment_state: z
             .enum(["active", "completed", "invited"])
             .default("active")
             .describe("Filter by enrollment state"),
-    }, async ({ enrollment_state }) => {
-        const courses = await canvasAll("/courses", {
-            enrollment_state,
-            include: "term",
-        });
+        search_term: z
+            .string()
+            .optional()
+            .describe("Search all courses by name or code (admin only). When provided, searches across the entire account instead of just enrolled courses."),
+    }, async ({ enrollment_state, search_term }) => {
+        let courses;
+        if (search_term) {
+            courses = await canvasAll("/accounts/self/courses", {
+                search_term,
+                include: "term",
+            });
+        }
+        else {
+            courses = await canvasAll("/courses", {
+                enrollment_state,
+                include: "term",
+            });
+        }
         const summary = courses.map((c) => ({
             id: c.id,
             name: c.name,
@@ -49,4 +62,23 @@ export function registerCourseTools(server) {
             content: [{ type: "text", text: JSON.stringify(modules, null, 2) }],
         };
     });
+    server.tool("list_grading_periods", "List the grading periods (e.g. semesters, quarters) defined for a course's term. Returns id, title, start_date, end_date, and is_closed for each period. The returned IDs can be passed as grading_period_id to get_student_enrollments and other grade-related tools to scope grades and submissions to a single period instead of the cumulative lifetime grade. Note: schools that don't use grading periods will get a single default period.", { course_id: z.string().describe("Canvas course ID") }, async ({ course_id }) => {
+        // The grading_periods endpoint returns a wrapped response:
+        // {"grading_periods": [...], "meta": {...}}
+        // Use canvas (not canvasAll) and unwrap manually.
+        const raw = await canvas(`/courses/${course_id}/grading_periods`);
+        const periods = (raw?.grading_periods ?? []);
+        const summary = periods.map((p) => ({
+            id: p.id,
+            title: p.title,
+            start_date: p.start_date,
+            end_date: p.end_date,
+            close_date: p.close_date,
+            is_closed: p.is_closed,
+            weight: p.weight,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
 }

package/dist/tools/enrollments.js

@@ -49,11 +49,18 @@ export function registerEnrollmentTools(server) {
             content: [{ type: "text", text: JSON.stringify(sections, null, 2) }],
         };
     });
-    server.tool("get_student_enrollments", "Get enrollment details for a specific student in a course, including grades if available.", {
+    server.tool("get_student_enrollments", "Get enrollment details for a specific student in a course, including grades if available. Pass grading_period_id to get the grade for a specific semester/term instead of the cumulative lifetime grade — find the id with list_grading_periods.", {
         course_id: z.string().describe("Canvas course ID"),
         student_id: z.string().describe("Canvas user ID of the student"),
-    }, async ({ course_id, student_id }) => {
-        const enrollments = await canvasAll(`/courses/${course_id}/enrollments`, { user_id: student_id });
+        grading_period_id: z
+            .string()
+            .optional()
+            .describe("Grading period ID to scope grades to a single semester/term. Without this, current_score reflects the entire course history. Use list_grading_periods to discover ids."),
+    }, async ({ course_id, student_id, grading_period_id }) => {
+        const params = { user_id: student_id };
+        if (grading_period_id)
+            params.grading_period_id = grading_period_id;
+        const enrollments = await canvasAll(`/courses/${course_id}/enrollments`, params);
         return {
             content: [
                 { type: "text", text: JSON.stringify(enrollments, null, 2) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for Instructure Canvas LMS — connect Claude AI to your courses",
   "type": "module",
   "bin": {