@relentlessbuild/decs-mcp 0.2.0

package/dist/tools.js

@@ -0,0 +1,304 @@
+import path from "node:path";
+import { z } from "zod";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { resolveCredentials } from "./config.js";
+import { partitionDecisions, renderDecisionContextMarkdown, toDecisionSummary } from "./decision-context.js";
+import { DecsError, toDecsError } from "./errors.js";
+import { readRepoDecsConfig, writeRepoDecsConfig } from "./repo-config.js";
+import { RelentlessApiClient } from "./relentless-api.js";
+const LIST_SCHEMA = z.object({
+    cwd: z.string().trim().min(1).optional(),
+    spaceId: z.string().trim().min(1).optional(),
+    isKeyDecision: z.boolean().optional(),
+    limit: z.number().int().positive().max(100).optional()
+});
+const GET_CONTEXT_SCHEMA = z.object({
+    cwd: z.string().trim().min(1).optional(),
+    spaceId: z.string().trim().min(1).optional(),
+    includeRecentLimit: z.number().int().positive().max(100).optional()
+});
+const CREATE_DECISION_SCHEMA = z.object({
+    cwd: z.string().trim().min(1).optional(),
+    parentId: z.string().trim().min(1).optional(),
+    title: z.string().trim().min(1),
+    what: z.string().trim().min(1),
+    why: z.string().trim().min(1),
+    purpose: z.string().trim().min(1),
+    constraints: z.string().trim().min(1),
+    isKeyDecision: z.boolean().optional()
+});
+const UPDATE_DECISION_SCHEMA = z
+    .object({
+    decisionId: z.string().trim().min(1),
+    title: z.string().trim().min(1).optional(),
+    what: z.string().trim().min(1).optional(),
+    why: z.string().trim().min(1).optional(),
+    purpose: z.string().trim().min(1).optional(),
+    constraints: z.string().trim().min(1).optional(),
+    isKeyDecision: z.boolean().optional()
+})
+    .refine((data) => data.title !== undefined ||
+    data.what !== undefined ||
+    data.why !== undefined ||
+    data.purpose !== undefined ||
+    data.constraints !== undefined ||
+    data.isKeyDecision !== undefined, "At least one field must be provided for update");
+const INIT_SPACE_SCHEMA = z.object({
+    projectNodeId: z.string().trim().min(1),
+    projectName: z.string().trim().min(1).optional(),
+    cwd: z.string().trim().min(1).optional()
+});
+const WRITE_REPO_CONFIG_SCHEMA = z.object({
+    spaceId: z.string().trim().min(1),
+    cwd: z.string().trim().min(1).optional()
+});
+const TOOLS = [
+    {
+        name: "decs_get_context",
+        description: "Fetches decision history from Relentless and returns key decisions plus recent decisions formatted for prompt context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string" },
+                spaceId: { type: "string" },
+                includeRecentLimit: { type: "number", minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "decs_list",
+        description: "Lists decisions from the configured Relentless decisions space or a supplied spaceId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string" },
+                spaceId: { type: "string" },
+                isKeyDecision: { type: "boolean" },
+                limit: { type: "number", minimum: 1, maximum: 100 }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "decs_create",
+        description: "Creates a decision node in Relentless. Use for architectural decisions after explicit user confirmation.",
+        inputSchema: {
+            type: "object",
+            required: ["title", "what", "why", "purpose", "constraints"],
+            properties: {
+                cwd: { type: "string" },
+                parentId: { type: "string" },
+                title: { type: "string" },
+                what: { type: "string" },
+                why: { type: "string" },
+                purpose: { type: "string" },
+                constraints: { type: "string" },
+                isKeyDecision: { type: "boolean" }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "decs_update",
+        description: "Updates an existing decision node by id. Missing fields are preserved from the existing node.",
+        inputSchema: {
+            type: "object",
+            required: ["decisionId"],
+            properties: {
+                decisionId: { type: "string" },
+                title: { type: "string" },
+                what: { type: "string" },
+                why: { type: "string" },
+                purpose: { type: "string" },
+                constraints: { type: "string" },
+                isKeyDecision: { type: "boolean" }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "decs_init_space",
+        description: "Creates a '<projectName> - Decisions' collection inside the supplied Relentless project node.",
+        inputSchema: {
+            type: "object",
+            required: ["projectNodeId"],
+            properties: {
+                projectNodeId: { type: "string" },
+                projectName: { type: "string" },
+                cwd: { type: "string" }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: "decs_write_repo_config",
+        description: "Writes a .decs.json file at repo root (or cwd) pointing to a Relentless decisions space id.",
+        inputSchema: {
+            type: "object",
+            required: ["spaceId"],
+            properties: {
+                spaceId: { type: "string" },
+                cwd: { type: "string" }
+            },
+            additionalProperties: false
+        }
+    }
+];
+function jsonResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            }
+        ]
+    };
+}
+function errorResult(error) {
+    const normalized = toDecsError(error);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    code: normalized.code,
+                    message: normalized.message,
+                    details: normalized.details
+                }, null, 2)
+            }
+        ]
+    };
+}
+function resolveSpaceId(input) {
+    if (input.spaceId) {
+        return input.spaceId;
+    }
+    const repoConfig = readRepoDecsConfig(input.cwd ?? process.cwd());
+    return repoConfig.config.relentlessSpaceId;
+}
+function getClient() {
+    return new RelentlessApiClient(resolveCredentials());
+}
+export function registerToolHandlers(server) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        try {
+            const toolName = request.params.name;
+            const rawArgs = request.params.arguments ?? {};
+            const client = getClient();
+            if (toolName === "decs_get_context") {
+                const args = GET_CONTEXT_SCHEMA.parse(rawArgs);
+                const spaceId = resolveSpaceId(args);
+                const decisions = (await client.listDecisions(spaceId)).map(toDecisionSummary);
+                const { keyDecisions, recentDecisions } = partitionDecisions(decisions, args.includeRecentLimit ?? 10);
+                return jsonResult({
+                    spaceId,
+                    counts: {
+                        total: decisions.length,
+                        key: keyDecisions.length,
+                        recent: recentDecisions.length
+                    },
+                    keyDecisions,
+                    recentDecisions,
+                    markdown: renderDecisionContextMarkdown({ keyDecisions, recentDecisions })
+                });
+            }
+            if (toolName === "decs_list") {
+                const args = LIST_SCHEMA.parse(rawArgs);
+                const spaceId = resolveSpaceId(args);
+                let decisions = (await client.listDecisions(spaceId)).map(toDecisionSummary);
+                if (args.isKeyDecision !== undefined) {
+                    decisions = decisions.filter((decision) => decision.isKeyDecision === args.isKeyDecision);
+                }
+                const sorted = decisions.sort((a, b) => {
+                    const aTs = a.updatedAt ? Date.parse(a.updatedAt) : 0;
+                    const bTs = b.updatedAt ? Date.parse(b.updatedAt) : 0;
+                    return bTs - aTs;
+                });
+                const limit = args.limit ?? 25;
+                return jsonResult({
+                    spaceId,
+                    total: sorted.length,
+                    decisions: sorted.slice(0, limit)
+                });
+            }
+            if (toolName === "decs_create") {
+                const args = CREATE_DECISION_SCHEMA.parse(rawArgs);
+                const parentId = args.parentId ?? resolveSpaceId(args);
+                const created = await client.createNode({
+                    kind: "decision",
+                    title: args.title,
+                    parentId,
+                    content: {
+                        what: args.what,
+                        why: args.why,
+                        purpose: args.purpose,
+                        constraints: args.constraints,
+                        isKeyDecision: args.isKeyDecision ?? false
+                    }
+                });
+                return jsonResult({
+                    created: true,
+                    decision: toDecisionSummary(created)
+                });
+            }
+            if (toolName === "decs_update") {
+                const args = UPDATE_DECISION_SCHEMA.parse(rawArgs);
+                const current = await client.getNode(args.decisionId);
+                const currentContent = (current.content ?? {});
+                const updated = await client.patchNode(args.decisionId, {
+                    title: args.title ?? current.title,
+                    content: {
+                        what: args.what ?? String(currentContent.what ?? ""),
+                        why: args.why ?? String(currentContent.why ?? ""),
+                        purpose: args.purpose ?? String(currentContent.purpose ?? ""),
+                        constraints: args.constraints ?? String(currentContent.constraints ?? ""),
+                        isKeyDecision: args.isKeyDecision ?? Boolean(currentContent.isKeyDecision === true)
+                    }
+                });
+                return jsonResult({
+                    updated: true,
+                    decision: toDecisionSummary(updated)
+                });
+            }
+            if (toolName === "decs_init_space") {
+                const args = INIT_SPACE_SCHEMA.parse(rawArgs);
+                await client.getNode(args.projectNodeId);
+                const cwd = args.cwd ?? process.cwd();
+                const projectName = args.projectName ?? path.basename(path.resolve(cwd));
+                const createdSpace = await client.createNode({
+                    kind: "collection",
+                    title: `${projectName} - Decisions`,
+                    parentId: args.projectNodeId
+                });
+                if (!createdSpace.id) {
+                    throw new DecsError("UPSTREAM_ERROR", "Relentless returned a collection without an id");
+                }
+                return jsonResult({
+                    projectNodeId: args.projectNodeId,
+                    projectName,
+                    spaceId: createdSpace.id,
+                    spaceTitle: createdSpace.title
+                });
+            }
+            if (toolName === "decs_write_repo_config") {
+                const args = WRITE_REPO_CONFIG_SCHEMA.parse(rawArgs);
+                const result = writeRepoDecsConfig(args.spaceId, args.cwd ?? process.cwd());
+                return jsonResult({
+                    saved: true,
+                    relentlessSpaceId: args.spaceId,
+                    configPath: result.path,
+                    repoRoot: result.repoRoot
+                });
+            }
+            throw new DecsError("VALIDATION_ERROR", `Unknown tool: ${toolName}`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/codex-quickstart.md

@@ -0,0 +1,59 @@
+# Codex Quickstart (DECS)
+
+This is the simplest path for Codex users.
+
+## One-Time Setup
+
+Run:
+
+```bash
+npx @relentless/decs-mcp setup codex --repo /path/to/your/repo
+```
+
+The setup command will:
+
+1. Prompt for your Relentless credentials (API key, URL, buildspace id).
+2. Save them to `~/.relentless/decs-config.json`.
+3. Add/update DECS MCP config in `~/.codex/config.toml`.
+4. Install DECS prompt shortcuts in `~/.codex/prompts/`.
+5. Merge DECS guidance into your repo `AGENTS.md`.
+
+If you cloned this repository locally, you can also run:
+
+```bash
+./install-codex.sh /path/to/your/repo
+```
+
+The local script writes Codex MCP config pointing to your local `dist/index.js`.
+
+## Enable DECS in a Repo
+
+After setup, in Codex run:
+
+```text
+npx @relentless/decs-mcp init <project-node-id> [project-name] --repo /path/to/your/repo
+```
+
+This creates a decisions collection in Relentless and writes `.decs.json` in your repo.
+
+Optional in-chat prompt command:
+
+```text
+/prompts:decs-init <project-node-id> [project-name]
+```
+
+## Daily Usage
+
+- `/prompts:decs-context`: read key/recent decisions
+- `/prompts:decs-log`: create a new decision (asks confirmation before write)
+- `/prompts:decs-update`: update an existing decision (asks confirmation before write)
+
+## Validation
+
+Run:
+
+```bash
+npx @relentless/decs-mcp doctor --repo /path/to/your/repo
+```
+
+It checks credentials, Codex MCP wiring, and `.decs.json`.

package/docs/legacy-claude-code-hooks.md

@@ -0,0 +1,37 @@
+# Legacy Claude Code Hooks Setup
+
+This is the original hook-based workflow for Claude Code CLI.
+
+## One-Time Setup
+
+```bash
+git clone https://github.com/RelentlessToph/relentless-decs.git
+cd relentless-decs
+./install.sh
+```
+
+Create `~/.claude/decs-config.json`:
+
+```json
+{
+  "relentlessApiKey": "rlnt_...",
+  "relentlessUrl": "https://relentless.build",
+  "buildspaceId": "..."
+}
+```
+
+## Enable in a Repository
+
+In Claude Code, run:
+
+```text
+/init-decs-project <project-node-id> [project-name]
+```
+
+This writes `.decs.json` and links the repository to a Relentless decisions collection.
+
+## Hook Behavior
+
+- Session start: loads prior decisions
+- Prompt submit: refreshes when decision-related keywords appear
+- Session stop: prompts decision hygiene and recording

package/docs/mcp-clients.md

@@ -0,0 +1,121 @@
+# Relentless DECS MCP Client Guide
+
+This guide covers general MCP usage plus client-specific setup.
+
+## Shared Prerequisites
+
+- Node.js 18+
+- A Relentless API key
+- Buildspace id (UUID shown in your Relentless URL)
+
+Credentials are stored in:
+
+- `~/.relentless/decs-config.json` (preferred)
+- `~/.claude/decs-config.json` (legacy fallback)
+
+Format:
+
+```json
+{
+  "relentlessApiKey": "rlnt_...",
+  "relentlessUrl": "https://relentless.build",
+  "buildspaceId": "..."
+}
+```
+
+## Codex
+
+Recommended:
+
+```bash
+npx @relentless/decs-mcp setup codex --repo /path/to/your/repo
+```
+
+Local clone alternative:
+
+```bash
+./install-codex.sh /path/to/your/repo
+```
+
+Manual target file:
+
+- `~/.codex/config.toml`
+
+Expected MCP block:
+
+```toml
+[mcp_servers.relentless_decs]
+command = "npx"
+args = ["-y", "@relentless/decs-mcp", "serve"]
+
+[mcp_servers.relentless_decs.env]
+RELENTLESS_API_KEY = "rlnt_..."
+RELENTLESS_URL = "https://relentless.build"
+RELENTLESS_BUILDSPACE_ID = "..."
+```
+
+## Claude Desktop
+
+### Manual setup
+
+Use the correct platform path:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
+
+Add:
+
+```json
+{
+  "mcpServers": {
+    "relentless-decs": {
+      "command": "npx",
+      "args": ["-y", "@relentless/decs-mcp", "serve"],
+      "env": {
+        "RELENTLESS_API_KEY": "rlnt_...",
+        "RELENTLESS_URL": "https://relentless.build",
+        "RELENTLESS_BUILDSPACE_ID": "..."
+      }
+    }
+  }
+}
+```
+
+### Optional automation
+
+```bash
+npx @relentless/decs-mcp setup claude-desktop
+```
+
+Local clone alternative:
+
+```bash
+./install-claude-desktop-mcp.sh
+```
+
+Optional flags:
+
+- `--platform macos|windows`
+- `--dry-run`
+- `--yes`
+- `--use-local-server` (for local clone installs)
+
+The command performs idempotent merge and writes a `.bak` backup before changes.
+
+## MCP Tools Exposed
+
+- `decs_get_context`
+- `decs_list`
+- `decs_create`
+- `decs_update`
+- `decs_init_space`
+- `decs_write_repo_config`
+
+## Troubleshooting
+
+- `doctor` command:
+  - `npx @relentless/decs-mcp doctor --repo /path/to/your/repo`
+- If Codex/Claude does not show tools:
+  - restart client fully
+  - confirm config path and JSON/TOML validity
+  - verify `npx -y @relentless/decs-mcp serve` runs

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@relentlessbuild/decs-mcp",
+  "version": "0.2.0",
+  "description": "Relentless DECS MCP server for Codex, Claude Desktop, and other MCP clients.",
+  "type": "module",
+  "bin": {
+    "relentless-decs-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "codex",
+    "docs",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist coverage",
+    "dev": "tsx src/index.ts",
+    "setup:codex": "tsx src/index.ts setup codex",
+    "setup:claude-desktop": "tsx src/index.ts setup claude-desktop",
+    "doctor": "tsx src/index.ts doctor",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.17.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}

package/templates/claude_desktop_config.example.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "relentless-decs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@relentless/decs-mcp",
+        "serve"
+      ],
+      "env": {
+        "RELENTLESS_API_KEY": "rlnt_your_api_key",
+        "RELENTLESS_URL": "https://relentless.build",
+        "RELENTLESS_BUILDSPACE_ID": "your-buildspace-id"
+      }
+    }
+  }
+}

package/templates/codex-config.example.toml

@@ -0,0 +1,10 @@
+# ~/.codex/config.toml
+
+[mcp_servers.relentless_decs]
+command = "npx"
+args = ["-y", "@relentless/decs-mcp", "serve"]
+
+[mcp_servers.relentless_decs.env]
+RELENTLESS_API_KEY = "rlnt_your_api_key"
+RELENTLESS_URL = "https://relentless.build"
+RELENTLESS_BUILDSPACE_ID = "your-buildspace-id"

package/templates/decs-config.example.json

@@ -0,0 +1,5 @@
+{
+  "relentlessApiKey": "rlnt_your_api_key",
+  "relentlessUrl": "https://relentless.build",
+  "buildspaceId": "your-buildspace-id"
+}