@tpsdev-ai/flair-mcp 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @tpsdev-ai/flair-mcp
+
+MCP server for [Flair](https://tps.dev/#flair) — persistent memory for Claude Code, Cursor, and any MCP client.
+
+## Quick Start
+
+### Claude Code
+
+```bash
+# Add to your project's .mcp.json
+cat > .mcp.json << 'EOF'
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project"
+      }
+    }
+  }
+}
+EOF
+```
+
+Or install globally and configure once in `~/.claude/settings.json`.
+
+### Prerequisites
+
+You need a running Flair instance:
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+flair agent add my-project
+```
+
+## Tools
+
+Once configured, Claude Code (or any MCP client) gets these tools:
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Semantic search across memories. Understands "what happened today". |
+| `memory_store` | Save a memory with type (lesson/decision/fact) and durability. |
+| `memory_get` | Retrieve a specific memory by ID. |
+| `memory_delete` | Delete a memory. |
+| `bootstrap` | Cold-start context — soul + recent memories in one call. |
+| `soul_set` | Set personality or project context (included in every bootstrap). |
+| `soul_get` | Get a personality or project context entry. |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FLAIR_AGENT_ID` | *(required)* | Agent identity for memory scoping |
+| `FLAIR_URL` | `http://localhost:9926` | Flair server URL |
+| `FLAIR_KEY_PATH` | auto-resolved | Path to Ed25519 private key |
+
+## How It Works
+
+```
+Claude Code ↔ stdio ↔ flair-mcp ↔ HTTP ↔ Flair (Harper)
+```
+
+The MCP server is a thin wrapper around `@tpsdev-ai/flair-client`. All memory is stored in your local Flair instance with Ed25519 authentication. Nothing leaves your machine unless you point `FLAIR_URL` at a remote server.
+
+## Remote Flair
+
+Point to a remote Flair instance:
+
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project",
+        "FLAIR_URL": "http://your-server:9926"
+      }
+    }
+  }
+}
+```
+
+Copy your key from the server: `scp server:~/.flair/keys/my-project.key ~/.flair/keys/`
+
+## License
+
+[Apache 2.0](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Flair MCP Server — persistent memory for Claude Code and any MCP client.
+ *
+ * Tools:
+ *   - memory_search  — semantic search across memories
+ *   - memory_store   — save a memory with type + durability
+ *   - memory_get     — retrieve a specific memory by ID
+ *   - memory_delete  — delete a memory
+ *   - bootstrap      — cold-start context (soul + recent memories)
+ *   - soul_set       — set a personality/context entry
+ *   - soul_get       — get a personality/context entry
+ *
+ * Usage:
+ *   npx @tpsdev-ai/flair-mcp
+ *
+ * Claude Code .mcp.json:
+ *   { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"] } } }
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * Flair MCP Server — persistent memory for Claude Code and any MCP client.
+ *
+ * Tools:
+ *   - memory_search  — semantic search across memories
+ *   - memory_store   — save a memory with type + durability
+ *   - memory_get     — retrieve a specific memory by ID
+ *   - memory_delete  — delete a memory
+ *   - bootstrap      — cold-start context (soul + recent memories)
+ *   - soul_set       — set a personality/context entry
+ *   - soul_get       — get a personality/context entry
+ *
+ * Usage:
+ *   npx @tpsdev-ai/flair-mcp
+ *
+ * Claude Code .mcp.json:
+ *   { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"] } } }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { FlairClient } from "@tpsdev-ai/flair-client";
+import { z } from "zod";
+// ─── Client setup ────────────────────────────────────────────────────────────
+const agentId = process.env.FLAIR_AGENT_ID;
+if (!agentId) {
+    console.error("FLAIR_AGENT_ID is required. Set it in your .mcp.json env or shell.");
+    process.exit(1);
+}
+const flair = new FlairClient({
+    agentId,
+    url: process.env.FLAIR_URL,
+    keyPath: process.env.FLAIR_KEY_PATH,
+});
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "flair",
+    version: "0.1.0",
+});
+// ─── Tools ───────────────────────────────────────────────────────────────────
+server.tool("memory_search", "Search memories by meaning. Understands temporal queries like 'what happened today'.", {
+    query: z.string().describe("Search query — natural language, semantic matching"),
+    limit: z.number().optional().default(5).describe("Max results (default 5)"),
+}, async ({ query, limit }) => {
+    const results = await flair.memory.search(query, { limit });
+    if (results.length === 0) {
+        return { content: [{ type: "text", text: "No relevant memories found." }] };
+    }
+    const text = results
+        .map((r, i) => {
+        const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
+        const meta = [date, r.type, r.durability].filter(Boolean).join(", ");
+        return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
+    })
+        .join("\n");
+    return { content: [{ type: "text", text }] };
+});
+server.tool("memory_store", "Save information to persistent memory. Use for lessons, decisions, preferences, facts.", {
+    content: z.string().describe("What to remember"),
+    type: z.enum(["session", "lesson", "decision", "preference", "fact", "goal"]).optional().default("session"),
+    durability: z.enum(["permanent", "persistent", "standard", "ephemeral"]).optional().default("standard")
+        .describe("permanent=inviolable, persistent=key decisions, standard=default, ephemeral=auto-expires 72h"),
+    tags: z.array(z.string()).optional().describe("Optional tags for categorization"),
+}, async ({ content, type, durability, tags }) => {
+    const result = await flair.memory.write(content, {
+        type: type,
+        durability: durability,
+        tags,
+        dedup: true,
+        dedupThreshold: 0.7,
+    });
+    const wasDeduped = !result.id?.startsWith(`${agentId}-`);
+    if (wasDeduped) {
+        return { content: [{ type: "text", text: `Similar memory already exists (id: ${result.id}): ${result.content?.slice(0, 200)}` }] };
+    }
+    return { content: [{ type: "text", text: `Memory stored (id: ${result.id})` }] };
+});
+server.tool("memory_get", "Retrieve a specific memory by ID.", {
+    id: z.string().describe("Memory ID"),
+}, async ({ id }) => {
+    const mem = await flair.memory.get(id);
+    if (!mem)
+        return { content: [{ type: "text", text: `Memory ${id} not found.` }] };
+    return { content: [{ type: "text", text: `${mem.content}\n\n(type: ${mem.type}, durability: ${mem.durability}, created: ${mem.createdAt})` }] };
+});
+server.tool("memory_delete", "Delete a memory by ID.", {
+    id: z.string().describe("Memory ID to delete"),
+}, async ({ id }) => {
+    await flair.memory.delete(id);
+    return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
+});
+server.tool("bootstrap", "Get cold-start context: soul + recent memories. Run this at the start of every session.", {
+    maxTokens: z.number().optional().default(4000).describe("Max tokens in output"),
+}, async ({ maxTokens }) => {
+    const result = await flair.bootstrap({ maxTokens });
+    if (!result.context) {
+        return { content: [{ type: "text", text: "No context available." }] };
+    }
+    return { content: [{ type: "text", text: result.context }] };
+});
+server.tool("soul_set", "Set a personality or project context entry. Included in every bootstrap.", {
+    key: z.string().describe("Entry key (e.g., 'role', 'standards', 'project')"),
+    value: z.string().describe("Entry value — personality trait, project context, coding standards, etc."),
+}, async ({ key, value }) => {
+    await flair.soul.set(key, value);
+    return { content: [{ type: "text", text: `Soul entry '${key}' set.` }] };
+});
+server.tool("soul_get", "Get a personality or project context entry.", {
+    key: z.string().describe("Entry key"),
+}, async ({ key }) => {
+    const entry = await flair.soul.get(key);
+    if (!entry)
+        return { content: [{ type: "text", text: `No soul entry for '${key}'.` }] };
+    return { content: [{ type: "text", text: entry.value }] };
+});
+// ─── Start ───────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tpsdev-ai/flair-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "flair-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --noCheck",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@tpsdev-ai/flair-client": "^0.2.0",
+    "zod": "^4.3.6"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tpsdev-ai/flair.git",
+    "directory": "packages/flair-mcp"
+  },
+  "homepage": "https://tps.dev/#flair",
+  "keywords": [
+    "flair",
+    "mcp",
+    "claude",
+    "claude-code",
+    "cursor",
+    "memory",
+    "ai",
+    "agent"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.11.0"
+  }
+}