mind-palace-graph 0.3.0

package/dist/mcp-server.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP server for mpg.
+ *
+ * Exposes mpg as an MCP-compatible tool server. Drop this into
+ * Claude Desktop, Cline, Windsurf, or any MCP client.
+ *
+ * Tools: mpg_search, mpg_stash, mpg_list_stashes, mpg_get_stash,
+ *        mpg_drop_stash, mpg_discover (--ls)
+ *
+ * Usage:
+ *   node mcp-server.js
+ *   # or from the repo root:
+ *   npx tsx mcp-server.ts
+ *
+ * Configuration (Claude Desktop mcp.json):
+ *   {
+ *     "mpg": {
+ *       "command": "node",
+ *       "args": ["path/to/mcp-server.js"]
+ *     }
+ *   }
+ */
+import { search, stash, listStashes, getStash, dropStash } from "./api.js";
+// Re-use the tool definitions from api.ts for MCP tool listing.
+import { claudeTools } from "./api.js";
+const log = (...args) => process.stderr.write(`[mpg-mcp] ${args.join(" ")}\n`);
+async function handleRequest(req) {
+    switch (req.method) {
+        case "initialize":
+            return {
+                jsonrpc: "2.0",
+                id: req.id,
+                result: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "mpg", version: "0.3.0" },
+                },
+            };
+        case "notifications/initialized":
+            return { jsonrpc: "2.0", result: {} };
+        case "tools/list":
+            return {
+                jsonrpc: "2.0",
+                id: req.id,
+                result: { tools: claudeTools.map((t) => t.function) },
+            };
+        case "tools/call": {
+            const params = req.params;
+            if (!params) {
+                return { jsonrpc: "2.0", id: req.id, error: { code: -32602, message: "Missing params" } };
+            }
+            try {
+                const result = await callTool(params.name, params.arguments ?? {});
+                return {
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    result: { content: [{ type: "text", text: result }] },
+                };
+            }
+            catch (err) {
+                return {
+                    jsonrpc: "2.0",
+                    id: req.id,
+                    error: { code: -32000, message: err.message },
+                };
+            }
+        }
+        default:
+            return { jsonrpc: "2.0", id: req.id, error: { code: -32601, message: `Unknown method: ${req.method}` } };
+    }
+}
+async function callTool(name, args) {
+    log(`tool call: ${name}`, JSON.stringify(args).slice(0, 200));
+    switch (name) {
+        case "mpg_search": {
+            const result = await search({
+                pattern: args.pattern,
+                in: args.in,
+                cmd: args.cmd,
+                url: args.url,
+                before: args.before,
+                after: args.after,
+                maxNodes: args.max_nodes,
+                maxTokens: args.max_tokens,
+                effort: args.effort,
+                strategy: args.strategy,
+                from: args.from,
+                compose: args.compose,
+                page: args.page,
+                pageSize: args.page_size,
+            });
+            return JSON.stringify(result, null, 2);
+        }
+        case "mpg_stash": {
+            // Run a search and stash the result in one call.
+            if (!args.pattern)
+                throw new Error("mpg_stash requires a pattern to search for.");
+            const searchResult = await search({
+                pattern: args.pattern,
+                in: args.in,
+                before: args.before,
+                after: args.after,
+                maxNodes: args.max_nodes,
+                effort: args.effort,
+            });
+            const stashResult = await stash(searchResult, {
+                name: args.name,
+                note: args.note ?? "",
+                tags: args.tags,
+                replace: args.replace,
+                palacePath: args.palace_path,
+            });
+            return JSON.stringify({ search: { total_nodes: searchResult.total_nodes, total_tokens: searchResult.total_tokens }, stash: stashResult }, null, 2);
+        }
+        case "mpg_list_stashes": {
+            const result = listStashes(args.palace_path, args.tag_filter);
+            return JSON.stringify(result.map((s) => ({
+                name: s.name,
+                note: s.note,
+                tags: s.tags,
+                nodes_count: s.nodes.length,
+                sources_count: s.sources.length,
+                relations_count: s.relations.length,
+                updated_at: s.updated_at,
+                expires_at: s.expires_at,
+            })), null, 2);
+        }
+        case "mpg_get_stash": {
+            const result = getStash(args.name, args.palace_path);
+            if (!result)
+                throw new Error(`No such stash: ${args.name}`);
+            // Default to the card view (no nodes block) — what an agent
+            // almost always wants. Pass `with_nodes: true` to recover the
+            // legacy full-content dump.
+            const withNodes = args.with_nodes === true;
+            if (!withNodes) {
+                const { nodes: _drop, ...card } = result;
+                return JSON.stringify({
+                    ...card,
+                    view: "card",
+                    nodes_count: result.nodes.length,
+                    hint: "Pass with_nodes:true to dump the captured nodes block.",
+                }, null, 2);
+            }
+            return JSON.stringify({ ...result, view: "full" }, null, 2);
+        }
+        case "mpg_drop_stash": {
+            const ok = dropStash(args.name, args.palace_path);
+            return JSON.stringify({ dropped: ok, name: args.name });
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+// ─── Read JSON-RPC from stdin, write to stdout ──────────────────────
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    // Process complete JSON-RPC messages (separated by newlines)
+    const lines = buffer.split("\n");
+    buffer = lines.pop();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        handleMessage(line);
+    }
+});
+process.stdin.on("end", () => {
+    if (buffer.trim())
+        handleMessage(buffer);
+});
+async function handleMessage(line) {
+    let req;
+    try {
+        req = JSON.parse(line);
+    }
+    catch {
+        log("invalid JSON:", line.slice(0, 100));
+        return;
+    }
+    const resp = await handleRequest(req);
+    process.stdout.write(JSON.stringify(resp) + "\n");
+}
+log("MCP server started. Waiting for requests on stdin...");
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

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

package/dist/mind-palace.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Mind Palace — the LLM's instantiable short-term memory.
+ *
+ * The metaphor: an LLM harness doing multi-step investigation needs
+ * named, addressable memory slots it can write to, read from, and
+ * compose. The mind palace provides exactly that.
+ *
+ *   --mp-stash <name> <note>     instantiate a slot: run the search,
+ *                                stash the result, output as normal
+ *   --mp-from <name>             read from a slot as search input
+ *                                (re-runs the search fresh, scoped to
+ *                                the stashed file paths)
+ *   --mp-compose <a> <b> ...     read from multiple slots at once
+ *   --mp-list [--tag t]          inspect: what slots exist
+ *   --mp-get <name>              inspect: full contents of a slot
+ *   --mp-drop <name>             destroy: free a slot
+ *
+ * Storage: a JSON file (default `./.mpg/mind-palace.json`, project-
+ * scoped). Use `--mp-path` to point at a different file for isolated
+ * sessions. The LLM can have multiple palaces (one per task) just by
+ * pointing `--mp-path` at different files.
+ */
+import type { Node, Source } from "./types.js";
+export declare const PALACE_VERSION = 1;
+export declare const DEFAULT_PALACE_FILENAME = "mind-palace.json";
+export declare const DEFAULT_PALACE_DIR = ".mpg";
+/** A stashed collection of nodes plus the metadata of the search that produced them. */
+export interface Stash {
+    name: string;
+    note: string;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    /** ISO timestamp when this stash auto-expires, or null. */
+    expires_at: string | null;
+    search: {
+        pattern: string;
+        effort: string;
+        sources_count: number;
+    };
+    /** Source paths involved in the original search (for context). */
+    sources: string[];
+    /** The stashed nodes (subset of full Node: source + location + matched text snapshot). */
+    nodes: StashedNode[];
+    /** Source file paths (filesystem paths only, no cmd/url/stdin). */
+    file_paths: string[];
+    /** Relationships to other stashes. */
+    relations: StashRelation[];
+}
+/** A directed edge between two stashes. */
+export interface StashRelation {
+    target: string;
+    type: string;
+    note: string;
+    created_at: string;
+}
+/** A compact, stash-friendly representation of a Node. */
+export interface StashedNode {
+    source: string;
+    /** Canonical filesystem path, or null if source is not a file. */
+    file_path: string | null;
+    source_type: string;
+    match_line: number;
+    start_line: number;
+    end_line: number;
+    /** Snapshot of the match line and its context, so the stash is self-contained. */
+    context_before: string[];
+    match_text: string;
+    context_after: string[];
+    tokens: number;
+}
+export interface Palace {
+    version: number;
+    stashes: Record<string, Stash>;
+}
+/** Walk up from `start` looking for a mind-palace.json. Returns null if none found. */
+export declare function findExistingPalace(start?: string): string | null;
+/** Resolve the default palace path: env override, then git root, then
+ *  nearest existing palace walking up, then CWD/.mpg/.
+ *  This ensures the mind palace is project-scoped by default — even
+ *  when invoked from a deep subdirectory. */
+export declare function defaultPalacePath(): string;
+export declare function loadPalace(path: string): Palace;
+export declare function savePalace(path: string, palace: Palace): void;
+/** Convert full Node objects into the compact StashedNode form. */
+export declare function stashNodes(nodes: Node[]): StashedNode[];
+/** Reverse: turn StashedNodes back into Sources (unique file paths). */
+export declare function stashToSources(stash: Stash): Source[];
+/** Add or merge a stash into the palace. Merge dedupes by (source, match_line). */
+export declare function addStash(palace: Palace, name: string, note: string, nodes: Node[], meta: Stash["search"], sources: string[], tags?: string[], options?: {
+    replace?: boolean;
+    locations?: boolean;
+    ttl?: string;
+}): {
+    stash: Stash;
+    action: "created" | "replaced" | "merged";
+};
+export declare function getStash(palace: Palace, name: string): Stash | null;
+export declare function dropStash(palace: Palace, name: string): boolean;
+export declare function listStashes(palace: Palace, tagFilter?: string[]): Stash[];
+/** Compose multiple stashes into a single set of unique Sources. */
+export declare function composeToSources(palace: Palace, names: string[]): Source[];
+/** Set difference: files in `a` but not in any of `b`. */
+export declare function exceptToSources(palace: Palace, a: string, b: string[]): Source[];
+/** Set intersection: files in ALL of the given stashes. */
+export declare function intersectToSources(palace: Palace, names: string[]): Source[];
+/** Lightweight stash: only (source, line, match_text), no context buffers. */
+export declare function stashNodesLocations(nodes: Node[]): StashedNode[];
+/** Parse a human-readable duration into milliseconds.
+ *  Accepts: "30s", "10m", "2h", "7d", "14d", or bare number (ms). */
+export declare function parseDuration(s: string): number;
+/** Format an ISO timestamp as a relative time string for display. */
+export declare function formatRelativeTime(iso: string): string;
+/** Compute an expiry timestamp from now + duration. */
+export declare function expiryFromNow(duration: string): string;
+export interface PruneResult {
+    removed: number;
+    names: string[];
+    dry_run: boolean;
+}
+/** Remove stashes whose updated_at is older than `duration`. */
+export declare function pruneOlderThan(palace: Palace, duration: string, dryRun?: boolean): PruneResult;
+/** Remove stashes whose expires_at is in the past. */
+export declare function pruneExpired(palace: Palace, dryRun?: boolean): PruneResult;
+/** Keep the N most recently updated stashes, remove the rest. */
+export declare function pruneKeep(palace: Palace, n: number, dryRun?: boolean): PruneResult;
+/** Remove all stashes with the given tag. */
+export declare function pruneTag(palace: Palace, tag: string, dryRun?: boolean): PruneResult;
+/** Remove all stashes. Requires explicit confirmation. */
+export declare function pruneAll(palace: Palace, confirmed: boolean, dryRun?: boolean): PruneResult;
+/** Add a directed relationship from `from` stash to `to` stash. */
+export declare function addRelation(palace: Palace, from: string, to: string, type: string, note: string): StashRelation;
+/** Remove a relationship from `from` to `to`. */
+export declare function removeRelation(palace: Palace, from: string, to: string): boolean;
+/** Get all stashes related to `name` (both outbound and inbound edges). */
+export declare function getRelated(palace: Palace, name: string): Array<{
+    stash: Stash;
+    direction: "outbound" | "inbound";
+    relation: StashRelation;
+}>;
+/** Traverse the relationship graph from `name` up to `maxDepth` levels. */
+export declare function traversalGraph(palace: Palace, name: string, maxDepth: number): Array<{
+    stash: Stash;
+    depth: number;
+    direction: "outbound" | "inbound";
+    via: string;
+    relation: StashRelation;
+}>;