mindpm 1.2.23 → 1.2.25

package/README.md

@@ -60,10 +60,11 @@ npm install
 npm run build
 ```
 
-### Configure with Claude Code
+### Configure your MCP client
 
-Add to your MCP config (`~/.claude/claude_desktop_config.json` or similar):
+All clients use the same JSON format — just different config file locations. They all share the same `~/.mindpm/memory.db`, so you can switch tools mid-project without losing context.
 
+**Claude Code** — `~/.claude/claude_desktop_config.json`
 ```json
 {
   "mcpServers": {
@@ -78,14 +79,18 @@ Add to your MCP config (`~/.claude/claude_desktop_config.json` or similar):
 }
 ```
 
-If running from source, use the built file directly:
+Or use the one-liner:
+```bash
+claude mcp add mindpm -e MINDPM_DB_PATH=~/.mindpm/memory.db -- npx -y mindpm
+```
 
+**Cursor** — `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` globally)
 ```json
 {
   "mcpServers": {
     "mindpm": {
-      "command": "node",
-      "args": ["/path/to/mindpm/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "mindpm"],
       "env": {
         "MINDPM_DB_PATH": "~/.mindpm/memory.db"
       }
@@ -94,6 +99,45 @@ If running from source, use the built file directly:
 }
 ```
 
+**VS Code + Copilot** — `.vscode/mcp.json` in your project root
+```json
+{
+  "servers": {
+    "mindpm": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mindpm"],
+      "env": {
+        "MINDPM_DB_PATH": "~/.mindpm/memory.db"
+      }
+    }
+  }
+}
+```
+
+**Cline** — Add via VS Code settings → Cline → MCP Servers, or edit `cline_mcp_settings.json`:
+```json
+{
+  "mcpServers": {
+    "mindpm": {
+      "command": "npx",
+      "args": ["-y", "mindpm"],
+      "env": {
+        "MINDPM_DB_PATH": "~/.mindpm/memory.db"
+      }
+    }
+  }
+}
+```
+
+**Windsurf** — Settings → Cascade → MCP, using the same JSON structure as Cline above.
+
+### Using mindpm with any LLM
+
+On first run, mindpm writes `~/.mindpm/AGENT.md` — a ready-to-paste system prompt that tells your LLM how to use mindpm proactively. Paste its contents into your client's custom instructions or system prompt box.
+
+You can also call the `get_agent_instructions` tool at any time to retrieve the instructions.
+
 ### Start Using
 
 That's it. The LLM now has access to mindpm tools. Just start talking about your projects.

package/assets/logo.svg

@@ -0,0 +1,61 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" viewBox="0 0 400 400">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#0f172a"/>
+      <stop offset="100%" stop-color="#1e1b4b"/>
+    </linearGradient>
+    <linearGradient id="stroke-grad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#a78bfa"/>
+      <stop offset="100%" stop-color="#6366f1"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background rounded square -->
+  <rect width="400" height="400" rx="72" fill="url(#bg)"/>
+
+  <!-- M shape — circuit-board style, with nodes at vertices -->
+  <!-- Lines first (behind nodes) -->
+  <!-- Left vertical -->
+  <line x1="110" y1="290" x2="110" y2="120" stroke="url(#stroke-grad)" stroke-width="14" stroke-linecap="round" filter="url(#glow)"/>
+  <!-- Left diagonal down to center -->
+  <line x1="110" y1="120" x2="200" y2="215" stroke="url(#stroke-grad)" stroke-width="14" stroke-linecap="round" filter="url(#glow)"/>
+  <!-- Right diagonal up from center -->
+  <line x1="200" y1="215" x2="290" y2="120" stroke="url(#stroke-grad)" stroke-width="14" stroke-linecap="round" filter="url(#glow)"/>
+  <!-- Right vertical -->
+  <line x1="290" y1="120" x2="290" y2="290" stroke="url(#stroke-grad)" stroke-width="14" stroke-linecap="round" filter="url(#glow)"/>
+
+  <!-- Bottom connector (subtle horizontal line) -->
+  <line x1="110" y1="290" x2="290" y2="290" stroke="#4338ca" stroke-width="5" stroke-linecap="round" opacity="0.5"/>
+
+  <!-- Circuit nodes -->
+  <!-- Bottom-left -->
+  <circle cx="110" cy="290" r="18" fill="#0f172a" stroke="#a78bfa" stroke-width="5"/>
+  <circle cx="110" cy="290" r="7" fill="#a78bfa"/>
+
+  <!-- Top-left -->
+  <circle cx="110" cy="120" r="18" fill="#0f172a" stroke="#a78bfa" stroke-width="5"/>
+  <circle cx="110" cy="120" r="7" fill="#a78bfa"/>
+
+  <!-- Center peak (larger, brighter — the "brain" node) -->
+  <circle cx="200" cy="215" r="24" fill="#0f172a" stroke="#818cf8" stroke-width="6" filter="url(#glow)"/>
+  <circle cx="200" cy="215" r="10" fill="#818cf8" filter="url(#glow)"/>
+
+  <!-- Top-right -->
+  <circle cx="290" cy="120" r="18" fill="#0f172a" stroke="#a78bfa" stroke-width="5"/>
+  <circle cx="290" cy="120" r="7" fill="#a78bfa"/>
+
+  <!-- Bottom-right -->
+  <circle cx="290" cy="290" r="18" fill="#0f172a" stroke="#a78bfa" stroke-width="5"/>
+  <circle cx="290" cy="290" r="7" fill="#a78bfa"/>
+
+  <!-- "pm" label — small, below the M, for context at full size -->
+  <text x="200" y="355" font-family="ui-monospace, 'Courier New', monospace" font-size="28" font-weight="700"
+        fill="#6366f1" text-anchor="middle" letter-spacing="6" opacity="0.8">mindpm</text>
+</svg>

package/dist/index.js

@@ -9,7 +9,7 @@ import { z } from "zod/v4";
 
 // src/db/connection.ts
 import Database from "better-sqlite3";
-import { mkdirSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { homedir } from "os";
 
@@ -212,6 +212,52 @@ function runMigrations(db2) {
   }
 }
 
+// src/tools/meta.ts
+var AGENT_INSTRUCTIONS = `# mindpm \u2014 Agent Instructions
+
+You have access to mindpm, a persistent project memory tool. Use it proactively to maintain context across conversations.
+
+## Session lifecycle
+
+**At the start of every conversation:**
+Call \`start_session\` immediately. It returns your project context: last session summary, active tasks, blockers, and recent decisions. Always show the kanban_url to the user as a clickable link.
+
+**During the conversation:**
+- When work is identified \u2192 call \`create_task\`
+- When a technical choice is made \u2192 call \`log_decision\` (include reasoning and alternatives)
+- When important context emerges \u2192 call \`add_note\` or \`set_context\`
+- When task status changes \u2192 call \`update_task\`
+
+**At the end of the conversation:**
+Call \`end_session\` with a summary of what was accomplished and clear next_steps for the following session.
+
+## Principles
+
+- Prefer \`get_next_tasks\` over \`list_tasks\` when the user asks what to work on next \u2014 it returns the highest priority unblocked tasks
+- Log decisions even for small choices \u2014 future sessions benefit from knowing *why*
+- Keep task titles short and actionable (imperative form: "Add rate limiting", not "Rate limiting")
+- Use \`search\` when the user references something you don't have in current context
+
+## Works across all MCP clients
+
+mindpm stores everything in a local SQLite database (~/.mindpm/memory.db). Any MCP-compatible client (Claude Code, Cursor, Cline, Copilot, Gemini) connecting to the same mindpm instance shares the same memory. You can switch tools mid-project without losing context.
+`;
+function registerMetaTools(server2) {
+  server2.registerTool(
+    "get_agent_instructions",
+    {
+      title: "Get Agent Instructions",
+      description: "Returns the recommended instructions for using mindpm effectively. Call this once if you are unsure how to use mindpm, or share it with the user to paste into other LLM clients.",
+      inputSchema: {}
+    },
+    async () => {
+      return {
+        content: [{ type: "text", text: AGENT_INSTRUCTIONS }]
+      };
+    }
+  );
+}
+
 // src/db/connection.ts
 var db = null;
 function resolveDbPath() {
@@ -223,7 +269,14 @@ function resolveDbPath() {
 }
 function ensureDbDirectory() {
   const dbPath = resolveDbPath();
-  mkdirSync(dirname(dbPath), { recursive: true });
+  const dir = dirname(dbPath);
+  mkdirSync(dir, { recursive: true });
+  const agentMdPath = resolve(dir, "AGENT.md");
+  if (!existsSync(agentMdPath)) {
+    writeFileSync(agentMdPath, AGENT_INSTRUCTIONS, "utf8");
+    process.stderr.write(`[mindpm] Created ${agentMdPath}
+`);
+  }
 }
 function getDb() {
   if (db) return db;
@@ -1528,6 +1581,7 @@ registerDecisionTools(server);
 registerNoteTools(server);
 registerSessionTools(server);
 registerQueryTools(server);
+registerMetaTools(server);
 var httpServer;
 async function main() {
   ensureDbDirectory();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindpm",
-  "version": "1.2.23",
+  "version": "1.2.25",
   "description": "Persistent project memory for LLMs via MCP. Never re-explain your project again.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,12 +21,25 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "llm",
     "memory",
+    "persistent-memory",
+    "project-memory",
     "sqlite",
     "project-management",
-    "model-context-protocol"
+    "task-management",
+    "kanban",
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai-memory",
+    "context",
+    "sessions",
+    "decisions"
   ],
+  "mcpName": "io.github.umitkavala/mindpm",
   "author": "",
   "license": "MIT",
   "engines": {
@@ -35,7 +48,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",