@squidcode/forever-plugin 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @squidcode/forever-plugin
+
+MCP (Model Context Protocol) plugin for [Forever](https://forever.squidcode.com) — a centralized persistent memory layer for Claude Code instances.
+
+Forever lets multiple Claude Code sessions share memory across machines, projects, and time. This plugin connects Claude Code to your Forever server via MCP.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18+
+- A Forever account ([register here](https://forever.squidcode.com/register))
+
+## Setup
+
+### 1. Authenticate
+
+```bash
+npx @squidcode/forever-plugin login
+```
+
+You'll be prompted for:
+- **Server URL**: `https://forever.squidcode.com`
+- **Email**: your registered email
+- **Password**: your password
+
+Credentials are saved to `~/.forever/credentials.json` (mode 0600).
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add forever -- npx @squidcode/forever-plugin
+```
+
+This registers the plugin as an MCP server that Claude Code will start automatically.
+
+## Tools
+
+The plugin exposes three MCP tools:
+
+### `memory_log`
+
+Log an entry to Forever memory.
+
+| Parameter   | Type     | Required | Description                          |
+|-------------|----------|----------|--------------------------------------|
+| `project`   | string   | yes      | Project name or git remote URL       |
+| `type`      | enum     | yes      | `summary`, `decision`, or `error`    |
+| `content`   | string   | yes      | The content to log                   |
+| `tags`      | string[] | no       | Tags for categorization              |
+| `sessionId` | string   | no       | Session ID for grouping entries      |
+
+### `memory_get_recent`
+
+Get recent memory entries for a project.
+
+| Parameter | Type   | Required | Description                    |
+|-----------|--------|----------|--------------------------------|
+| `project` | string | yes      | Project name or git remote URL |
+| `limit`   | number | no       | Number of entries (default 20) |
+
+### `memory_search`
+
+Search memory entries across projects.
+
+| Parameter | Type   | Required | Description            |
+|-----------|--------|----------|------------------------|
+| `query`   | string | yes      | Search query           |
+| `project` | string | no       | Filter by project      |
+| `type`    | enum   | no       | Filter by entry type   |
+| `limit`   | number | no       | Max results (default 20) |
+
+## How It Works
+
+- The plugin runs as an MCP stdio server, started by Claude Code on demand.
+- Each machine gets a unique ID (stored in `~/.forever/machine.json`) for tracking which machine produced each memory entry.
+- All API calls are authenticated via JWT token obtained during login.
+
+## Development
+
+```bash
+git clone https://github.com/squidcode/forever-plugin.git
+cd forever-plugin
+npm install
+npm run build
+```
+
+### Scripts
+
+| Script          | Description                  |
+|-----------------|------------------------------|
+| `npm run build` | Compile TypeScript           |
+| `npm run dev`   | Watch mode                   |
+| `npm run lint`  | Run ESLint                   |
+| `npm run format`| Format with Prettier         |
+| `npm run typecheck` | Type-check without emit  |
+
+### Pre-commit Hooks
+
+This project uses [Husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged) to enforce code quality on every commit:
+
+- ESLint auto-fix + Prettier formatting on staged `.ts` files
+- Full TypeScript type-check
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import { type AxiosInstance } from 'axios';
+interface Credentials {
+    serverUrl: string;
+    token: string;
+}
+interface MachineConfig {
+    machineId: string;
+    alias: string;
+}
+export declare function getCredentials(): Credentials | null;
+export declare function saveCredentials(creds: Credentials): void;
+export declare function getMachineConfig(): MachineConfig | null;
+export declare function saveMachineConfig(config: MachineConfig): void;
+export declare function createApiClient(): AxiosInstance | null;
+export {};

package/dist/client.js

@@ -0,0 +1,57 @@
+import axios from 'axios';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const CONFIG_DIR = join(homedir(), '.forever');
+const CREDENTIALS_FILE = join(CONFIG_DIR, 'credentials.json');
+const MACHINE_FILE = join(CONFIG_DIR, 'machine.json');
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+export function getCredentials() {
+    if (!existsSync(CREDENTIALS_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCredentials(creds) {
+    ensureConfigDir();
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), {
+        mode: 0o600,
+    });
+}
+export function getMachineConfig() {
+    if (!existsSync(MACHINE_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(MACHINE_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveMachineConfig(config) {
+    ensureConfigDir();
+    writeFileSync(MACHINE_FILE, JSON.stringify(config, null, 2), {
+        mode: 0o600,
+    });
+}
+export function createApiClient() {
+    const creds = getCredentials();
+    if (!creds)
+        return null;
+    return axios.create({
+        baseURL: creds.serverUrl.replace(/\/$/, '') + '/api',
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+        },
+        timeout: 10000,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createApiClient } from './client.js';
+import { getOrCreateMachineId } from './machine.js';
+const server = new McpServer({
+    name: 'forever',
+    version: '0.1.0',
+});
+const machineId = getOrCreateMachineId();
+server.tool('memory_log', 'Log an entry to Forever memory (summary, decision, or error)', {
+    project: z.string().describe('Project name or git remote URL'),
+    type: z
+        .enum(['summary', 'decision', 'error'])
+        .describe('Type of memory entry'),
+    content: z.string().describe('The content to log'),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe('Optional tags for categorization'),
+    sessionId: z.string().optional().describe('Session ID for grouping'),
+}, async ({ project, type, content, tags, sessionId }) => {
+    const api = createApiClient();
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: forever-plugin login',
+                },
+            ],
+        };
+    }
+    try {
+        await api.post('/logs', {
+            project,
+            type,
+            content,
+            machineId,
+            tags,
+            sessionId,
+        });
+        return {
+            content: [{ type: 'text', text: `Logged ${type} entry.` }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to log: ${err.message}`,
+                },
+            ],
+        };
+    }
+});
+server.tool('memory_get_recent', 'Get recent memory entries for a project', {
+    project: z.string().describe('Project name or git remote URL'),
+    limit: z
+        .number()
+        .optional()
+        .default(20)
+        .describe('Number of entries to fetch'),
+}, async ({ project, limit }) => {
+    const api = createApiClient();
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: forever-plugin login',
+                },
+            ],
+        };
+    }
+    try {
+        const res = await api.get('/logs/recent', {
+            params: { project, limit },
+        });
+        const logs = res.data;
+        if (!logs.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No memory entries found for project "${project}".`,
+                    },
+                ],
+            };
+        }
+        const formatted = logs
+            .map((log) => `[${log.type}] ${log.createdAt}\n${log.content}${log.tags?.length ? `\ntags: ${log.tags.join(', ')}` : ''}`)
+            .join('\n---\n');
+        return { content: [{ type: 'text', text: formatted }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to fetch: ${err.message}`,
+                },
+            ],
+        };
+    }
+});
+server.tool('memory_search', 'Search memory entries across projects', {
+    query: z.string().describe('Search query'),
+    project: z.string().optional().describe('Filter by project'),
+    type: z
+        .enum(['user_input', 'claude_reply', 'summary', 'decision', 'error'])
+        .optional()
+        .describe('Filter by entry type'),
+    limit: z.number().optional().default(20).describe('Max results'),
+}, async ({ query, project, type, limit }) => {
+    const api = createApiClient();
+    if (!api) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Not authenticated. Run: forever-plugin login',
+                },
+            ],
+        };
+    }
+    try {
+        const params = { query, limit };
+        if (project)
+            params.project = project;
+        if (type)
+            params.type = type;
+        const res = await api.get('/logs/search', { params });
+        const logs = res.data;
+        if (!logs.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No results for "${query}".`,
+                    },
+                ],
+            };
+        }
+        const formatted = logs
+            .map((log) => `[${log.type}] ${log.project} - ${log.createdAt}\n${log.content}`)
+            .join('\n---\n');
+        return { content: [{ type: 'text', text: formatted }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Search failed: ${err.message}`,
+                },
+            ],
+        };
+    }
+});
+// Login subcommand
+if (process.argv[2] === 'login') {
+    const readline = await import('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+    console.log('Forever Plugin Login\n');
+    const serverUrl = await ask('Server URL (e.g. https://forever-z44hy.ondigitalocean.app): ');
+    const email = await ask('Email: ');
+    const password = await ask('Password: ');
+    try {
+        const { default: axios } = await import('axios');
+        const res = await axios.post(`${serverUrl.replace(/\/$/, '')}/api/auth/login`, {
+            email,
+            password,
+        });
+        const { saveCredentials } = await import('./client.js');
+        saveCredentials({ serverUrl, token: res.data.access_token });
+        console.log('\nAuthenticated! Credentials saved to ~/.forever/credentials.json');
+    }
+    catch (err) {
+        console.error('\nLogin failed:', err.response?.data?.message || err.message);
+        process.exit(1);
+    }
+    rl.close();
+    process.exit(0);
+}
+// Start MCP server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/machine.d.ts

@@ -0,0 +1 @@
+export declare function getOrCreateMachineId(): string;

package/dist/machine.js

@@ -0,0 +1,11 @@
+import { randomBytes } from 'crypto';
+import { hostname } from 'os';
+import { getMachineConfig, saveMachineConfig } from './client.js';
+export function getOrCreateMachineId() {
+    const config = getMachineConfig();
+    if (config?.machineId)
+        return config.machineId;
+    const id = `${hostname()}-${randomBytes(4).toString('hex')}`;
+    saveMachineConfig({ machineId: id, alias: hostname() });
+    return id;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@squidcode/forever-plugin",
+  "version": "0.1.0",
+  "description": "MCP plugin for Forever - Claude Memory System",
+  "type": "module",
+  "bin": {
+    "forever-plugin": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "lint": "eslint 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "memory",
+    "forever"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/squidcode/forever-plugin.git"
+  }
+}