devscribe-reason 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(''''version:'''', d.get\\(''''version''''\\)\\); print\\(''''main:'''', d.get\\(''''main''''\\)\\); print\\(''''exports keys:'''', list\\(d.get\\(''''exports'''',{}\\).keys\\(\\)\\)[:20]\\)\")",
+      "Bash(claude --version)",
+      "Read(//Users/giannihart/.claude/**)",
+      "Bash(node -e \"const http = require\\(''http''\\); const crypto = require\\(''crypto''\\); console.log\\(''http:'', typeof http.createServer\\); console.log\\(''crypto:'', typeof crypto.createHmac\\);\")",
+      "Bash(node -e \":*)",
+      "Bash(timeout 5 node src/index.js)",
+      "Bash(timeout 3 node src/index.js)",
+      "Bash(node -c src/index.js)",
+      "Bash(chmod +x scripts/setup.js)",
+      "Bash(npm install:*)",
+      "Bash(npm link:*)",
+      "Bash(devscribe-reason)",
+      "Bash(claude mcp:*)",
+      "Bash(GITHUB_TOKEN=ghp_test GITHUB_REPO=owner/repo npm run setup)",
+      "Bash(npm unlink:*)",
+      "Bash(GITHUB_TOKEN=ghp_test npm run setup)",
+      "Bash(node -c scripts/setup.js)",
+      "Bash(git -C . status --short)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,10 @@
+# Required for committing reasoning docs to GitHub
+GITHUB_TOKEN=ghp_your_personal_access_token
+# Optional: auto-detected from git remote if not set
+GITHUB_REPO=owner/repo
+GITHUB_BRANCH=main
+
+# Optional: enable GitHub webhook auto-finalization
+# Both WEBHOOK_PORT and GITHUB_WEBHOOK_SECRET must be set to activate
+# WEBHOOK_PORT=3001
+# GITHUB_WEBHOOK_SECRET=your_webhook_secret_from_github

package/README.md

@@ -0,0 +1,118 @@
+# Devscribe Reason
+
+An MCP server that automatically captures the reasoning behind engineering decisions made during Claude Code sessions and commits them as structured markdown files to `/docs/decisions/` in your GitHub repo.
+
+## The Problem
+
+When developers and AI agents write code, the reasoning behind decisions — why this approach over alternatives, what tradeoffs were made, what was considered and rejected — lives only in the chat session and disappears when it closes. Devscribe Reason captures that reasoning automatically in real time.
+
+## Quick Start
+
+**One command, 30 seconds, fully configured:**
+
+```bash
+GITHUB_TOKEN=ghp_your_personal_access_token npx devscribe-reason
+```
+
+That's it. The MCP server is now active in all your Claude Code sessions. Reasoning docs auto-commit to `/docs/decisions/`.
+
+## How It Works
+
+The server exposes four MCP tools that Claude Code calls throughout a coding session **automatically** — no manual configuration required:
+
+| Tool | When It's Called | What It Does |
+|------|-----------------|--------------|
+| `log_intent` | Start of session | Records what you're building and why |
+| `log_decision` | When a technical choice is made | Captures the decision, reasoning, and code context |
+| `log_alternative` | When an approach is rejected | Documents what was considered and why it was dropped |
+| `finalize_reasoning_doc` | When work is done | Automatically triggered when you say "we're done", "open a PR", etc. |
+
+## Setup
+
+### Option 1: NPM (Recommended)
+
+```bash
+# Install globally and configure in one step
+GITHUB_TOKEN=ghp_your_personal_access_token npx devscribe-reason
+```
+
+The setup script will:
+- Detect your Claude Code installation automatically
+- Register devscribe-reason as a user-level MCP server (works in all repos)
+- Auto-detect your GitHub repo from the current directory
+- Done! Restart Claude Code
+
+### Option 2: Docker / Development
+
+```bash
+git clone https://github.com/YOUR_USERNAME/Devscribe-Reason.git
+cd Devscribe-Reason
+npm install
+npm run setup
+```
+
+### Environment Variables
+
+**Required:**
+- `GITHUB_TOKEN` — [Personal Access Token](https://github.com/settings/tokens) with `repo` scope
+
+**Optional (auto-detected):**
+- `GITHUB_REPO` — GitHub repo (`owner/repo`), auto-detected from git remote
+- `GITHUB_BRANCH` — Target branch (default: `main`)
+
+**Optional (webhook auto-finalization):**
+- `WEBHOOK_PORT` — Port for GitHub webhook listener (e.g., `3001`)
+- `GITHUB_WEBHOOK_SECRET` — GitHub webhook secret (both env vars required to activate)
+
+## Features
+
+✅ **Zero setup** — Inject `instructions` via MCP protocol, no CLAUDE.md needed
+✅ **Automatic logging** — Captures decisions silently throughout your session
+✅ **Natural language triggers** — Say "we're done", "ship it", "open a PR" — anything works
+✅ **GitHub webhook** — Auto-finalize reasoning docs when PRs are opened (optional)
+✅ **Auto-detect repo** — Parses git remote to populate `GITHUB_REPO` automatically
+✅ **Global MCP server** — Works in every repo, configured once at user level
+
+## Output
+
+Each session produces a markdown file in `/docs/decisions/` like:
+
+```
+docs/decisions/2026-03-06-auth-refactor-oauth.md
+```
+
+With structured sections: Intent, Key Decisions, Alternatives Considered, Open Questions, and Links.
+
+## GitHub Webhook (Optional)
+
+To auto-commit reasoning docs when PRs are opened:
+
+1. Create a GitHub App or use a Personal Access Token with webhook permissions
+2. Run the server with:
+   ```bash
+   WEBHOOK_PORT=3001 GITHUB_WEBHOOK_SECRET=your_secret npm start
+   ```
+3. Add webhook in GitHub repo settings:
+   - Payload URL: `https://your-domain.com/webhook`
+   - Events: `Pull Requests`
+   - Secret: `your_secret`
+
+When a PR is opened, the reasoning doc is automatically committed to the PR's base branch.
+
+## Troubleshooting
+
+**"Could not find the 'claude' command"**
+- Ensure Claude Code CLI or VS Code/Cursor with Claude Code extension is installed
+- Reinstall: `npm run setup`
+
+**"MCP server already exists"**
+- The server is already registered. To re-register: `claude mcp remove --scope user devscribe-reason` then run setup again
+
+**Reasoning docs not committing**
+- Verify `GITHUB_TOKEN` has `repo` scope
+- Check that `GITHUB_REPO` is set correctly: `echo $GITHUB_REPO`
+- Verify the repo exists and the token has push access
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "devscribe-reason",
+  "version": "1.0.0",
+  "description": "MCP server that captures engineering decision reasoning and commits structured markdown to GitHub",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "devscribe-reason": "scripts/setup.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "setup": "node scripts/setup.js"
+  },
+  "keywords": [
+    "mcp",
+    "reasoning",
+    "decisions",
+    "documentation",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@octokit/rest": "^21.1.1",
+    "dotenv": "^16.4.7",
+    "glob": "^10.5.0",
+    "uuid": "^11.1.0"
+  }
+}

package/scripts/setup.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { globSync } from "glob";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = resolve(__dirname, "../src/index.js");
+const token = process.env.GITHUB_TOKEN || "";
+const repo = process.env.GITHUB_REPO || "";
+const branch = process.env.GITHUB_BRANCH || "main";
+
+// Try to find the claude binary in common locations
+function findClaudeBinary() {
+  // 1. Try 'which claude' if claude is in PATH
+  try {
+    const result = execSync("which claude", { stdio: "pipe", timeout: 1000 }).toString().trim();
+    if (result) return result;
+  } catch {
+    // Not in PATH
+  }
+
+  // 2. Try Cursor extensions (macOS)
+  try {
+    const cursorPattern = join(homedir(), ".cursor/extensions/*/resources/native-binary/claude");
+    const matches = globSync(cursorPattern, { absolute: true });
+    if (matches.length > 0) return matches[0];
+  } catch {
+    // globSync not available or pattern didn't match
+  }
+
+  // 3. Try VS Code extensions (macOS)
+  try {
+    const vscodePattern = join(homedir(), ".vscode/extensions/*/resources/native-binary/claude");
+    const matches = globSync(vscodePattern, { absolute: true });
+    if (matches.length > 0) return matches[0];
+  } catch {
+    // globSync not available or pattern didn't match
+  }
+
+  // 4. Try Claude Desktop installation (macOS)
+  const claudeDesktopPath = join(
+    homedir(),
+    "Library/Application Support/Claude/claude-code/claude"
+  );
+  if (existsSync(claudeDesktopPath)) return claudeDesktopPath;
+
+  // 5. Try Claude Desktop on Linux
+  const claudeLinuxPath = join(homedir(), ".local/share/Claude/claude");
+  if (existsSync(claudeLinuxPath)) return claudeLinuxPath;
+
+  return null;
+}
+
+// Build env args for the CLI
+const envArgs = [
+  token && `-e GITHUB_TOKEN=${token}`,
+  repo && `-e GITHUB_REPO=${repo}`,
+  `-e GITHUB_BRANCH=${branch}`,
+]
+  .filter(Boolean)
+  .join(" ");
+
+const claudeCmd = findClaudeBinary();
+
+if (!claudeCmd) {
+  console.error(
+    "\n❌ Could not find the 'claude' command. Please ensure you have:\n"
+  );
+  console.error("  • Claude Code CLI installed (https://claude.com/claude-code)");
+  console.error("  • Or VS Code with the Claude Code extension");
+  console.error("  • Or Cursor with Claude Code support\n");
+  console.error("After installation, run: npm run setup\n");
+  process.exit(1);
+}
+
+const cmd = `${claudeCmd} mcp add --scope user devscribe-reason node ${serverPath} ${envArgs}`;
+
+try {
+  execSync(cmd, { stdio: "inherit" });
+  console.log(
+    "\n✅ Setup complete. devscribe-reason is now active in all your Claude Code sessions."
+  );
+  console.log(
+    "\nTo verify: Open Claude Code and check Settings > MCP Servers\n"
+  );
+} catch (err) {
+  console.error("\n❌ Setup failed. Run this command manually:\n");
+  console.error(`  ${cmd}\n`);
+  process.exit(1);
+}

package/src/CLAUDE.md

@@ -0,0 +1,100 @@
+# Devscribe Reason
+
+An MCP server that automatically captures the reasoning behind engineering decisions made during Claude Code sessions and commits them as structured markdown files to `/docs/decisions/` in your GitHub repo.
+
+## The Problem
+
+When developers and AI agents write code, the reasoning behind decisions — why this approach over alternatives, what tradeoffs were made, what was considered and rejected — lives only in the chat session and disappears when it closes. Devscribe Reason captures that reasoning automatically in real time.
+
+## How It Works
+
+The server exposes four MCP tools that Claude Code calls throughout a coding session:
+
+| Tool | When It's Called | What It Does |
+|------|-----------------|--------------|
+| `log_intent` | Start of session | Records what you're building and why |
+| `log_decision` | When a technical choice is made | Captures the decision, reasoning, and code context |
+| `log_alternative` | When an approach is rejected | Documents what was considered and why it was dropped |
+| `finalize_reasoning_doc` | End of session / PR time | Builds a structured markdown doc and commits it to GitHub |
+
+## Setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/YOUR_USERNAME/Devscribe-Reason.git
+cd Devscribe-Reason
+npm install
+```
+
+### 2. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your values:
+
+```
+GITHUB_TOKEN=ghp_your_personal_access_token
+GITHUB_REPO=owner/repo
+GITHUB_BRANCH=main
+```
+
+**GitHub Token:** Create a [Personal Access Token](https://github.com/settings/tokens) with `repo` scope (or `contents: write` for fine-grained tokens).
+
+### 3. Connect to Claude Code
+
+Add this to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or via the Claude Code CLI):
+
+```json
+{
+  "mcpServers": {
+    "devscribe-reason": {
+      "command": "node",
+      "args": ["/absolute/path/to/Devscribe-Reason/src/index.js"],
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_token",
+        "GITHUB_REPO": "owner/repo",
+        "GITHUB_BRANCH": "main"
+      }
+    }
+  }
+}
+```
+
+Or using the Claude Code CLI:
+
+```bash
+claude mcp add devscribe-reason node /absolute/path/to/Devscribe-Reason/src/index.js \
+  -e GITHUB_TOKEN=ghp_your_token \
+  -e GITHUB_REPO=owner/repo \
+  -e GITHUB_BRANCH=main
+```
+
+### 4. Add system prompt instructions
+
+Add these instructions to your Claude Code system prompt (via CLAUDE.md or settings) so it uses the tools automatically:
+
+```
+When the devscribe-reason MCP server is connected:
+- Call log_intent at the start of every session before doing any work
+- Call log_decision whenever making a significant technical or architectural choice
+- Call log_alternative whenever an approach is considered and rejected
+- Call finalize_reasoning_doc when work is complete or a PR is ready
+- Never ask permission to log — just do it silently in the background
+```
+
+## Output
+
+Each session produces a markdown file in `/docs/decisions/` like:
+
+```
+docs/decisions/2026-03-06-auth-refactor-oauth.md
+```
+
+See the file for structured sections: Intent, Key Decisions, Alternatives Considered, Open Questions, and Links.
+
+## License
+
+MIT

package/src/index.js

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { Octokit } from "@octokit/rest";
+import { v4 as uuidv4 } from "uuid";
+import dotenv from "dotenv";
+import { createServer as createHttpServer } from "node:http";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+dotenv.config();
+
+// --- Session state (in-memory) ---
+
+const sessions = new Map();
+
+function getOrCreateSession(sessionId) {
+  if (!sessions.has(sessionId)) {
+    sessions.set(sessionId, {
+      id: sessionId || uuidv4(),
+      intent: null,
+      projectContext: null,
+      decisions: [],
+      alternatives: [],
+      openQuestions: [],
+      createdAt: new Date().toISOString(),
+    });
+  }
+  return sessions.get(sessionId);
+}
+
+// Use a default session for simplicity — Claude Code calls tools sequentially in one session
+const DEFAULT_SESSION = uuidv4();
+
+// --- Markdown generation ---
+
+function buildMarkdown(session, prTitle, prDescription, branch) {
+  const date = new Date().toISOString().split("T")[0];
+  const lines = [];
+
+  lines.push(`# ${prTitle}`);
+  lines.push(`**Date:** ${date}  `);
+  lines.push(`**Branch:** ${branch || process.env.GITHUB_BRANCH || "main"}  `);
+  lines.push(`**Session ID:** ${session.id}`);
+  lines.push("");
+
+  // Intent
+  lines.push("## Intent");
+  if (session.intent) {
+    lines.push(session.intent);
+    if (session.projectContext) {
+      lines.push("");
+      lines.push(`**Project context:** ${session.projectContext}`);
+    }
+  } else {
+    lines.push("_No intent was logged for this session._");
+  }
+  lines.push("");
+
+  // Key Decisions
+  lines.push("## Key Decisions");
+  if (session.decisions.length === 0) {
+    lines.push("_No decisions were logged for this session._");
+  } else {
+    session.decisions.forEach((d, i) => {
+      lines.push(`### Decision ${i + 1}: ${d.decision.split(".")[0].slice(0, 80)}`);
+      lines.push(`**What:** ${d.decision}  `);
+      lines.push(`**Why:** ${d.reasoning}  `);
+      lines.push(`**Code context:** ${d.codeContext}`);
+      lines.push("");
+    });
+  }
+  lines.push("");
+
+  // Alternatives Considered
+  lines.push("## Alternatives Considered");
+  if (session.alternatives.length === 0) {
+    lines.push("_No alternatives were logged for this session._");
+  } else {
+    session.alternatives.forEach((a, i) => {
+      lines.push(`### Alternative ${i + 1}: ${a.alternative.split(".")[0].slice(0, 80)}`);
+      lines.push(`**What was considered:** ${a.alternative}  `);
+      lines.push(`**Why rejected:** ${a.rejectionReason}`);
+      lines.push("");
+    });
+  }
+  lines.push("");
+
+  // Open Questions
+  lines.push("## Open Questions");
+  if (session.openQuestions.length === 0) {
+    lines.push("_No open questions were flagged during this session._");
+  } else {
+    session.openQuestions.forEach((q) => {
+      lines.push(`- ${q}`);
+    });
+  }
+  lines.push("");
+
+  // Links
+  lines.push("## Links");
+  if (prDescription) {
+    lines.push(`- **PR Description:** ${prDescription}`);
+  }
+  lines.push("- Related decisions: _see `/docs/decisions/` for other decision records_");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function toKebabCase(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+}
+
+// --- GitHub commit ---
+
+async function commitToGitHub(filePath, content, commitMessage, branch) {
+  const token = process.env.GITHUB_TOKEN;
+  const repo = process.env.GITHUB_REPO;
+
+  if (!token || !repo) {
+    throw new Error(
+      "Missing GITHUB_TOKEN or GITHUB_REPO environment variables. " +
+        "Set them in your .env file or environment."
+    );
+  }
+
+  const [owner, repoName] = repo.split("/");
+  const targetBranch = branch || process.env.GITHUB_BRANCH || "main";
+
+  const octokit = new Octokit({ auth: token });
+
+  // Get the latest commit SHA on the branch
+  const { data: ref } = await octokit.git.getRef({
+    owner,
+    repo: repoName,
+    ref: `heads/${targetBranch}`,
+  });
+  const latestCommitSha = ref.object.sha;
+
+  // Get the tree SHA of the latest commit
+  const { data: commit } = await octokit.git.getCommit({
+    owner,
+    repo: repoName,
+    commit_sha: latestCommitSha,
+  });
+  const treeSha = commit.tree.sha;
+
+  // Create a blob with the file content
+  const { data: blob } = await octokit.git.createBlob({
+    owner,
+    repo: repoName,
+    content: Buffer.from(content).toString("base64"),
+    encoding: "base64",
+  });
+
+  // Create a new tree with the file
+  const { data: newTree } = await octokit.git.createTree({
+    owner,
+    repo: repoName,
+    base_tree: treeSha,
+    tree: [
+      {
+        path: filePath,
+        mode: "100644",
+        type: "blob",
+        sha: blob.sha,
+      },
+    ],
+  });
+
+  // Create a new commit
+  const { data: newCommit } = await octokit.git.createCommit({
+    owner,
+    repo: repoName,
+    message: commitMessage,
+    tree: newTree.sha,
+    parents: [latestCommitSha],
+  });
+
+  // Update the branch reference
+  await octokit.git.updateRef({
+    owner,
+    repo: repoName,
+    ref: `heads/${targetBranch}`,
+    sha: newCommit.sha,
+  });
+
+  return {
+    commitSha: newCommit.sha,
+    commitUrl: newCommit.html_url,
+  };
+}
+
+// --- Finalization helper (reusable by MCP tool and webhook) ---
+
+let finalizationInFlight = false;
+
+async function runFinalization(prTitle, prDescription, branch) {
+  if (finalizationInFlight) {
+    throw new Error("Finalization is already in progress. Please wait.");
+  }
+  finalizationInFlight = true;
+  try {
+    const session = getOrCreateSession(DEFAULT_SESSION);
+    const targetBranch = branch || process.env.GITHUB_BRANCH || "main";
+    const markdown = buildMarkdown(session, prTitle, prDescription, targetBranch);
+    const date = new Date().toISOString().split("T")[0];
+    const fileName = `${date}-${toKebabCase(prTitle)}.md`;
+    const filePath = `docs/decisions/${fileName}`;
+    const commitMessage = `docs: add reasoning doc for "${prTitle}"`;
+
+    const result = await commitToGitHub(filePath, markdown, commitMessage, targetBranch);
+
+    // Clear the session after successful commit
+    sessions.delete(DEFAULT_SESSION);
+
+    return {
+      filePath,
+      commitSha: result.commitSha,
+      branch: targetBranch,
+      decisionsCount: session.decisions.length,
+      alternativesCount: session.alternatives.length,
+      hasIntent: Boolean(session.intent),
+    };
+  } finally {
+    finalizationInFlight = false;
+  }
+}
+
+// --- MCP Server setup ---
+
+const SERVER_INSTRUCTIONS = `You are connected to the devscribe-reason MCP server, which automatically documents your engineering decisions.
+
+REQUIRED BEHAVIOR - follow these rules silently without asking permission:
+
+1. SESSION START: Call log_intent immediately at the start of every session, before doing any other work. Capture what the developer is trying to build and why.
+
+2. DURING WORK: Call log_decision whenever you make any meaningful technical choice — architecture, library selection, data model design, API design, file/module structure, or implementation approach. Do not ask; just log it silently.
+
+3. DURING WORK: Call log_alternative whenever you evaluate an approach and decide against it. Do not ask; just log it silently.
+
+4. SESSION END: Call finalize_reasoning_doc when the developer indicates the session is ending. Recognize these signal phrases:
+   - "we're done", "all done", "that's it", "done for now"
+   - "open a PR", "create a PR", "make a PR", "submit a PR"
+   - "commit this", "ship it", "push this", "merge this"
+   - "finalize", "wrap up", "finish up"
+   - Any request to open or create a pull request
+
+Never ask permission before calling any of these tools. Log silently in the background.`;
+
+const server = new Server(
+  {
+    name: "devscribe-reason",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+    instructions: SERVER_INSTRUCTIONS,
+  }
+);
+
+// List tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "log_intent",
+        description:
+          "Log the intent for the current coding session. Call this at the START of every session before doing any work. Captures what the developer is trying to build and why.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            intent: {
+              type: "string",
+              description: "What the developer is trying to build or accomplish",
+            },
+            project_context: {
+              type: "string",
+              description:
+                "Relevant background context about the project, codebase, or feature area",
+            },
+          },
+          required: ["intent"],
+        },
+      },
+      {
+        name: "log_decision",
+        description:
+          "Log a significant architectural or technical decision. Call this whenever you make a meaningful choice about approach, architecture, library selection, data model design, API design, or implementation strategy. Do NOT ask the developer for permission — just log it silently.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            decision: {
+              type: "string",
+              description: "What was decided",
+            },
+            reasoning: {
+              type: "string",
+              description: "Why this approach was chosen over alternatives",
+            },
+            code_context: {
+              type: "string",
+              description:
+                "Which files, functions, or modules this decision affects",
+            },
+          },
+          required: ["decision", "reasoning", "code_context"],
+        },
+      },
+      {
+        name: "log_alternative",
+        description:
+          "Log an approach that was considered but rejected. Call this whenever you evaluate an alternative approach and decide against it. Do NOT ask the developer for permission — just log it silently.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            alternative: {
+              type: "string",
+              description: "What approach or solution was considered",
+            },
+            rejection_reason: {
+              type: "string",
+              description: "Why this approach was not chosen",
+            },
+          },
+          required: ["alternative", "rejection_reason"],
+        },
+      },
+      {
+        name: "finalize_reasoning_doc",
+        description:
+          'Finalize and commit the reasoning document for this session. Call this when the developer signals the session is ending, including: "we\'re done", "all done", "that\'s it", "done for now", "open a PR", "create a PR", "make a PR", "submit a PR", "commit this", "ship it", "push this", "merge this", "finalize", "wrap up", or "finish up". Structures all logged decisions into a clean markdown document and commits it to /docs/decisions/ in the GitHub repo.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            pr_title: {
+              type: "string",
+              description: "The PR title or feature name for this reasoning document",
+            },
+            pr_description: {
+              type: "string",
+              description: "Optional PR description or summary",
+            },
+            branch: {
+              type: "string",
+              description:
+                "Target branch to commit to. Defaults to GITHUB_BRANCH env var or 'main'",
+            },
+          },
+          required: ["pr_title"],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const session = getOrCreateSession(DEFAULT_SESSION);
+
+  try {
+    switch (name) {
+      case "log_intent": {
+        session.intent = args.intent;
+        session.projectContext = args.project_context || null;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Intent logged for session ${session.id}: "${args.intent}"`,
+            },
+          ],
+        };
+      }
+
+      case "log_decision": {
+        session.decisions.push({
+          decision: args.decision,
+          reasoning: args.reasoning,
+          codeContext: args.code_context,
+          timestamp: new Date().toISOString(),
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Decision #${session.decisions.length} logged: "${args.decision.slice(0, 80)}..."`,
+            },
+          ],
+        };
+      }
+
+      case "log_alternative": {
+        session.alternatives.push({
+          alternative: args.alternative,
+          rejectionReason: args.rejection_reason,
+          timestamp: new Date().toISOString(),
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Alternative #${session.alternatives.length} logged: "${args.alternative.slice(0, 80)}..."`,
+            },
+          ],
+        };
+      }
+
+      case "finalize_reasoning_doc": {
+        const prTitle = args.pr_title;
+        const prDescription = args.pr_description || null;
+        const branch = args.branch || process.env.GITHUB_BRANCH || "main";
+
+        try {
+          const r = await runFinalization(prTitle, prDescription, branch);
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `Reasoning document committed successfully!`,
+                  `File: ${r.filePath}`,
+                  `Commit: ${r.commitSha}`,
+                  `Branch: ${r.branch}`,
+                  ``,
+                  `Summary:`,
+                  `- ${r.decisionsCount} decisions logged`,
+                  `- ${r.alternativesCount} alternatives documented`,
+                  `- Intent: ${r.hasIntent ? "captured" : "not logged"}`,
+                ].join("\n"),
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Failed to commit reasoning doc to GitHub: ${err.message}\n\nThe document was generated but could not be committed. Check your GITHUB_TOKEN, GITHUB_REPO, and GITHUB_BRANCH environment variables.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error in ${name}: ${err.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// --- Webhook server (optional, for auto-finalization on PR open) ---
+
+function verifyGitHubSignature(rawBody, sigHeader, secret) {
+  if (!sigHeader?.startsWith("sha256=")) return false;
+  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
+  const a = Buffer.from(sigHeader);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  try {
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+function startWebhookServer(port, secret) {
+  const httpServer = createHttpServer((req, res) => {
+    // Only accept POST to /webhook
+    if (req.method !== "POST" || req.url !== "/webhook") {
+      res.writeHead(404);
+      res.end("Not found");
+      return;
+    }
+
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", async () => {
+      const rawBody = Buffer.concat(chunks);
+
+      // Verify signature
+      const sig = req.headers["x-hub-signature-256"];
+      if (!verifyGitHubSignature(rawBody, sig, secret)) {
+        console.error("[webhook] Invalid signature - rejecting request");
+        res.writeHead(401);
+        res.end("Invalid signature");
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.parse(rawBody.toString("utf8"));
+      } catch (e) {
+        res.writeHead(400);
+        res.end("Invalid JSON");
+        return;
+      }
+
+      // Only handle pull_request.opened events
+      const event = req.headers["x-github-event"];
+      if (event !== "pull_request" || payload.action !== "opened") {
+        res.writeHead(200);
+        res.end("Event ignored");
+        return;
+      }
+
+      const prTitle = payload.pull_request?.title || "Untitled PR";
+      const prUrl = payload.pull_request?.html_url || "";
+      const branch = payload.pull_request?.base?.ref || process.env.GITHUB_BRANCH || "main";
+      const prDescription = prUrl ? `PR: ${prUrl}` : null;
+
+      console.error(`[webhook] PR opened: "${prTitle}" - triggering finalization`);
+
+      try {
+        const r = await runFinalization(prTitle, prDescription, branch);
+        console.error(`[webhook] Committed ${r.filePath} (${r.commitSha})`);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, filePath: r.filePath, commitSha: r.commitSha }));
+      } catch (err) {
+        console.error(`[webhook] Finalization failed: ${err.message}`);
+        res.writeHead(500);
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+    });
+
+    req.on("error", (err) => {
+      console.error("[webhook] Request error:", err.message);
+      res.writeHead(500);
+      res.end("Internal error");
+    });
+  });
+
+  httpServer.listen(port, "127.0.0.1", () => {
+    console.error(`[webhook] Listening on http://127.0.0.1:${port}/webhook`);
+  });
+
+  httpServer.on("error", (err) => {
+    console.error(`[webhook] Server error: ${err.message}`);
+  });
+
+  return httpServer;
+}
+
+// --- Start server ---
+
+async function main() {
+  // Auto-detect GITHUB_REPO from git remote if not set
+  if (!process.env.GITHUB_REPO) {
+    try {
+      const { execSync } = await import("node:child_process");
+      const remoteUrl = execSync("git remote get-url origin", {
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 3000,
+      })
+        .toString()
+        .trim();
+      const match =
+        remoteUrl.match(/git@github\.com:([^/]+\/[^/]+?)(?:\.git)?$/) ||
+        remoteUrl.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
+      if (match) {
+        process.env.GITHUB_REPO = match[1];
+        console.error(`[auto-detect] GITHUB_REPO set to: ${process.env.GITHUB_REPO}`);
+      }
+    } catch {
+      // Not a git repo, or git not installed, or no remote — silently ignore
+    }
+  }
+
+  // Start webhook server if opt-in env vars are present
+  const webhookPort = process.env.WEBHOOK_PORT
+    ? parseInt(process.env.WEBHOOK_PORT, 10)
+    : null;
+  const webhookSecret = process.env.GITHUB_WEBHOOK_SECRET || null;
+
+  if (webhookPort && webhookSecret) {
+    startWebhookServer(webhookPort, webhookSecret);
+  } else if (webhookPort || webhookSecret) {
+    console.error(
+      "[webhook] Skipped: both WEBHOOK_PORT and GITHUB_WEBHOOK_SECRET must be set to enable the webhook server."
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Devscribe Reason MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});