@imstudium/mcp 0.1.1

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { createSdk, expandPath, extractSlug, normalizeStudiumWorkspace, pageRef, pickCourse, resolveCourseDir, agentSearchGuidance } from "@imstudium/sdk";
+import { readdir, readFile } from "fs/promises";
+import { basename, join } from "path";
+
+// src/tools.ts
+var MCP_TOOLS = [
+  {
+    name: "studium_overview",
+    description: "Full course map and semester context from local studium.json. Call this first for study planning.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "studium_klausuren",
+    description: "Exam timeline with days-remaining from klausuren.md / studium.json",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "studium_course_brief",
+    description: "One course: schedule, materials count, exams, COURSE.md content",
+    inputSchema: {
+      type: "object",
+      properties: {
+        course: { type: "string", description: "Course title substring or id" }
+      },
+      required: ["course"]
+    }
+  },
+  {
+    name: "studium_find_materials",
+    description: "List synced files by course and optional filename query. For content search, grep `<course.path>/search/corpus.jsonl` with your native tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        course: { type: "string", description: "Course title substring" },
+        query: { type: "string", description: "Filename search" }
+      },
+      required: ["course"]
+    }
+  },
+  {
+    name: "studium_read_material",
+    description: "Extract one course file (PDF/PPTX/DOCX/images). Returns text + pageImages + viewerHtml. MANDATORY for agents: read every pageImage OR open viewerFileUrl in Playwright/browser before explaining slides \u2014 text alone misses diagrams and formulas.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        course: { type: "string", description: "Course title substring" },
+        file: { type: "string", description: "Filename substring (e.g. 'vorlesung 3', 'klausur')" },
+        page: { type: "number", description: "Optional: only this page/slide (1-based)" }
+      },
+      required: ["course", "file"]
+    }
+  },
+  {
+    name: "imstudium_sync",
+    description: "Refresh workspace from live Stud.IP (requires login). Full sync + rebuild.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        course: { type: "string", description: "Optional single course filter" }
+      }
+    }
+  },
+  {
+    name: "imstudium_sync_dry_run",
+    description: "Preview pending file downloads without downloading",
+    inputSchema: {
+      type: "object",
+      properties: {
+        course: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "imstudium_list_courses",
+    description: "Live course list from Stud.IP API (when workspace is stale)",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "imstudium_whoami",
+    description: "Check authentication status and current user",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+var TOOL_NAMES = MCP_TOOLS.map((t) => t.name);
+
+// src/visual.ts
+import { buildAgentVisualPayload, buildSlideViewer } from "@imstudium/sdk";
+async function materialVisualPayload(outDir, title) {
+  const { viewerHtml, pageImages } = await buildSlideViewer(outDir, title);
+  const visual = buildAgentVisualPayload(pageImages, pageImages.length > 0 ? viewerHtml : void 0);
+  return { ...visual, pageImages, viewerHtml: pageImages.length > 0 ? viewerHtml : void 0 };
+}
+
+// src/index.ts
+var server = new Server(
+  { name: "imstudium-studium", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+var workspacePath = process.env.IMSTUDIUM_WORKSPACE || process.env.DIGICAMPUS_WORKSPACE || "";
+var sdkPromise = null;
+async function getSdk() {
+  if (!sdkPromise) sdkPromise = createSdk();
+  const sdk = await sdkPromise;
+  if (!workspacePath) workspacePath = expandPath(sdk.workspacePath);
+  return sdk;
+}
+function jsonText(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [...MCP_TOOLS]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const sdk = await getSdk();
+    switch (name) {
+      case "studium_overview": {
+        const ws = await loadWorkspace(sdk);
+        const focusId = ws.activeSemester?.id;
+        return jsonText({
+          activeSemester: ws.activeSemester,
+          otherSemesters: ws.otherSemesters,
+          search: ws.search,
+          searchGuidance: agentSearchGuidance(workspacePath, ws),
+          focusCourses: ws.courses.filter((c) => !focusId || c.semesterId === focusId),
+          allCourses: ws.courses,
+          nextDeadlines: ws.nextDeadlines,
+          hint: "Default to focusCourses. Find content: grep/semantic-search corpus.jsonl (see searchGuidance). Paths: course.path + search/materials.json."
+        });
+      }
+      case "studium_klausuren": {
+        const ws = await loadWorkspace(sdk);
+        const exams = ws.courses.flatMap(
+          (c) => c.examDates.map((e) => ({ ...e, courseTitle: c.title }))
+        );
+        return jsonText({ nextDeadlines: ws.nextDeadlines, exams });
+      }
+      case "studium_course_brief": {
+        const ws = await loadWorkspace(sdk);
+        const courseArg = String(args?.course || "");
+        const course = pickCourse(ws, courseArg);
+        if (!course) {
+          return jsonText({ error: "Course not found", available: ws.courses.map((c) => c.title) });
+        }
+        const courseDir = resolveCourseDir(workspacePath, course, ws);
+        let courseMd = "";
+        try {
+          courseMd = await readFile(join(courseDir, "COURSE.md"), "utf-8");
+        } catch {
+        }
+        let materials;
+        try {
+          materials = JSON.parse(await readFile(join(courseDir, "search", "materials.json"), "utf-8"));
+        } catch {
+        }
+        return jsonText({ course, courseMd, materials, activeSemester: ws.activeSemester });
+      }
+      case "studium_find_materials": {
+        const ws = await loadWorkspace(sdk);
+        const courseArg = String(args?.course || "");
+        const query = String(args?.query || "").toLowerCase();
+        const course = pickCourse(ws, courseArg);
+        if (!course) return jsonText({ error: "Course not found" });
+        const filesDir = join(resolveCourseDir(workspacePath, course, ws), "files");
+        const matches = await findFilesRecursive(filesDir, query);
+        return jsonText({ course: course.title, path: course.path, matches });
+      }
+      case "studium_read_material": {
+        const ws = await loadWorkspace(sdk);
+        const courseArg = String(args?.course || "");
+        const fileArg = String(args?.file || "").toLowerCase();
+        const page = args?.page;
+        const course = pickCourse(ws, courseArg);
+        if (!course) {
+          return jsonText({ error: "Course not found", available: ws.courses.map((c) => c.title) });
+        }
+        const courseDir = resolveCourseDir(workspacePath, course, ws);
+        const filesDir = join(courseDir, "files");
+        const candidates = await findFilesRecursive(filesDir, fileArg);
+        if (candidates.length === 0) {
+          return jsonText({
+            error: `No file matching "${fileArg}" in ${course.title}`,
+            path: course.path,
+            hint: "Use studium_find_materials to list files, or imstudium_sync to refresh"
+          });
+        }
+        const src = candidates[0];
+        const outDir = join(courseDir, "extracted", extractSlug(basename(src)));
+        const result = await sdk.extractor.extractFile(src, outDir);
+        if (result.error) {
+          return jsonText({ error: result.error, hint: result.hint, source: src });
+        }
+        let content = "";
+        try {
+          content = await readFile(join(outDir, "content.md"), "utf-8");
+        } catch {
+        }
+        if (page && content) {
+          const sections = content.split(/^## (?:Page|Slide) /m);
+          const match = sections.find((s) => s.startsWith(`${page}
+`) || s.startsWith(`${page}\r`));
+          if (match) content = `## Page ${match}`;
+        }
+        const visual = await materialVisualPayload(outDir, basename(src));
+        let { pageImages, viewerHtml } = visual;
+        if (page) {
+          pageImages = pageImages.filter((p) => new RegExp(`-0*${page}\\.`).test(p));
+        }
+        return jsonText({
+          course: course.title,
+          source: src,
+          kind: result.kind,
+          pages: result.pages,
+          ref: page ? pageRef(course.path || course.slug, basename(src), page) : void 0,
+          citation: page ? `${course.title} \xB7 ${basename(src)} \xB7 p.${page}` : void 0,
+          content,
+          pageImages,
+          viewerHtml,
+          requiredAction: visual.requiredAction,
+          viewerFileUrl: visual.viewerFileUrl,
+          methods: visual.methods,
+          hint: pageImages.length ? void 0 : result.hint || "Install poppler for slide images: imstudium doctor",
+          otherMatches: candidates.slice(1)
+        });
+      }
+      case "imstudium_sync": {
+        const course = args?.course;
+        const semOpts = { semesterId: sdk.config.semesterId };
+        const report = await sdk.sync.sync({
+          outputDir: workspacePath,
+          include: ["wiki", "news", "calendar"],
+          ...semOpts,
+          courseFilter: course ? (c) => c.title.toLowerCase().includes(course.toLowerCase()) : void 0
+        });
+        const workspace = await sdk.studium.build(workspacePath, sdk.config.instanceOrigin, semOpts);
+        return jsonText({
+          report,
+          workspaceSummary: {
+            courses: workspace.courses.length,
+            activeSemester: workspace.activeSemester,
+            workspaceFolder: workspace.workspaceFolder,
+            otherSemesters: workspace.otherSemesters
+          }
+        });
+      }
+      case "imstudium_sync_dry_run": {
+        const course = args?.course;
+        const semOpts = { semesterId: sdk.config.semesterId };
+        const report = await sdk.sync.sync({
+          outputDir: workspacePath,
+          dryRun: true,
+          ...semOpts,
+          courseFilter: course ? (c) => c.title.toLowerCase().includes(course.toLowerCase()) : void 0
+        });
+        return jsonText(report);
+      }
+      case "imstudium_list_courses": {
+        const me = await sdk.courses.getMe();
+        const ctx = await sdk.courses.resolveSemesterContext({ semesterId: sdk.config.semesterId });
+        const courses = await sdk.courses.listMine(me.id, { semesterId: ctx?.semester.id });
+        return jsonText({
+          semester: ctx ? { id: ctx.semester.id, title: ctx.title, slug: ctx.slug, isCurrent: ctx.isCurrent } : void 0,
+          hint: "This defaults to the current semester. Pass allSemesters or sync --semester for older terms.",
+          courses: courses.map((c) => ({
+            id: c.id,
+            title: c.attributes?.title,
+            type: c.attributes?.["course-type"]
+          }))
+        });
+      }
+      case "imstudium_whoami": {
+        const session = await sdk.auth.loadSession();
+        if (!session) return jsonText({ authenticated: false, hint: "Run imstudium login" });
+        const me = await sdk.courses.getMe();
+        return jsonText({
+          authenticated: true,
+          user: { id: me.id, name: me.attributes?.["formatted-name"] },
+          workspace: workspacePath
+        });
+      }
+      default:
+        return jsonText({ error: `Unknown tool: ${name}` });
+    }
+  } catch (e) {
+    return jsonText({
+      error: e instanceof Error ? e.message : String(e),
+      hint: "Run imstudium login if not authenticated"
+    });
+  }
+});
+async function loadWorkspace(sdk) {
+  const ws = await sdk.studium.loadWorkspace(workspacePath);
+  if (!ws) {
+    throw new Error(
+      `No Studium workspace at ${workspacePath}. Run: imstudium init`
+    );
+  }
+  return normalizeStudiumWorkspace(ws);
+}
+async function findFilesRecursive(dir, query, results = []) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        await findFilesRecursive(p, query, results);
+      } else if (!query || e.name.toLowerCase().includes(query)) {
+        results.push(p);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@imstudium/mcp",
+  "version": "0.1.1",
+  "description": "ImStudium MCP server — study planning tools for LLMs",
+  "license": "MIT",
+  "type": "module",
+  "author": "Patrick Schröppel",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paddy-shrp/imstudium.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/paddy-shrp/imstudium#readme",
+  "bugs": {
+    "url": "https://github.com/paddy-shrp/imstudium/issues"
+  },
+  "keywords": [
+    "imstudium",
+    "studip",
+    "studium",
+    "mcp",
+    "cursor",
+    "claude",
+    "codex",
+    "windsurf",
+    "opencode"
+  ],
+  "bin": {
+    "imstudium-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build && bun run typecheck"
+  },
+  "dependencies": {
+    "@imstudium/sdk": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}