speclock 1.1.0

package/src/mcp/server.js

@@ -0,0 +1,730 @@
+import os from "os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  ensureInit,
+  setGoal,
+  addLock,
+  removeLock,
+  addDecision,
+  addNote,
+  updateDeployFacts,
+  logChange,
+  checkConflict,
+  getSessionBriefing,
+  endSession,
+  suggestLocks,
+  detectDrift,
+} from "../core/engine.js";
+import { generateContext, generateContextPack } from "../core/context.js";
+import {
+  readBrain,
+  readEvents,
+  newId,
+  nowIso,
+  appendEvent,
+  bumpEvents,
+  writeBrain,
+} from "../core/storage.js";
+import {
+  captureStatus,
+  createTag,
+  getDiffSummary,
+} from "../core/git.js";
+
+// --- Project root resolution ---
+function parseArgs(argv) {
+  const args = { project: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--project" && argv[i + 1]) {
+      args.project = argv[i + 1];
+      i++;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const PROJECT_ROOT =
+  args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
+
+// --- MCP Server ---
+const VERSION = "1.1.0";
+const AUTHOR = "Sandeep Roy";
+
+const server = new McpServer(
+  { name: "speclock", version: VERSION },
+  {
+    instructions:
+      `SpecLock is an AI continuity engine. Developed by ${AUTHOR}. Call speclock_session_briefing at the start of a new session, and speclock_session_summary before ending. Use speclock_get_context to refresh your project understanding at any time.`,
+  }
+);
+
+// ========================================
+// MEMORY MANAGEMENT TOOLS
+// ========================================
+
+// Tool 1: speclock_init
+server.tool(
+  "speclock_init",
+  "Initialize SpecLock in the current project directory. Creates .speclock/ with brain.json, events.log, and supporting directories.",
+  {},
+  async () => {
+    const brain = ensureInit(PROJECT_ROOT);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `SpecLock initialized for "${brain.project.name}" at ${brain.project.root}`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 2: speclock_get_context — THE KEY TOOL
+server.tool(
+  "speclock_get_context",
+  "THE KEY TOOL. Returns the full structured context pack including goal, locks, decisions, recent changes, deploy facts, reverts, session history, and notes. Call this at the start of every session or whenever you need to refresh your understanding of the project.",
+  {
+    format: z
+      .enum(["markdown", "json"])
+      .optional()
+      .default("markdown")
+      .describe("Output format: markdown (readable) or json (structured)"),
+  },
+  async ({ format }) => {
+    if (format === "json") {
+      const pack = generateContextPack(PROJECT_ROOT);
+      return {
+        content: [{ type: "text", text: JSON.stringify(pack, null, 2) }],
+      };
+    }
+    const md = generateContext(PROJECT_ROOT);
+    return { content: [{ type: "text", text: md }] };
+  }
+);
+
+// Tool 3: speclock_set_goal
+server.tool(
+  "speclock_set_goal",
+  "Set or update the project goal. This is the high-level objective that guides all work.",
+  {
+    text: z.string().min(1).describe("The project goal text"),
+  },
+  async ({ text }) => {
+    setGoal(PROJECT_ROOT, text);
+    return {
+      content: [{ type: "text", text: `Goal set: "${text}"` }],
+    };
+  }
+);
+
+// Tool 4: speclock_add_lock
+server.tool(
+  "speclock_add_lock",
+  "Add a non-negotiable constraint (SpecLock). These are rules that must NEVER be violated during development.",
+  {
+    text: z.string().min(1).describe("The constraint text"),
+    tags: z
+      .array(z.string())
+      .optional()
+      .default([])
+      .describe("Category tags"),
+    source: z
+      .enum(["user", "agent"])
+      .optional()
+      .default("agent")
+      .describe("Who created this lock"),
+  },
+  async ({ text, tags, source }) => {
+    const { lockId } = addLock(PROJECT_ROOT, text, tags, source);
+    return {
+      content: [
+        { type: "text", text: `Lock added (${lockId}): "${text}"` },
+      ],
+    };
+  }
+);
+
+// Tool 5: speclock_remove_lock
+server.tool(
+  "speclock_remove_lock",
+  "Remove (deactivate) a SpecLock by its ID. The lock is soft-deleted and kept in history.",
+  {
+    lockId: z.string().min(1).describe("The lock ID to remove"),
+  },
+  async ({ lockId }) => {
+    const result = removeLock(PROJECT_ROOT, lockId);
+    if (!result.removed) {
+      return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Lock removed: "${result.lockText}"`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 6: speclock_add_decision
+server.tool(
+  "speclock_add_decision",
+  "Record an architectural or design decision. Decisions guide future work and prevent contradictory changes.",
+  {
+    text: z.string().min(1).describe("The decision text"),
+    tags: z.array(z.string()).optional().default([]),
+    source: z
+      .enum(["user", "agent"])
+      .optional()
+      .default("agent"),
+  },
+  async ({ text, tags, source }) => {
+    const { decId } = addDecision(PROJECT_ROOT, text, tags, source);
+    return {
+      content: [
+        { type: "text", text: `Decision recorded (${decId}): "${text}"` },
+      ],
+    };
+  }
+);
+
+// Tool 7: speclock_add_note
+server.tool(
+  "speclock_add_note",
+  "Add a pinned note for reference. Notes persist across sessions as reminders.",
+  {
+    text: z.string().min(1).describe("The note text"),
+    pinned: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Whether to pin this note in context"),
+  },
+  async ({ text, pinned }) => {
+    const { noteId } = addNote(PROJECT_ROOT, text, pinned);
+    return {
+      content: [
+        { type: "text", text: `Note added (${noteId}): "${text}"` },
+      ],
+    };
+  }
+);
+
+// Tool 8: speclock_set_deploy_facts
+server.tool(
+  "speclock_set_deploy_facts",
+  "Record deployment configuration facts (provider, branch, auto-deploy settings).",
+  {
+    provider: z
+      .string()
+      .optional()
+      .describe("Deploy provider (vercel, railway, aws, netlify, etc.)"),
+    branch: z.string().optional().describe("Deploy branch"),
+    autoDeploy: z
+      .boolean()
+      .optional()
+      .describe("Whether auto-deploy is enabled"),
+    url: z.string().optional().describe("Deployment URL"),
+    notes: z.string().optional().describe("Additional deploy notes"),
+  },
+  async (params) => {
+    updateDeployFacts(PROJECT_ROOT, params);
+    return {
+      content: [{ type: "text", text: "Deploy facts updated." }],
+    };
+  }
+);
+
+// ========================================
+// CHANGE TRACKING TOOLS
+// ========================================
+
+// Tool 9: speclock_log_change
+server.tool(
+  "speclock_log_change",
+  "Manually log a significant change. Use this when you make an important modification that should be tracked in the context.",
+  {
+    summary: z
+      .string()
+      .min(1)
+      .describe("Brief description of the change"),
+    files: z
+      .array(z.string())
+      .optional()
+      .default([])
+      .describe("Files affected"),
+  },
+  async ({ summary, files }) => {
+    const { eventId } = logChange(PROJECT_ROOT, summary, files);
+    return {
+      content: [
+        { type: "text", text: `Change logged (${eventId}): "${summary}"` },
+      ],
+    };
+  }
+);
+
+// Tool 10: speclock_get_changes
+server.tool(
+  "speclock_get_changes",
+  "Get recent file changes tracked by SpecLock.",
+  {
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .default(20),
+  },
+  async ({ limit }) => {
+    const brain = readBrain(PROJECT_ROOT);
+    if (!brain) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "SpecLock not initialized. Run speclock_init first.",
+          },
+        ],
+        isError: true,
+      };
+    }
+    const changes = brain.state.recentChanges.slice(0, limit);
+    if (changes.length === 0) {
+      return {
+        content: [{ type: "text", text: "No changes tracked yet." }],
+      };
+    }
+    const formatted = changes
+      .map((ch) => {
+        const files =
+          ch.files && ch.files.length > 0
+            ? ` (${ch.files.join(", ")})`
+            : "";
+        return `- [${ch.at.substring(0, 19)}] ${ch.summary}${files}`;
+      })
+      .join("\n");
+    return {
+      content: [
+        { type: "text", text: `Recent changes (${changes.length}):\n${formatted}` },
+      ],
+    };
+  }
+);
+
+// Tool 11: speclock_get_events
+server.tool(
+  "speclock_get_events",
+  "Get the event log, optionally filtered by type. Event types: init, goal_updated, lock_added, lock_removed, decision_added, note_added, fact_updated, file_created, file_changed, file_deleted, revert_detected, context_generated, session_started, session_ended, manual_change, checkpoint_created.",
+  {
+    type: z.string().optional().describe("Filter by event type"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(200)
+      .optional()
+      .default(50),
+    since: z
+      .string()
+      .optional()
+      .describe("ISO timestamp; only return events after this time"),
+  },
+  async ({ type, limit, since }) => {
+    const events = readEvents(PROJECT_ROOT, { type, limit, since });
+    if (events.length === 0) {
+      return {
+        content: [{ type: "text", text: "No events found." }],
+      };
+    }
+    const formatted = events
+      .map(
+        (e) =>
+          `- [${e.at.substring(0, 19)}] ${e.type}: ${e.summary || ""}`
+      )
+      .join("\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Events (${events.length}):\n${formatted}`,
+        },
+      ],
+    };
+  }
+);
+
+// ========================================
+// CONTINUITY PROTECTION TOOLS
+// ========================================
+
+// Tool 12: speclock_check_conflict
+server.tool(
+  "speclock_check_conflict",
+  "Check if a proposed action conflicts with any active SpecLock. Use before making significant changes.",
+  {
+    proposedAction: z
+      .string()
+      .min(1)
+      .describe("Description of the action you plan to take"),
+  },
+  async ({ proposedAction }) => {
+    const result = checkConflict(PROJECT_ROOT, proposedAction);
+    return {
+      content: [{ type: "text", text: result.analysis }],
+    };
+  }
+);
+
+// Tool 13: speclock_session_briefing
+server.tool(
+  "speclock_session_briefing",
+  "Start a new session and get a full briefing. Returns context pack plus what happened since the last session. Call this at the very beginning of a new conversation.",
+  {
+    toolName: z
+      .enum(["claude-code", "cursor", "codex", "windsurf", "cline", "unknown"])
+      .optional()
+      .default("unknown")
+      .describe("Which AI tool is being used"),
+  },
+  async ({ toolName }) => {
+    const briefing = getSessionBriefing(PROJECT_ROOT, toolName);
+    const contextMd = generateContext(PROJECT_ROOT);
+
+    const parts = [];
+
+    // Session info
+    parts.push(`# SpecLock Session Briefing`);
+    parts.push(`Session started (${toolName}). ID: ${briefing.session.id}`);
+    parts.push("");
+
+    // Last session summary
+    if (briefing.lastSession) {
+      parts.push("## Last Session");
+      parts.push(`- Tool: **${briefing.lastSession.toolUsed}**`);
+      parts.push(`- Ended: ${briefing.lastSession.endedAt || "unknown"}`);
+      if (briefing.lastSession.summary)
+        parts.push(`- Summary: ${briefing.lastSession.summary}`);
+      parts.push(
+        `- Events: ${briefing.lastSession.eventsInSession || 0}`
+      );
+      parts.push(
+        `- Changes since then: ${briefing.changesSinceLastSession}`
+      );
+      parts.push("");
+    }
+
+    // Warnings
+    if (briefing.warnings.length > 0) {
+      parts.push("## ⚠ Warnings");
+      for (const w of briefing.warnings) {
+        parts.push(`- ${w}`);
+      }
+      parts.push("");
+    }
+
+    // Full context
+    parts.push("---");
+    parts.push(contextMd);
+
+    return {
+      content: [{ type: "text", text: parts.join("\n") }],
+    };
+  }
+);
+
+// Tool 14: speclock_session_summary
+server.tool(
+  "speclock_session_summary",
+  "End the current session and record what was accomplished. Call this before ending a conversation.",
+  {
+    summary: z
+      .string()
+      .min(1)
+      .describe("Summary of what was accomplished in this session"),
+  },
+  async ({ summary }) => {
+    const result = endSession(PROJECT_ROOT, summary);
+    if (!result.ended) {
+      return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+      };
+    }
+    const session = result.session;
+    const duration =
+      session.startedAt && session.endedAt
+        ? Math.round(
+            (new Date(session.endedAt) - new Date(session.startedAt)) /
+              60000
+          )
+        : 0;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Session ended. Duration: ${duration} min. Events: ${session.eventsInSession}. Summary: "${summary}"`,
+        },
+      ],
+    };
+  }
+);
+
+// ========================================
+// GIT INTEGRATION TOOLS
+// ========================================
+
+// Tool 15: speclock_checkpoint
+server.tool(
+  "speclock_checkpoint",
+  "Create a named git tag checkpoint for easy rollback.",
+  {
+    name: z
+      .string()
+      .min(1)
+      .describe("Checkpoint name (alphanumeric, hyphens, underscores)"),
+  },
+  async ({ name }) => {
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const tag = `sl_${safeName}_${Date.now()}`;
+    const result = createTag(PROJECT_ROOT, tag);
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to create checkpoint: ${result.error}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Record event
+    const brain = readBrain(PROJECT_ROOT);
+    if (brain) {
+      const eventId = newId("evt");
+      const event = {
+        eventId,
+        type: "checkpoint_created",
+        at: nowIso(),
+        files: [],
+        summary: `Checkpoint: ${tag}`,
+        patchPath: "",
+      };
+      bumpEvents(brain, eventId);
+      appendEvent(PROJECT_ROOT, event);
+      writeBrain(PROJECT_ROOT, brain);
+    }
+
+    return {
+      content: [
+        { type: "text", text: `Checkpoint created: ${tag}` },
+      ],
+    };
+  }
+);
+
+// Tool 16: speclock_repo_status
+server.tool(
+  "speclock_repo_status",
+  "Get current git repository status including branch, commit, changed files, and diff summary.",
+  {},
+  async () => {
+    const status = captureStatus(PROJECT_ROOT);
+    const diffSummary = getDiffSummary(PROJECT_ROOT);
+
+    const lines = [
+      `Branch: ${status.branch}`,
+      `Commit: ${status.commit}`,
+      "",
+      `Changed files (${status.changedFiles.length}):`,
+    ];
+
+    if (status.changedFiles.length > 0) {
+      for (const f of status.changedFiles) {
+        lines.push(`  ${f.status} ${f.file}`);
+      }
+    } else {
+      lines.push("  (clean working tree)");
+    }
+
+    if (diffSummary) {
+      lines.push("");
+      lines.push("Diff summary:");
+      lines.push(diffSummary);
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+    };
+  }
+);
+
+// ========================================
+// INTELLIGENCE TOOLS
+// ========================================
+
+// Tool 17: speclock_suggest_locks
+server.tool(
+  "speclock_suggest_locks",
+  "Analyze project decisions, notes, and patterns to suggest new SpecLock constraints. Returns auto-generated lock suggestions based on commitment language, prohibitive patterns, and common best practices.",
+  {},
+  async () => {
+    const result = suggestLocks(PROJECT_ROOT);
+
+    if (result.suggestions.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No suggestions at this time. You have ${result.totalLocks} active lock(s). Add more decisions and notes to get AI-powered lock suggestions.`,
+          },
+        ],
+      };
+    }
+
+    const formatted = result.suggestions
+      .map(
+        (s, i) =>
+          `${i + 1}. **"${s.text}"**\n   Source: ${s.source}${s.sourceId ? ` (${s.sourceId})` : ""}\n   Reason: ${s.reason}`
+      )
+      .join("\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Lock Suggestions (${result.suggestions.length})\n\nCurrent active locks: ${result.totalLocks}\n\n${formatted}\n\nTo add any suggestion as a lock, call \`speclock_add_lock\` with the text.`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 18: speclock_detect_drift
+server.tool(
+  "speclock_detect_drift",
+  "Scan recent changes and events against active SpecLock constraints to detect potential violations or drift. Use this proactively to ensure project integrity.",
+  {},
+  async () => {
+    const result = detectDrift(PROJECT_ROOT);
+
+    if (result.status === "no_locks") {
+      return {
+        content: [{ type: "text", text: result.message }],
+      };
+    }
+
+    if (result.status === "clean") {
+      return {
+        content: [{ type: "text", text: result.message }],
+      };
+    }
+
+    const formatted = result.drifts
+      .map(
+        (d) =>
+          `- [${d.severity.toUpperCase()}] Change: "${d.changeSummary}" (${d.changeAt.substring(0, 19)})\n  Lock: "${d.lockText}"\n  Matched: ${d.matchedTerms.join(", ")}`
+      )
+      .join("\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Drift Report\n\n${result.message}\n\n${formatted}\n\nReview each drift and take corrective action if needed.`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 19: speclock_health
+server.tool(
+  "speclock_health",
+  "Get a health check of the SpecLock setup including completeness score, missing recommended items, and multi-agent session timeline.",
+  {},
+  async () => {
+    const brain = ensureInit(PROJECT_ROOT);
+    const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+    // Calculate health score
+    let score = 0;
+    const checks = [];
+
+    if (brain.goal.text) { score += 20; checks.push("[PASS] Goal is set"); }
+    else checks.push("[MISS] No project goal set");
+
+    if (activeLocks.length > 0) { score += 25; checks.push(`[PASS] ${activeLocks.length} active lock(s)`); }
+    else checks.push("[MISS] No SpecLock constraints defined");
+
+    if (brain.decisions.length > 0) { score += 15; checks.push(`[PASS] ${brain.decisions.length} decision(s) recorded`); }
+    else checks.push("[MISS] No decisions recorded");
+
+    if (brain.notes.length > 0) { score += 10; checks.push(`[PASS] ${brain.notes.length} note(s)`); }
+    else checks.push("[MISS] No notes added");
+
+    if (brain.sessions.history.length > 0) { score += 15; checks.push(`[PASS] ${brain.sessions.history.length} session(s) in history`); }
+    else checks.push("[MISS] No session history yet");
+
+    if (brain.state.recentChanges.length > 0) { score += 10; checks.push(`[PASS] ${brain.state.recentChanges.length} change(s) tracked`); }
+    else checks.push("[MISS] No changes tracked");
+
+    if (brain.facts.deploy.provider !== "unknown") { score += 5; checks.push("[PASS] Deploy facts configured"); }
+    else checks.push("[MISS] Deploy facts not configured");
+
+    // Multi-agent timeline
+    const agentMap = {};
+    for (const session of brain.sessions.history) {
+      const tool = session.toolUsed || "unknown";
+      if (!agentMap[tool]) agentMap[tool] = { count: 0, lastUsed: "", summaries: [] };
+      agentMap[tool].count++;
+      if (!agentMap[tool].lastUsed || session.endedAt > agentMap[tool].lastUsed) {
+        agentMap[tool].lastUsed = session.endedAt || session.startedAt;
+      }
+      if (session.summary && agentMap[tool].summaries.length < 3) {
+        agentMap[tool].summaries.push(session.summary.substring(0, 80));
+      }
+    }
+
+    let agentTimeline = "";
+    if (Object.keys(agentMap).length > 0) {
+      agentTimeline = "\n\n## Multi-Agent Timeline\n" +
+        Object.entries(agentMap)
+          .map(([tool, info]) =>
+            `- **${tool}**: ${info.count} session(s), last active ${info.lastUsed ? info.lastUsed.substring(0, 16) : "unknown"}\n  Recent: ${info.summaries.length > 0 ? info.summaries.map(s => `"${s}"`).join(", ") : "(no summaries)"}`
+          )
+          .join("\n");
+    }
+
+    const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## SpecLock Health Check\n\nScore: **${score}/100** (Grade: ${grade})\nEvents: ${brain.events.count} | Reverts: ${brain.state.reverts.length}\n\n### Checks\n${checks.join("\n")}${agentTimeline}\n\n---\n*SpecLock v${VERSION} — Developed by ${AUTHOR}*`,
+        },
+      ],
+    };
+  }
+);
+
+// --- Start server ---
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+process.stderr.write(
+  `SpecLock MCP v${VERSION} running (stdio) — Developed by ${AUTHOR}. Root: ${PROJECT_ROOT}${os.EOL}`
+);