moodlia-sync-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+This project is licensed under the GNU General Public License, version 3 or later.
+See https://www.gnu.org/licenses/gpl-3.0.txt for the complete license text.

package/README.md

@@ -0,0 +1,95 @@
+# MoodlIA Sync MCP
+
+`moodlia-sync-mcp` is an MCP coordinator for one-way course-content synchronization between Moodle sites. Each endpoint may use Moodle Core web services, the MoodlIA plugin, or both. Provider selection is capability-based and is frozen into every approved action.
+
+It requires Node.js 22.13 or later because its durable state store uses the
+built-in SQLite API without experimental process flags.
+
+The coordinator does not send Moodle tokens or binary files through MCP tool arguments or results. Profiles reference environment variables, and an allowlist restricts profile pairs, course IDs, and effects.
+
+## Status
+
+The current preview synchronizes verified course metadata, hidden target-course creation, sections, groups and grouping membership, portable Pages/Labels/URLs, file resources and folders, Books with chapter files, selected assignment definitions and grading forms, Workshop forms, supported question banks and Quiz slots, portable Lesson pages, Database fields, Feedback items, course-completion criteria, and selected gradebook configuration. The coordinator uses the same engine and adaptive adapters as the CLI, so provider selection and advanced action semantics are identical. Existing unsupported authoring changes and unsafe transformations are reported before writing. It does not use Moodle backup files.
+
+## Configuration
+
+Create `.moodle-profiles.json`:
+
+```json
+{
+  "schema_version": 1,
+  "profiles": {
+    "source": {
+      "url": "https://source.example.edu",
+      "backend": "auto",
+      "credentials": {
+        "core": { "token_env": "SOURCE_CORE_TOKEN" },
+        "moodlia": { "token_env": "SOURCE_MOODLIA_TOKEN" }
+      }
+    },
+    "target": {
+      "url": "https://target.example.edu",
+      "backend": "auto",
+      "credentials": {
+        "core": { "token_env": "TARGET_CORE_TOKEN" },
+        "moodlia": { "token_env": "TARGET_MOODLIA_TOKEN" }
+      }
+    }
+  }
+}
+```
+
+Create `.moodle-sync-policy.json`:
+
+```json
+{
+  "schema_version": 1,
+  "allowed_profiles": ["source", "target"],
+  "allowed_pairs": [
+    {
+      "source": "source",
+      "target": "target",
+      "source_courses": [42],
+      "target_courses": [81],
+      "target_categories": [7],
+      "effects": ["content.read", "content.write"]
+    }
+  ]
+}
+```
+
+Set `MOODLIA_SYNC_CONFIG`, `MOODLIA_SYNC_POLICY`, and optionally `MOODLIA_SYNC_STATE`. Start the stdio server with `npx moodlia-sync-mcp`.
+
+For Streamable HTTP, set a random `MOODLIA_SYNC_BEARER_TOKEN` of at least 32 bytes and run `npx moodlia-sync-mcp-http`. It binds to `127.0.0.1:3333` by default. Put a TLS-authenticated reverse proxy in front of it for remote clients, set `MOODLIA_SYNC_ALLOWED_HOSTS`, and never expose the plain HTTP listener directly. The bearer token authenticates the client to the coordinator; Moodle tokens remain separate downstream credentials.
+
+## Approval boundary
+
+`sync_plan_course` is read-only. `sync_apply_plan` accepts only a plan that was approved outside MCP and stored in the same SQLite state database:
+
+```powershell
+moodlia course sync `
+  --approve-plan ".moodle-sync\plans\PLAN_ID.json" `
+  --state ".moodle-sync\coordinator.sqlite" `
+  --yes
+```
+
+Approval is bound to the complete plan digest, expires with the plan, and is consumed before execution. A model-provided boolean is never treated as human authorization.
+
+## MCP tools
+
+- `sync_list_profiles`
+- `sync_discover_capabilities`
+- `sync_plan_course`
+- `sync_get_plan` (bounded pagination across actions, conflicts, gaps, unchanged, and unknown entries)
+- `sync_apply_plan`
+- `sync_get_job`
+- `sync_cancel_job`
+- `sync_resume_job`
+- `sync_verify_course`
+- `sync_get_conflicts`
+- `sync_resolve_conflict`
+- `sync_get_history`
+
+Jobs, action attempts, approvals, mappings, baselines, and leases are durable in SQLite. On restart, in-flight jobs become `interrupted` and must be reconciled and explicitly re-approved before resume. Timeout outcomes are marked `unknown_outcome`, not retried blindly.
+
+All documentation, schemas, source identifiers, and source comments are in English.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "moodlia-sync-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP coordinator for policy-bound cross-site Moodle course synchronization.",
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "author": "Pablo Gallego",
+  "bin": {
+    "moodlia-sync-mcp": "server/stdio.mjs",
+    "moodlia-sync-mcp-http": "server/http.mjs"
+  },
+  "exports": {
+    ".": "./server/coordinator.mjs",
+    "./mcp-server": "./server/mcp-server.mjs",
+    "./http": "./server/http.mjs"
+  },
+  "files": [
+    "server/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "node --check server/coordinator.mjs && node --check server/mcp-server.mjs && node --check server/stdio.mjs && node --check server/http.mjs && npm test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "moodle-core-cli": "^0.3.0",
+    "moodlia": "^0.3.0",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/server/coordinator.mjs

@@ -0,0 +1,369 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createAdaptiveSiteAdapter } from 'moodlia/adaptive';
+import { loadContractFromFile } from 'moodlia';
+import { describeProfile, loadProfiles, resolveProfile } from 'moodle-core-cli/profiles';
+import { createCourseSyncEngine, SqliteSyncStateStore, validateSyncPlan } from 'moodle-core-cli/sync';
+
+function assertObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object.`);
+  return value;
+}
+
+function loadJson(filePath, name) {
+  return assertObject(JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8').replace(/^\uFEFF/, '')), name);
+}
+
+function defaultContractPath() {
+  return fileURLToPath(import.meta.resolve('moodlia/contract'));
+}
+
+export function loadCoordinatorPolicy(policyPath) {
+  const policy = loadJson(policyPath, 'coordinator policy');
+  if (policy.schema_version !== 1 || !Array.isArray(policy.allowed_profiles) || !Array.isArray(policy.allowed_pairs)) {
+    throw new TypeError('Coordinator policy must use schema version 1 and define allowed_profiles and allowed_pairs.');
+  }
+  return policy;
+}
+
+export class SyncCoordinator {
+  constructor({ configPath, policyPath, statePath, contractPath = defaultContractPath(), environment = process.env }) {
+    this.profiles = loadProfiles(configPath);
+    this.policy = loadCoordinatorPolicy(policyPath);
+    this.environment = environment;
+    this.contract = loadContractFromFile(contractPath);
+    fs.mkdirSync(path.dirname(path.resolve(statePath)), { recursive: true, mode: 0o700 });
+    this.store = new SqliteSyncStateStore(statePath);
+    this.engine = createCourseSyncEngine({ stateStore: this.store });
+    this.workers = new Map();
+    for (const job of this.store.listJobs()) {
+      if (!['queued', 'running', 'cancel_requested'].includes(job.status)) continue;
+      job.status = 'interrupted';
+      job.updated_at = new Date().toISOString();
+      job.error = { code: 'coordinator_restarted', message: 'The coordinator stopped before this job completed.' };
+      this.store.saveJob(job);
+    }
+  }
+
+  assertProfileAllowed(name) {
+    if (!this.policy.allowed_profiles.includes(name)) throw new TypeError(`Profile ${name} is not authorized for this coordinator.`);
+  }
+
+  pairPolicy(sourceProfile, targetProfile, sourceCourseId, targetCourseId, effect, targetCategoryId = null) {
+    this.assertProfileAllowed(sourceProfile);
+    this.assertProfileAllowed(targetProfile);
+    const pair = this.policy.allowed_pairs.find((entry) =>
+      entry.source === sourceProfile
+      && entry.target === targetProfile
+      && (entry.source_courses === '*' || entry.source_courses?.includes(sourceCourseId))
+      && (targetCourseId === null
+        ? (entry.target_categories === '*' || entry.target_categories?.includes(targetCategoryId))
+        : (entry.target_courses === '*' || entry.target_courses?.includes(targetCourseId))));
+    if (!pair || !pair.effects?.includes(effect)) {
+      throw new TypeError('The requested profile pair, course IDs, or effect is not authorized.');
+    }
+    return pair;
+  }
+
+  profile(name) {
+    this.assertProfileAllowed(name);
+    return resolveProfile(this.profiles, name, this.environment);
+  }
+
+  adapter(name, allowWrite = false) {
+    return createAdaptiveSiteAdapter({
+      profile: this.profile(name),
+      moodliaContract: this.contract,
+      allowWrite
+    });
+  }
+
+  listProfiles() {
+    return this.policy.allowed_profiles.map((name) => describeProfile(this.profiles.get(name)));
+  }
+
+  async discoverCapabilities({ profile, course_id }) {
+    const adapter = this.adapter(profile);
+    return {
+      profile: describeProfile(this.profiles.get(profile)),
+      discovery: await adapter.discoverSite(),
+      capabilities: await adapter.syncCapabilities({ courseId: course_id })
+    };
+  }
+
+  async planCourse({
+    source_profile, source_course_id, target_profile, target_course_id,
+    create_target_category_id, target_shortname, unsupported_policy, conflict_policy
+  }) {
+    const createsTarget = create_target_category_id !== undefined;
+    if ((target_course_id !== undefined) === createsTarget) {
+      throw new TypeError('Provide exactly one target_course_id or create_target_category_id.');
+    }
+    if (createsTarget && !String(target_shortname ?? '').trim()) {
+      throw new TypeError('target_shortname is required when creating a target course.');
+    }
+    const targetCourseId = target_course_id ?? null;
+    this.pairPolicy(
+      source_profile, target_profile, source_course_id, targetCourseId, 'content.read',
+      create_target_category_id ?? null
+    );
+    return this.engine.plan({
+      sourceAdapter: this.adapter(source_profile),
+      targetAdapter: this.adapter(target_profile),
+      sourceCourseId: source_course_id,
+      targetCourseId,
+      targetCreation: createsTarget ? {
+        category_id: create_target_category_id,
+        shortname: String(target_shortname)
+      } : null,
+      policies: { unsupported: unsupported_policy ?? 'error', conflict: conflict_policy ?? 'abort' }
+    });
+  }
+
+  authorizePlan(plan_id, plan_digest) {
+    const plan = this.store.getPlan(plan_id);
+    if (!plan) throw new TypeError(`Unknown sync plan: ${plan_id}.`);
+    validateSyncPlan(plan);
+    this.pairPolicy(
+      plan.source.site.profile,
+      plan.target.site.profile,
+      plan.source.course_id,
+      plan.target.course_id,
+      'content.write',
+      plan.target.creation?.category_id ?? null
+    );
+    return plan;
+  }
+
+  claimApprovedJob(plan, planDigest, job) {
+    if (!this.store.consumeApprovalAndSaveJob(plan.plan_id, planDigest, job)) {
+      throw new TypeError('This exact plan has no unconsumed external approval or it has expired.');
+    }
+    return job;
+  }
+
+  trackWorker(jobId, promise) {
+    this.workers.set(jobId, promise);
+    promise.finally(() => this.workers.delete(jobId)).catch(() => {});
+    return promise;
+  }
+
+  async applyPlan({ plan_id, plan_digest }) {
+    const plan = this.authorizePlan(plan_id, plan_digest);
+    const job = this.claimApprovedJob(plan, plan_digest, {
+      schema_version: 1,
+      job_id: randomUUID(),
+      plan_id,
+      status: 'queued',
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      results: []
+    });
+    return this.engine.apply({
+      planId: plan_id,
+      planDigest: plan_digest,
+      sourceAdapter: this.adapter(plan.source.site.profile),
+      targetAdapter: this.adapter(plan.target.site.profile, true),
+      jobId: job.job_id
+    });
+  }
+
+  startPlan({ plan_id, plan_digest }) {
+    const plan = this.authorizePlan(plan_id, plan_digest);
+    const job = {
+      schema_version: 1,
+      job_id: randomUUID(),
+      plan_id,
+      status: 'queued',
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      results: []
+    };
+    this.claimApprovedJob(plan, plan_digest, job);
+    setImmediate(() => {
+      const worker = this.engine.apply({
+        planId: plan_id,
+        planDigest: plan_digest,
+        sourceAdapter: this.adapter(plan.source.site.profile),
+        targetAdapter: this.adapter(plan.target.site.profile, true),
+        jobId: job.job_id
+      }).catch((error) => {
+        const current = this.store.getJob(job.job_id) ?? job;
+        if (['failed', 'partially_applied', 'verification_failed', 'unknown_outcome', 'cancelled'].includes(current.status)) return;
+        current.status = 'failed';
+        current.error = { name: error.name, code: error.code, message: error.message };
+        current.updated_at = new Date().toISOString();
+        this.store.saveJob(current);
+      });
+      this.trackWorker(job.job_id, worker);
+    });
+    return job;
+  }
+
+  getJob(jobId) {
+    const job = this.store.getJob(jobId);
+    if (!job) throw new TypeError(`Unknown sync job: ${jobId}.`);
+    return job;
+  }
+
+  requestCancellation(jobId) {
+    const job = this.getJob(jobId);
+    if (!['queued', 'running'].includes(job.status)) return job;
+    job.status = 'cancel_requested';
+    job.updated_at = new Date().toISOString();
+    this.store.saveJob(job);
+    return job;
+  }
+
+  resumeJob({ job_id, plan_digest }) {
+    const existingJob = this.getJob(job_id);
+    if (!['failed', 'partially_applied', 'verification_failed', 'unknown_outcome', 'cancelled', 'interrupted'].includes(existingJob.status)) {
+      throw new TypeError('Only an interrupted or failed job can be resumed.');
+    }
+    const plan = this.authorizePlan(existingJob.plan_id, plan_digest);
+    existingJob.status = 'queued';
+    existingJob.updated_at = new Date().toISOString();
+    this.claimApprovedJob(plan, plan_digest, existingJob);
+    setImmediate(() => {
+      const worker = this.engine.apply({
+        planId: plan.plan_id,
+        planDigest: plan_digest,
+        sourceAdapter: this.adapter(plan.source.site.profile),
+        targetAdapter: this.adapter(plan.target.site.profile, true),
+        resumeJobId: job_id
+      }).catch((error) => {
+        const current = this.store.getJob(job_id) ?? existingJob;
+        if (['failed', 'partially_applied', 'verification_failed', 'unknown_outcome', 'cancelled'].includes(current.status)) return;
+        current.status = current.results?.length > 0 ? 'partially_applied' : 'failed';
+        current.error = { name: error.name, code: error.code, message: error.message };
+        current.updated_at = new Date().toISOString();
+        this.store.saveJob(current);
+      });
+      this.trackWorker(job_id, worker);
+    });
+    return existingJob;
+  }
+
+  listHistory() {
+    return this.store.listJobs();
+  }
+
+  getPlan({ plan_id: planId, section = 'actions', cursor = 0, limit = 50 }) {
+    const plan = this.store.getPlan(planId);
+    if (!plan) throw new TypeError(`Unknown sync plan: ${planId}.`);
+    this.pairPolicy(
+      plan.source.site.profile,
+      plan.target.site.profile,
+      plan.source.course_id,
+      plan.target.course_id,
+      'content.read',
+      plan.target.creation?.category_id ?? null
+    );
+    const collections = {
+      actions: plan.actions ?? [],
+      conflicts: plan.conflicts ?? [],
+      divergences: plan.divergences ?? [],
+      unsupported: plan.unsupported ?? [],
+      skipped: plan.skipped ?? [],
+      unchanged: plan.unchanged ?? [],
+      unknown: plan.unknown ?? []
+    };
+    if (!Object.hasOwn(collections, section)) throw new TypeError(`Unknown plan section: ${section}.`);
+    if (!Number.isInteger(cursor) || cursor < 0) throw new TypeError('cursor must be a non-negative integer.');
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new TypeError('limit must be an integer from 1 to 100.');
+    }
+    const collection = collections[section];
+    const items = collection.slice(cursor, cursor + limit);
+    const nextCursor = cursor + items.length < collection.length ? cursor + items.length : null;
+    return {
+      plan_id: plan.plan_id,
+      digest: plan.digest,
+      schema_version: plan.schema_version,
+      created_at: plan.created_at,
+      expires_at: plan.expires_at,
+      applicable: plan.applicable,
+      action_summary: plan.action_summary,
+      policies: plan.policies,
+      section,
+      cursor,
+      limit,
+      total: collection.length,
+      next_cursor: nextCursor,
+      items
+    };
+  }
+
+  getConflicts(planId) {
+    const plan = this.store.getPlan(planId);
+    if (!plan) throw new TypeError(`Unknown sync plan: ${planId}.`);
+    this.pairPolicy(
+      plan.source.site.profile,
+      plan.target.site.profile,
+      plan.source.course_id,
+      plan.target.course_id,
+      'content.read',
+      plan.target.creation?.category_id ?? null
+    );
+    return { plan_id: planId, conflicts: plan.conflicts ?? [], divergences: plan.divergences ?? [] };
+  }
+
+  async resolveConflicts({ plan_id: planId, resolution }) {
+    if (!['source-wins', 'target-wins'].includes(resolution)) {
+      throw new TypeError('resolution must be source-wins or target-wins.');
+    }
+    const plan = this.store.getPlan(planId);
+    if (!plan) throw new TypeError(`Unknown sync plan: ${planId}.`);
+    const binding = this.store.getBinding(plan.binding_id);
+    const targetCourseId = binding?.target?.course_id ?? plan.target.course_id;
+    this.pairPolicy(
+      plan.source.site.profile,
+      plan.target.site.profile,
+      plan.source.course_id,
+      targetCourseId,
+      'content.read',
+      plan.target.creation?.category_id ?? null
+    );
+    return this.engine.plan({
+      sourceAdapter: this.adapter(plan.source.site.profile),
+      targetAdapter: this.adapter(plan.target.site.profile),
+      sourceCourseId: plan.source.course_id,
+      targetCourseId,
+      targetCreation: targetCourseId ? null : plan.target.creation,
+      mapping: plan.entity_mapping_snapshot ?? {},
+      policies: { unsupported: plan.policies.unsupported, conflict: resolution }
+    });
+  }
+
+  async verifyCourse({ plan_id: planId, job_id: jobId }) {
+    const plan = this.store.getPlan(planId);
+    if (!plan) throw new TypeError(`Unknown sync plan: ${planId}.`);
+    const binding = this.store.getBinding(plan.binding_id);
+    const targetCourseId = binding?.target?.course_id ?? plan.target.course_id;
+    this.pairPolicy(
+      plan.source.site.profile,
+      plan.target.site.profile,
+      plan.source.course_id,
+      targetCourseId,
+      'content.read',
+      plan.target.creation?.category_id ?? null
+    );
+    return this.engine.verify({
+      planId,
+      jobId,
+      targetAdapter: this.adapter(plan.target.site.profile)
+    });
+  }
+
+  async close() {
+    for (const jobId of this.workers.keys()) this.requestCancellation(jobId);
+    await Promise.allSettled([...this.workers.values()]);
+    this.store.close();
+  }
+}
+
+export function createSyncCoordinator(options) {
+  return new SyncCoordinator(options);
+}

package/server/http.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { createSyncCoordinator } from './coordinator.mjs';
+import { createMcpServer } from './mcp-server.mjs';
+
+function requiredEnvironment(environment, name) {
+  const value = environment[name];
+  if (!value) throw new TypeError(`${name} is required.`);
+  return value;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: moodlia-sync-mcp-http\n\nEnvironment:\n  MOODLIA_SYNC_CONFIG          Profile configuration JSON path (required)\n  MOODLIA_SYNC_POLICY          Coordinator policy JSON path (required)\n  MOODLIA_SYNC_BEARER_TOKEN    MCP bearer token of at least 32 bytes (required)\n  MOODLIA_SYNC_STATE           SQLite state path\n  MOODLIA_SYNC_HOST            Listen host (default: 127.0.0.1)\n  MOODLIA_SYNC_PORT            Listen port (default: 3333)\n  MOODLIA_SYNC_ALLOWED_HOSTS   Comma-separated Host allowlist\n`);
+}
+
+export function tokenMatches(header, expected) {
+  const supplied = Buffer.from(String(header ?? '').replace(/^Bearer\s+/i, ''));
+  const wanted = Buffer.from(expected);
+  return supplied.length === wanted.length && timingSafeEqual(supplied, wanted);
+}
+
+export function createAuthenticatedMcpApp({ coordinator, bearerToken, host = '127.0.0.1', allowedHosts = [] }) {
+  if (!coordinator) throw new TypeError('coordinator is required.');
+  if (Buffer.byteLength(String(bearerToken ?? '')) < 32) {
+    throw new TypeError('bearerToken must contain at least 32 bytes.');
+  }
+  const app = createMcpExpressApp({ host, ...(allowedHosts.length > 0 ? { allowedHosts } : {}) });
+  const sessions = new Map();
+  app.get('/health', (_request, response) => response.json({ status: 'ok' }));
+  app.use('/mcp', (request, response, next) => {
+    if (!tokenMatches(request.headers.authorization, bearerToken)) {
+      response.status(401).set('WWW-Authenticate', 'Bearer').json({ error: 'unauthorized' });
+      return;
+    }
+    next();
+  });
+  app.post('/mcp', async (request, response) => {
+    try {
+      const sessionId = request.headers['mcp-session-id'];
+      let session = sessionId ? sessions.get(String(sessionId)) : null;
+      if (!session && !sessionId && isInitializeRequest(request.body)) {
+        const server = createMcpServer(coordinator);
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          enableJsonResponse: true,
+          onsessioninitialized: (id) => sessions.set(id, { server, transport })
+        });
+        transport.onclose = () => {
+          if (transport.sessionId) sessions.delete(transport.sessionId);
+        };
+        await server.connect(transport);
+        session = { server, transport };
+      }
+      if (!session) {
+        response.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Invalid MCP session.' }, id: null });
+        return;
+      }
+      await session.transport.handleRequest(request, response, request.body);
+    } catch {
+      if (!response.headersSent) {
+        response.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal server error.' }, id: null });
+      }
+    }
+  });
+  for (const method of ['get', 'delete']) {
+    app[method]('/mcp', async (request, response) => {
+      const session = sessions.get(String(request.headers['mcp-session-id'] ?? ''));
+      if (!session) {
+        response.status(400).send('Invalid MCP session.');
+        return;
+      }
+      await session.transport.handleRequest(request, response);
+    });
+  }
+  return { app, sessions };
+}
+
+export function startHttpServer(environment = process.env) {
+  const host = environment.MOODLIA_SYNC_HOST ?? '127.0.0.1';
+  const port = Number(environment.MOODLIA_SYNC_PORT ?? 3333);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new TypeError('MOODLIA_SYNC_PORT is invalid.');
+  if (!['127.0.0.1', '::1', 'localhost'].includes(host)
+    && environment.MOODLIA_SYNC_ALLOW_INSECURE_HTTP !== 'true') {
+    throw new TypeError('Non-loopback HTTP requires explicit opt-in and a TLS reverse proxy.');
+  }
+  const bearerToken = requiredEnvironment(environment, 'MOODLIA_SYNC_BEARER_TOKEN');
+  const coordinator = createSyncCoordinator({
+    configPath: requiredEnvironment(environment, 'MOODLIA_SYNC_CONFIG'),
+    policyPath: requiredEnvironment(environment, 'MOODLIA_SYNC_POLICY'),
+    statePath: environment.MOODLIA_SYNC_STATE ?? '.moodle-sync/coordinator.sqlite',
+    environment
+  });
+  const allowedHosts = (environment.MOODLIA_SYNC_ALLOWED_HOSTS ?? '')
+    .split(',').map((value) => value.trim()).filter(Boolean);
+  const { app, sessions } = createAuthenticatedMcpApp({ coordinator, bearerToken, host, allowedHosts });
+  const httpServer = app.listen(port, host);
+  return { coordinator, httpServer, sessions };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  if (process.argv.slice(2).some((argument) => argument === '--help' || argument === '-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  const runtime = startHttpServer();
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, async () => {
+      runtime.httpServer.close();
+      await Promise.allSettled([...runtime.sessions.values()].map(({ server }) => server.close()));
+      await runtime.coordinator.close();
+      process.exit(0);
+    });
+  }
+}

package/server/mcp-server.mjs

@@ -0,0 +1,73 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+function jsonResult(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+
+export function createMcpServer(coordinator) {
+  const server = new McpServer({ name: 'moodlia-sync', version: '0.1.0' });
+
+  server.registerTool('sync_list_profiles', {
+    description: 'List authorized Moodle profiles without returning credentials.', inputSchema: {}
+  }, async () => jsonResult({ profiles: coordinator.listProfiles() }));
+  server.registerTool('sync_discover_capabilities', {
+    description: 'Discover live synchronization capabilities for an authorized profile.',
+    inputSchema: { profile: z.string().min(1), course_id: z.number().int().positive().optional() }
+  }, async (input) => jsonResult(await coordinator.discoverCapabilities(input)));
+  server.registerTool('sync_plan_course', {
+    description: 'Create an immutable read-only plan for one-way course synchronization.',
+    inputSchema: {
+      source_profile: z.string().min(1), source_course_id: z.number().int().positive(),
+      target_profile: z.string().min(1), target_course_id: z.number().int().positive().optional(),
+      create_target_category_id: z.number().int().positive().optional(),
+      target_shortname: z.string().min(1).optional(),
+      unsupported_policy: z.enum(['error', 'skip', 'degrade']).optional(),
+      conflict_policy: z.enum(['abort', 'source-wins', 'target-wins', 'report']).optional()
+    }
+  }, async (input) => jsonResult(await coordinator.planCourse(input)));
+  server.registerTool('sync_apply_plan', {
+    description: 'Queue an externally approved immutable plan.',
+    inputSchema: { plan_id: z.string().min(1), plan_digest: z.string().min(1) }
+  }, async (input) => jsonResult(coordinator.startPlan(input)));
+  server.registerTool('sync_get_plan', {
+    description: 'Read one authorized immutable plan section with bounded pagination.',
+    inputSchema: {
+      plan_id: z.string().min(1),
+      section: z.enum([
+        'actions', 'conflicts', 'divergences', 'unsupported', 'skipped', 'unchanged', 'unknown'
+      ]).optional(),
+      cursor: z.number().int().nonnegative().optional(),
+      limit: z.number().int().min(1).max(100).optional()
+    }
+  }, async (input) => jsonResult(coordinator.getPlan(input)));
+  server.registerTool('sync_get_job', {
+    description: 'Read a synchronization job and its verification status.',
+    inputSchema: { job_id: z.string().min(1) }
+  }, async ({ job_id }) => jsonResult(coordinator.getJob(job_id)));
+  server.registerTool('sync_cancel_job', {
+    description: 'Request that a running coordinator stop scheduling new actions.',
+    inputSchema: { job_id: z.string().min(1) }
+  }, async ({ job_id }) => jsonResult(coordinator.requestCancellation(job_id)));
+  server.registerTool('sync_resume_job', {
+    description: 'Resume an interrupted job after reconciliation and exact external re-approval.',
+    inputSchema: { job_id: z.string().min(1), plan_digest: z.string().min(1) }
+  }, async (input) => jsonResult(coordinator.resumeJob(input)));
+  server.registerTool('sync_get_conflicts', {
+    description: 'Read conflicts and target-only divergences in an immutable plan.',
+    inputSchema: { plan_id: z.string().min(1) }
+  }, async ({ plan_id }) => jsonResult(coordinator.getConflicts(plan_id)));
+  server.registerTool('sync_resolve_conflict', {
+    description: 'Replan current conflicts with an explicit policy; no writes are performed.',
+    inputSchema: { plan_id: z.string().min(1), resolution: z.enum(['source-wins', 'target-wins']) }
+  }, async (input) => jsonResult(await coordinator.resolveConflicts(input)));
+  server.registerTool('sync_verify_course', {
+    description: 'Re-read and verify a synchronization job without performing content writes.',
+    inputSchema: { plan_id: z.string().min(1), job_id: z.string().min(1).optional() }
+  }, async (input) => jsonResult(await coordinator.verifyCourse(input)));
+  server.registerTool('sync_get_history', {
+    description: 'List durable jobs visible to this policy-scoped coordinator.', inputSchema: {}
+  }, async () => jsonResult({ jobs: coordinator.listHistory() }));
+
+  return server;
+}

package/server/stdio.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createSyncCoordinator } from './coordinator.mjs';
+import { createMcpServer } from './mcp-server.mjs';
+
+function requiredEnvironment(name) {
+  const value = process.env[name];
+  if (!value) throw new TypeError(`${name} is required.`);
+  return value;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: moodlia-sync-mcp\n\nEnvironment:\n  MOODLIA_SYNC_CONFIG   Profile configuration JSON path (required)\n  MOODLIA_SYNC_POLICY   Coordinator policy JSON path (required)\n  MOODLIA_SYNC_STATE    SQLite state path (default: .moodle-sync/coordinator.sqlite)\n`);
+}
+
+if (process.argv.slice(2).some((argument) => argument === '--help' || argument === '-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+const coordinator = createSyncCoordinator({
+  configPath: requiredEnvironment('MOODLIA_SYNC_CONFIG'),
+  policyPath: requiredEnvironment('MOODLIA_SYNC_POLICY'),
+  statePath: process.env.MOODLIA_SYNC_STATE ?? '.moodle-sync/coordinator.sqlite'
+});
+const server = createMcpServer(coordinator);
+await server.connect(new StdioServerTransport());
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.once(signal, async () => {
+    await coordinator.close();
+    await server.close();
+    process.exit(0);
+  });
+}