frinus-mcp 3.2.1 → 3.3.0

package/README.md

@@ -1,13 +1,32 @@
 # Frinus MCP Server
 
-> **φρήν + νοῦς** — The cognitive memory bridge between Claude agents and the [Frinus](https://github.com/frinus-ai) platform.
+> **φρήν + νοῦς** — Gives your Claude agent long-term, cognitive memory backed by the [Frinus](https://frinus.rdxsec.com.br) platform.
 
-MCP (Model Context Protocol) server that exposes **70 tools** spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. The server speaks stdio and is consumed by Claude Desktop, Claude Code, and any MCP-aware client.
+`frinus-mcp` is an MCP (Model Context Protocol) server. It is the **bridge** between your MCP client — Claude Code, Cursor, or Claude Desktop — and the **Frinus platform hosted at https://frinus.rdxsec.com.br**.
 
-- **Version:** 3.1.0
+It does **not** run on its own. It stores nothing locally: every tool call is forwarded over HTTPS to your Frinus account. So before it does anything useful you need two things:
+
+1. a **Frinus account** (free, no card), and
+2. a **Frinus API key** (`sk-frinus-...`).
+
+With those in place, the server exposes **70 tools** spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. It speaks stdio and works with any MCP-aware client.
+
+- **Version:** 3.3.0
 - **Tools:** 70 (see [Tools Reference](#tools-reference))
-- **Backends:** Memory Engine (`:8001`) + Control Plane (`:8000`) + Agent Service (`:8002`)
-- **Public mirror:** https://github.com/frinus-ai/frinus-mcp
+- **Platform:** https://frinus.rdxsec.com.br (hosted SaaS — the backend this server talks to)
+- **npm package:** [`frinus-mcp`](https://www.npmjs.com/package/frinus-mcp)
+
+## How it fits together
+
+```
++-------------------+        +--------------+        +----------------------------+
+| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
+| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
+|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
++-------------------+        +--------------+        +----------------------------+
+```
+
+The server validates your API key against the platform at startup, resolves your account + organisation, and routes every tool call there. No API key → it refuses to start.
 
 ## Rule Zero — MCP is mandatory
 
@@ -20,70 +39,51 @@ The Frinus MCP **is** the agent's long-term memory, identity, and intelligence.
 
 The complete protocol set lives in the global `CLAUDE.md` (Frinus organisation), summarised below in [The 7 Protocols](#the-7-protocols).
 
-## Requirements
+## Before you start — account + API key
 
-- Node.js 18+
-- Frinus stack reachable (Memory Engine, Control Plane, Agent Service)
-- Personal API key (`sk-frinus-...`) tied to your tenant
+You need a Frinus account and an API key. Both are free to get.
 
-## Installation
+### 1. Create a free account
 
-**End users — no install needed.** Use the published package via `npx` (see config below), or the one-click `.mcpb` extension for Claude Desktop.
+Sign up at **https://frinus.rdxsec.com.br**. The **Free plan (R$0)** is enough to get started:
 
-**Developers / from source:**
+- 100 memories
+- 20 queries/day
+- no credit card required
+
+### 2. Generate an API key
+
+Once logged in, open your account **Settings → API Keys** and create a new key. You'll get a value shaped like:
 
-```bash
-npm install
-npm run build
+```
+sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
-The build emits `dist/index.js`, ready to be wired into Claude Desktop / Claude Code.
+Copy it now — for security it's shown **only once**. This value goes into the `FRINUS_API_KEY` environment variable below. Treat it like a password; never commit it to a repo.
 
-## Distribution
+## Getting started (zero to first memory)
 
-| Channel | Client | User effort |
-|---------|--------|-------------|
-| **npm** (`npx -y frinus-mcp`) | Claude Code, Cursor, Codex, opencode | Paste config + API key |
-| **`.mcpb` bundle** | Claude Desktop | Double-click + paste API key |
-| **From source** | any | Clone + build + absolute path |
+Five minutes, four steps.
 
-URL defaults point at the Frinus SaaS, so only `FRINUS_API_KEY` is required. Override `MEMORY_SERVICE_URL` / `FRINUS_CP_URL` / `AGENT_SERVICE_URL` for self-hosted instances or local dev.
+### Step 1 — Create your account
 
-### Publishing (maintainers)
+Sign up at https://frinus.rdxsec.com.br (Free plan, no card). See [above](#1-create-a-free-account).
 
-```bash
-# 1) npm package — powers `npx -y frinus-mcp` everywhere
-npm version <patch|minor|major>
-npm publish                      # prepublishOnly runs the build
+### Step 2 — Generate your API key
 
-# 2) .mcpb bundle — powers the Claude Desktop one-click install
-npm run pack:mcpb                # -> frinus.mcpb
-gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
-# Frontend points at: releases/latest/download/frinus.mcpb
-```
+Settings → API Keys → create. Copy the `sk-frinus-...` value. See [above](#2-generate-an-api-key).
 
-## Environment Variables
+### Step 3 — Add the server to your client
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `FRINUS_API_KEY` | **required** | Personal API key (`sk-frinus-...`). Resolves tenant + user identity at boot. |
-| `MEMORY_SERVICE_URL` | `http://localhost:8001` | Memory Engine base URL |
-| `FRINUS_CP_URL` | `http://localhost:8000` | Control Plane base URL (universes, orgs, billing) |
-| `AGENT_SERVICE_URL` | `http://localhost:8002` | Agent Service base URL (agents, invocation, skills) |
-| `FRINUS_MEMORY_API_KEY` | — | Legacy fallback for `FRINUS_API_KEY` |
+You don't install anything — `npx` fetches and runs the package on demand. The only value you must provide is your API key; the platform URLs already default to production.
 
-Production endpoints (Frinus SaaS):
+**Claude Code (one-liner):**
 
 ```bash
-MEMORY_SERVICE_URL=https://frinus-memory.rdxsec.com.br
-FRINUS_CP_URL=https://frinus-api.rdxsec.com.br
-AGENT_SERVICE_URL=https://frinus-agents.rdxsec.com.br
-FRINUS_API_KEY=sk-frinus-...
+claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest
 ```
 
-## Claude Desktop / Claude Code Configuration
-
-Add the server to your MCP client configuration. **Recommended (npx, no install):**
+**Cursor / Claude Desktop / any client (config JSON):**
 
 ```json
 {
@@ -99,35 +99,45 @@ Add the server to your MCP client configuration. **Recommended (npx, no install)
 }
 ```
 
-Claude Code one-liner:
+Config file locations:
 
-```bash
-claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest
+- **Claude Code:** `~/.claude.json`, under `mcpServers`.
+- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `~/.config/claude/claude_desktop_config.json` (Linux). Or use the one-click `.mcpb` extension and just paste your API key.
+- **Cursor:** `~/.cursor/mcp.json`, under `mcpServers`.
+
+Restart the client so it picks up the new server.
+
+> Replace `sk-frinus-...` with the real key from Step 2. You normally set **only** `FRINUS_API_KEY` — every backend URL already defaults to the hosted platform. See [Environment Variables](#environment-variables) for the full list and the self-host override.
+
+### Step 4 — Validate with your first memory
+
+In your client, ask the agent to store and recall something:
+
+```
+Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."
 ```
 
-From source (developers), point at the built entry and override URLs as needed:
+then in the same or a later session:
 
-```json
-{
-  "mcpServers": {
-    "frinus": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp/dist/index.js"],
-      "env": {
-        "FRINUS_API_KEY": "sk-frinus-...",
-        "MEMORY_SERVICE_URL": "http://localhost:8001",
-        "FRINUS_CP_URL": "http://localhost:8000",
-        "AGENT_SERVICE_URL": "http://localhost:8002"
-      }
-    }
-  }
-}
 ```
+What time does our staging DB reset?
+```
+
+Behind the scenes the agent calls `memory_store` then `memory_search` / `search_with_attention`. If the recall comes back, the bridge is live. You can confirm the same memory appears in the web app at https://frinus.rdxsec.com.br.
 
-Claude Desktop config path: `~/.config/claude/claude_desktop_config.json` (Linux) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).
-Claude Code config path: `~/.claude.json` under `mcpServers`.
+## Environment Variables
+
+In normal use you set **only** `FRINUS_API_KEY`. The service URLs already point at the hosted platform — leave them alone unless you self-host (see [Advanced — self-host](#advanced--self-host--local-dev)).
+
+| Variable | Default (hosted platform) | Description |
+|----------|---------------------------|-------------|
+| `FRINUS_API_KEY` | **required** | Your personal API key (`sk-frinus-...`). Resolves account + organisation at boot. |
+| `MEMORY_SERVICE_URL` | `https://frinus-memory.rdxsec.com.br` | Memory Engine base URL |
+| `FRINUS_CP_URL` | `https://frinus-api.rdxsec.com.br` | Control Plane base URL (account, orgs, API keys, billing) |
+| `AGENT_SERVICE_URL` | `https://frinus-agents.rdxsec.com.br` | Agent Service base URL (agents, invocation, skills) |
+| `FRINUS_MEMORY_API_KEY` | — | Legacy fallback for `FRINUS_API_KEY` |
 
-On startup the server validates the API key via `/auth/me` and resolves the tenant org ID + logged-in user. Failures abort the process with `[FATAL]` so the client surfaces the error.
+On startup the server validates the API key against the platform and resolves your organisation + logged-in user. If validation fails it aborts with `[FATAL]` so the client surfaces the error — re-check the key from Settings → API Keys.
 
 ## The 7 Protocols
 
@@ -409,6 +419,46 @@ Operational guidelines:
 
 Tenant isolation is database-per-tenant. The MCP resolves your tenant org ID from the API key at boot — you never pass `org_id` manually.
 
+## Advanced — self-host / local dev
+
+Everything above targets the hosted platform at https://frinus.rdxsec.com.br, which is what almost everyone wants. If you run your own Frinus stack (or develop the MCP against a local backend), build from source and override the three URLs:
+
+```bash
+git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
+npm install
+npm run build      # emits dist/index.js
+```
+
+```json
+{
+  "mcpServers": {
+    "frinus": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/dist/index.js"],
+      "env": {
+        "FRINUS_API_KEY": "sk-frinus-...",
+        "MEMORY_SERVICE_URL": "http://localhost:8001",
+        "FRINUS_CP_URL": "http://localhost:8000",
+        "AGENT_SERVICE_URL": "http://localhost:8002"
+      }
+    }
+  }
+}
+```
+
+### Publishing (maintainers)
+
+```bash
+# 1) npm package — powers `npx -y frinus-mcp` everywhere
+npm version <patch|minor|major>
+npm publish                      # prepublishOnly runs the build
+
+# 2) .mcpb bundle — powers the Claude Desktop one-click install
+npm run pack:mcpb                # -> frinus.mcpb
+gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
+# Frontend points at: releases/latest/download/frinus.mcpb
+```
+
 ## Development
 
 ```

package/dist/client/client-info.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolved MCP client identity.
+ *
+ * The MCP client sends its `clientInfo: { name, version }` during the
+ * `initialize` handshake. We normalize the raw `name` into a small, stable
+ * set of buckets and expose it as the `X-Client` header so the Control Plane
+ * can attribute the `mcp_connected` PostHog event to the right client
+ * ("claude_code", "cursor", "desktop", "codex", "unknown").
+ *
+ * Module-level singleton (getter/setter), mirroring `resolvedTenantOrgId` in
+ * memory-client.ts: it is captured by an Axios request interceptor at
+ * construction time and read lazily on each request, so a single mutable
+ * module value is the least-surprising shape here.
+ */
+export type ResolvedClient = "claude_code" | "cursor" | "desktop" | "codex" | "unknown";
+/**
+ * Normalize a raw `clientInfo.name` into a stable bucket.
+ *
+ * Order matters: the more specific "claude-code" check must run before the
+ * generic "claude" → desktop fallback, so Claude Code is never misclassified
+ * as the desktop app.
+ */
+export declare function normalizeClient(rawName?: string | null): ResolvedClient;
+export declare function setResolvedClient(rawName?: string | null): void;
+export declare function getResolvedClient(): ResolvedClient;

package/dist/client/client-info.js

@@ -0,0 +1,48 @@
+/**
+ * Resolved MCP client identity.
+ *
+ * The MCP client sends its `clientInfo: { name, version }` during the
+ * `initialize` handshake. We normalize the raw `name` into a small, stable
+ * set of buckets and expose it as the `X-Client` header so the Control Plane
+ * can attribute the `mcp_connected` PostHog event to the right client
+ * ("claude_code", "cursor", "desktop", "codex", "unknown").
+ *
+ * Module-level singleton (getter/setter), mirroring `resolvedTenantOrgId` in
+ * memory-client.ts: it is captured by an Axios request interceptor at
+ * construction time and read lazily on each request, so a single mutable
+ * module value is the least-surprising shape here.
+ */
+let resolvedClient = "unknown";
+/**
+ * Normalize a raw `clientInfo.name` into a stable bucket.
+ *
+ * Order matters: the more specific "claude-code" check must run before the
+ * generic "claude" → desktop fallback, so Claude Code is never misclassified
+ * as the desktop app.
+ */
+export function normalizeClient(rawName) {
+    if (!rawName)
+        return "unknown";
+    const name = rawName.toLowerCase();
+    if (name.includes("claude-code") || name.includes("claudecode")) {
+        return "claude_code";
+    }
+    if (name.includes("cursor")) {
+        return "cursor";
+    }
+    if (name.includes("codex")) {
+        return "codex";
+    }
+    // Generic Claude clients (Claude Desktop, claude-ai, etc.) — must come after
+    // the claude-code check above.
+    if (name.includes("claude") || name.includes("claude-ai") || name.includes("desktop")) {
+        return "desktop";
+    }
+    return "unknown";
+}
+export function setResolvedClient(rawName) {
+    resolvedClient = normalizeClient(rawName);
+}
+export function getResolvedClient() {
+    return resolvedClient;
+}

package/dist/client/cp-client.js

@@ -3,6 +3,7 @@
  */
 import axios from "axios";
 import { getResolvedTenantOrgId } from "./memory-client.js";
+import { getResolvedClient } from "./client-info.js";
 export class CpClient {
     client;
     constructor(baseURL, apiKey) {
@@ -16,6 +17,7 @@ export class CpClient {
             const orgId = getResolvedTenantOrgId();
             if (orgId)
                 config.headers['X-Tenant-ID'] = orgId;
+            config.headers['X-Client'] = getResolvedClient();
             return config;
         });
     }

package/dist/index.js

@@ -17,6 +17,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { MemoryClient, getResolvedUserEmail, getResolvedUserId, setResolvedTenantOrgId, setResolvedUserEmail, setResolvedUserId, getResolvedTenantOrgId, } from "./client/memory-client.js";
 import { AgentClient } from "./client/agent-client.js";
 import { CpClient } from "./client/cp-client.js";
+import { getResolvedClient, setResolvedClient } from "./client/client-info.js";
 import { InteractionCapture } from "./capture/interaction-capture.js";
 import { TOOLS } from "./tools/definitions.js";
 import { dispatchTool } from "./tools/handlers.js";
@@ -95,6 +96,17 @@ async function main() {
         }
         return toolResult;
     });
+    // Resolve the connecting MCP client's identity for the X-Client header.
+    // `getClientVersion()` is only populated after the `initialize` handshake,
+    // so we read it from the `oninitialized` callback (fired on the client's
+    // `notifications/initialized`), not right after `connect()`.
+    server.oninitialized = () => {
+        const rawName = server.getClientVersion()?.name;
+        setResolvedClient(rawName);
+        // Logged once for calibration against real clients (stderr, not stdout —
+        // stdout is the MCP transport).
+        console.error(`[Client] clientInfo.name=${JSON.stringify(rawName ?? null)} normalized=${getResolvedClient()}`);
+    };
     // Start server
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Frinus - MCP Server for Cognitive Memory (φρήν + νοῦς). Long-term memory, sessions, agents and knowledge for Claude and any MCP client.",
   "type": "module",
   "main": "dist/index.js",