@agentfold/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentFold contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AgentFoldConfig } from "@agentfold/shared";
+import { AgentFoldStore } from "@agentfold/store";
+/**
+ * AgentFold MCP server (Mode B) �?stdio.
+ *
+ * Tools are opt-in helpers for agents that want explicit control. The
+ * automatic Context Compiler in proxy mode remains the core mechanism;
+ * agents are NOT required to call MCP for folding to happen.
+ */
+export interface McpServerOptions {
+    config: AgentFoldConfig;
+    store: AgentFoldStore;
+}
+export declare function createAgentFoldMcpServer(opts: McpServerOptions): McpServer;
+export declare function runMcpStdio(opts: McpServerOptions): Promise<void>;

package/dist/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { AgentFoldRuntime } from "@agentfold/proxy";
+import { AgentFoldStore } from "@agentfold/store";
+export function createAgentFoldMcpServer(opts) {
+    const runtime = new AgentFoldRuntime(opts.config, opts.store);
+    const server = new McpServer({ name: "agentfold", version: "0.1.0" });
+    server.tool("agentfold_status", "AgentFold runtime status, config and aggregate savings", {}, async () => {
+        return textOut(JSON.stringify(runtime.status(), null, 2));
+    });
+    server.tool("agentfold_search", "Search historical observations (tool outputs, errors, decisions) by keywords", { query: z.string().describe("keyword query"), limit: z.number().optional() }, async ({ query, limit }) => {
+        const memories = opts.store.searchMemories(query, { limit: limit ?? 8 });
+        const folds = opts.store.searchFoldDigests(query, limit ?? 8);
+        return textOut(JSON.stringify({
+            memories: memories.map((m) => ({
+                id: m.id,
+                title: m.title,
+                status: m.status,
+                score: Number(m.score.toFixed(3)),
+                evidence: m.evidence,
+                recall: `agentfold_recall id=${m.id}`
+            })),
+            folds: folds.map((f) => ({
+                id: f.foldId,
+                tool: f.toolName,
+                result: f.resultKind,
+                original_tokens: f.originalTokens,
+                anchors: f.anchors.slice(0, 6),
+                recall: `agentfold_recall id=${f.foldId}`
+            }))
+        }, null, 2));
+    });
+    server.tool("agentfold_recall", "Recover the original content behind a folded block [AFOLD:id] with SHA256 integrity verification", {
+        id: z.string().describe("fold id, e.g. 7f92a1b2"),
+        grep: z.string().optional().describe("only return matching lines with context"),
+        token_cap: z.number().optional().describe("max tokens returned")
+    }, async ({ id, grep, token_cap }) => {
+        try {
+            const out = runtime.recall(id, { grep, tokenCap: token_cap });
+            return textOut(`integrity=${out.integrityVerified ? "verified" : "UNKNOWN"} truncated=${out.truncated}\n` + out.content);
+        }
+        catch (err) {
+            return textOut(`recall failed: ${err.message}`);
+        }
+    });
+    server.tool("agentfold_timeline", "Show a compact timeline of a session's events", { session_id: z.string(), limit: z.number().optional() }, async ({ session_id, limit }) => {
+        const timeline = opts.store.sessionTimeline(session_id, limit ?? 200);
+        return textOut(JSON.stringify(timeline, null, 2));
+    });
+    server.tool("agentfold_pin", "Pin high-priority context (task, constraint, decision) so the compiler never folds it", { text: z.string(), session_id: z.string().optional() }, async ({ text, session_id }) => {
+        const id = opts.store.addPin(text, session_id ?? null, "agent");
+        return textOut(`pinned: ${id}`);
+    });
+    server.tool("agentfold_unpin", "Remove a pin", { id: z.string() }, async ({ id }) => {
+        const removed = opts.store.removePin(id);
+        return textOut(removed ? `unpinned: ${id}` : `pin not found: ${id}`);
+    });
+    server.tool("agentfold_explain", "Explain why recent memory was injected into the prompt", {}, async () => {
+        const expl = opts.store.lastRetrievalExplanation();
+        return textOut(expl ? JSON.stringify(expl, null, 2) : "no retrieval recorded yet");
+    });
+    server.tool("agentfold_handoff", "Generate a compact cross-session handoff seed (~1-2K tokens)", { session_id: z.string() }, async ({ session_id }) => {
+        const seed = runtime.handoff(session_id);
+        return textOut(JSON.stringify(seed, null, 2));
+    });
+    return server;
+}
+export async function runMcpStdio(opts) {
+    const server = createAgentFoldMcpServer(opts);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function textOut(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+// Allow direct execution: node dist/index.js
+if (process.argv[1]?.endsWith("index.js") || process.argv[1]?.endsWith("agentfold-mcp")) {
+    runMcpStdio({ config: defaultMcpConfig(), store: new AgentFoldStore(process.env.AGENTFOLD_DB ?? ".agentfold/agentfold.db") }).catch((err) => {
+        console.error(String(err));
+        process.exit(1);
+    });
+}
+function defaultMcpConfig() {
+    // Minimal standalone config; the CLI passes a full config when available.
+    return {
+        ...{},
+        foldAt: 0.45,
+        foldStep: 0.12,
+        targetLiveBudgetFraction: 0.7,
+        absoluteLiveCap: 200000,
+        outputReserve: 0.2,
+        protocolReserve: 0.05,
+        protectedTailTokens: null,
+        retrievalTopK: 3,
+        retrievalBudgetTokens: 800,
+        storage: { dbPath: process.env.AGENTFOLD_DB ?? ".agentfold/agentfold.db", redactSecrets: true },
+        strictMode: false,
+        defaultContextWindow: 128000,
+        upstreamBaseUrl: "https://api.openai.com",
+        port: 3897,
+        recallTokenCap: 8000
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@agentfold/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agentfold-mcp": "./dist/index.js"
+  },
+  "dependencies": {
+    "@agentfold/proxy": "0.1.0",
+    "@agentfold/core": "0.1.0",
+    "@agentfold/shared": "0.1.0",
+    "@agentfold/store": "0.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/279458179/agentfold.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "context",
+    "llm",
+    "memory",
+    "tokens",
+    "context-window",
+    "openai",
+    "mcp"
+  ],
+  "license": "MIT",
+  "description": "AgentFold — virtual memory for AI agents: fold cold context, recall anything.",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}