@relentlessbuild/decs-mcp 0.2.0

package/dist/index.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { parseArgs, flagBoolean, flagString } from "./cli/args.js";
+import { logError, logStep } from "./cli/output.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runInit } from "./commands/init.js";
+import { runSetupClaudeDesktop } from "./commands/setup-claude-desktop.js";
+import { runSetupCodex } from "./commands/setup-codex.js";
+import { startMcpServer } from "./server.js";
+function printUsage() {
+    logStep("relentless-decs-mcp");
+    logStep("");
+    logStep("Usage:");
+    logStep("  relentless-decs-mcp serve");
+    logStep("  relentless-decs-mcp setup codex [--repo <path>] [--yes] [--dry-run] [--no-prompts] [--use-local-server]");
+    logStep("  relentless-decs-mcp setup claude-desktop [--platform macos|windows] [--yes] [--dry-run] [--use-local-server]");
+    logStep("  relentless-decs-mcp doctor [--repo <path>]");
+    logStep("  relentless-decs-mcp init <project-node-id> [project-name] [--repo <path>] [--bootstrap]");
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const command = parsed.positional[0] ?? "serve";
+    if (command === "help" || command === "--help" || command === "-h") {
+        printUsage();
+        return;
+    }
+    if (command === "serve") {
+        await startMcpServer();
+        return;
+    }
+    if (command === "setup") {
+        const target = parsed.positional[1];
+        const yes = flagBoolean(parsed.flags, "yes", false);
+        const dryRun = flagBoolean(parsed.flags, "dry-run", false);
+        if (target === "codex") {
+            await runSetupCodex({
+                repoPath: flagString(parsed.flags, "repo") ?? process.cwd(),
+                yes,
+                dryRun,
+                noPrompts: flagBoolean(parsed.flags, "no-prompts", false),
+                useLocalServer: flagBoolean(parsed.flags, "use-local-server", false)
+            });
+            return;
+        }
+        if (target === "claude-desktop") {
+            const platform = flagString(parsed.flags, "platform");
+            if (platform !== undefined &&
+                platform !== "macos" &&
+                platform !== "windows") {
+                throw new Error("--platform must be one of: macos, windows");
+            }
+            await runSetupClaudeDesktop({
+                yes,
+                dryRun,
+                platform: platform,
+                useLocalServer: flagBoolean(parsed.flags, "use-local-server", false)
+            });
+            return;
+        }
+        throw new Error("setup requires a target: codex | claude-desktop");
+    }
+    if (command === "doctor") {
+        runDoctor(path.resolve(flagString(parsed.flags, "repo") ?? process.cwd()));
+        return;
+    }
+    if (command === "init") {
+        const projectNodeId = parsed.positional[1];
+        const projectName = parsed.positional[2];
+        if (!projectNodeId) {
+            throw new Error("init requires <project-node-id>");
+        }
+        await runInit({
+            projectNodeId,
+            projectName,
+            repoPath: flagString(parsed.flags, "repo") ?? process.cwd(),
+            createBootstrapDecision: flagBoolean(parsed.flags, "bootstrap", false)
+        });
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+await main().catch((error) => {
+    logError(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/install/codex-assets.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ensureParentDirectory, readTextFileIfExists, writeTextFile } from "./fs-utils.js";
+const AGENTS_START = "<!-- RELENTLESS_DECS:START -->";
+const AGENTS_END = "<!-- RELENTLESS_DECS:END -->";
+const AGENTS_BLOCK = `${AGENTS_START}
+# Relentless DECS Workflow
+
+1. Before architecture-affecting work, call \`decs_get_context\`.
+2. Draft decisions with: title, what, why, purpose, constraints.
+3. Ask explicit confirmation before \`decs_create\` or \`decs_update\`.
+4. If a key decision is contradicted, explain it and ask whether to supersede.
+5. If \`.decs.json\` is missing, run DECS init flow first.
+${AGENTS_END}
+`;
+const PROMPTS = [
+    {
+        fileName: "decs-init.md",
+        content: `Initialize Relentless DECS for this repository.
+
+Arguments: <project-node-id> [project-name]
+
+1. Validate project node id.
+2. Call \`decs_init_space\`.
+3. Ask for confirmation to write \`.decs.json\`.
+4. Call \`decs_write_repo_config\`.
+5. Offer bootstrap key decision via \`decs_create\`.
+`
+    },
+    {
+        fileName: "decs-context.md",
+        content: `Load current architectural decisions.
+
+1. Call \`decs_get_context\`.
+2. Render markdown context.
+3. Highlight key decisions and contradictions for current task.
+`
+    },
+    {
+        fileName: "decs-log.md",
+        content: `Log a new architectural decision.
+
+1. Collect: title, what, why, purpose, constraints, isKeyDecision.
+2. Show payload preview.
+3. Ask explicit confirmation.
+4. Call \`decs_create\`.
+`
+    },
+    {
+        fileName: "decs-update.md",
+        content: `Update an existing architectural decision.
+
+1. If id missing, list decisions via \`decs_list\`.
+2. Collect changed fields.
+3. Show patch preview.
+4. Ask explicit confirmation.
+5. Call \`decs_update\`.
+`
+    }
+];
+export function mergeAgentsBlock(repoPath) {
+    const agentsPath = path.join(repoPath, "AGENTS.md");
+    const current = readTextFileIfExists(agentsPath);
+    if (!current) {
+        writeTextFile(agentsPath, `${AGENTS_BLOCK}\n`);
+        return { path: agentsPath, changed: true };
+    }
+    if (current.includes(AGENTS_START) && current.includes(AGENTS_END)) {
+        const next = current.replace(new RegExp(`${escapeRegExp(AGENTS_START)}[\\s\\S]*${escapeRegExp(AGENTS_END)}`), AGENTS_BLOCK.trimEnd());
+        if (next !== current) {
+            writeTextFile(agentsPath, `${next.trimEnd()}\n`);
+            return { path: agentsPath, changed: true };
+        }
+        return { path: agentsPath, changed: false };
+    }
+    const next = `${current.trimEnd()}\n\n${AGENTS_BLOCK}`;
+    writeTextFile(agentsPath, next);
+    return { path: agentsPath, changed: true };
+}
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function installPrompts(promptDir) {
+    ensureParentDirectory(path.join(promptDir, ".keep"));
+    const writtenFiles = [];
+    let changed = false;
+    for (const prompt of PROMPTS) {
+        const target = path.join(promptDir, prompt.fileName);
+        const current = readTextFileIfExists(target);
+        const next = `${prompt.content.trimEnd()}\n`;
+        if (current !== next) {
+            fs.writeFileSync(target, next, "utf8");
+            changed = true;
+        }
+        writtenFiles.push(target);
+    }
+    return { files: writtenFiles, changed };
+}

package/dist/install/fs-utils.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+export function ensureParentDirectory(filePath) {
+    const directory = path.dirname(filePath);
+    fs.mkdirSync(directory, { recursive: true });
+}
+export function writeTextFile(filePath, content, options) {
+    ensureParentDirectory(filePath);
+    fs.writeFileSync(filePath, content, {
+        encoding: "utf8",
+        mode: options?.mode
+    });
+}
+export function maybeBackupFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const backupPath = `${filePath}.bak`;
+    if (!fs.existsSync(backupPath)) {
+        fs.copyFileSync(filePath, backupPath);
+    }
+    return backupPath;
+}
+export function readTextFileIfExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return fs.readFileSync(filePath, "utf8");
+}

package/dist/install/json-merge.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+const CLAUDE_DESKTOP_SCHEMA = z.object({
+    mcpServers: z.record(z.any()).optional()
+});
+function deepEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function upsertClaudeDesktopServer(input) {
+    let parsed = {};
+    if (input.currentJson) {
+        const raw = JSON.parse(input.currentJson);
+        const validated = CLAUDE_DESKTOP_SCHEMA.safeParse(raw);
+        if (!validated.success) {
+            throw new Error(`Invalid Claude Desktop config JSON shape: ${validated.error.message}`);
+        }
+        parsed = raw;
+    }
+    const servers = typeof parsed.mcpServers === "object" && parsed.mcpServers
+        ? { ...parsed.mcpServers }
+        : {};
+    const existingServer = servers[input.serverName];
+    servers[input.serverName] = input.serverConfig;
+    parsed.mcpServers = servers;
+    return {
+        nextJson: `${JSON.stringify(parsed, null, 2)}\n`,
+        changed: !deepEqual(existingServer, input.serverConfig) || input.currentJson === null
+    };
+}

package/dist/install/paths.js

@@ -0,0 +1,27 @@
+import os from "node:os";
+import path from "node:path";
+export function getRelentlessConfigPath() {
+    return path.join(os.homedir(), ".relentless", "decs-config.json");
+}
+export function getCodexUserConfigPath() {
+    return path.join(os.homedir(), ".codex", "config.toml");
+}
+export function getCodexPromptDirPath() {
+    return path.join(os.homedir(), ".codex", "prompts");
+}
+export function resolveClaudeDesktopConfigPath(platformOverride) {
+    const platform = platformOverride ??
+        (process.platform === "darwin"
+            ? "macos"
+            : process.platform === "win32"
+                ? "windows"
+                : null);
+    if (!platform) {
+        throw new Error("Unsupported platform for Claude Desktop auto-config. Use --platform macos or --platform windows.");
+    }
+    if (platform === "macos") {
+        return path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appData, "Claude", "claude_desktop_config.json");
+}

package/dist/install/toml-merge.js

@@ -0,0 +1,31 @@
+import TOML from "@iarna/toml";
+function normalizeServerConfig(input) {
+    const normalized = {
+        command: input.command,
+        args: input.args
+    };
+    if (input.env && Object.keys(input.env).length > 0) {
+        normalized.env = input.env;
+    }
+    return normalized;
+}
+function deepEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function upsertCodexMcpServer(input) {
+    const parsed = input.currentToml
+        ? TOML.parse(input.currentToml)
+        : {};
+    const mcpServers = typeof parsed.mcp_servers === "object" && parsed.mcp_servers
+        ? { ...parsed.mcp_servers }
+        : {};
+    const desiredServer = normalizeServerConfig(input.serverConfig);
+    const existingServer = mcpServers[input.serverName];
+    mcpServers[input.serverName] = desiredServer;
+    parsed.mcp_servers = mcpServers;
+    const nextToml = TOML.stringify(parsed).trimEnd() + "\n";
+    return {
+        nextToml,
+        changed: !deepEqual(existingServer, desiredServer) || input.currentToml === null
+    };
+}

package/dist/relentless-api.js

@@ -0,0 +1,107 @@
+import { DecsError } from "./errors.js";
+function appendQuery(url, query) {
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined) {
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+}
+function mapHttpError(status, message, details) {
+    if (status === 401 || status === 403) {
+        return new DecsError("AUTH_ERROR", message, details);
+    }
+    if (status === 404) {
+        return new DecsError("NOT_FOUND", message, details);
+    }
+    if (status === 429) {
+        return new DecsError("RATE_LIMITED", message, details);
+    }
+    return new DecsError("UPSTREAM_ERROR", message, details);
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+export class RelentlessApiClient {
+    credentials;
+    fetchImpl;
+    constructor(credentials, fetchImpl = fetch) {
+        this.credentials = credentials;
+        this.fetchImpl = fetchImpl;
+    }
+    buildUrl(pathname, query) {
+        const url = new URL(pathname, this.credentials.baseUrl);
+        appendQuery(url, { buildspaceId: this.credentials.buildspaceId, ...query });
+        return url;
+    }
+    async request(method, pathname, options = {}) {
+        const url = this.buildUrl(pathname, options.query);
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        const headers = {
+            Authorization: `Bearer ${this.credentials.apiKey}`
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const attempts = 3;
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                const response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    body
+                });
+                const raw = await response.text();
+                const payload = raw.length > 0 ? safeParseJson(raw) : null;
+                if (!response.ok) {
+                    throw mapHttpError(response.status, `Relentless API request failed with status ${response.status}`, payload ?? raw);
+                }
+                return payload;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < attempts) {
+                    await sleep(attempt * 250);
+                    continue;
+                }
+            }
+        }
+        if (lastError instanceof DecsError) {
+            throw lastError;
+        }
+        throw new DecsError("UPSTREAM_ERROR", "Relentless API request failed", lastError);
+    }
+    async getNode(nodeId) {
+        return this.request("GET", `/api/nodes/${nodeId}`);
+    }
+    async listDecisions(spaceId) {
+        const result = await this.request("GET", "/api/nodes", {
+            query: {
+                parentId: spaceId,
+                kind: "decision"
+            }
+        });
+        return Array.isArray(result) ? result : [];
+    }
+    async createNode(payload) {
+        return this.request("POST", "/api/nodes", {
+            body: payload
+        });
+    }
+    async patchNode(nodeId, payload) {
+        return this.request("PATCH", `/api/nodes/${nodeId}`, {
+            body: payload
+        });
+    }
+}
+function safeParseJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return input;
+    }
+}

package/dist/repo-config.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { DecsError } from "./errors.js";
+const REPO_CONFIG_FILENAME = ".decs.json";
+const REPO_CONFIG_SCHEMA = z.object({
+    relentlessSpaceId: z.string().trim().min(1),
+    version: z.number().int().positive().optional()
+});
+function findAncestorFile(startDirectory, filename) {
+    let currentDir = path.resolve(startDirectory);
+    while (currentDir !== path.parse(currentDir).root) {
+        const candidate = path.join(currentDir, filename);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    const rootCandidate = path.join(path.parse(currentDir).root, filename);
+    if (fs.existsSync(rootCandidate)) {
+        return rootCandidate;
+    }
+    return null;
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new DecsError("CONFIG_ERROR", `Could not parse JSON file: ${filePath}`, error);
+    }
+}
+function findGitRoot(startDirectory) {
+    let currentDir = path.resolve(startDirectory);
+    while (currentDir !== path.parse(currentDir).root) {
+        const gitDir = path.join(currentDir, ".git");
+        if (fs.existsSync(gitDir)) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return null;
+}
+export function readRepoDecsConfig(cwd = process.cwd()) {
+    const configPath = findAncestorFile(cwd, REPO_CONFIG_FILENAME);
+    if (!configPath) {
+        throw new DecsError("NOT_FOUND", `No ${REPO_CONFIG_FILENAME} found in ${cwd} or parent directories`);
+    }
+    const parsed = REPO_CONFIG_SCHEMA.safeParse(readJsonFile(configPath));
+    if (!parsed.success) {
+        throw new DecsError("CONFIG_ERROR", `Invalid ${REPO_CONFIG_FILENAME} at ${configPath}`, parsed.error.flatten());
+    }
+    return {
+        path: configPath,
+        repoRoot: path.dirname(configPath),
+        config: parsed.data
+    };
+}
+export function writeRepoDecsConfig(relentlessSpaceId, cwd = process.cwd()) {
+    const repoRoot = findGitRoot(cwd) ?? path.resolve(cwd);
+    const configPath = path.join(repoRoot, REPO_CONFIG_FILENAME);
+    const payload = {
+        relentlessSpaceId,
+        version: 1
+    };
+    fs.writeFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return {
+        path: configPath,
+        repoRoot
+    };
+}

package/dist/server.js

@@ -0,0 +1,16 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerToolHandlers } from "./tools.js";
+export async function startMcpServer() {
+    const server = new Server({
+        name: "relentless-decs-mcp",
+        version: "0.2.0"
+    }, {
+        capabilities: {
+            tools: {}
+        }
+    });
+    registerToolHandlers(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}