velixar-mcp-server 0.1.2 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velixar AI Inc.
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velixar-mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server for Velixar persistent memory — give your AI agents long-term recall",
   "type": "module",
   "bin": {

package/src/index.js

@@ -9,6 +9,7 @@ import {
 const API_KEY = process.env.VELIXAR_API_KEY;
 const API_BASE = process.env.VELIXAR_API_URL || "https://t4xrnwgo7f.execute-api.us-east-1.amazonaws.com/v1";
 const USER_ID = process.env.VELIXAR_USER_ID || "kiro-cli";
+const TIMEOUT_MS = 15000;
 
 if (!API_KEY) {
   console.error("VELIXAR_API_KEY environment variable required");
@@ -16,23 +17,33 @@ if (!API_KEY) {
 }
 
 async function apiRequest(path, options = {}) {
-  const res = await fetch(`${API_BASE}${path}`, {
-    ...options,
-    headers: {
-      "authorization": `Bearer ${API_KEY}`,
-      "Content-Type": "application/json",
-      ...options.headers,
-    },
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`API ${res.status}: ${body.slice(0, 200)}`);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...options,
+      signal: controller.signal,
+      headers: {
+        "authorization": `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`API ${res.status}: ${body.slice(0, 200)}`);
+    }
+    return res.json();
+  } catch (e) {
+    if (e.name === "AbortError") throw new Error(`API timeout after ${TIMEOUT_MS}ms`);
+    throw e;
+  } finally {
+    clearTimeout(timer);
   }
-  return res.json();
 }
 
 const server = new Server(
-  { name: "velixar-mcp-server", version: "0.1.1" },
+  { name: "velixar-mcp-server", version: "0.1.3" },
   { capabilities: { tools: {} } }
 );
 
@@ -46,7 +57,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           content: { type: "string", description: "The memory content to store" },
           tags: { type: "array", items: { type: "string" }, description: "Optional tags for categorization" },
-          tier: { type: "number", description: "Memory tier: 0=pinned, 1=session, 2=semantic, 3=org" },
+          tier: { type: "number", description: "Memory tier: 0=pinned, 1=session, 2=semantic (default), 3=org" },
         },
         required: ["content"],
       },
@@ -65,7 +76,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "velixar_delete",
-      description: "Delete a memory by ID.",
+      description: "Delete a memory by ID. Use velixar_list to find memory IDs first.",
       inputSchema: {
         type: "object",
         properties: {
@@ -76,19 +87,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "velixar_list",
-      description: "List memories with pagination support.",
+      description: "List memories with pagination. Returns full metadata including IDs, tags, salience, and timestamps.",
       inputSchema: {
         type: "object",
         properties: {
           limit: { type: "number", description: "Max results (default 10)" },
-          cursor: { type: "string", description: "Pagination cursor" },
+          cursor: { type: "string", description: "Pagination cursor from previous response" },
         },
         required: [],
       },
     },
     {
       name: "velixar_update",
-      description: "Update an existing memory.",
+      description: "Update an existing memory's content or tags. Use velixar_list to find memory IDs first.",
       inputSchema: {
         type: "object",
         properties: {
@@ -112,18 +123,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         body: JSON.stringify({
           content: args.content,
           user_id: USER_ID,
-          tier: args.tier || 2,
+          tier: args.tier ?? 2,
           tags: args.tags || [],
         }),
       });
       if (result.error) throw new Error(result.error);
       if (!result.id) throw new Error("Store succeeded but no ID returned");
-      // Verify the memory was actually persisted
-      const verify = await apiRequest(`/memory/search?q=${encodeURIComponent(args.content.slice(0, 60))}&user_id=${USER_ID}&limit=1`);
-      const verified = verify.memories?.some(m => m.id === result.id);
-      return { content: [{ type: "text", text: verified
-        ? `✓ Stored and verified memory (id: ${result.id})`
-        : `⚠ Stored memory (id: ${result.id}) but verification failed — may not be searchable yet` }] };
+      return { content: [{ type: "text", text: `✓ Stored memory (id: ${result.id})` }] };
     }
 
     if (name === "velixar_search") {
@@ -131,11 +137,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (args.limit) params.set("limit", String(args.limit));
       const result = await apiRequest(`/memory/search?${params}`);
       if (result.error) throw new Error(result.error);
-      
+
       if (!result.memories?.length) {
         return { content: [{ type: "text", text: "No memories found." }] };
       }
-      const memories = result.memories.map((m) => `• ${m.content}`).join("\n");
+      const memories = result.memories.map((m) =>
+        `• ${m.content}${m.score ? ` (score: ${m.score})` : ""}`
+      ).join("\n");
       return { content: [{ type: "text", text: `Found ${result.count} memories:\n${memories}` }] };
     }
 
@@ -151,13 +159,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (args.cursor) params.set("cursor", args.cursor);
       const result = await apiRequest(`/memory/list?${params}`);
       if (result.error) throw new Error(result.error);
-      
+
       if (!result.memories?.length) {
         return { content: [{ type: "text", text: "No memories found." }] };
       }
-      const memories = result.memories.map((m) => `• ${m.id}: ${m.content.substring(0, 100)}...`).join("\n");
+      const memories = result.memories.map((m) => {
+        const tags = m.tags?.length ? ` [${m.tags.join(", ")}]` : "";
+        const preview = m.content.length > 120 ? m.content.substring(0, 120) + "…" : m.content;
+        return `• ${m.id}: ${preview}${tags}`;
+      }).join("\n");
       const cursor = result.cursor ? `\nNext cursor: ${result.cursor}` : "";
-      return { content: [{ type: "text", text: `Found ${result.count} memories:${cursor}\n${memories}` }] };
+      return { content: [{ type: "text", text: `${result.count} memories:${cursor}\n${memories}` }] };
     }
 
     if (name === "velixar_update") {
@@ -172,9 +184,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: "text", text: `✓ Updated memory: ${args.id}` }] };
     }
 
-    return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+    return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
   } catch (error) {
-    return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+    return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
   }
 });
 

package/tests/server.test.js

@@ -1,96 +1,193 @@
-import { test } from "node:test";
+import { test, describe, beforeEach } from "node:test";
 import assert from "node:assert";
 
-// Mock fetch globally
+// Capture the last fetch call for assertions
+let lastFetch = {};
+let mockResponse = {};
+
 global.fetch = async (url, options) => {
-  const mockResponses = {
-    "/memory": { success: true },
-    "/memory/search": { memories: [{ content: "test memory" }], count: 1 },
-    "/memory/test-id": { success: true }
-  };
-  
+  lastFetch = { url, options };
   const path = url.replace(/^.*\/v1/, "").split("?")[0];
-  return { json: async () => mockResponses[path] || {} };
+  const resp = mockResponse[path] || {};
+  return {
+    ok: resp._fail ? false : true,
+    status: resp._fail ? 500 : 200,
+    json: async () => resp,
+    text: async () => JSON.stringify(resp),
+  };
 };
 
-// Set required env vars
 process.env.VELIXAR_API_KEY = "test-key";
+process.env.VELIXAR_USER_ID = "test-user";
+
+// Import the handler by extracting it from the server
+// Since index.js connects to stdio on import, we test the logic via API calls
+// These tests validate the request/response contract
+
+describe("velixar_store", () => {
+  test("sends correct POST body", async () => {
+    mockResponse = { "/memory": { id: "abc-123", stored: true } };
+    const handler = makeHandler("velixar_store", { content: "test fact", tags: ["a"], tier: 0 });
+    const result = await handler();
+    assert.ok(lastFetch.url.endsWith("/memory"));
+    const body = JSON.parse(lastFetch.options.body);
+    assert.strictEqual(body.content, "test fact");
+    assert.strictEqual(body.tier, 0);
+    assert.deepStrictEqual(body.tags, ["a"]);
+    assert.strictEqual(body.user_id, "test-user");
+  });
 
-test("tool definitions have correct names and schemas", () => {
-  const tools = [
-    {
-      name: "velixar_store",
-      inputSchema: {
-        type: "object",
-        properties: {
-          content: { type: "string" },
-          tags: { type: "array", items: { type: "string" } },
-          tier: { type: "number" },
-        },
-        required: ["content"],
-      },
-    },
-    {
-      name: "velixar_search",
-      inputSchema: {
-        type: "object",
-        properties: {
-          query: { type: "string" },
-          limit: { type: "number" },
-        },
-        required: ["query"],
-      },
-    },
-    {
-      name: "velixar_delete",
-      inputSchema: {
-        type: "object",
-        properties: {
-          id: { type: "string" },
-        },
-        required: ["id"],
-      },
-    },
-  ];
-
-  assert.strictEqual(tools.length, 3);
-  assert.strictEqual(tools[0].name, "velixar_store");
-  assert.deepStrictEqual(tools[0].inputSchema.required, ["content"]);
-  assert.strictEqual(tools[1].name, "velixar_search");
-  assert.deepStrictEqual(tools[1].inputSchema.required, ["query"]);
-  assert.strictEqual(tools[2].name, "velixar_delete");
-  assert.deepStrictEqual(tools[2].inputSchema.required, ["id"]);
+  test("tier defaults to 2 when omitted", async () => {
+    mockResponse = { "/memory": { id: "abc-123", stored: true } };
+    const handler = makeHandler("velixar_store", { content: "test" });
+    await handler();
+    const body = JSON.parse(lastFetch.options.body);
+    assert.strictEqual(body.tier, 2);
+  });
+
+  test("tier 0 is allowed (not coerced to default)", async () => {
+    mockResponse = { "/memory": { id: "abc-123", stored: true } };
+    const handler = makeHandler("velixar_store", { content: "pinned", tier: 0 });
+    await handler();
+    const body = JSON.parse(lastFetch.options.body);
+    assert.strictEqual(body.tier, 0);
+  });
 });
 
-test("store handler formats correct response", async () => {
-  const mockHandler = async (name, args) => {
-    if (name === "velixar_store") {
-      return { content: [{ type: "text", text: "✓ Stored memory" }] };
-    }
-  };
+describe("velixar_search", () => {
+  test("passes query and limit as URL params", async () => {
+    mockResponse = { "/memory/search": { memories: [{ content: "found it" }], count: 1 } };
+    const handler = makeHandler("velixar_search", { query: "test query", limit: 3 });
+    await handler();
+    assert.ok(lastFetch.url.includes("q=test+query") || lastFetch.url.includes("q=test%20query"));
+    assert.ok(lastFetch.url.includes("limit=3"));
+  });
 
-  const result = await mockHandler("velixar_store", { content: "test" });
-  assert.strictEqual(result.content[0].text, "✓ Stored memory");
+  test("returns 'No memories found' when empty", async () => {
+    mockResponse = { "/memory/search": { memories: [], count: 0 } };
+    const handler = makeHandler("velixar_search", { query: "nothing" });
+    const result = await handler();
+    assert.strictEqual(result.text, "No memories found.");
+  });
 });
 
-test("search handler formats correct response", async () => {
-  const mockHandler = async (name, args) => {
-    if (name === "velixar_search") {
-      return { content: [{ type: "text", text: "Found 1 memories:\n• test memory" }] };
-    }
-  };
+describe("velixar_list", () => {
+  test("passes cursor for pagination", async () => {
+    mockResponse = { "/memory/list": { memories: [{ id: "x", content: "hi", tags: [] }], count: 1 } };
+    const handler = makeHandler("velixar_list", { limit: 5, cursor: "abc" });
+    await handler();
+    assert.ok(lastFetch.url.includes("cursor=abc"));
+    assert.ok(lastFetch.url.includes("limit=5"));
+  });
 
-  const result = await mockHandler("velixar_search", { query: "test" });
-  assert.ok(result.content[0].text.includes("Found 1 memories"));
+  test("returns 'No memories found' when empty", async () => {
+    mockResponse = { "/memory/list": { memories: [], count: 0 } };
+    const handler = makeHandler("velixar_list", {});
+    const result = await handler();
+    assert.strictEqual(result.text, "No memories found.");
+  });
 });
 
-test("delete handler formats correct response", async () => {
-  const mockHandler = async (name, args) => {
-    if (name === "velixar_delete") {
-      return { content: [{ type: "text", text: `✓ Deleted memory: ${args.id}` }] };
+describe("velixar_update", () => {
+  test("sends PATCH with content and tags", async () => {
+    mockResponse = { "/memory/up-123": { updated: true } };
+    const handler = makeHandler("velixar_update", { id: "up-123", content: "new", tags: ["x"] });
+    await handler();
+    assert.ok(lastFetch.url.includes("/memory/up-123"));
+    assert.strictEqual(lastFetch.options.method, "PATCH");
+    const body = JSON.parse(lastFetch.options.body);
+    assert.strictEqual(body.content, "new");
+    assert.deepStrictEqual(body.tags, ["x"]);
+  });
+});
+
+describe("velixar_delete", () => {
+  test("sends DELETE to correct URL", async () => {
+    mockResponse = { "/memory/del-456": { deleted: true } };
+    const handler = makeHandler("velixar_delete", { id: "del-456" });
+    await handler();
+    assert.ok(lastFetch.url.includes("/memory/del-456"));
+    assert.strictEqual(lastFetch.options.method, "DELETE");
+  });
+});
+
+describe("error handling", () => {
+  test("returns isError on API error response", async () => {
+    mockResponse = { "/memory": { error: "bad request" } };
+    const handler = makeHandler("velixar_store", { content: "fail" });
+    const result = await handler();
+    assert.ok(result.text.includes("Error:"));
+    assert.strictEqual(result.isError, true);
+  });
+});
+
+// Helper: simulates the CallTool handler logic from index.js
+// This mirrors the actual handler without needing stdio transport
+function makeHandler(name, args) {
+  const API_BASE = "https://t4xrnwgo7f.execute-api.us-east-1.amazonaws.com/v1";
+  const API_KEY = process.env.VELIXAR_API_KEY;
+  const USER_ID = process.env.VELIXAR_USER_ID;
+
+  async function apiRequest(path, options = {}) {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...options,
+      headers: { authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", ...options.headers },
+    });
+    if (!res.ok) { const body = await res.text().catch(() => ""); throw new Error(`API ${res.status}: ${body.slice(0, 200)}`); }
+    return res.json();
+  }
+
+  return async () => {
+    try {
+      if (name === "velixar_store") {
+        const result = await apiRequest("/memory", {
+          method: "POST",
+          body: JSON.stringify({ content: args.content, user_id: USER_ID, tier: args.tier ?? 2, tags: args.tags || [] }),
+        });
+        if (result.error) throw new Error(result.error);
+        if (!result.id) throw new Error("Store succeeded but no ID returned");
+        return { text: `✓ Stored memory (id: ${result.id})` };
+      }
+      if (name === "velixar_search") {
+        const params = new URLSearchParams({ q: args.query, user_id: USER_ID });
+        if (args.limit) params.set("limit", String(args.limit));
+        const result = await apiRequest(`/memory/search?${params}`);
+        if (result.error) throw new Error(result.error);
+        if (!result.memories?.length) return { text: "No memories found." };
+        const memories = result.memories.map((m) => `• ${m.content}${m.score ? ` (score: ${m.score})` : ""}`).join("\n");
+        return { text: `Found ${result.count} memories:\n${memories}` };
+      }
+      if (name === "velixar_delete") {
+        const result = await apiRequest(`/memory/${args.id}`, { method: "DELETE" });
+        if (result.error) throw new Error(result.error);
+        return { text: `✓ Deleted memory: ${args.id}` };
+      }
+      if (name === "velixar_list") {
+        const params = new URLSearchParams({ user_id: USER_ID });
+        if (args.limit) params.set("limit", String(args.limit));
+        if (args.cursor) params.set("cursor", args.cursor);
+        const result = await apiRequest(`/memory/list?${params}`);
+        if (result.error) throw new Error(result.error);
+        if (!result.memories?.length) return { text: "No memories found." };
+        const memories = result.memories.map((m) => {
+          const tags = m.tags?.length ? ` [${m.tags.join(", ")}]` : "";
+          const preview = m.content.length > 120 ? m.content.substring(0, 120) + "…" : m.content;
+          return `• ${m.id}: ${preview}${tags}`;
+        }).join("\n");
+        const cursor = result.cursor ? `\nNext cursor: ${result.cursor}` : "";
+        return { text: `${result.count} memories:${cursor}\n${memories}` };
+      }
+      if (name === "velixar_update") {
+        const body = { user_id: USER_ID };
+        if (args.content) body.content = args.content;
+        if (args.tags) body.tags = args.tags;
+        const result = await apiRequest(`/memory/${args.id}`, { method: "PATCH", body: JSON.stringify(body) });
+        if (result.error) throw new Error(result.error);
+        return { text: `✓ Updated memory: ${args.id}` };
+      }
+      return { text: `Unknown tool: ${name}`, isError: true };
+    } catch (error) {
+      return { text: `Error: ${error.message}`, isError: true };
     }
   };
-
-  const result = await mockHandler("velixar_delete", { id: "test-id" });
-  assert.strictEqual(result.content[0].text, "✓ Deleted memory: test-id");
-});
+}