@mhrj/mcp-agent-loop 1.0.0

package/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: Agentic Loop Memory Server
+description: A powerful persistent memory and state-management system serving to allow any AI to execute autonomous agent loops, self-heal, and prevent context window exhaustion.
+---
+
+# Agentic Loop Memory Server Skill ♾️
+
+This skill connects you to the \`@mhrj/mcp-agent-loop\` server. This server provides you with persistent memory, preventing you from forgetting your overarching goal or crashing due to context window limits when working on complex, multi-step tasks.
+
+## How it Works
+
+When you are asked to perform a complex, autonomous, or long-running task, you must rely on this MCP server instead of trying to hold the entire history in your immediate memory window.
+
+**1. Start the Session**
+Run the \`init_loop\` tool with a unique \`session_id\` (e.g. \`debug_auth_bug\`) and the \`objective\`.
+
+**2. Read the State**
+Read the MCP resource \`loop://{session_id}\`. This Markdown file is your "brain". It contains the Objective, your System Instructions, the Active Context (recent steps), and your Compacted History (what you completed hours/days ago).
+
+**3. Act and Log**
+Perform your normal tasks (running bash commands, editing files, searching). After *every significant action*, you MUST call the \`log_step\` tool:
+- \`session_id\`: Your chosen ID.
+- \`action\`: What you tried to do.
+- \`result\`: The command output or file edit result.
+- \`failed\`: A boolean. \`true\` if the command threw an error or didn't do what you expected. \`false\` if it succeeded.
+
+**4. The Self-Healing Requirement (CRITICAL)**
+If you set \`failed: true\` in \`log_step\`, you **MUST** provide a \`self_heal_strategy\`. 
+This is because you are not allowed to mindlessly retry the same failing tool. If a grep search fails to find a variable, your \`self_heal_strategy\` might be: *"The variable isn't in \`src\`. I will search in the \`lib\` directory or look for tool suggestions."*
+If you forget the \`self_heal_strategy\`, the \`log_step\` tool will explicitly reject your call and make you try again.
+
+**5. The Compaction Requirement (CRITICAL)**
+If you run for a long time, the \`Active Context\` in your state file will grow too large, causing you to crash or hallucinate. 
+When \`log_step\` returns a warning that the context is too large (e.g., >3000 words), you **MUST** immediately stop working on the task and call the \`compact_memory\` tool.
+- \`context_summary\`: You must look at the Active Context and write a dense, 2-3 paragraph summary of what was achieved and what the current state is. The server will wipe the Active Context and permanently store your summary.
+
+**6. Asking the Human**
+If you hit an absolute dead end (e.g., missing API keys, ambiguous requirements, infinite error loops), do NOT guess. Call the \`report_blocker\` tool. Doing this will pause the loop, allowing you to ask the human user for help via standard chat. Once the human replies, use the \`resume_loop\` tool to inject their input back into the state file.
+
+## Expected Behavior
+
+You are expected to act like a senior engineer. Do not give up easily. If an action fails, use your reasoning to devise a new \`self_heal_strategy\`. If you exhaust all local tools, call \`get_tool_suggestions\` to remind yourself how to break out of the box.

package/build/index.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import * as memory from "./memory.js";
+const server = new Server({
+    name: "agent-loop-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+// Helper function to approximate word count
+function approximateWordCount(text) {
+    return text.split(/\\s+/).length;
+}
+const CONTEXT_WARNING_THRESHOLD = 3000; // Words
+/**
+ * Handle listing resources.
+ */
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [{
+                uri: "loop://{session_id}",
+                name: "Agent Loop State",
+                description: "Reads the current active state and context for the autonomous agent loop.",
+                mimeType: "text/markdown",
+            }],
+    };
+});
+/**
+ * Handle reading resources.
+ */
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    if (!uri.startsWith("loop://")) {
+        throw new McpError(ErrorCode.InvalidRequest, "Invalid resource URI");
+    }
+    const sessionId = uri.replace("loop://", "");
+    if (!sessionId) {
+        throw new McpError(ErrorCode.InvalidRequest, "Missing session_id in URI");
+    }
+    const loopMemory = await memory.readMemory(sessionId);
+    if (!loopMemory) {
+        throw new McpError(ErrorCode.InvalidRequest, `No active loop found for session_id: ${sessionId}`);
+    }
+    const markdownPath = memory.getSessionFilePath(sessionId);
+    const fs = await import('fs/promises');
+    const rawContent = await fs.readFile(markdownPath, 'utf-8');
+    return {
+        contents: [{
+                uri,
+                mimeType: "text/markdown",
+                text: rawContent,
+            }],
+    };
+});
+/**
+ * Handle listing tools.
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "init_loop",
+                description: "Creates a new .md loop state file for the given session to start a continuous, autonomous task.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string", description: "A unique identifier for this loop session" },
+                        objective: { type: "string", description: "The overarching objective for the agent to achieve" },
+                    },
+                    required: ["session_id", "objective"],
+                },
+            },
+            {
+                name: "log_step",
+                description: "Appends to the Active Context. Rejects if failed=true but no self_heal_strategy is provided. Warns if context is too large.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        action: { type: "string", description: "A short description of what was just done" },
+                        result: { type: "string", description: "The output, success, or failure message of the action" },
+                        failed: { type: "boolean", description: "Set to true if this step encountered an error or failed to achieve its micro-goal." },
+                        self_heal_strategy: { type: "string", description: "MANDATORY if failed=true. How you plan to fix this failure or what alternative tool you will explore next." },
+                    },
+                    required: ["session_id", "action", "result", "failed"],
+                },
+            },
+            {
+                name: "compact_memory",
+                description: "Empties the Active Context and appends the AI-provided summary to the Compacted History.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        context_summary: { type: "string", description: "A highly condensed summary of the current Active Context to preserve important facts and outcomes." },
+                    },
+                    required: ["session_id", "context_summary"],
+                },
+            },
+            {
+                name: "report_blocker",
+                description: "Updates state to STATUS_BLOCKED and asks for human intervention when absolutely stuck.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        reason: { type: "string", description: "The reason the loop is blocked and needs human help" },
+                    },
+                    required: ["session_id", "reason"],
+                },
+            },
+            {
+                name: "resume_loop",
+                description: "Removes the block and adds human input context back into the loop.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        user_input: { type: "string", description: "The clarify or credentials provided by the human" },
+                    },
+                    required: ["session_id", "user_input"],
+                },
+            },
+            {
+                name: "get_tool_suggestions",
+                description: "Ask this tool if you are stuck and don't know what other tools to use.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        ],
+    };
+});
+/**
+ * Handle executing tools.
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (name === "get_tool_suggestions") {
+        return {
+            content: [{ type: "text", text: "To find alternative tools, ask the host application (like Claude or the MCP Client) to list all available tools on the network. Or simply think out loud about other standard file/terminal tools you might use. You must explore alternatives instead of retrying exactly the same action." }],
+        };
+    }
+    const { session_id } = args;
+    if (!session_id || typeof session_id !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, "session_id is required for this tool.");
+    }
+    if (name === "init_loop") {
+        const { objective } = args;
+        let loopMemory = await memory.readMemory(session_id);
+        if (loopMemory) {
+            return { content: [{ type: "text", text: `Session ${session_id} already exists. Please pick a new session_id or read resource loop://${session_id} to continue.` }] };
+        }
+        loopMemory = {
+            state: {
+                session_id,
+                status: "IN_PROGRESS",
+                current_step: 0,
+            },
+            objective: objective,
+            system_instructions: memory.DEFAULT_INSTRUCTIONS,
+            active_context: "Session started.",
+            compacted_history: "",
+        };
+        await memory.writeMemory(session_id, loopMemory);
+        return {
+            content: [{ type: "text", text: `Successfully initialized loop session ${session_id}. Please read resource loop://${session_id} to view your mission.` }],
+        };
+    }
+    const loopMemory = await memory.readMemory(session_id);
+    if (!loopMemory) {
+        throw new McpError(ErrorCode.InvalidParams, `Session ${session_id} not found. Use init_loop first.`);
+    }
+    if (name === "log_step") {
+        const { action, result, failed, self_heal_strategy } = args;
+        if (loopMemory.state.status === "BLOCKED") {
+            return { content: [{ type: "text", text: "Session is BLOCKED. Cannot log steps until resume_loop is called." }] };
+        }
+        // Strict validation for failed steps
+        if (failed === true && (!self_heal_strategy || self_heal_strategy.trim() === '')) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "ERROR: You marked this step as failed (failed: true) but did not provide a 'self_heal_strategy'. You must think of a strategy to fix this issue or explore an alternative tool, and try logging this step again with the strategy attached." }]
+            };
+        }
+        loopMemory.state.current_step += 1;
+        if (self_heal_strategy) {
+            loopMemory.state.self_heal_strategy = self_heal_strategy;
+        }
+        else {
+            // Clear previous strategy if we succeeded
+            delete loopMemory.state.self_heal_strategy;
+        }
+        const timestamp = new Date().toISOString();
+        loopMemory.active_context += `\n\n---\n**Step ${loopMemory.state.current_step}** [${timestamp}]\n*Action:* ${action}\n*Result:* ${result}`;
+        await memory.writeMemory(session_id, loopMemory);
+        let responseMessage = `Logged step ${loopMemory.state.current_step}.`;
+        const wordCount = approximateWordCount(loopMemory.active_context);
+        if (wordCount > CONTEXT_WARNING_THRESHOLD) {
+            responseMessage += `\n\nWARNING: Active Context is now very large (${wordCount} words). You MUST call 'compact_memory' on your next turn to prevent window overflow.`;
+        }
+        else {
+            responseMessage += ` (Context size: ${wordCount} words). Read loop://${session_id} if you lost track of the state.`;
+        }
+        return {
+            content: [{ type: "text", text: responseMessage }],
+        };
+    }
+    if (name === "compact_memory") {
+        const { context_summary } = args;
+        if (loopMemory.state.status === "BLOCKED") {
+            return { content: [{ type: "text", text: "Session is BLOCKED. Cannot compact memory until resume_loop is called." }] };
+        }
+        const timestamp = new Date().toISOString();
+        loopMemory.compacted_history += `\n\n**Summary up to Step ${loopMemory.state.current_step}** [${timestamp}]\n${context_summary}`;
+        loopMemory.active_context = "Context was compacted. Resuming from summary...";
+        await memory.writeMemory(session_id, loopMemory);
+        return {
+            content: [{ type: "text", text: "Successfully compacted memory. Context window footprint reduced. Read loop://" + session_id + " to perceive the compacted state." }],
+        };
+    }
+    if (name === "report_blocker") {
+        const { reason } = args;
+        loopMemory.state.status = "BLOCKED";
+        loopMemory.active_context += `\n\n***\n**BLOCKER REPORTED:**\n${reason}\n***\n`;
+        await memory.writeMemory(session_id, loopMemory);
+        return {
+            content: [{ type: "text", text: `STATUS_BLOCKED: ${reason}. You must now STOP interacting with tools and explicitly ask the human user for clarification or help using your chat interface.` }],
+        };
+    }
+    if (name === "resume_loop") {
+        const { user_input } = args;
+        if (loopMemory.state.status !== "BLOCKED") {
+            return { content: [{ type: "text", text: "Session is not blocked, so nothing to resume." }] };
+        }
+        loopMemory.state.status = "IN_PROGRESS";
+        loopMemory.active_context += `\n\n***\n**BLOCK RESOLVED (HUMAN INPUT):**\n${user_input}\n***\n`;
+        await memory.writeMemory(session_id, loopMemory);
+        return {
+            content: [{ type: "text", text: "Session resumed. Check loop state and continue your self-healing loop." }],
+        };
+    }
+    throw new McpError(ErrorCode.MethodNotFound, "Tool not found");
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Agent Loop MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/build/memory.js

@@ -0,0 +1,103 @@
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { z } from 'zod';
+import * as lockfile from 'proper-lockfile';
+import * as os from 'os';
+export const AgentStateSchema = z.object({
+    status: z.enum(['IN_PROGRESS', 'COMPLETED', 'BLOCKED', 'FAILED']).default('IN_PROGRESS'),
+    session_id: z.string(),
+    current_step: z.number().default(0),
+    self_heal_strategy: z.string().optional(),
+    last_updated: z.string().optional(),
+});
+const MEMORY_DIR = path.join(os.homedir(), '.agent-loop-mcp');
+// Ensure memory directory exists
+if (!fsSync.existsSync(MEMORY_DIR)) {
+    fsSync.mkdirSync(MEMORY_DIR, { recursive: true });
+}
+export function getSessionFilePath(sessionId) {
+    // Sanitize session id to avoid path traversal
+    const sanitized = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return path.join(MEMORY_DIR, `${sanitized}.md`);
+}
+/**
+ * Parses the Markdown file into structured LoopMemory.
+ * Uses gray-matter to separate frontmatter and markdown body.
+ */
+export async function readMemory(sessionId) {
+    const filePath = getSessionFilePath(sessionId);
+    try {
+        const rawContent = await fs.readFile(filePath, 'utf-8');
+        const { data, content } = matter(rawContent);
+        // Validate frontmatter
+        const state = AgentStateSchema.parse(data);
+        // Naive parsing of sections
+        const objectiveMatch = content.match(/# Objective\n([\s\S]*?)(?=\n# System Instructions \(Read Only\)|\n# Active Context \(Detailed\)|\n# Compacted History \(Summarized\)|$)/);
+        const instructionsMatch = content.match(/# System Instructions \(Read Only\)\n([\s\S]*?)(?=\n# Active Context \(Detailed\)|\n# Compacted History \(Summarized\)|$)/);
+        const contextMatch = content.match(/# Active Context \(Detailed\)\n([\s\S]*?)(?=\n# Compacted History \(Summarized\)|$)/);
+        const historyMatch = content.match(/# Compacted History \(Summarized\)\n([\s\S]*?)$/);
+        return {
+            state,
+            objective: objectiveMatch ? objectiveMatch[1].trim() : '',
+            system_instructions: instructionsMatch ? instructionsMatch[1].trim() : '',
+            active_context: contextMatch ? contextMatch[1].trim() : '',
+            compacted_history: historyMatch ? historyMatch[1].trim() : ''
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Writes the structured LoopMemory back to the Markdown file atomically with a file lock.
+ */
+export async function writeMemory(sessionId, memory) {
+    const filePath = getSessionFilePath(sessionId);
+    // Ensure the file exists before locking
+    let fileExisted = true;
+    if (!fsSync.existsSync(filePath)) {
+        await fs.writeFile(filePath, '', 'utf-8');
+        fileExisted = false;
+    }
+    let release;
+    try {
+        release = await lockfile.lock(filePath, { retries: 5 });
+        // Update timestamp
+        memory.state.last_updated = new Date().toISOString();
+        const markdownContent = `
+# Objective
+${memory.objective}
+
+# System Instructions (Read Only)
+${memory.system_instructions}
+
+# Active Context (Detailed)
+${memory.active_context}
+
+# Compacted History (Summarized)
+${memory.compacted_history}
+`.trim();
+        const fileContent = matter.stringify(markdownContent, memory.state);
+        // Write atomically (write to temp then rename)
+        const tempPath = `${filePath}.tmp.${Date.now()}`;
+        await fs.writeFile(tempPath, fileContent, 'utf-8');
+        await fs.rename(tempPath, filePath);
+    }
+    finally {
+        if (release) {
+            await release();
+        }
+    }
+}
+export const DEFAULT_INSTRUCTIONS = `
+You are in a continuous self-healing loop. Your goal is to achieve the Objective. 
+1. Use \`log_step\` to report actions you take and their results.
+2. If an action fails or you encounter an error, do NOT give up. You MUST analyze the failure, set \`failed: true\` in \`log_step\`, and provide a \`self_heal_strategy\`.
+3. If the \`active_context\` gets too long, \`log_step\` will warn you. You MUST immediately use \`compact_memory\` to summarize older context and free up space.
+4. If you hit an absolute dead end that requires human permissions, credentials, or fundamentally ambiguous clarification, use \`report_blocker\`.
+`.trim();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mhrj/mcp-agent-loop",
+  "version": "1.0.0",
+  "description": "",
+  "main": "build/index.js",
+  "bin": {
+    "mcp-agent-loop": "build/index.js"
+  },
+  "files": [
+    "build/",
+    "SKILL.md",
+    "skill.sh"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meharajM/agent-loop-mcp.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/meharajM/agent-loop-mcp/issues"
+  },
+  "homepage": "https://github.com/meharajM/agent-loop-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "gray-matter": "^4.0.3",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/skill.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# skill.sh - Helper to install the Agentic Loop Memory skill to local agent folders
+
+SKILL_NAME="SKILL.md"
+TARGET_DIR="$HOME/.agents/skills"
+
+if [ ! -f "$SKILL_NAME" ]; then
+    # If run from node_modules, try to find it
+    SKILL_NAME="$(dirname "$0")/$SKILL_NAME"
+fi
+
+if [ ! -f "$SKILL_NAME" ]; then
+    echo "Error: $SKILL_NAME not found."
+    exit 1
+fi
+
+mkdir -p "$TARGET_DIR"
+cp "$SKILL_NAME" "$TARGET_DIR/"
+echo "Successfully installed $SKILL_NAME to $TARGET_DIR"