@velua-ai/memory-mcp 0.1.5

package/README.md

@@ -0,0 +1,121 @@
+# @velua-ai/memory-mcp
+
+**Shared memory & TODO for your AI agents.** Connect any MCP-compatible agent
+(Claude Code, Cursor, Codex, and more) to a single, shared per-project TODO list
+and knowledge base — so every agent, and every teammate, works from the same
+plan and the same context.
+
+Stop re-explaining the project to each new agent. One shared memory. One shared
+backlog. Always in sync.
+
+---
+
+## Why
+
+- **One source of truth** — every agent reads and writes the same TODO and memory
+  for the project, instead of each keeping its own scratchpad.
+- **Team-aware** — memory is scoped to your organization, so your whole team's
+  agents collaborate on the same board.
+- **Frictionless sign-in** — no tokens to copy. The agent asks you to approve
+  once in the browser, and you're in.
+- **Works everywhere** — any MCP client. Same tools, same data, wherever you code.
+
+## Install
+
+```bash
+npm install -g @velua-ai/memory-mcp
+```
+
+## Sign in (one click)
+
+The first time an agent needs it, it calls the **`velua_login`** tool — a browser
+tab opens, you approve once, done. Your session is saved locally in
+`~/.velua/mcp.json`. No token copy-paste.
+
+> For CI/headless use, set `VELUA_TOKEN` with a token issued from your Velua
+> account.
+
+## Add it to your agent
+
+Each agent registers MCP servers a little differently — pick yours.
+
+**Claude Code** — one command, no file editing:
+```bash
+claude mcp add velua-memory -s user -- npx -y @velua-ai/memory-mcp
+```
+
+**Cursor** (`~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` in a repo):
+```json
+{
+  "mcpServers": {
+    "velua-memory": { "command": "npx", "args": ["-y", "@velua-ai/memory-mcp"] }
+  }
+}
+```
+
+**Codex CLI** — TOML, not JSON (`~/.codex/config.toml`):
+```toml
+[mcp_servers.velua-memory]
+command = "npx"
+args = ["-y", "@velua-ai/memory-mcp"]
+```
+
+**VS Code** (`.vscode/mcp.json`) — note the top-level key is `servers`, not `mcpServers`:
+```json
+{
+  "servers": {
+    "velua-memory": { "command": "npx", "args": ["-y", "@velua-ai/memory-mcp"] }
+  }
+}
+```
+
+> Using `npx` means you never run a separate install step — it fetches and caches
+> the package on first launch. Prefer a fixed binary? `npm install -g
+> @velua-ai/memory-mcp` and use `"command": "velua-memory-mcp"` instead.
+
+## How projects are identified
+
+Each TODO/memory board is scoped to a **project**. The project is resolved, in order:
+
+1. **`VELUA_PROJECT`** if set — an explicit override.
+2. A **`.velua.json`** file in the folder (or any parent) — see below.
+3. Otherwise your **git remote** name (e.g. `github.com/acme/checkout` → `checkout`).
+4. Otherwise the **current folder** name.
+
+Because it keys off the git remote, two clones of the same repo — on different
+machines or paths — map to the **same** shared board, so your whole team lands in
+sync automatically.
+
+### No git? Drop a `.velua.json` in the folder
+
+When a folder isn't a git repo (or you just want to pin the name), create a
+`.velua.json` in it — the server searches up from the working directory, like git:
+
+```json
+{
+  "project": "cliente-acme",
+  "agent": "cursor"
+}
+```
+
+All fields optional: `project` (the board name), `agent` (label for who created
+each item), `apiUrl` (advanced). An `.velua.example.json` is included to copy.
+
+### Options (all optional)
+| Env | Default | What it does |
+|---|---|---|
+| `VELUA_PROJECT` | your git repo name (or folder) | which project the TODO/memory belongs to |
+| `VELUA_TOKEN` | — | a ready token, skips the browser sign-in |
+| `VELUA_AGENT` | `mcp` | a label for who created each item |
+
+## Tools
+
+- **`velua_login`** — sign this device in (opens the browser).
+- **`todo_list` / `todo_add` / `todo_update`** — the project's shared TODO list.
+- **`memory_get` / `memory_set`** — the project's shared memory (key → content).
+
+---
+
+Part of the **Velua** platform. Learn more at [velua.ai](https://velua.ai).
+
+_Licensed under Apache-2.0._

package/dist/index.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * @velua-ai/memory-mcp — shared memory & TODO for your AI agents.
+ *
+ * Connects any MCP-compatible agent (Claude Code, Cursor, Codex, …) to a single
+ * shared per-project TODO list and knowledge base, scoped to your organization,
+ * so every agent and teammate works from the same plan and context.
+ *
+ * Frictionless sign-in: the `velua_login` tool opens the browser, you approve
+ * once, and the session is saved to ~/.velua/mcp.json. For CI/headless use, set
+ * VELUA_TOKEN.
+ *
+ * Options (env, all optional):
+ *   VELUA_PROJECT   which project the TODO/memory belongs to (default: git repo name)
+ *   VELUA_TOKEN     a ready token — skips the browser sign-in
+ *   VELUA_AGENT     a label for who created each item (default: mcp)
+ */
+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 { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+function findProjectConfig() {
+    let dir = process.cwd();
+    for (;;) {
+        const p = join(dir, ".velua.json");
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf8"));
+            }
+            catch {
+                return {};
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return {};
+        dir = parent;
+    }
+}
+const CONFIG = findProjectConfig();
+const API_URL = (process.env.VELUA_API_URL || CONFIG.apiUrl || "https://platform.velua.ai").replace(/\/+$/, "");
+const SSO_URL = (process.env.VELUA_SSO_URL || "https://sso.velua.ai").replace(/\/+$/, "");
+const CLIENT_ID = process.env.VELUA_OAUTH_CLIENT_ID || "velua-mcp";
+const TOKEN_PATH = join(homedir(), ".velua", "mcp.json");
+function loadToken() {
+    if (process.env.VELUA_TOKEN)
+        return process.env.VELUA_TOKEN.trim();
+    try {
+        return JSON.parse(readFileSync(TOKEN_PATH, "utf8")).token;
+    }
+    catch {
+        return undefined;
+    }
+}
+function saveToken(token) {
+    try {
+        mkdirSync(join(homedir(), ".velua"), { recursive: true });
+    }
+    catch { }
+    writeFileSync(TOKEN_PATH, JSON.stringify({ token }, null, 2), { mode: 0o600 });
+}
+/** Projeto: env → .velua.json → nome do repo git (basename do remote) → cwd. */
+function resolveProject() {
+    if (process.env.VELUA_PROJECT)
+        return process.env.VELUA_PROJECT.trim();
+    if (CONFIG.project)
+        return CONFIG.project.trim();
+    try {
+        const remote = execSync("git config --get remote.origin.url", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+        const m = remote.match(/([^/:]+?)(?:\.git)?$/);
+        if (m?.[1])
+            return m[1];
+    }
+    catch { }
+    return process.cwd().split(/[/\\]/).pop() || "default";
+}
+const AGENT = process.env.VELUA_AGENT || CONFIG.agent || "mcp";
+const PROJECT = resolveProject();
+async function api(path, init = {}) {
+    const token = loadToken();
+    if (!token)
+        throw new Error("NOT_AUTHENTICATED");
+    const res = await fetch(`${API_URL}${path}`, {
+        ...init,
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ...(init.headers || {}) },
+    });
+    if (res.status === 401)
+        throw new Error("NOT_AUTHENTICATED");
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(json?.error || `platform ${res.status}`);
+    return json;
+}
+// ── OAuth localhost (baixa fricção) ───────────────────────────────────────────
+function b64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Página de sucesso do callback OAuth — branded Velua (auto-fecha se possível). */
+const SUCCESS_HTML = `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Velua conectado</title>
+<style>
+  :root{color-scheme:dark light}
+  *{box-sizing:border-box}
+  body{margin:0;min-height:100vh;display:grid;place-items:center;background:#0f0f14;color:#e9e9ee;
+    font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}
+  .card{max-width:400px;padding:40px 36px;text-align:center;border:1px solid #23232c;border-radius:18px;
+    background:#17171d;box-shadow:0 30px 70px -30px rgba(0,0,0,.7)}
+  .mark{width:56px;height:56px;margin:0 auto 20px;border-radius:50%;display:grid;place-items:center;
+    background:linear-gradient(135deg,#FF8A5B,#C24BE0 52%,#6457F6)}
+  .mark svg{width:28px;height:28px;stroke:#fff;stroke-width:3;fill:none;stroke-linecap:round;stroke-linejoin:round}
+  h1{margin:0 0 8px;font-size:19px;font-weight:700}
+  p{margin:0;color:#a0a0ad;font-size:14px}
+  .brand{margin-top:22px;font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:#6b6b78}
+</style></head><body>
+  <div class="card">
+    <div class="mark"><svg viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"/></svg></div>
+    <h1>Conectado à Velua</h1>
+    <p>Pode fechar esta aba e voltar ao seu terminal.</p>
+    <div class="brand">Velua</div>
+  </div>
+  <script>setTimeout(function(){window.close()},1200)</script>
+</body></html>`;
+async function loginViaBrowser() {
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const state = b64url(randomBytes(16));
+    let resolve, reject;
+    const done = new Promise((res, rej) => { resolve = res; reject = rej; });
+    const server = createServer(async (req, res) => {
+        const u = new URL(req.url || "/", "http://127.0.0.1");
+        if (!u.pathname.startsWith("/callback")) {
+            res.writeHead(404).end();
+            return;
+        }
+        const code = u.searchParams.get("code");
+        if (u.searchParams.get("state") !== state || !code) {
+            res.writeHead(400).end("invalid callback");
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(SUCCESS_HTML);
+        server.close();
+        try {
+            // usa o mesmo port/redirect_uri mandado ao SSO (server.address() já é null após close()).
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const tk = await fetch(`${SSO_URL}/oauth/token`, {
+                method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: CLIENT_ID, code_verifier: verifier }),
+            });
+            const j = (await tk.json());
+            if (!j.access_token)
+                throw new Error(j.error || "sem access_token");
+            saveToken(j.access_token);
+            resolve(j.access_token);
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const url = `${SSO_URL}/oauth/authorize?` + new URLSearchParams({
+        response_type: "code", client_id: CLIENT_ID, redirect_uri: redirectUri,
+        code_challenge: challenge, code_challenge_method: "S256",
+        scope: "openid profile", state,
+    }).toString();
+    setTimeout(() => { try {
+        server.close();
+    }
+    catch { } ; reject(new Error("login expirou (2min)")); }, 120_000);
+    return { url, done };
+}
+function tryOpen(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        execSync(`${cmd} "${url}"`, { stdio: "ignore" });
+    }
+    catch { }
+}
+// ── MCP tools ─────────────────────────────────────────────────────────────────
+const TOOLS = [
+    { name: "velua_login", description: "Authenticate this device with Velua (opens a browser to approve). Call this first if other tools return NOT_AUTHENTICATED.", inputSchema: { type: "object", properties: {} } },
+    { name: "todo_list", description: "List the shared project TODO items (visible to every agent working on this project).", inputSchema: { type: "object", properties: {} } },
+    { name: "todo_add", description: "Add a TODO item to the shared project list.", inputSchema: { type: "object", properties: { title: { type: "string" }, detail: { type: "string" } }, required: ["title"] } },
+    { name: "todo_update", description: "Update a TODO's status or text. status: open | in_progress | done.", inputSchema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, title: { type: "string" }, detail: { type: "string" } }, required: ["id"] } },
+    { name: "memory_get", description: "Read shared project memory. Omit key to list all keys, or pass key for one.", inputSchema: { type: "object", properties: { key: { type: "string" } } } },
+    { name: "memory_set", description: "Write/update a shared project memory entry (key → content).", inputSchema: { type: "object", properties: { key: { type: "string" }, content: { type: "string" } }, required: ["key", "content"] } },
+];
+const server = new Server({ name: "velua-memory", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+function text(t) { return { content: [{ type: "text", text: t }] }; }
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    try {
+        if (name === "velua_login") {
+            const { url, done } = await loginViaBrowser();
+            tryOpen(url);
+            await done;
+            return text(`Autenticado com sucesso na Velua. Projeto: "${PROJECT}".`);
+        }
+        if (name === "todo_list") {
+            const d = await api(`/api/project/${encodeURIComponent(PROJECT)}/todos`);
+            const items = (d.todos || []).map((t) => `- [${t.status}] ${t.title}${t.detail ? " — " + t.detail : ""} (id: ${t.id}${t.createdByAgent ? ", por " + t.createdByAgent : ""})`).join("\n");
+            return text(items ? `TODO de "${PROJECT}":\n${items}` : `Nenhum TODO em "${PROJECT}".`);
+        }
+        if (name === "todo_add") {
+            const d = await api(`/api/project/${encodeURIComponent(PROJECT)}/todos`, { method: "POST", body: JSON.stringify({ title: args.title, detail: args.detail, agent: AGENT }) });
+            return text(`Adicionado: "${d.todo.title}" (id: ${d.todo.id}).`);
+        }
+        if (name === "todo_update") {
+            const d = await api(`/api/project/todos/${encodeURIComponent(args.id)}`, { method: "PATCH", body: JSON.stringify({ status: args.status, title: args.title, detail: args.detail }) });
+            return text(`Atualizado: "${d.todo.title}" → ${d.todo.status}.`);
+        }
+        if (name === "memory_get") {
+            const q = args.key ? `?key=${encodeURIComponent(args.key)}` : "";
+            const d = await api(`/api/project/${encodeURIComponent(PROJECT)}/memory${q}`);
+            const rows = (d.memory || []).map((m) => `## ${m.key}\n${m.content}`).join("\n\n");
+            return text(rows || `Nenhuma memória em "${PROJECT}".`);
+        }
+        if (name === "memory_set") {
+            await api(`/api/project/${encodeURIComponent(PROJECT)}/memory`, { method: "POST", body: JSON.stringify({ key: args.key, content: args.content }) });
+            return text(`Memória "${args.key}" salva em "${PROJECT}".`);
+        }
+        return text(`tool desconhecida: ${name}`);
+    }
+    catch (e) {
+        const msg = e.message;
+        if (msg === "NOT_AUTHENTICATED")
+            return text("Não autenticado. Chame a tool `velua_login` — vou abrir o navegador para você aprovar o acesso (uma vez só).");
+        return text(`Erro: ${msg}`);
+    }
+});
+await server.connect(new StdioServerTransport());
+console.error(`[velua-memory-mcp] pronto — projeto "${PROJECT}", api ${API_URL}`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@velua-ai/memory-mcp",
+  "version": "0.1.5",
+  "description": "Velua shared memory & TODO MCP server — connect any agent (Claude Code, Cursor, Codex) to a shared per-project TODO/memory.",
+  "type": "module",
+  "bin": {
+    "velua-memory-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "tsx": "^4.0.0"
+  },
+  "license": "Apache-2.0"
+}