hyperstack-mcp 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# 🃏 HyperStack MCP Server
+
+**Cloud memory for AI agents. One key. Zero dependencies. No LLM costs.**
+
+Give Claude, Cursor, VS Code, or any MCP client persistent memory in 30 seconds.
+
+## Why HyperStack over alternatives?
+
+|  | HyperStack | Mem0 | Letta |
+|---|---|---|---|
+| **Env vars needed** | 1 (`API_KEY`) | 6+ (API key, OpenAI key, DB URL, LLM provider, model, embedding) | 3+ (URL, password, Node.js) |
+| **LLM cost per memory op** | $0 | ~$0.002 (embedding call) | ~$0.002 |
+| **Docker required** | No | Yes (self-hosted) | Yes |
+| **Setup time** | 30 seconds | 5-15 minutes | 10+ minutes |
+| **Token savings** | 94% (~350 vs ~6,000) | Up to 80% | Varies |
+| **Works offline** | Cloud API (always available) | Depends on config | Needs running server |
+
+## Install
+
+### Claude Desktop / Claude Code
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hyperstack": {
+      "command": "npx",
+      "args": ["-y", "@cascadeai/hyperstack-mcp"],
+      "env": {
+        "HYPERSTACK_API_KEY": "hs_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "hyperstack": {
+      "command": "npx",
+      "args": ["-y", "@cascadeai/hyperstack-mcp"],
+      "env": {
+        "HYPERSTACK_API_KEY": "hs_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "hyperstack": {
+      "command": "npx",
+      "args": ["-y", "@cascadeai/hyperstack-mcp"],
+      "env": {
+        "HYPERSTACK_API_KEY": "hs_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "hyperstack": {
+      "command": "npx",
+      "args": ["-y", "@cascadeai/hyperstack-mcp"],
+      "env": {
+        "HYPERSTACK_API_KEY": "hs_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**That's it.** Get your free API key at [cascadeai.dev](https://cascadeai.dev).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `store_memory` | Save or update a memory card (upserts by slug) |
+| `search_memory` | Search cards by keyword, title, or content |
+| `list_memories` | List all cards, optionally filter by stack |
+| `delete_memory` | Remove a card by slug |
+| `memory_stats` | Usage summary, savings estimate, plan info |
+
+### Stacks (categories)
+
+Organize memories into stacks for better retrieval:
+
+- `projects` — Tech stacks, repos, architecture
+- `people` — Teammates, contacts, roles
+- `decisions` — Why you chose X over Y
+- `preferences` — Editor, tools, coding style
+- `workflows` — Deploy steps, review processes
+- `general` — Everything else
+
+## How it works
+
+Your agent stores small knowledge cards (~350 tokens each) instead of stuffing entire conversation histories into the prompt (~6,000 tokens). Before responding, it searches for relevant cards. Result: **94% less token usage**, which means real money saved on API bills.
+
+```
+Without HyperStack:  $270/mo (6,000 tokens × every message)
+With HyperStack:      $16/mo (350 tokens × only relevant cards)
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `HYPERSTACK_API_KEY` | ✅ | — | Your API key (starts with `hs_`) |
+| `HYPERSTACK_WORKSPACE` | — | `default` | Workspace to use |
+| `HYPERSTACK_API_URL` | — | `https://hyperstack-cloud.vercel.app` | API base URL |
+
+## Get a free API key
+
+1. Go to [cascadeai.dev](https://cascadeai.dev)
+2. Enter your email → create account
+3. Copy your `hs_` key from the dashboard
+4. Paste into config above
+
+**50 cards free forever. No credit card. Upgrade to Pro ($15/mo) for unlimited.**
+
+## Links
+
+- 🌐 [Website](https://cascadeai.dev)
+- 📖 [API Docs](https://cascadeai.dev)
+- 💬 [Discord](https://discord.gg/tdnXaV6e)
+- 🐛 [Issues](https://github.com/cascadeai/hyperstack-mcp/issues)
+
+## License
+
+MIT © [CascadeAI](https://cascadeai.dev)

package/build/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * HyperStack MCP Server
+ *
+ * Cloud memory for AI agents via Model Context Protocol.
+ *
+ * SETUP (30 seconds):
+ *   1. Get API key at https://cascadeai.dev
+ *   2. Add to your MCP client config:
+ *      {
+ *        "mcpServers": {
+ *          "hyperstack": {
+ *            "command": "npx",
+ *            "args": ["-y", "@cascadeai/hyperstack-mcp"],
+ *            "env": { "HYPERSTACK_API_KEY": "hs_your_key" }
+ *          }
+ *        }
+ *      }
+ *   3. Done. Your agent now has persistent cloud memory.
+ *
+ * WHY HYPERSTACK:
+ *   - 1 env var (vs Mem0's 6+)
+ *   - No LLM costs for memory ops (Mem0 charges per embedding)
+ *   - No Docker, no database, no OpenAI key needed
+ *   - 94% token savings — ~350 tokens vs ~6,000 per message
+ *
+ * @see https://cascadeai.dev
+ * @see https://hyperstack-cloud.vercel.app
+ */
+export {};

package/build/index.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * HyperStack MCP Server
+ *
+ * Cloud memory for AI agents via Model Context Protocol.
+ *
+ * SETUP (30 seconds):
+ *   1. Get API key at https://cascadeai.dev
+ *   2. Add to your MCP client config:
+ *      {
+ *        "mcpServers": {
+ *          "hyperstack": {
+ *            "command": "npx",
+ *            "args": ["-y", "@cascadeai/hyperstack-mcp"],
+ *            "env": { "HYPERSTACK_API_KEY": "hs_your_key" }
+ *          }
+ *        }
+ *      }
+ *   3. Done. Your agent now has persistent cloud memory.
+ *
+ * WHY HYPERSTACK:
+ *   - 1 env var (vs Mem0's 6+)
+ *   - No LLM costs for memory ops (Mem0 charges per embedding)
+ *   - No Docker, no database, no OpenAI key needed
+ *   - 94% token savings — ~350 tokens vs ~6,000 per message
+ *
+ * @see https://cascadeai.dev
+ * @see https://hyperstack-cloud.vercel.app
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ═══════════════════════════════════════════════════════
+// CONFIG
+// ═══════════════════════════════════════════════════════
+const API_KEY = process.env.HYPERSTACK_API_KEY;
+const WORKSPACE = process.env.HYPERSTACK_WORKSPACE || "default";
+const API_BASE = process.env.HYPERSTACK_API_URL || "https://hyperstack-cloud.vercel.app";
+if (!API_KEY) {
+    console.error(`
+╔══════════════════════════════════════════════════════╗
+║  HyperStack MCP — Missing API Key                   ║
+╠══════════════════════════════════════════════════════╣
+║                                                      ║
+║  Set HYPERSTACK_API_KEY in your MCP config:           ║
+║                                                      ║
+║  "env": {                                            ║
+║    "HYPERSTACK_API_KEY": "hs_your_key_here"          ║
+║  }                                                   ║
+║                                                      ║
+║  Get your free key at: https://cascadeai.dev         ║
+║  50 cards free. No credit card.                      ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+`);
+    process.exit(1);
+}
+async function api(endpoint, opts = {}) {
+    const url = new URL(`${API_BASE}/api/${endpoint}`);
+    url.searchParams.set("workspace", WORKSPACE);
+    if (opts.params) {
+        for (const [k, v] of Object.entries(opts.params)) {
+            url.searchParams.set(k, v);
+        }
+    }
+    const headers = {
+        "X-API-Key": API_KEY,
+        "Content-Type": "application/json",
+    };
+    const res = await fetch(url.toString(), {
+        method: opts.method || "GET",
+        headers,
+        body: opts.body ? JSON.stringify(opts.body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        throw new Error(data.error || `API error ${res.status}`);
+    }
+    return data;
+}
+// ═══════════════════════════════════════════════════════
+// MCP SERVER
+// ═══════════════════════════════════════════════════════
+const server = new McpServer({
+    name: "hyperstack",
+    version: "1.0.0",
+});
+// ───────────────────────────────────────────────────────
+// TOOL: store_memory
+// ───────────────────────────────────────────────────────
+server.tool("store_memory", `Store or update a memory card in HyperStack. Use this whenever you learn something worth remembering — a user preference, project detail, decision, person info, or workflow step. If a card with the same slug exists, it will be updated (upsert).
+
+Stacks (categories): projects, people, decisions, preferences, workflows, general.
+Cost: This saves money — instead of stuffing 6,000 tokens into every prompt, you store knowledge as ~350-token cards and only retrieve what's relevant.`, {
+    slug: z.string().describe("Unique ID for this memory (kebab-case, e.g. 'project-webapp', 'person-alice')"),
+    title: z.string().describe("Short human-readable title"),
+    body: z.string().describe("The knowledge to remember (markdown OK, keep concise — a few lines)"),
+    stack: z.enum(["projects", "people", "decisions", "preferences", "workflows", "general"])
+        .default("general")
+        .describe("Category for this memory"),
+    keywords: z.array(z.string()).default([])
+        .describe("Tags for search (e.g. ['react', 'vercel', 'auth'])"),
+}, async ({ slug, title, body, stack, keywords }) => {
+    try {
+        const result = await api("cards", {
+            method: "POST",
+            body: { slug, title, body, stack, keywords },
+        });
+        const action = result.created ? "Created" : "Updated";
+        return {
+            content: [{
+                    type: "text",
+                    text: `✅ ${action} card "${title}" (${slug}) in ${stack} stack. ${result.card?.tokens || 0} tokens stored.`,
+                }],
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `❌ Failed to store: ${e.message}` }],
+            isError: true,
+        };
+    }
+});
+// ───────────────────────────────────────────────────────
+// TOOL: search_memory
+// ───────────────────────────────────────────────────────
+server.tool("search_memory", `Search your HyperStack memory for relevant cards. Use this BEFORE answering questions — check if you already know something about the topic. Searches titles, keywords, and body content.
+
+Always search memory at the start of a conversation or when a new topic comes up. This is how you stay context-aware without wasting tokens.`, {
+    query: z.string().describe("Search term (e.g. 'auth', 'alice', 'deployment')"),
+}, async ({ query }) => {
+    try {
+        const result = await api("search", { params: { q: query } });
+        const cards = result.cards || [];
+        if (cards.length === 0) {
+            return {
+                content: [{ type: "text", text: `No memories found for "${query}". You may want to store_memory if you learn something new.` }],
+            };
+        }
+        const formatted = cards.map((c) => `📄 **${c.title}** (${c.stack})\n` +
+            `   slug: ${c.slug} | keywords: ${(c.keywords || []).join(", ")}\n` +
+            `   ${c.body}`).join("\n\n");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Found ${cards.length} memor${cards.length === 1 ? "y" : "ies"} for "${query}":\n\n${formatted}`,
+                }],
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `❌ Search failed: ${e.message}` }],
+            isError: true,
+        };
+    }
+});
+// ───────────────────────────────────────────────────────
+// TOOL: list_memories
+// ───────────────────────────────────────────────────────
+server.tool("list_memories", `List all memory cards in your workspace, optionally filtered by stack. Use this to get an overview of everything stored, find stale cards, or check what categories exist.`, {
+    stack: z.enum(["projects", "people", "decisions", "preferences", "workflows", "general", "all"])
+        .default("all")
+        .describe("Filter by stack category, or 'all' for everything"),
+}, async ({ stack }) => {
+    try {
+        const result = await api("cards");
+        let cards = result.cards || [];
+        if (stack !== "all") {
+            cards = cards.filter((c) => c.stack === stack);
+        }
+        if (cards.length === 0) {
+            return {
+                content: [{ type: "text", text: stack === "all"
+                            ? "No memories stored yet. Use store_memory to create your first card."
+                            : `No memories in the "${stack}" stack.` }],
+            };
+        }
+        // Group by stack
+        const grouped = {};
+        for (const c of cards) {
+            (grouped[c.stack] = grouped[c.stack] || []).push(c);
+        }
+        let text = `📚 **${cards.length} memor${cards.length === 1 ? "y" : "ies"}** in workspace "${WORKSPACE}"`;
+        text += ` (${result.plan || "FREE"} plan, limit: ${result.limit || 50})\n\n`;
+        for (const [stackName, stackCards] of Object.entries(grouped)) {
+            text += `### ${stackName} (${stackCards.length})\n`;
+            for (const c of stackCards) {
+                const kw = (c.keywords || []).slice(0, 4).join(", ");
+                text += `- **${c.title}** \`${c.slug}\`${kw ? ` [${kw}]` : ""} — ${c.tokens || 0}t\n`;
+            }
+            text += "\n";
+        }
+        const totalTokens = cards.reduce((sum, c) => sum + (c.tokens || 0), 0);
+        text += `---\nTotal: ${totalTokens} tokens stored. Without HyperStack this would cost ~${cards.length * 6000} tokens per message.`;
+        return { content: [{ type: "text", text }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `❌ Failed to list: ${e.message}` }],
+            isError: true,
+        };
+    }
+});
+// ───────────────────────────────────────────────────────
+// TOOL: delete_memory
+// ───────────────────────────────────────────────────────
+server.tool("delete_memory", `Delete a memory card by its slug. Use this for outdated, incorrect, or duplicate memories. Keeping your memory clean improves search quality and saves tokens.`, {
+    slug: z.string().describe("The slug of the card to delete"),
+}, async ({ slug }) => {
+    try {
+        await api("cards", { method: "DELETE", params: { id: slug } });
+        return {
+            content: [{ type: "text", text: `🗑️ Deleted card "${slug}".` }],
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `❌ Failed to delete: ${e.message}` }],
+            isError: true,
+        };
+    }
+});
+// ───────────────────────────────────────────────────────
+// TOOL: memory_stats
+// ───────────────────────────────────────────────────────
+server.tool("memory_stats", `Get a summary of your memory usage — card count, tokens stored, savings estimate, and breakdown by stack. Useful for understanding how much you're saving and whether you need to upgrade.`, {}, async () => {
+    try {
+        const result = await api("cards");
+        const cards = result.cards || [];
+        const totalTokens = cards.reduce((sum, c) => sum + (c.tokens || 0), 0);
+        const withoutHS = cards.length * 6000;
+        const savings = withoutHS > 0 ? Math.round((1 - totalTokens / withoutHS) * 100) : 0;
+        // Stack breakdown
+        const stacks = {};
+        for (const c of cards) {
+            stacks[c.stack] = (stacks[c.stack] || 0) + 1;
+        }
+        let text = `📊 **HyperStack Memory Stats**\n\n`;
+        text += `Cards: **${cards.length}** / ${result.limit || 50}\n`;
+        text += `Plan: **${result.plan || "FREE"}**\n`;
+        text += `Workspace: ${WORKSPACE}\n`;
+        text += `Tokens stored: ${totalTokens.toLocaleString()}\n`;
+        text += `Without HyperStack: ~${withoutHS.toLocaleString()} tokens/message\n`;
+        text += `**Savings: ${savings}%**\n\n`;
+        if (Object.keys(stacks).length > 0) {
+            text += `**By stack:**\n`;
+            for (const [s, count] of Object.entries(stacks).sort((a, b) => b[1] - a[1])) {
+                text += `  ${s}: ${count} card${count !== 1 ? "s" : ""}\n`;
+            }
+        }
+        if (result.plan === "FREE" && cards.length >= (result.limit || 50) * 0.8) {
+            text += `\n⚠️ You're at ${cards.length}/${result.limit || 50} cards. Consider upgrading to Pro for unlimited cards at https://cascadeai.dev`;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `❌ Failed to get stats: ${e.message}` }],
+            isError: true,
+        };
+    }
+});
+// ═══════════════════════════════════════════════════════
+// START
+// ═══════════════════════════════════════════════════════
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🃏 HyperStack MCP server running (workspace: %s)", WORKSPACE);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "hyperstack-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for HyperStack — cloud memory for AI agents. One API key, zero dependencies, no LLM costs.",
+  "type": "module",
+  "bin": {
+    "hyperstack-mcp": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepare": "npm run build",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-memory",
+    "hyperstack",
+    "claude",
+    "cursor",
+    "agent-memory",
+    "llm"
+  ],
+  "author": "CascadeAI <deeqyaqub@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://cascadeai.dev",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}