debug-ledger-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hi0001234d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# debug-ledger
+
+*AI should debug with memory, not amnesia.*
+
+`debug-ledger` exists because AI-assisted debugging repeatedly breaks old fixes, removes “weird” code that exists for a reason, and reintroduces bugs teams already paid for in the past. Code survives. Debug context doesn’t. This project preserves that lost memory in a form AI tools can actually see.
+
+---
+
+## Example: AI Debug With Memory
+![Example: AI Debug With Memory](./example-ai-debug-with-memory.gif)
+
+**Note:** Do not forget to add this line **"Before starting, call the list_ledger_files MCP tool and show me the output."** at last in every prompt when you want to apply your project constraint or debug memory.
+
+---
+
+## The Problem
+
+AI tools are very good at understanding code as it exists today.  
+They are very bad at understanding *why* code exists the way it does.
+
+In real, long-lived software:
+- Bugs repeat  
+- Fixes regress  
+- Tests look unnecessary but are critical  
+- “Ugly” code often protects against past failures  
+
+Humans remember this history.  
+AI does not.
+
+So AI:
+- Suggests fixes that already failed before  
+- Cleans up code that hides old landmines  
+- Breaks systems in ways that feel _obviously avoidable_ to maintainers  
+
+This isn’t a model intelligence problem.  
+It’s a *missing memory problem*.
+
+---
+
+## What `debug-ledger` Is
+
+`debug-ledger` is a *read-only, repo-local debug memory*.
+
+It is a small, human-written ledger that documents:
+- Past incidents that mattered  
+- Fixes that were tried and rejected  
+- Regressions that came back  
+- Constraints that must not be violated again  
+
+This ledger lives *inside the repository*, versioned with the code, and is exposed to AI tools so they can *see historical truth before suggesting changes*.
+
+It does not tell AI _what to do_.  
+It reminds AI _what already happened_.
+
+---
+
+## What `debug-ledger` Is NOT
+
+`debug-ledger` is *not*:
+- An error tracker  
+- An observability system  
+- A test framework  
+- A policy engine  
+- An autonomous agent  
+- A bug-fixing tool  
+
+It does not:
+- Enforce rules  
+- Block changes  
+- Decide correctness  
+- Automate debugging  
+
+It only preserves memory.
+
+---
+
+## How It Fits Into AI Editors & MCP
+
+AI editors already read your code.  
+`debug-ledger` lets them read your *debug history*.
+
+Using MCP (Model Context Protocol), the ledger is exposed as *read-only context* that AI tools can consult *before* proposing fixes or refactors.
+
+The flow is simple:
+1. Developer asks AI to debug or change code  
+2. MCP surfaces relevant ledger entries (if any exist)  
+3. AI responds with awareness of past failures and constraints  
+
+If no historical context exists, nothing changes.  
+MCP is a delivery mechanism — not the product.
+
+---
+
+## Why It’s Intentionally Simple
+
+Most valuable maintenance knowledge is:
+- Sparse  
+- Expensive to learn  
+- Easy to forget  
+- Hard to rediscover  
+
+So `debug-ledger` is deliberately simple:
+- Plain text  
+- Human-written  
+- Read-only for AI  
+- No automation  
+- No inference  
+- No hidden logic  
+
+If it becomes clever, it becomes fragile.  
+If it becomes heavy, people stop using it.  
+Simplicity is the feature.
+
+---
+
+## How to Try It (Conceptually)
+
+You don’t need new workflows.
+1. Add a ledger entry after a painful bug or incident.  
+Create the entry inside the `debug_ledger` folder in the cloned MCP project.  
+Create a new `.md` file with a meaningful name for your entry and add it there. The file name must start with one of the supported prefixes: `constraints`, `incidents`, `regressions`, or `rejected_fixes`.
+2. Keep your entry short and factual  
+3. Explain what failed and what must not be repeated  
+4. Let AI tools see it during future debugging sessions  
+
+If nothing painful happened, don’t write anything.  
+The ledger grows slowly — only when reality demands it.
+
+---
+
+## Quick Start
+
+## Installation
+
+1. Open your project in VS Code.
+
+2. Clone the debug-ledger repository from GitHub using the following command.
+
+```bash
+git clone https://github.com/bhavnesh75/debug-ledger.git
+```
+
+3. Open the terminal.
+
+```bash
+cd debug-ledger
+npm install
+npm run build
+```
+
+4. After running the above commands, the build file will be available in your project at:
+
+```
+debug-ledger/dist/mcp/server.js
+```
+
+5. Open your editor MCP settings file.  
+(If you are using editors like Kilo Code, Cursor, or any other editor that supports MCP.)
+Add the following MCP configuration in your project MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "debug-ledger": {
+      "command": "node",
+      "args": ["dist/mcp/server.js"],
+      "cwd": "your debug-ledger repo path"
+    }
+  }
+}
+```
+6. Replace your `debug-ledger repo path` with the actual path of your `debug-ledger` folder.
+
+**Note:** Do not forget to add this line **"Before starting, call the list_ledger_files MCP tool and show me the output."** at last in every prompt when you want to apply your project constraint or debug memory.
+
+---
+
+## Contributing
+
+We welcome contributions! Please see:
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute  
+
+---
+
+## Kill Criteria
+
+This experiment should be considered a failure if:
+- Developers don’t recognize the problem immediately  
+- The ledger fills with low-value noise  
+- People ask for automation before understanding the idea  
+- It turns into governance, enforcement, or policy  
+- It only makes sense with MCP and nowhere else  
+
+Killing this early is a valid outcome.
+
+---
+
+*Code shows what exists.  
+Debug ledger explains why it must stay that way.*

package/dist/mcp/context-policy.js

@@ -0,0 +1,24 @@
+/**
+  POLICY = prefix based configuration
+ * NO filenames here
+ * ONLY category prefixes
+ */
+export const CONTEXT_POLICY = {
+    minimal: [
+        "constraints-",
+    ],
+    normal: [
+        "constraints-",
+        "regressions-",
+    ],
+    deep: [
+        "constraints-",
+        "regressions-",
+        "incidents-",
+        "rejected_fixes-",
+    ],
+};
+export const DEFAULT_CONTEXT_LEVEL = "normal";
+export function isValidContextLevel(level) {
+    return level === "minimal" || level === "normal" || level === "deep";
+}

package/dist/mcp/contextAssembler.js

@@ -0,0 +1,54 @@
+import { readLedgerFile } from "./ledgerReader.js";
+/**
+ * C3 — Context Assembly
+ * Handles:
+ *  - Single file
+ *  - Multiple files
+ *  - Separators: , | space \n \t
+ *  - Returns structured AI-ready context
+ */
+export function assembleLedgerContext(input) {
+    if (!input || typeof input !== "string") {
+        throw new Error("Invalid file input");
+    }
+    // Normalize separators:
+    // Replace , | newline tab multiple spaces with single comma
+    // const normalized = input
+    //   .replace(/\|/g, ",")
+    //   .replace(/\n/g, ",")
+    //   .replace(/\t/g, ",")
+    //   .replace(/\s+/g, ",")
+    //   .split(",")
+    //   .map((f) => f.trim())
+    //   .filter((f) => f.length > 0);
+    const rawFiles = input
+        .toLowerCase()
+        .replace(/["']/g, "")
+        .replace(/\(.*?\)/g, "")
+        .replace(/\band\b/g, ",")
+        .replace(/&/g, ",")
+        .replace(/^- /gm, "")
+        .replace(/^• /gm, "")
+        .replace(/\bfiles?:/g, "")
+        .replace(/[\r\n\t|;]+/g, ",")
+        .replace(/\s+/g, ",")
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean)
+        .map((f) => f.replace(/[^a-z0-9._-]/gi, ""));
+    // Remove duplicate filenames
+    const uniqueFiles = [...new Set(rawFiles)];
+    let finalContext = "";
+    for (const fileName of uniqueFiles) {
+        try {
+            const content = readLedgerFile(fileName);
+            finalContext += `\n=== ${fileName} ===\n`;
+            finalContext += content + "\n";
+        }
+        catch (error) {
+            finalContext += `\n=== ${fileName} ===\n`;
+            finalContext += `Error reading file: ${error.message}\n`;
+        }
+    }
+    return finalContext.trim();
+}

package/dist/mcp/contextSelector.js

@@ -0,0 +1,24 @@
+import { CONTEXT_POLICY, DEFAULT_CONTEXT_LEVEL, isValidContextLevel, } from "./context-policy.js";
+import { listLedgerFiles } from "./ledgerIndexer.js";
+/**
+ * C2 — Context Selection Engine
+ *
+ * 1. Reads available ledger files (B1)
+ * 2. Applies prefix policy
+ * 3. Returns matching filenames
+ */
+export function selectContextFiles(requestedLevel) {
+    let level = DEFAULT_CONTEXT_LEVEL;
+    if (requestedLevel && isValidContextLevel(requestedLevel)) {
+        level = requestedLevel;
+    }
+    // prefixes allowed for this level
+    const allowedPrefixes = CONTEXT_POLICY[level];
+    // get all ledger files (from B1)
+    const files = listLedgerFiles();
+    // filter by prefix
+    const selectedFiles = files
+        .map((f) => f.name)
+        .filter((fileName) => allowedPrefixes.some((prefix) => fileName.startsWith(prefix)));
+    return selectedFiles;
+}

package/dist/mcp/ledgerIndexer.js

@@ -0,0 +1,26 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Absolute path to debug_ledger folder
+ * (server.ts થી run થાય ત્યારે correct resolve થાય)
+ */
+const LEDGER_DIR = path.resolve(process.cwd(), "debug_ledger");
+/**
+ * B1 — List all ledger files
+ * ONLY discovery logic (no parsing, no filtering)
+ */
+export function listLedgerFiles() {
+    // check folder exists
+    if (!fs.existsSync(LEDGER_DIR)) {
+        throw new Error("debug_ledger folder not found");
+    }
+    const files = fs.readdirSync(LEDGER_DIR);
+    // only markdown files
+    const ledgerFiles = files
+        .filter((file) => file.endsWith(".md") && file !== "README.md")
+        .map((file) => ({
+        name: file,
+        path: path.join(LEDGER_DIR, file),
+    }));
+    return ledgerFiles;
+}

package/dist/mcp/ledgerReader.js

@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+const LEDGER_DIR = path.resolve(process.cwd(), "debug_ledger");
+/**
+ * Normalize incoming filename string
+ * Supports multiple separators
+ */
+function extractFileNames(input) {
+    return input
+        .split(/[,|\s;\n]+/) // comma | pipe | space | newline | semicolon
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+}
+/**
+ * Read single ledger file safely
+ */
+function readSingleFile(fileName) {
+    if (!fileName.endsWith(".md")) {
+        throw new Error(`Invalid file type: ${fileName}`);
+    }
+    const filePath = path.join(LEDGER_DIR, fileName);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Ledger file not found: ${fileName}`);
+    }
+    return fs.readFileSync(filePath, "utf-8");
+}
+/**
+ * B2 — Multi-file supported reader
+ */
+export function readLedgerFile(input) {
+    const fileNames = extractFileNames(input);
+    if (fileNames.length === 0) {
+        throw new Error("No valid ledger file provided");
+    }
+    let finalOutput = "";
+    for (const file of fileNames) {
+        const content = readSingleFile(file);
+        finalOutput +=
+            `===== ${file} =====\n` +
+                `${content}\n\n`;
+    }
+    return finalOutput.trim();
+}

package/dist/mcp/server.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { assembleLedgerContext } from "./contextAssembler.js";
+/**
+ * debug-ledger MCP server
+ *
+ * NOTE:
+ * - This file defines ONLY structure and boundaries
+ * - Business logic is intentionally NOT implemented here
+ * - All real logic must come via PRs
+ */
+const server = new Server({
+    name: "debug-ledger",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+import { listLedgerFiles } from "./ledgerIndexer.js";
+const files = listLedgerFiles();
+/**
+ * Tool registry
+ * These describe WHAT the server exposes, not HOW it works
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "list_ledger_files",
+                description: "List available debug ledger files",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "read_ledger_file",
+                description: "Read a specific debug ledger file",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filename: {
+                            type: "string",
+                            description: "Ledger file name",
+                        },
+                    },
+                    required: ["filename"],
+                },
+            },
+        ],
+    };
+});
+/**
+ * Tool execution handler
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name } = request.params;
+    // BUSINESS LOGIC IMPLEMENTED IN PRs
+    // This skeleton intentionally returns placeholders only
+    switch (name) {
+        case "list_ledger_files": {
+            const files = listLedgerFiles();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(files, null, 2),
+                    },
+                ],
+            };
+        }
+        case "read_ledger_file": {
+            const { filename } = request.params.arguments;
+            const assembledContext = assembleLedgerContext(filename);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: assembledContext,
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+/**
+ * Server bootstrap
+ */
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("debug-ledger MCP server failed to start:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "debug-ledger-mcp",
+  "version": "0.1.0",
+  "description": "Read-only debug memory for AI — a repo-local ledger of past bugs, rejected fixes, and historical constraints so AI debugs with context, not amnesia.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "debug-ledger-mcp": "./dist/mcp/server.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/mcp/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  }
+}