@hiveai/mcp 0.2.7 → 0.2.9

package/README.md

@@ -0,0 +1,362 @@
+# @hiveai/mcp
+
+> **hAIve MCP server** — exposes shared team memory and project context to any MCP-compatible AI client (Claude Code, Cursor, GitHub Copilot, VS Code, etc.)
+
+Connect your AI coding tools to a shared, version-controlled knowledge base. Every convention, architectural decision, and gotcha your team has discovered is surfaced automatically when relevant — no more re-explaining the same things in every session.
+
+---
+
+## Install
+
+```bash
+npm install -g @hiveai/mcp
+```
+
+Also install the CLI to manage memories:
+
+```bash
+npm install -g @hiveai/cli
+```
+
+---
+
+## Quick start
+
+```bash
+# 1. Initialize hAIve in your project
+haive init
+
+# 2. Add your AI client config (see below)
+# 3. Ask your AI to call get_briefing before starting any task
+```
+
+---
+
+## Client configuration
+
+### Claude Code
+
+Add to `~/.claude.json` (global) or `.claude/settings.json` (per-project):
+
+```json
+{
+  "mcpServers": {
+    "haive": {
+      "command": "haive-mcp",
+      "args": ["--root", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "haive": {
+      "command": "haive-mcp",
+      "args": ["--root", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+### VS Code
+
+```bash
+code --add-mcp '{"name":"haive","command":"haive-mcp","args":["--root","/absolute/path/to/project"]}'
+```
+
+### Project-scoped (auto-detected)
+
+Add a `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "haive": {
+      "command": "haive-mcp",
+      "args": ["--root", "."]
+    }
+  }
+}
+```
+
+The project root can also be set via the `HAIVE_PROJECT_ROOT` environment variable, or auto-detected from the nearest `.ai/`, `.git/`, or `package.json`.
+
+---
+
+## MCP Tools
+
+### `get_briefing` ⭐ Start every task with this
+
+One-shot onboarding: returns project context + module contexts + ranked relevant memories under a token budget. Replaces 4–5 separate calls at the start of a session.
+
+```json
+{
+  "task": "add a Stripe payment integration",
+  "files": ["src/payments/PaymentService.ts"],
+  "max_tokens": 8000,
+  "max_memories": 8,
+  "format": "full",
+  "semantic": true
+}
+```
+
+**Parameters:**
+
+| Parameter | Default | Description |
+|---|---|---|
+| `task` | — | What you're about to do. Used to rank memories by relevance. |
+| `files` | `[]` | Files you're editing. Surfaces memories anchored to these files. |
+| `max_tokens` | `8000` | Token budget for the entire response. Sections are truncated to fit. |
+| `max_memories` | `8` | Max memories to include. |
+| `format` | `"full"` | `"full"` = complete bodies · `"compact"` = 1-line summaries (call `mem_get` for details) |
+| `semantic` | `true` | Use embedding-based ranking if `@hiveai/embeddings` is indexed. |
+| `include_stale` | `false` | Include stale memories (may be outdated). |
+| `track` | `true` | Increment read_count for returned memories. |
+
+**Response includes:**
+- `project_context` — the contents of `.ai/project-context.md`
+- `module_contexts` — relevant `.ai/modules/<name>/context.md` files
+- `memories` — ranked list of relevant memories with body, confidence, and match reason
+- `decay_warnings` — memory IDs not read in >90 days (review or deprecate)
+- `search_mode` — `"semantic"` | `"literal_fallback"` | `"literal"`
+
+---
+
+### `mem_save`
+
+Save a new memory. For failed approaches, use `mem_tried` instead — it enforces better structure.
+
+```json
+{
+  "type": "gotcha",
+  "slug": "open-in-view-false",
+  "scope": "team",
+  "body": "spring.jpa.open-in-view=false is intentional — do not re-enable. Lazy loading outside transactions causes N+1 queries.",
+  "paths": ["src/main/resources/application.properties"],
+  "tags": ["spring", "jpa", "performance"]
+}
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `type` | ✅ | `convention` · `decision` · `gotcha` · `architecture` · `glossary` |
+| `slug` | ✅ | Short kebab-case identifier |
+| `scope` | — | `personal` (default) · `team` · `module` |
+| `body` | ✅ | Markdown content |
+| `paths` | — | File paths to anchor to (enables staleness detection) |
+| `symbols` | — | Function/class names to anchor to |
+| `tags` | — | Tags for filtering |
+| `domain` | — | Business domain (e.g. `payments`) |
+| `author` | — | Author handle |
+
+---
+
+### `mem_tried` ⭐ Record failures immediately
+
+Record a failed approach. Automatically surfaces first in future `get_briefing` calls so agents don't repeat the same mistake.
+
+```json
+{
+  "what": "using require() to import gray-matter in an ESM package",
+  "why_failed": "The package is ESM-only — require() throws ERR_REQUIRE_ESM",
+  "instead": "Use import matter from 'gray-matter' (named default import)",
+  "scope": "team",
+  "paths": ["src/parser.ts"]
+}
+```
+
+Auto-validated — no approval cycle needed.
+
+---
+
+### `mem_search`
+
+Search memories by substring or semantic similarity.
+
+```json
+{
+  "query": "flyway migration",
+  "scope": "team",
+  "semantic": true,
+  "limit": 10
+}
+```
+
+Falls back to literal search if embeddings are not indexed.
+
+---
+
+### `mem_get`
+
+Fetch a single memory with full body, anchor, confidence, and usage stats.
+
+```json
+{ "id": "2025-01-15-gotcha-flyway-strict" }
+```
+
+---
+
+### `mem_list`
+
+List memories with optional filters.
+
+```json
+{
+  "scope": "team",
+  "type": "gotcha",
+  "status": "validated",
+  "tags": ["payments"]
+}
+```
+
+---
+
+### `mem_for_files`
+
+Given the files you're editing, return relevant memories grouped by reason (anchor overlap, module, domain).
+
+```json
+{
+  "files": ["src/payments/PaymentService.java", "src/payments/WaveProvider.java"]
+}
+```
+
+---
+
+### `mem_update`
+
+Update a memory's body, tags, or anchor without changing its id or usage history.
+
+```json
+{
+  "id": "2025-01-15-gotcha-flyway-strict",
+  "body": "Updated explanation...",
+  "paths": ["src/main/resources/db/migration"]
+}
+```
+
+---
+
+### `mem_verify`
+
+Check if anchor paths and symbols still exist in the current code. Detects stale memories and suggests possible renames when files have moved.
+
+```json
+{ "id": "2025-01-15-gotcha-flyway-strict", "update": true }
+```
+
+---
+
+### `mem_diff`
+
+Compare two memories side-by-side: shows frontmatter fields that differ and lines unique to each body. Useful before merging duplicates.
+
+```json
+{ "id_a": "2025-01-15-gotcha-flyway-strict", "id_b": "2025-02-01-decision-flyway-naming" }
+```
+
+---
+
+### `mem_approve` / `mem_reject` / `mem_pending` / `mem_delete`
+
+Lifecycle operations:
+
+```json
+{ "id": "2025-01-15-gotcha-flyway-strict" }               // mem_approve
+{ "id": "2025-01-15-gotcha-old", "reason": "Outdated" }   // mem_reject
+{}                                                          // mem_pending (list all)
+{ "id": "2025-01-15-gotcha-old" }                          // mem_delete
+```
+
+---
+
+### `get_project_context`
+
+Read `.ai/project-context.md` directly (without token budgeting).
+
+```json
+{ "module": "payments" }   // Also loads .ai/modules/payments/context.md
+```
+
+---
+
+### `bootstrap_project_save`
+
+Persist a project (or module) context document generated by the AI.
+
+```json
+{
+  "content": "# Project context\n\n## Architecture\n...",
+  "module": "payments"   // Optional: save as .ai/modules/payments/context.md
+}
+```
+
+---
+
+### `code_map`
+
+Browse the pre-computed code map (file → exports + descriptions) instead of grepping.
+
+```json
+{ "query": "payment" }              // Filter by keyword
+{ "file": "src/payments" }          // Filter by file prefix
+{ "symbol": "PaymentService" }      // Find a specific export
+```
+
+Requires `haive index code` to be run first.
+
+---
+
+## MCP Prompts
+
+### `post_task` ⭐ Run before closing every session
+
+Post-task reflection checklist. Guides the AI through capturing failed approaches, conventions, decisions, and gotchas before the session ends.
+
+```
+Use the post_task prompt with:
+  task_summary: "Added Stripe payment integration"
+  files_touched: ["src/payments/StripeService.ts", "src/payments/PaymentController.ts"]
+```
+
+### `bootstrap_project`
+
+Instructions for the AI to analyze the current project and save a structured context document to `.ai/project-context.md`. Run once after `haive init`.
+
+### `import_docs`
+
+Analyze documentation (README, ADR, wiki page, API spec) and save actionable knowledge as hAIve memories.
+
+```
+Use the import_docs prompt with:
+  content: "<full document text>"
+  source: "docs/architecture.md"
+  scope: "team"
+```
+
+The AI extracts up to 10 memories (conventions, decisions, gotchas, architecture) and calls `mem_save` for each.
+
+---
+
+## Memory lifecycle
+
+```
+mem_save / mem_tried  → draft (personal) or proposed (team)
+mem_approve           → validated
+mem_verify            → stale (if anchors broken)
+mem_reject            → rejected
+```
+
+Validated team memories appear in `get_briefing`. Stale memories are excluded by default (pass `include_stale: true` to override).
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -397,6 +397,7 @@ async function memVerify(input, ctx) {
       file_path: filePath,
       stale: result.stale,
       reason: result.reason,
+      ...result.possibleRenames.length > 0 ? { possible_renames: result.possibleRenames } : {},
       status_after: statusAfter
     });
   }
@@ -859,6 +860,7 @@ import {
   estimateTokens,
   getUsage as getUsage5,
   inferModulesFromPaths as inferModulesFromPaths2,
+  isDecaying,
   literalMatchesAllTokens as literalMatchesAllTokens2,
   loadMemoriesFromDir as loadMemoriesFromDir12,
   loadUsageIndex as loadUsageIndex7,
@@ -883,12 +885,17 @@ var GetBriefingInputSchema = {
     "Use semantic ranking when a task is provided (requires `haive embeddings index`)."
   ),
   include_stale: z15.boolean().default(false).describe("Include stale memories (excluded by default \u2014 they may be outdated)"),
-  track: z15.boolean().default(true).describe("Increment read_count on returned memories")
+  track: z15.boolean().default(true).describe("Increment read_count on returned memories"),
+  format: z15.enum(["full", "compact"]).default("full").describe(
+    "Output format: 'full' returns complete memory bodies; 'compact' returns id + 1-line summary only (call mem_get for details)."
+  )
 };
 async function getBriefing(input, ctx) {
   const inferred = inferModulesFromPaths2(input.files);
   const memories = [];
   let searchMode = "literal";
+  let usage = { version: 1, updated_at: "", by_id: {} };
+  let byId = /* @__PURE__ */ new Map();
   if (existsSync15(ctx.paths.memoriesDir)) {
     const allLoaded = await loadMemoriesFromDir12(ctx.paths.memoriesDir);
     const allMemories = allLoaded.filter(({ memory }) => {
@@ -897,7 +904,7 @@ async function getBriefing(input, ctx) {
       if (!input.include_stale && s === "stale") return false;
       return true;
     });
-    const usage = await loadUsageIndex7(ctx.paths);
+    usage = await loadUsageIndex7(ctx.paths);
     const semanticHits = input.task && input.semantic ? await trySemanticHits(ctx, input.task, allMemories.length * 2) : null;
     if (input.task && input.semantic) {
       searchMode = semanticHits ? "semantic" : "literal_fallback";
@@ -954,7 +961,6 @@ async function getBriefing(input, ctx) {
         }
       }
       if (semanticHits) {
-        const byId = new Map(allMemories.map((m) => [m.memory.frontmatter.id, m]));
         for (const hit of semanticHits) {
           const loaded = byId.get(hit.id);
           if (loaded) addOrUpdate(loaded, "semantic", hit.score, "semantic");
@@ -969,6 +975,17 @@ async function getBriefing(input, ctx) {
       const sb = reasonScore(b) + confidenceScore(b) + (b.semantic_score ?? 0);
       return sb - sa;
     });
+    byId = new Map(allMemories.map((m) => [m.memory.frontmatter.id, m]));
+    for (const mem of ranked.slice(0, input.max_memories)) {
+      if (seen.size >= input.max_memories * 2) break;
+      const loaded = byId.get(mem.id);
+      if (!loaded) continue;
+      for (const relId of loaded.memory.frontmatter.related_ids ?? []) {
+        if (seen.has(relId)) continue;
+        const related = byId.get(relId);
+        if (related) addOrUpdate(related, "anchor", void 0, "partial");
+      }
+    }
     memories.push(...ranked.slice(0, input.max_memories));
     if (input.track && memories.length > 0) {
       await trackReads3(ctx.paths, memories.map((m) => m.id));
@@ -1009,7 +1026,6 @@ ${m.content}`).join("\n\n---\n\n"),
       trimmedModules.push({ name: m.name, content: sub.text, truncated: sub.truncated });
     }
   }
-  const trimmedMemoriesText = memoriesSlice.text;
   const trimmedMemories = [];
   if (!memoriesSlice.truncated) {
     trimmedMemories.push(...memories);
@@ -1029,13 +1045,22 @@ ${m.content}`).join("\n\n---\n\n"),
     }
   }
   const totalTokens = projectSlice.estimatedTokens + modulesSlice.estimatedTokens + memoriesSlice.estimatedTokens;
+  const decayWarnings = [];
+  for (const m of trimmedMemories) {
+    const u = getUsage5(usage, m.id);
+    const loaded = byId.get(m.id);
+    const createdAt = loaded?.memory.frontmatter.created_at ?? (/* @__PURE__ */ new Date()).toISOString();
+    if (isDecaying(u, createdAt)) decayWarnings.push(m.id);
+  }
+  const outputMemories = input.format === "compact" ? trimmedMemories.map((m) => ({ ...m, body: compactSummary(m.body) })) : trimmedMemories;
   return {
     ...input.task ? { task: input.task } : {},
     search_mode: searchMode,
     inferred_modules: inferred,
     project_context: projectContext ? { content: projectSlice.text, truncated: projectSlice.truncated } : null,
     module_contexts: trimmedModules,
-    memories: trimmedMemories,
+    memories: outputMemories,
+    decay_warnings: decayWarnings,
     estimated_tokens: totalTokens,
     budget: {
       max_tokens: input.max_tokens,
@@ -1047,6 +1072,13 @@ ${m.content}`).join("\n\n---\n\n"),
     }
   };
 }
+function compactSummary(body) {
+  for (const line of body.split("\n")) {
+    const trimmed = line.replace(/^#+\s*/, "").trim();
+    if (trimmed.length > 0) return trimmed.slice(0, 120);
+  }
+  return body.slice(0, 120);
+}
 async function trySemanticHits(ctx, task, limit) {
   let mod;
   try {
@@ -1106,13 +1138,58 @@ async function codeMapTool(input, ctx) {
   };
 }
 
-// src/prompts/bootstrap-project.ts
+// src/tools/mem-diff.ts
+import { existsSync as existsSync16 } from "fs";
+import { loadMemoriesFromDir as loadMemoriesFromDir13 } from "@hiveai/core";
 import { z as z17 } from "zod";
+var MemDiffInputSchema = {
+  id_a: z17.string().min(1).describe("First memory id"),
+  id_b: z17.string().min(1).describe("Second memory id")
+};
+async function memDiff(input, ctx) {
+  if (!existsSync16(ctx.paths.memoriesDir)) {
+    throw new Error(`No .ai/memories at ${ctx.paths.root}.`);
+  }
+  const all = await loadMemoriesFromDir13(ctx.paths.memoriesDir);
+  const foundA = all.find((m) => m.memory.frontmatter.id === input.id_a);
+  const foundB = all.find((m) => m.memory.frontmatter.id === input.id_b);
+  if (!foundA) throw new Error(`No memory with id "${input.id_a}".`);
+  if (!foundB) throw new Error(`No memory with id "${input.id_b}".`);
+  const fmA = foundA.memory.frontmatter;
+  const fmB = foundB.memory.frontmatter;
+  const frontmatterDiff = {};
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(fmA), ...Object.keys(fmB)]);
+  for (const key of allKeys) {
+    const va = fmA[key];
+    const vb = fmB[key];
+    if (JSON.stringify(va) !== JSON.stringify(vb)) {
+      frontmatterDiff[key] = { a: va, b: vb };
+    }
+  }
+  const linesA = new Set(foundA.memory.body.split("\n").map((l) => l.trim()).filter(Boolean));
+  const linesB = new Set(foundB.memory.body.split("\n").map((l) => l.trim()).filter(Boolean));
+  const onlyA = [...linesA].filter((l) => !linesB.has(l));
+  const onlyB = [...linesB].filter((l) => !linesA.has(l));
+  const common = [...linesA].filter((l) => linesB.has(l)).length;
+  return {
+    id_a: input.id_a,
+    id_b: input.id_b,
+    frontmatter_diff: frontmatterDiff,
+    body_diff: {
+      lines_only_in_a: onlyA,
+      lines_only_in_b: onlyB,
+      common_lines: common
+    }
+  };
+}
+
+// src/prompts/bootstrap-project.ts
+import { z as z18 } from "zod";
 var BootstrapProjectArgsSchema = {
-  module: z17.string().optional().describe(
+  module: z18.string().optional().describe(
     "Optional module name to scope the analysis to (writes to .ai/modules/<module>/context.md)"
   ),
-  focus: z17.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
+  focus: z18.string().optional().describe("Optional area to emphasize (e.g. 'data layer', 'API surface')")
 };
 var ROOT_TEMPLATE = `# Project context
 
@@ -1194,10 +1271,10 @@ ${template}\`\`\`
 }
 
 // src/prompts/post-task.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 var PostTaskArgsSchema = {
-  task_summary: z18.string().optional().describe("One sentence describing what you just did"),
-  files_touched: z18.array(z18.string()).optional().describe("Files you created or modified during the task")
+  task_summary: z19.string().optional().describe("One sentence describing what you just did"),
+  files_touched: z19.array(z19.string()).optional().describe("Files you created or modified during the task")
 };
 function postTaskPrompt(args, ctx) {
   const taskLine = args.task_summary ? `
@@ -1253,9 +1330,78 @@ When done, respond with a brief summary: "Saved N memories: [list of IDs]" or "N
   };
 }
 
+// src/prompts/import-docs.ts
+import { z as z20 } from "zod";
+var ImportDocsArgsSchema = {
+  content: z20.string().describe("The documentation content to analyze and import as memories (Markdown, README, ADR, etc.)"),
+  source: z20.string().optional().describe("Origin of the content (file path, URL, or document title) \u2014 used to anchor memories"),
+  scope: z20.enum(["personal", "team"]).default("team").describe("Scope to assign to created memories"),
+  dry_run: z20.boolean().default(false).describe("If true, describe what would be saved without actually calling mem_save")
+};
+function importDocsPrompt(args, ctx) {
+  const sourceLine = args.source ? `
+Source: **${args.source}**` : "";
+  const dryRunNote = args.dry_run ? "\n> **DRY RUN** \u2014 describe what you would save but do not call any tools." : "";
+  const text = `You are given documentation to analyze and import into the hAIve memory system.
+${sourceLine}
+Scope: **${args.scope}**
+Project root: \`${ctx.paths.root}\`
+${dryRunNote}
+
+## Your task
+
+Read the documentation below and extract actionable memories. For each distinct piece of knowledge:
+
+1. **Identify the memory type** \u2014 which category fits best?
+   - \`convention\` \u2014 how things are done here (naming, patterns, workflow)
+   - \`decision\` \u2014 a choice that was made and why (tradeoffs, constraints)
+   - \`gotcha\` \u2014 non-obvious behavior, traps, things that surprise newcomers
+   - \`architecture\` \u2014 structural overview of a system or module
+   - \`glossary\` \u2014 domain terms and their meaning in this project
+
+2. **Determine the anchor** \u2014 which files or symbols does this knowledge apply to? List them in \`paths\`.
+
+3. **Write a focused body** \u2014 one memory = one insight. Do not combine multiple unrelated facts.
+   - Start with the key fact or rule
+   - Add context: why it matters, when it applies
+   - Add examples if helpful
+
+4. **Call \`mem_save\`** for each memory (unless dry_run).
+   - Set \`scope="${args.scope}"\`
+   - Set \`slug\` to a short kebab-case identifier
+   - Set \`paths\` to the relevant file paths (extracted from the doc if present)
+
+## Rules
+
+- Skip generic documentation that applies to any project (e.g., "install with npm install").
+- Prioritize gotchas, non-obvious decisions, and domain-specific conventions.
+- If the same knowledge is repeated in different sections, save it once.
+- Maximum 10 memories per import \u2014 select the most actionable ones.
+
+## Documentation to import
+
+---
+
+${args.content}
+
+---
+
+When done, respond with: "Imported N memories: [list of IDs]" or "Nothing actionable found."
+`;
+  return {
+    description: "Import documentation as hAIve memories",
+    messages: [
+      {
+        role: "user",
+        content: { type: "text", text }
+      }
+    ]
+  };
+}
+
 // src/server.ts
 var SERVER_NAME = "haive";
-var SERVER_VERSION = "0.2.7";
+var SERVER_VERSION = "0.2.9";
 function jsonResult(data) {
   return {
     content: [
@@ -1368,6 +1514,12 @@ function createHaiveServer(options = {}) {
     MemTriedInputSchema,
     async (input) => jsonResult(await memTried(input, context))
   );
+  server.tool(
+    "mem_diff",
+    "Compare two memories side-by-side: shows frontmatter fields that differ and lines unique to each body. Useful before merging or deduplicating memories.",
+    MemDiffInputSchema,
+    async (input) => jsonResult(await memDiff(input, context))
+  );
   server.prompt(
     "bootstrap_project",
     "Instructions for the AI client to analyze the project and save the context.",
@@ -1380,6 +1532,12 @@ function createHaiveServer(options = {}) {
     PostTaskArgsSchema,
     (args) => postTaskPrompt(args, context)
   );
+  server.prompt(
+    "import_docs",
+    "Analyze documentation (README, ADR, wiki page, etc.) and save the actionable knowledge as hAIve memories. Pass the content and an optional source/scope.",
+    ImportDocsArgsSchema,
+    (args) => importDocsPrompt(args, context)
+  );
   return { server, context };
 }