@plur-ai/mcp 0.2.9 → 0.3.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-var VERSION = "0.2.8";
+var VERSION = "0.2.9";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -75,7 +75,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-QXWHRZ4G.js");
+  const { runStdio } = await import("./server-I5WX7CVH.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-QXWHRZ4G.js → server-I5WX7CVH.js}

@@ -1,15 +1,25 @@
 // src/server.ts
 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 {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ErrorCode,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
 import { Plur, checkForUpdate } from "@plur-ai/core";
 
 // src/tools.ts
 function getToolDefinitions() {
   return [
     {
-      name: "plur.learn",
+      name: "plur_learn",
       description: "Create an engram \u2014 record a reusable learning, preference, or correction",
+      annotations: { title: "Learn", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -36,8 +46,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.recall",
-      description: "Query engrams by semantic similarity \u2014 retrieve relevant learned knowledge",
+      name: "plur_recall",
+      description: "Query engrams by BM25 keyword matching \u2014 use plur_recall_hybrid for semantic similarity",
+      annotations: { title: "Recall (BM25)", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -70,8 +81,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.recall.hybrid",
+      name: "plur_recall_hybrid",
       description: "Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion. No API calls, fully local. Best default for most use cases.",
+      annotations: { title: "Recall (hybrid)", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -105,8 +117,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.inject",
+      name: "plur_inject",
       description: "Get a scored context injection for a task \u2014 returns directives and considerations within token budget",
+      annotations: { title: "Inject (BM25)", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -130,8 +143,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.inject.hybrid",
+      name: "plur_inject_hybrid",
       description: "Hybrid injection \u2014 BM25 + embeddings for better context selection. Falls back to BM25 if embeddings unavailable. Best default for injection.",
+      annotations: { title: "Inject (hybrid)", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -156,8 +170,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.feedback",
+      name: "plur_feedback",
       description: "Rate an engram's usefulness \u2014 trains injection relevance over time",
+      annotations: { title: "Feedback", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -176,8 +191,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.forget",
+      name: "plur_forget",
       description: "Retire an engram \u2014 marks it as no longer active without deleting history",
+      annotations: { title: "Forget", destructiveHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -192,8 +208,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.capture",
+      name: "plur_capture",
       description: "Append an episode to the episodic timeline \u2014 records what happened in a session",
+      annotations: { title: "Capture episode", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -220,8 +237,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.timeline",
+      name: "plur_timeline",
       description: "Query the episodic timeline \u2014 retrieve past episodes filtered by time, agent, or search",
+      annotations: { title: "Timeline", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -254,8 +272,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.ingest",
+      name: "plur_ingest",
       description: "Extract engram candidates from content using pattern matching \u2014 optionally auto-save them",
+      annotations: { title: "Ingest", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
@@ -289,8 +308,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.packs.install",
+      name: "plur_packs_install",
       description: "Install an engram pack from a directory path \u2014 adds curated engrams to the store",
+      annotations: { title: "Install pack", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -304,8 +324,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.packs.list",
+      name: "plur_packs_list",
       description: "List all installed engram packs",
+      annotations: { title: "List packs", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {}
@@ -324,8 +345,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.sync",
+      name: "plur_sync",
       description: "Sync engrams via git \u2014 initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync.",
+      annotations: { title: "Sync", openWorldHint: true, destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -341,8 +363,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.sync.status",
+      name: "plur_sync_status",
       description: "Check git sync status \u2014 whether repo is initialized, has remote, is dirty, ahead/behind counts",
+      annotations: { title: "Sync status", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {}
@@ -352,8 +375,9 @@ function getToolDefinitions() {
       }
     },
     {
-      name: "plur.status",
+      name: "plur_status",
       description: "Return system health \u2014 engram count, episode count, pack count, storage root",
+      annotations: { title: "Status", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {}
@@ -372,7 +396,88 @@ function getToolDefinitions() {
 }
 
 // src/server.ts
-var VERSION = "0.2.8";
+import { z } from "zod";
+var VERSION = "0.3.0";
+var INSTRUCTIONS = `PLUR is your persistent memory. It stores corrections, preferences, and conventions as engrams that persist across sessions.
+
+Use PLUR proactively:
+- Call plur_recall_hybrid at session start to load relevant context for the current task
+- Call plur_learn when the user corrects you, states a preference ("always use X", "never do Y"), or when you discover a project convention
+- Call plur_feedback after using recalled engrams to train relevance
+- Call plur_status to check system health and engram counts
+
+You do not need permission to use these tools \u2014 they are your memory system.`;
+var GUIDE_RESOURCE = `# PLUR \u2014 Agent Guide
+
+## What is PLUR?
+
+Persistent memory for AI agents. Corrections, preferences, and conventions are stored as **engrams** \u2014 small assertions that strengthen with use and decay when irrelevant (ACT-R model). Storage is plain YAML on disk. Search is fully local (BM25 + embeddings). Zero API calls.
+
+## Quick Start
+
+1. \`plur_status\` \u2014 check health and engram count
+2. \`plur_recall_hybrid\` \u2014 search for relevant memories
+3. \`plur_learn\` \u2014 store a new learning
+4. \`plur_feedback\` \u2014 rate an engram's usefulness
+
+## When to Call Each Tool
+
+| Trigger | Tool |
+|---------|------|
+| Session starts | \`plur_recall_hybrid\` or \`plur_inject_hybrid\` with task description |
+| User corrects you | \`plur_learn\` with the correction |
+| User states preference ("always X", "never Y") | \`plur_learn\` with scope and type |
+| You used a recalled engram successfully | \`plur_feedback\` with "positive" |
+| A recalled engram was wrong or irrelevant | \`plur_feedback\` with "negative" |
+| User says "forget X" or a memory is outdated | \`plur_forget\` |
+| You need to check what's stored | \`plur_status\` or \`plur_packs_list\` |
+| End of session | \`plur_capture\` to record what happened |
+
+## Tool Categories
+
+### Core Memory
+- **plur_learn** \u2014 store a correction, preference, or convention
+- **plur_recall** \u2014 BM25 keyword search
+- **plur_recall_hybrid** \u2014 BM25 + embeddings (recommended default)
+- **plur_feedback** \u2014 rate an engram (trains relevance)
+- **plur_forget** \u2014 retire an outdated engram
+
+### Context Injection
+- **plur_inject** \u2014 select engrams for a task (BM25)
+- **plur_inject_hybrid** \u2014 select engrams for a task (BM25 + embeddings, recommended)
+
+### Episodic Timeline
+- **plur_capture** \u2014 record what happened in a session
+- **plur_timeline** \u2014 query past episodes
+
+### Knowledge Management
+- **plur_ingest** \u2014 extract engrams from text content
+- **plur_packs_install** \u2014 install curated engram packs
+- **plur_packs_list** \u2014 list installed packs
+
+### Sync & Status
+- **plur_sync** \u2014 sync engrams across devices via git
+- **plur_sync_status** \u2014 check sync state
+- **plur_status** \u2014 system health
+
+## Scoping
+
+Use \`scope\` to namespace engrams per project:
+- \`scope: "global"\` \u2014 applies everywhere (default)
+- \`scope: "project:my-app"\` \u2014 applies only to my-app
+- Scoped recall automatically includes global engrams
+
+## Storage
+
+\`\`\`
+~/.plur/
+\u251C\u2500\u2500 engrams.yaml     # learned knowledge
+\u251C\u2500\u2500 episodes.yaml    # session timeline
+\u2514\u2500\u2500 config.yaml      # settings
+\`\`\`
+
+Override with \`PLUR_PATH\` environment variable.
+`;
 async function createServer(plur) {
   const instance = plur ?? new Plur();
   const tools = getToolDefinitions();
@@ -383,13 +488,22 @@ async function createServer(plur) {
   });
   const server = new Server(
     { name: "plur-mcp", version: VERSION },
-    { capabilities: { tools: {} } }
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+        logging: {}
+      },
+      instructions: INSTRUCTIONS
+    }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
-      inputSchema: t.inputSchema
+      inputSchema: t.inputSchema,
+      ...t.annotations && { annotations: t.annotations }
     }))
   }));
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -401,15 +515,146 @@ async function createServer(plur) {
       };
     }
     try {
-      const result = await tool.handler(request.params.arguments ?? {}, instance);
+      const args = request.params.arguments ?? {};
+      const schema = tool.inputSchema;
+      if (schema?.properties) {
+        const shape = {};
+        for (const [key, prop] of Object.entries(schema.properties)) {
+          let field;
+          if (prop.type === "string") field = prop.enum ? z.enum(prop.enum) : z.string();
+          else if (prop.type === "number") field = z.number();
+          else if (prop.type === "boolean") field = z.boolean();
+          else if (prop.type === "array") field = z.array(z.unknown());
+          else field = z.unknown();
+          shape[key] = schema.required?.includes(key) ? field : field.optional();
+        }
+        const parsed = z.object(shape).passthrough().safeParse(args);
+        if (!parsed.success) {
+          return {
+            content: [{ type: "text", text: `Invalid arguments: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ")}` }],
+            isError: true
+          };
+        }
+      }
+      const result = await tool.handler(args, instance);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
+      const message = err?.message ?? String(err);
+      server.sendLoggingMessage({ level: "error", data: `Tool ${request.params.name} failed: ${message}` });
       return {
-        content: [{ type: "text", text: `Error: ${err.message}` }],
+        content: [{ type: "text", text: `Error: ${message}` }],
         isError: true
       };
     }
   });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: "plur://guide",
+        name: "PLUR Agent Guide",
+        description: "Complete reference for all PLUR tools, when to use them, scoping, and storage",
+        mimeType: "text/markdown"
+      },
+      {
+        uri: "plur://status",
+        name: "PLUR Status",
+        description: "Live system health \u2014 engram count, episode count, pack count, storage path",
+        mimeType: "application/json"
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    if (uri === "plur://guide") {
+      return {
+        contents: [{
+          uri: "plur://guide",
+          mimeType: "text/markdown",
+          text: GUIDE_RESOURCE
+        }]
+      };
+    }
+    if (uri === "plur://status") {
+      const status = instance.status();
+      return {
+        contents: [{
+          uri: "plur://status",
+          mimeType: "application/json",
+          text: JSON.stringify({
+            engram_count: status.engram_count,
+            episode_count: status.episode_count,
+            pack_count: status.pack_count,
+            storage_root: status.storage_root,
+            version: VERSION
+          }, null, 2)
+        }]
+      };
+    }
+    throw new McpError(ErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
+  });
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+      {
+        name: "plur-getting-started",
+        description: "Step-by-step guide to set up and start using PLUR memory"
+      },
+      {
+        name: "plur-session-start",
+        description: "Load relevant context for a task \u2014 call at the start of each session",
+        arguments: [
+          { name: "task", description: "Brief description of the task or goal", required: true },
+          { name: "scope", description: "Project scope (e.g. project:my-app)", required: false }
+        ]
+      }
+    ]
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const name = request.params.name;
+    if (name === "plur-getting-started") {
+      const status = instance.status();
+      return {
+        description: "Get started with PLUR memory",
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `I just set up PLUR. Here's my current status:
+
+- Engrams stored: ${status.engram_count}
+- Episodes recorded: ${status.episode_count}
+- Packs installed: ${status.pack_count}
+- Storage: ${status.storage_root}
+
+${status.engram_count === 0 ? `I have no memories yet. Help me get started by:
+1. Teaching me a coding preference or convention (I'll use plur_learn)
+2. Then recalling it to verify it works (I'll use plur_recall_hybrid)
+3. Rating the recall quality (I'll use plur_feedback)` : `I have ${status.engram_count} engrams stored. Try asking me something related to your project \u2014 I'll check my memory first.`}`
+          }
+        }]
+      };
+    }
+    if (name === "plur-session-start") {
+      const task = request.params.arguments?.task ?? "general work";
+      const scope = request.params.arguments?.scope;
+      return {
+        description: "Load relevant context for this session",
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `Starting a new session. Task: ${task}${scope ? ` (scope: ${scope})` : ""}
+
+Please:
+1. Call plur_recall_hybrid with query "${task}"${scope ? ` and scope "${scope}"` : ""} to load relevant memories
+2. Review the recalled engrams and apply any relevant conventions or preferences
+3. If any recalled engrams are helpful, call plur_feedback with "positive"
+4. If any are irrelevant, call plur_feedback with "negative"`
+          }
+        }]
+      };
+    }
+    throw new McpError(ErrorCode.InvalidRequest, `Unknown prompt: ${name}`);
+  });
   return server;
 }
 async function runStdio() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js",
@@ -13,7 +13,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.2.9"
+    "@plur-ai/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"
@@ -38,9 +38,8 @@
   "author": "PLUR <info@plur.ai>",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "scripts": {