@scopelock/mcp 0.1.0-beta.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,14 @@
+# @scopelock/mcp
+
+The narrow stdio MCP server for
+[ScopeLock](https://github.com/Daewooox/ScopeLock). It exposes deterministic
+scope conflict, scheduling, and drift-verification tools.
+
+The package has not been published to npm yet. Until the first beta release,
+build the repository and run `node packages/mcp/dist/index.js` from source.
+After publication, the intended command is `npx --yes @scopelock/mcp@beta`.
+
+The server is pinned to its startup repository and does not provide a generic
+agent runtime.
+
+MIT licensed. Requires Node.js 22 or newer.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createScopeLockMcpServer } from "./tools.js";
+async function main() {
+    const server = createScopeLockMcpServer();
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`ScopeLock MCP server failed: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/tools.d.ts

@@ -0,0 +1,64 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type TaskScope } from "@scopelock/core";
+export declare const SERVER_NAME = "scopelock";
+export declare const SERVER_VERSION = "0.1.0";
+export declare function planParallelTool(input: {
+    plan: unknown;
+    includeReadHazards?: boolean;
+}, serverRepoRoot?: string): Promise<{
+    planId: string;
+    waves: string[][];
+    conflicts: import("@scopelock/core").ScopeConflict[];
+    cycles: string[][];
+}>;
+export declare function scopesConflictTool(input: {
+    a: TaskScope;
+    b: TaskScope;
+}): {
+    conflict: boolean;
+    detail: import("@scopelock/core").ScopeConflict | null;
+};
+export declare function checkDriftTool(input?: {
+    base?: string;
+}, serverRepoRoot?: string): Promise<{
+    ok: boolean;
+    reportPath: string;
+    report: {
+        schemaVersion: 1;
+        contractId: string;
+        checkedAt: string;
+        repoMode: "normal" | "degraded" | "refused";
+        repoState: {
+            kind: "clean";
+        } | {
+            kind: "merge";
+        } | {
+            kind: "rebase";
+        } | {
+            kind: "cherry-pick";
+        } | {
+            kind: "revert";
+        } | {
+            kind: "am";
+        } | {
+            kind: "bisect";
+        };
+        changedFiles: {
+            path: string;
+            previousPath: string | null;
+            status: "modified" | "added" | "deleted" | "renamed" | "copied" | "untracked" | "conflicted";
+            stage: "untracked" | "conflicted" | "staged" | "unstaged";
+            isBinary: boolean;
+            insertions: number;
+            deletions: number;
+            sizeBytes: number;
+        }[];
+        violations: {
+            type: "outside_scope" | "forbidden_path" | "missing_tests" | "high_risk_file" | "repo_state" | "repo_mode";
+            path: string | null;
+            message: string;
+        }[];
+        contractIds?: string[] | undefined;
+    };
+}>;
+export declare function createScopeLockMcpServer(repoRoot?: string): McpServer;

package/dist/tools.js

@@ -0,0 +1,167 @@
+import { readFile, realpath } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { approvedContractSchema, buildConflictGraph, buildDriftReport, collectChangedFiles, commitExists, driftReportFileName, findRepoRoot, getActiveContractId, loadContract, schedule, schedulePlanSchema, scopelockConfigSchema, scopelockPaths, scopesConflict, verifyApprovalSeal, writeJsonAtomic, } from "@scopelock/core";
+import { join } from "node:path";
+import { z } from "zod/v4";
+export const SERVER_NAME = "scopelock";
+export const SERVER_VERSION = "0.1.0";
+const taskScopeInputSchema = z.object({
+    id: z.string().min(1),
+    planned: z.array(z.string().min(1)),
+    forbidden: z.array(z.string().min(1)).default([]),
+    read: z.array(z.string().min(1)).default([]),
+});
+const planParallelInputSchema = {
+    plan: z.unknown().describe("A ScopeLock schedule plan JSON object."),
+    includeReadHazards: z.boolean().optional().default(false),
+};
+const scopesConflictInputSchema = {
+    a: taskScopeInputSchema,
+    b: taskScopeInputSchema,
+};
+const checkDriftInputSchema = {
+    base: z.string().min(1).optional(),
+};
+function jsonContent(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        structuredContent: value,
+    };
+}
+function resolveFromRoot(repoRoot, path) {
+    if (isAbsolute(path)) {
+        throw new Error("contract paths must be relative to the MCP server repo root");
+    }
+    const resolved = resolve(repoRoot, path);
+    const rel = relative(repoRoot, resolved);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("contract path escapes the MCP server repo root");
+    }
+    return resolved;
+}
+async function readJsonFile(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function loadTaskScope(repoRoot, task) {
+    const contractPath = await realpath(resolveFromRoot(repoRoot, task.contract));
+    const rel = relative(repoRoot, contractPath);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("contract path resolves outside the MCP server repo root");
+    }
+    const raw = await readJsonFile(contractPath);
+    const contract = approvedContractSchema.parse(raw);
+    return scopeFromContract(task.id, contract);
+}
+function scopeFromContract(id, contract) {
+    return {
+        id,
+        planned: contract.scope.plannedPathPatterns,
+        forbidden: contract.scope.forbiddenPathPatterns,
+        read: contract.scope.readPathPatterns,
+    };
+}
+async function loadConfig(paths) {
+    try {
+        const raw = await readFile(paths.configPath, "utf8");
+        return scopelockConfigSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return scopelockConfigSchema.parse({ schemaVersion: 1 });
+        }
+        throw error;
+    }
+}
+function requireRepoRoot(candidate) {
+    const root = findRepoRoot(candidate ?? process.cwd());
+    if (root === null) {
+        throw new Error("ScopeLock MCP tools must run inside a git repository");
+    }
+    return realpathSync(root);
+}
+export async function planParallelTool(input, serverRepoRoot) {
+    const repoRoot = requireRepoRoot(serverRepoRoot);
+    const plan = schedulePlanSchema.parse(input.plan);
+    const scopes = [];
+    for (const task of plan.tasks) {
+        scopes.push(await loadTaskScope(repoRoot, task));
+    }
+    const graph = buildConflictGraph(scopes, { readHazards: input.includeReadHazards === true });
+    const result = schedule(graph);
+    return {
+        planId: plan.planId,
+        waves: result.waves,
+        conflicts: graph.conflicts,
+        cycles: result.cycles,
+    };
+}
+export function scopesConflictTool(input) {
+    const a = taskScopeInputSchema.parse(input.a);
+    const b = taskScopeInputSchema.parse(input.b);
+    const conflict = scopesConflict(a, b);
+    return {
+        conflict: conflict !== null,
+        detail: conflict,
+    };
+}
+export async function checkDriftTool(input = {}, serverRepoRoot) {
+    const repoRoot = requireRepoRoot(serverRepoRoot);
+    const paths = scopelockPaths(repoRoot);
+    const config = await loadConfig(paths);
+    const activeId = await getActiveContractId(paths);
+    if (activeId === null) {
+        throw new Error("no active approved contract; approve one with `scopelock contract approve <file>`");
+    }
+    const contract = await loadContract(paths, activeId);
+    const approvalIntegrity = await verifyApprovalSeal(repoRoot, contract);
+    if (!approvalIntegrity.ok) {
+        throw new Error(`approval integrity failed: ${approvalIntegrity.detail}`);
+    }
+    const baselineSha = input.base ?? contract.baseline?.headSha ?? null;
+    if (baselineSha === null) {
+        throw new Error("active contract has no baseline; approve it with `scopelock contract approve <file>`");
+    }
+    if (!commitExists(repoRoot, baselineSha)) {
+        throw new Error(`baseline commit ${baselineSha} not found (history rewritten?); run \`scopelock contract rebaseline\``);
+    }
+    const collected = await collectChangedFiles(repoRoot, baselineSha, {
+        degradedThreshold: config.degradedFileThreshold,
+    });
+    const checkedAt = new Date().toISOString();
+    const report = buildDriftReport({
+        contract,
+        files: collected.files,
+        repoState: collected.repoState,
+        repoMode: collected.repoMode,
+        projectTypes: config.projectTypes,
+        checkedAt,
+    });
+    const reportPath = join(paths.reportsDir, driftReportFileName(checkedAt));
+    await writeJsonAtomic(reportPath, report);
+    return {
+        ok: report.violations.length === 0,
+        reportPath,
+        report,
+    };
+}
+export function createScopeLockMcpServer(repoRoot = requireRepoRoot()) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    server.registerTool("plan_parallel", {
+        title: "Plan Parallel",
+        description: "Build a deterministic ScopeLock wave schedule from a plan JSON object and draft/approved contract files.",
+        inputSchema: planParallelInputSchema,
+    }, async (input) => jsonContent(await planParallelTool(input, repoRoot)));
+    server.registerTool("scopes_conflict", {
+        title: "Scopes Conflict",
+        description: "Check whether two ScopeLock task scopes conflict and return the concrete witness.",
+        inputSchema: scopesConflictInputSchema,
+    }, async (input) => jsonContent(scopesConflictTool(input)));
+    server.registerTool("check_drift", {
+        title: "Check Drift",
+        description: "Run ScopeLock drift verification for the active approved contract in a git repository.",
+        inputSchema: checkDriftInputSchema,
+    }, async (input) => jsonContent(await checkDriftTool(input, repoRoot)));
+    return server;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@scopelock/mcp",
+  "version": "0.1.0-beta.1",
+  "description": "MCP stdio server for ScopeLock's narrow planning and drift-verification tools.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "scopelock-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/tools.d.ts",
+    "dist/tools.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Daewooox/ScopeLock.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/Daewooox/ScopeLock#readme",
+  "bugs": {
+    "url": "https://github.com/Daewooox/ScopeLock/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-coding-agents",
+    "scope-control",
+    "developer-tools"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3",
+    "@scopelock/core": "^0.1.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test dist/*.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}