@memoryrelay/mcp-server 0.1.6

package/dist/index.js

@@ -0,0 +1,804 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import { z } from "zod";
+var configSchema = z.object({
+  apiKey: z.string().startsWith("mem_", { message: 'API key must start with "mem_"' }).min(20, { message: "API key appears to be invalid (too short)" }),
+  apiUrl: z.string().url({ message: "API URL must be a valid URL" }).default("https://api.memoryrelay.net"),
+  agentId: z.string().optional().describe("Agent identifier - auto-detected if not provided"),
+  timeout: z.number().positive({ message: "Timeout must be positive" }).default(3e4),
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info")
+});
+function loadConfig() {
+  try {
+    const config = configSchema.parse({
+      apiKey: process.env.MEMORYRELAY_API_KEY,
+      apiUrl: process.env.MEMORYRELAY_API_URL,
+      agentId: process.env.MEMORYRELAY_AGENT_ID,
+      timeout: process.env.MEMORYRELAY_TIMEOUT ? parseInt(process.env.MEMORYRELAY_TIMEOUT, 10) : void 0,
+      logLevel: process.env.MEMORYRELAY_LOG_LEVEL
+    });
+    return config;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const issues = error.issues.map(
+        (issue) => `  - ${issue.path.join(".")}: ${issue.message}`
+      ).join("\n");
+      throw new Error(
+        `Configuration validation failed:
+${issues}
+
+Please check your environment variables:
+  - MEMORYRELAY_API_KEY (required, starts with "mem_")
+  - MEMORYRELAY_API_URL (optional, default: https://api.memoryrelay.net)
+  - MEMORYRELAY_AGENT_ID (optional, auto-detected)
+  - MEMORYRELAY_TIMEOUT (optional, default: 30000)
+  - MEMORYRELAY_LOG_LEVEL (optional, default: info)`
+      );
+    }
+    throw error;
+  }
+}
+function getAgentId(config) {
+  if (config.agentId) {
+    return config.agentId;
+  }
+  const hostname = process.env.HOSTNAME || "unknown";
+  return `agent-${hostname.slice(0, 8)}`;
+}
+
+// src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var Logger = class {
+  minLevel;
+  constructor(level = "info") {
+    this.minLevel = LOG_LEVELS[level];
+  }
+  /**
+   * Mask sensitive data in log messages
+   * - API keys starting with "mem_" are masked
+   * - Internal paths are sanitized
+   */
+  sanitize(message) {
+    let sanitized = message;
+    sanitized = sanitized.replace(/mem_[a-zA-Z0-9_-]+/g, "mem_****");
+    sanitized = sanitized.replace(/\/[a-zA-Z0-9_\-./]+\.(ts|js|json)/g, "<file>");
+    sanitized = sanitized.replace(/at\s+[^\s]+\s+\([^)]+\)/g, "at <location>");
+    return sanitized;
+  }
+  /**
+   * Format log message with timestamp and level
+   */
+  format(level, message, data) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const sanitizedMessage = this.sanitize(message);
+    let output = `[${timestamp}] [${level.toUpperCase()}] ${sanitizedMessage}`;
+    if (data !== void 0) {
+      const sanitizedData = this.sanitize(JSON.stringify(data, null, 2));
+      output += `
+${sanitizedData}`;
+    }
+    return output;
+  }
+  debug(message, data) {
+    if (this.minLevel <= LOG_LEVELS.debug) {
+      console.error(this.format("debug", message, data));
+    }
+  }
+  info(message, data) {
+    if (this.minLevel <= LOG_LEVELS.info) {
+      console.error(this.format("info", message, data));
+    }
+  }
+  warn(message, data) {
+    if (this.minLevel <= LOG_LEVELS.warn) {
+      console.error(this.format("warn", message, data));
+    }
+  }
+  error(message, data) {
+    if (this.minLevel <= LOG_LEVELS.error) {
+      console.error(this.format("error", message, data));
+    }
+  }
+};
+var logger;
+function initLogger(level = "info") {
+  logger = new Logger(level);
+  return logger;
+}
+function getLogger() {
+  if (!logger) {
+    logger = new Logger();
+  }
+  return logger;
+}
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { z as z2 } from "zod";
+
+// src/client.ts
+var MAX_RETRIES = 3;
+var INITIAL_DELAY_MS = 1e3;
+var MAX_CONTENT_SIZE = 50 * 1024;
+async function withRetry(fn, retries = MAX_RETRIES) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.message.includes("401") || lastError.message.includes("403") || lastError.message.includes("404") || lastError.message.includes("400")) {
+        throw lastError;
+      }
+      if (attempt === retries) {
+        throw lastError;
+      }
+      const delay = INITIAL_DELAY_MS * Math.pow(2, attempt);
+      const jitter = Math.random() * 0.3 * delay;
+      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+    }
+  }
+  throw lastError || new Error("Retry failed");
+}
+function maskApiKey(message, apiKey) {
+  if (!apiKey) return message;
+  const maskedKey = apiKey.substring(0, 8) + "***";
+  return message.replace(new RegExp(apiKey, "g"), maskedKey);
+}
+var MemoryRelayClient = class {
+  config;
+  logger = getLogger();
+  constructor(config) {
+    this.config = config;
+    this.logger.info("MemoryRelay client initialized", {
+      apiUrl: config.apiUrl,
+      agentId: config.agentId
+    });
+  }
+  /**
+   * Make authenticated HTTP request to MemoryRelay API with retry logic
+   */
+  async request(method, path, body) {
+    return withRetry(async () => {
+      const url = `${this.config.apiUrl}${path}`;
+      this.logger.debug(`API request: ${method} ${path}`);
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.config.timeout);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.config.apiKey}`,
+            "User-Agent": "@memoryrelay/mcp-server"
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          if (response.status === 429) {
+            const retryAfter = response.headers.get("Retry-After");
+            const waitMs = retryAfter ? parseInt(retryAfter) * 1e3 : 5e3;
+            this.logger.warn(`Rate limited, waiting ${waitMs}ms`);
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            throw new Error(`Rate limited: 429 - Retry after ${waitMs}ms`);
+          }
+          const errorData = await response.json().catch(() => ({}));
+          const errorMsg = `API request failed: ${response.status} ${response.statusText}` + (errorData.message ? ` - ${errorData.message}` : "");
+          throw new Error(maskApiKey(errorMsg, this.config.apiKey));
+        }
+        const data = await response.json();
+        this.logger.debug(`API response: ${method} ${path}`, { status: response.status });
+        return data;
+      } catch (error) {
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new Error(`Request timeout after ${this.config.timeout}ms`);
+          }
+          error.message = maskApiKey(error.message, this.config.apiKey);
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+    });
+  }
+  /**
+   * Validate content size
+   */
+  validateContentSize(content) {
+    if (content.length > MAX_CONTENT_SIZE) {
+      throw new Error(`Content exceeds maximum size of ${MAX_CONTENT_SIZE} bytes`);
+    }
+  }
+  /**
+   * Store a new memory
+   */
+  async storeMemory(content, metadata) {
+    this.validateContentSize(content);
+    return this.request("POST", "/v1/memories/memories", {
+      content,
+      metadata,
+      agent_id: this.config.agentId
+    });
+  }
+  /**
+   * Search memories using semantic search
+   */
+  async searchMemories(query, limit = 10, threshold = 0.5) {
+    this.validateContentSize(query);
+    const response = await this.request(
+      "POST",
+      "/v1/memories/memories/search",
+      { query, limit, threshold, agent_id: this.config.agentId }
+    );
+    return response.data;
+  }
+  /**
+   * List recent memories with pagination
+   */
+  async listMemories(limit = 20, offset = 0) {
+    return this.request(
+      "GET",
+      `/v1/memories/memories?limit=${limit}&offset=${offset}`
+    );
+  }
+  /**
+   * Get a specific memory by ID
+   */
+  async getMemory(id) {
+    return this.request("GET", `/v1/memories/memories/${id}`);
+  }
+  /**
+   * Update an existing memory
+   */
+  async updateMemory(id, content, metadata) {
+    this.validateContentSize(content);
+    return this.request("PATCH", `/v1/memories/memories/${id}`, {
+      content,
+      metadata
+    });
+  }
+  /**
+   * Delete a memory
+   */
+  async deleteMemory(id) {
+    await this.request("DELETE", `/v1/memories/memories/${id}`);
+  }
+  /**
+   * Create a named entity
+   */
+  async createEntity(name, type, metadata) {
+    this.validateContentSize(name);
+    return this.request("POST", "/v1/entities", {
+      name,
+      type,
+      metadata
+    });
+  }
+  /**
+   * Link an entity to a memory
+   */
+  async linkEntity(entityId, memoryId, relationship = "mentioned_in") {
+    await this.request("POST", "/v1/entities/links", {
+      entity_id: entityId,
+      memory_id: memoryId,
+      relationship
+    });
+  }
+  /**
+   * Get an entity by ID
+   */
+  async getEntity(id) {
+    return this.request("GET", `/v1/entities/${id}`);
+  }
+  /**
+   * List entities with pagination
+   */
+  async listEntities(limit = 20, offset = 0) {
+    return this.request(
+      "GET",
+      `/v1/entities?limit=${limit}&offset=${offset}`
+    );
+  }
+  /**
+   * Delete an entity
+   */
+  async deleteEntity(id) {
+    await this.request("DELETE", `/v1/entities/${id}`);
+  }
+  /**
+   * Health check - verify API connectivity
+   */
+  async healthCheck() {
+    try {
+      await this.request("GET", "/v1/health");
+      return {
+        status: "healthy",
+        message: "API connection successful"
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : "Unknown error";
+      return {
+        status: "unhealthy",
+        message: `API connection failed: ${errorMsg}`
+      };
+    }
+  }
+};
+
+// src/server.ts
+function sanitizeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;").replace(/\//g, "&#x2F;");
+}
+var uuidSchema = z2.string().uuid();
+function validateUuid(id, fieldName = "id") {
+  const result = uuidSchema.safeParse(id);
+  if (!result.success) {
+    throw new Error(`Invalid ${fieldName}: must be a valid UUID`);
+  }
+}
+var MemoryRelayMCPServer = class {
+  server;
+  client;
+  logger = getLogger();
+  constructor(config) {
+    this.client = new MemoryRelayClient(config);
+    this.server = new Server(
+      {
+        name: "@memoryrelay/mcp-server",
+        version: "0.1.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupHandlers();
+    this.logger.info("MCP server initialized");
+  }
+  /**
+   * Setup MCP protocol handlers
+   */
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: "memory_store",
+          description: "Store a new memory. Use this to save important information, facts, preferences, or context that should be remembered for future conversations.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              content: {
+                type: "string",
+                description: "The memory content to store. Be specific and include relevant context."
+              },
+              metadata: {
+                type: "object",
+                description: "Optional key-value metadata to attach to the memory",
+                additionalProperties: { type: "string" }
+              }
+            },
+            required: ["content"]
+          }
+        },
+        {
+          name: "memory_search",
+          description: "Search memories using natural language. Returns the most relevant memories based on semantic similarity to the query.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Natural language search query"
+              },
+              limit: {
+                type: "number",
+                description: "Maximum number of results to return (1-50)",
+                minimum: 1,
+                maximum: 50,
+                default: 10
+              },
+              threshold: {
+                type: "number",
+                description: "Minimum similarity threshold (0-1)",
+                minimum: 0,
+                maximum: 1,
+                default: 0.5
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "memory_list",
+          description: "List recent memories chronologically. Use to review what has been remembered.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                description: "Number of memories to return (1-100)",
+                minimum: 1,
+                maximum: 100,
+                default: 20
+              },
+              offset: {
+                type: "number",
+                description: "Offset for pagination",
+                minimum: 0,
+                default: 0
+              }
+            }
+          }
+        },
+        {
+          name: "memory_get",
+          description: "Retrieve a specific memory by its ID.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "The memory ID (UUID) to retrieve"
+              }
+            },
+            required: ["id"]
+          }
+        },
+        {
+          name: "memory_update",
+          description: "Update the content of an existing memory. Use to correct or expand stored information.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "The memory ID (UUID) to update"
+              },
+              content: {
+                type: "string",
+                description: "The new content to replace the existing memory"
+              },
+              metadata: {
+                type: "object",
+                description: "Updated metadata (replaces existing)",
+                additionalProperties: { type: "string" }
+              }
+            },
+            required: ["id", "content"]
+          }
+        },
+        {
+          name: "memory_delete",
+          description: "Permanently delete a memory. Use sparingly - memories are valuable context.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "The memory ID (UUID) to delete"
+              }
+            },
+            required: ["id"]
+          }
+        },
+        {
+          name: "entity_create",
+          description: "Create a named entity (person, place, organization, project, concept) for the knowledge graph. Entities help organize and connect memories.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              name: {
+                type: "string",
+                minLength: 1,
+                maxLength: 200,
+                description: "Entity name (1-200 characters)"
+              },
+              type: {
+                type: "string",
+                enum: ["person", "place", "organization", "project", "concept", "other"],
+                description: "Entity type classification"
+              },
+              metadata: {
+                type: "object",
+                description: "Optional key-value metadata",
+                additionalProperties: { type: "string" }
+              }
+            },
+            required: ["name", "type"]
+          }
+        },
+        {
+          name: "entity_link",
+          description: "Link an entity to a memory to establish relationships in the knowledge graph.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              entity_id: {
+                type: "string",
+                description: "Entity UUID"
+              },
+              memory_id: {
+                type: "string",
+                description: "Memory UUID"
+              },
+              relationship: {
+                type: "string",
+                description: 'Relationship type (e.g., "mentioned_in", "created_by", "relates_to")',
+                default: "mentioned_in"
+              }
+            },
+            required: ["entity_id", "memory_id"]
+          }
+        },
+        {
+          name: "memory_health",
+          description: "Check API connectivity and health status.",
+          inputSchema: {
+            type: "object",
+            properties: {}
+          }
+        }
+      ]
+    }));
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      this.logger.debug(`Tool called: ${name}`, args);
+      try {
+        switch (name) {
+          case "memory_store": {
+            const memory = await this.client.storeMemory(
+              args.content,
+              args.metadata
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_search": {
+            const results = await this.client.searchMemories(
+              args.query,
+              args.limit,
+              args.threshold
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { memories: results, total: results.length },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "memory_list": {
+            const response = await this.client.listMemories(
+              args.limit,
+              args.offset
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(response, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_get": {
+            const id = args.id;
+            validateUuid(id, "memory_id");
+            const memory = await this.client.getMemory(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_update": {
+            const id = args.id;
+            validateUuid(id, "memory_id");
+            const memory = await this.client.updateMemory(
+              id,
+              args.content,
+              args.metadata
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(memory, null, 2)
+                }
+              ]
+            };
+          }
+          case "memory_delete": {
+            const id = args.id;
+            validateUuid(id, "memory_id");
+            await this.client.deleteMemory(id);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    { success: true, message: "Memory deleted successfully" },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "entity_create": {
+            const entitySchema = z2.object({
+              name: z2.string().min(1).max(200),
+              type: z2.enum(["person", "place", "organization", "project", "concept", "other"]),
+              metadata: z2.record(z2.string()).optional()
+            });
+            const validatedInput = entitySchema.parse(args);
+            const sanitizedName = sanitizeHtml(validatedInput.name);
+            const entity = await this.client.createEntity(
+              sanitizedName,
+              validatedInput.type,
+              validatedInput.metadata
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(entity, null, 2)
+                }
+              ]
+            };
+          }
+          case "entity_link": {
+            const linkSchema = z2.object({
+              entity_id: z2.string().uuid(),
+              memory_id: z2.string().uuid(),
+              relationship: z2.string().default("mentioned_in")
+            });
+            const validatedInput = linkSchema.parse(args);
+            await this.client.linkEntity(
+              validatedInput.entity_id,
+              validatedInput.memory_id,
+              validatedInput.relationship
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      message: "Entity linked to memory successfully",
+                      entity_id: validatedInput.entity_id,
+                      memory_id: validatedInput.memory_id,
+                      relationship: validatedInput.relationship
+                    },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          case "memory_health": {
+            const health = await this.client.healthCheck();
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(health, null, 2)
+                }
+              ]
+            };
+          }
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        let errorMessage = "Unknown error";
+        let errorDetails = void 0;
+        if (error instanceof z2.ZodError) {
+          errorMessage = "Validation error";
+          errorDetails = error.errors;
+        } else if (error instanceof Error) {
+          errorMessage = error.message;
+        }
+        this.logger.error(`Tool execution failed: ${name}`, {
+          error: errorMessage,
+          details: errorDetails
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  error: "Tool execution failed",
+                  message: errorMessage,
+                  details: errorDetails
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+    });
+  }
+  /**
+   * Start the MCP server with STDIO transport
+   */
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    this.logger.info("MCP server started on STDIO");
+  }
+};
+
+// src/index.ts
+async function main() {
+  try {
+    const config = loadConfig();
+    initLogger(config.logLevel);
+    const logger2 = getLogger();
+    logger2.info("Starting MemoryRelay MCP server");
+    const agentId = getAgentId(config);
+    const server = new MemoryRelayMCPServer({
+      apiKey: config.apiKey,
+      apiUrl: config.apiUrl,
+      agentId,
+      timeout: config.timeout
+    });
+    await server.start();
+    process.on("SIGINT", () => {
+      logger2.info("Received SIGINT, shutting down gracefully");
+      process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+      logger2.info("Received SIGTERM, shutting down gracefully");
+      process.exit(0);
+    });
+  } catch (error) {
+    const logger2 = getLogger();
+    if (error instanceof Error) {
+      logger2.error("Fatal error:", { message: error.message });
+      console.error("\n\u274C Failed to start MemoryRelay MCP server\n");
+      console.error(error.message);
+      console.error("\nFor help, see: https://github.com/Alteriom/ai-memory-service/tree/main/mcp\n");
+    } else {
+      logger2.error("Fatal error:", { error });
+      console.error("\n\u274C An unexpected error occurred\n");
+    }
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=index.js.map