npm package: @iforgot/memory-mcp
Description: A multi-transport MCP server for iForgot memory management supporting STDIO, HTTP, and SSE transports
Author: iForgot Team
Latest version: 0.0.7

# @iforgot/memory-mcp

A multi-transport MCP (Model Context Protocol) server for iForgot memory management that supports STDIO, HTTP, and SSE transports.

## Overview

This package provides a local MCP server that bridges AI assistants with the iForgot memory system. It provides two essential tools for memory management:

- `add_memories` - Add new memories to your iForgot account
- `search_memories` - Search through your existing memories

## Transport Support

The server supports multiple transport types:

- **STDIO**: Traditional standard input/output (default)
- **HTTP**: HTTP-based transport
- **SSE**: Server-Sent Events transport for real-time communication

## Prerequisites

Before using this package, you need to have Node.js installed on your system since the package is distributed via npm and uses npx.

### Installing Node.js

1. Visit [nodejs.org](https://nodejs.org/)
2. Download the LTS (Long Term Support) version for your operating system
3. Run the installer and follow the installation wizard
4. Verify installation by running: `node --version` and `npm --version`

### Verifying Installation

After installing Node.js, verify that both Node.js and npm are installed:

```bash
node --version
npm --version
```

You should see version numbers for both commands. npm (Node Package Manager) comes bundled with Node.js and includes npx.

## Configuration

The MCP server requires environment variables for authentication:

### Required Environment Variables

- `IFORGOT_API_KEY` - Your iForgot API key

### Optional Environment Variables

- `IFORGOT_SERVER_URL` - iForgot server URL (defaults to `https://app.iforgot.ai`)

## Command Line Options

The server supports the following CLI options:

- `--transport <stdio|http|sse>` - Transport type (default: stdio)
- `--port <number>` - Port for HTTP/SSE transport (default: 3000)

### Examples

```bash
# Run with default STDIO transport
npx @iforgot/memory-mcp

# Run with HTTP transport on default port (3000)
npx @iforgot/memory-mcp --transport http

# Run with SSE transport on custom port
npx @iforgot/memory-mcp --transport sse --port 3001

# Run with HTTP transport on custom port
npx @iforgot/memory-mcp --transport http --port 8080
```

## Usage with AI Assistants

### Claude Desktop (STDIO)

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "iforgot": {
      "command": "npx",
      "args": ["-y", "@iforgot/memory-mcp"],
      "env": {
        "IFORGOT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Desktop (SSE)

For SSE transport with Claude Desktop:

```json
{
  "mcpServers": {
    "iforgot": {
      "command": "npx",
      "args": ["-y", "@iforgot/memory-mcp", "--transport", "sse", "--port", "3000"],
      "env": {
        "IFORGOT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor (STDIO)

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "iforgot": {
      "command": "npx",
      "args": ["-y", "@iforgot/memory-mcp"],
      "env": {
        "IFORGOT_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### HTTP/SSE Endpoints

When running in HTTP or SSE mode, the following endpoints are available:

- **GET /ping** - Health check endpoint
- **POST /mcp** - HTTP transport endpoint
- **GET /sse** - SSE transport initialization
- **POST /messages?sessionId=<id>** - SSE message handling

Example HTTP/SSE usage:

```bash
# Start the server
npx @iforgot/memory-mcp --transport sse --port 3000

# Health check
curl http://localhost:3000/ping

# Initialize SSE connection
curl http://localhost:3000/sse
```

### Other MCP Clients

For any MCP client that supports STDIO transport:

```json
{
  "command": "npx",
  "args": ["-y", "@iforgot/memory-mcp"],
  "env": {
    "IFORGOT_API_KEY": "your-api-key-here"
  }
}
```

For HTTP/SSE transport, configure your client to connect to:
- HTTP: `http://localhost:3000/mcp`
- SSE: `http://localhost:3000/sse`

## Available Tools

### add_memories

Adds a new memory to your iForgot account.

**Parameters:**
- `text` (string, required) - The text to add to memory

**Example:**
```
Add this to memory: "I prefer dark mode for all applications"
```

### search_memories

Searches through your stored memories.

**Parameters:**
- `query` (string, required) - Search query using relevant keywords

**Example:**
```
Search for memories about: "dark mode preferences"
```

## Development

### Local Development

```bash
# Clone and install dependencies
git clone <repository-url>
cd packages/memory-mcp
npm install

# Build the project
npm run build

# Run in development mode
npm run build:watch

# Start with different transports
node dist/index.js --transport stdio
node dist/index.js --transport http --port 3000
node dist/index.js --transport sse --port 3001
```

### Environment Setup

Create a `.env` file:

```env
IFORGOT_API_KEY=your-api-key-here
IFORGOT_SERVER_URL=https://app.iforgot.ai
```

## Troubleshooting

### Common Issues

**"Missing required environment variables"**
- Ensure `IFORGOT_API_KEY` is set
- Check that your API key is valid

**"Memory API error: 401"**
- Verify your API key is correct
- Check that your iForgot account has API access

**"Connection refused"**
- Verify the `IFORGOT_SERVER_URL` is correct
- Check your internet connection

**"Port already in use"**
- The server will automatically try the next available port
- Use `--port` to specify a different starting port

**"Invalid transport value"**
- Ensure you're using one of: `stdio`, `http`, or `sse`
- Check for typos in the transport parameter

### Transport-Specific Troubleshooting

**HTTP/SSE Transport:**
- Ensure the port is available and not blocked by firewall
- Check that no other services are running on the same port
- Verify CORS headers if accessing from a web application

**STDIO Transport:**
- This is the most reliable transport for local AI assistants
- Use this when in doubt or for simple integrations

## License

See the main repository license.