@compr/opscontext-mcp 2.0.0

package/dist/sessions.js

@@ -0,0 +1,153 @@
+// LOCKED — verified March 3 2026 — session persistence: save/load/list/delete + auto-session inject
+// DO NOT RE-AUDIT — 16 session tests passing, stable since v1.16.0
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { safeAppend } from "./audit.js";
+/**
+ * Session Persistence — save/restore conversation context between sessions.
+ *
+ * Sessions are saved as JSON files in ~/.contextengine/sessions/.
+ * Each session has a name, timestamp, and key-value data store.
+ *
+ * Use cases:
+ * - AI agent saves decisions/context at end of session → picks up next time
+ * - Track what was discussed, changed, or planned across sessions
+ * - Store project-specific notes that persist between agent restarts
+ */
+const SESSIONS_DIR = join(homedir(), ".contextengine", "sessions");
+function ensureDir() {
+    if (!existsSync(SESSIONS_DIR)) {
+        mkdirSync(SESSIONS_DIR, { recursive: true });
+    }
+}
+function sessionPath(name) {
+    // Sanitize name for filesystem
+    const safe = name.replace(/[^a-zA-Z0-9_\-\.]/g, "_").substring(0, 100);
+    return join(SESSIONS_DIR, `${safe}.json`);
+}
+/**
+ * Save or update a key-value pair in a named session.
+ */
+export function saveSession(name, key, value) {
+    ensureDir();
+    const path = sessionPath(name);
+    const now = new Date().toISOString();
+    let session;
+    if (existsSync(path)) {
+        session = JSON.parse(readFileSync(path, "utf-8"));
+        session.updated = now;
+    }
+    else {
+        session = { name, created: now, updated: now, entries: [] };
+    }
+    // Update existing key or add new one
+    const existing = session.entries.find((e) => e.key === key);
+    if (existing) {
+        existing.value = value;
+        existing.timestamp = now;
+    }
+    else {
+        session.entries.push({ key, value, timestamp: now });
+    }
+    writeFileSync(path, JSON.stringify(session, null, 2));
+    safeAppend("session.save", {
+        name: session.name,
+        key,
+        value_length: value.length,
+        entries: session.entries.length,
+    });
+    return session;
+}
+/**
+ * Load a session by name.
+ */
+export function loadSession(name) {
+    const path = sessionPath(name);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List all saved sessions.
+ */
+export function listSessions() {
+    ensureDir();
+    try {
+        return readdirSync(SESSIONS_DIR)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => {
+            try {
+                const session = JSON.parse(readFileSync(join(SESSIONS_DIR, f), "utf-8"));
+                return {
+                    name: session.name,
+                    entries: session.entries.length,
+                    created: session.created,
+                    updated: session.updated,
+                };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Delete a session.
+ */
+export function deleteSession(name) {
+    const path = sessionPath(name);
+    if (existsSync(path)) {
+        unlinkSync(path);
+        safeAppend("session.delete", { name });
+        return true;
+    }
+    return false;
+}
+/**
+ * Format a session for display.
+ */
+export function formatSession(session) {
+    const lines = [];
+    lines.push(`# Session: ${session.name}`);
+    lines.push(`Created: ${session.created}`);
+    lines.push(`Updated: ${session.updated}`);
+    lines.push(`Entries: ${session.entries.length}`);
+    lines.push("");
+    for (const entry of session.entries) {
+        lines.push(`## ${entry.key}`);
+        lines.push(`_Updated: ${entry.timestamp}_`);
+        lines.push("");
+        lines.push(entry.value);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Format session list for display.
+ */
+export function formatSessionList(sessions) {
+    if (sessions.length === 0) {
+        return "No saved sessions. Use `save_session` to create one.";
+    }
+    const lines = [];
+    lines.push("# 📋 Saved Sessions\n");
+    lines.push("| Session | Entries | Created | Last Updated |");
+    lines.push("|---------|---------|---------|-------------|");
+    for (const s of sessions) {
+        const created = s.created.split("T")[0];
+        const updated = s.updated.split("T")[0];
+        lines.push(`| ${s.name} | ${s.entries} | ${created} | ${updated} |`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=sessions.js.map

package/examples/adapters/notion-adapter.js

@@ -0,0 +1,108 @@
+/**
+ * Example ContextEngine Adapter — Notion Integration
+ *
+ * This is a SKELETON adapter showing how to build a custom data source
+ * connector for ContextEngine. It demonstrates the full Adapter interface.
+ *
+ * To use this adapter:
+ * 1. Copy this file to your project
+ * 2. Install the Notion SDK: npm install @notionhq/client
+ * 3. Add to contextengine.json:
+ *    {
+ *      "adapters": [{
+ *        "name": "notion",
+ *        "module": "./adapters/notion-adapter.js",
+ *        "config": { "token": "$NOTION_API_TOKEN", "databases": ["db-id-1", "db-id-2"] }
+ *      }]
+ *    }
+ * 4. Set NOTION_API_TOKEN in your environment
+ *
+ * @module
+ */
+
+// Import the Adapter type from ContextEngine
+// import type { Adapter } from "@compr/contextengine-mcp/adapters";
+
+/**
+ * Notion adapter — fetches pages and databases from Notion
+ * and converts them into searchable ContextEngine chunks.
+ */
+const notionAdapter = {
+  name: "notion",
+  description: "Fetches pages and databases from Notion workspace",
+
+  /**
+   * Validate adapter configuration.
+   * Return null if valid, error message string if invalid.
+   */
+  validate(config) {
+    if (!config?.token) {
+      return "Missing 'token' in config. Set NOTION_API_TOKEN env var and use \"$NOTION_API_TOKEN\" in config.";
+    }
+    return null;
+  },
+
+  /**
+   * Optional initialization — called once when adapter loads.
+   * Use for auth handshake, API client setup, etc.
+   */
+  async init(config) {
+    // Example: Initialize Notion client
+    // const { Client } = await import("@notionhq/client");
+    // this._client = new Client({ auth: config.token });
+    console.error(`[Notion Adapter] Initialized with token: ${config?.token ? "✓" : "✗"}`);
+  },
+
+  /**
+   * Collect data — the core method.
+   * Called during every reindex. Must be safe (read-only, no side effects).
+   * Returns Chunk[] compatible with ContextEngine's search index.
+   */
+  async collect(config) {
+    const chunks = [];
+
+    try {
+      // Example: Fetch pages from configured databases
+      const databases = config?.databases || [];
+
+      for (const dbId of databases) {
+        // In a real adapter, you'd call the Notion API here:
+        // const response = await this._client.databases.query({ database_id: dbId });
+        // for (const page of response.results) { ... }
+
+        // Example chunk structure:
+        chunks.push({
+          source: `Notion DB ${dbId}`,
+          section: "## Page Title",
+          content: "Page content extracted from Notion blocks...",
+          lineStart: 1,
+          lineEnd: 1,
+          // Optional: add indexedAt for temporal decay
+          indexedAt: new Date().toISOString(),
+        });
+      }
+    } catch (err) {
+      // Never throw — return empty array on failure
+      console.error(`[Notion Adapter] Error: ${err?.message || err}`);
+      return [];
+    }
+
+    return chunks;
+  },
+
+  /**
+   * Optional cleanup — called on server shutdown.
+   */
+  async destroy() {
+    // Close connections, flush buffers, etc.
+    console.error("[Notion Adapter] Destroyed");
+  },
+};
+
+// Export as default (ContextEngine auto-detects)
+export default notionAdapter;
+
+// Alternative: export a factory function for per-instance config
+// export function createAdapter(config) {
+//   return { ...notionAdapter, _config: config };
+// }

package/examples/adapters/rss-adapter.js

@@ -0,0 +1,76 @@
+/**
+ * Example ContextEngine Adapter — RSS/Atom Feed
+ *
+ * A minimal adapter that fetches RSS/Atom feeds and indexes them
+ * as searchable chunks. Good starting point for simple adapters.
+ *
+ * Usage in contextengine.json:
+ * {
+ *   "adapters": [{
+ *     "name": "feeds",
+ *     "module": "./adapters/rss-adapter.js",
+ *     "config": {
+ *       "feeds": [
+ *         "https://blog.example.com/rss.xml",
+ *         "https://changelog.example.com/feed.atom"
+ *       ],
+ *       "maxItems": 20
+ *     }
+ *   }]
+ * }
+ *
+ * @module
+ */
+
+export function createAdapter(config) {
+  const maxItems = config?.maxItems || 10;
+
+  return {
+    name: "rss-feed",
+    description: `RSS/Atom feed indexer (max ${maxItems} items per feed)`,
+
+    validate(cfg) {
+      if (!cfg?.feeds || !Array.isArray(cfg.feeds) || cfg.feeds.length === 0) {
+        return "Missing 'feeds' array in config. Provide at least one RSS/Atom URL.";
+      }
+      return null;
+    },
+
+    async collect(cfg) {
+      const feeds = cfg?.feeds || [];
+      const chunks = [];
+
+      for (const feedUrl of feeds) {
+        try {
+          const response = await fetch(feedUrl);
+          if (!response.ok) continue;
+          const text = await response.text();
+
+          // Simple XML parsing — extract <item> or <entry> elements
+          const items = text.match(/<(?:item|entry)[\s>][\s\S]*?<\/(?:item|entry)>/gi) || [];
+
+          for (const item of items.slice(0, maxItems)) {
+            const title = item.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1")?.trim() || "Untitled";
+            const description = item.match(/<(?:description|summary|content)[^>]*>([\s\S]*?)<\/(?:description|summary|content)>/i)?.[1]?.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1")?.replace(/<[^>]+>/g, "")?.trim() || "";
+            const pubDate = item.match(/<(?:pubDate|published|updated)[^>]*>([\s\S]*?)<\/(?:pubDate|published|updated)>/i)?.[1]?.trim();
+
+            if (title || description) {
+              chunks.push({
+                source: new URL(feedUrl).hostname,
+                section: `## ${title}`,
+                content: description.slice(0, 2000),
+                lineStart: 1,
+                lineEnd: 1,
+                indexedAt: pubDate ? new Date(pubDate).toISOString() : new Date().toISOString(),
+              });
+            }
+          }
+        } catch {
+          // Skip failed feeds silently
+        }
+      }
+
+      return chunks;
+    },
+  };
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@compr/opscontext-mcp",
+  "version": "2.0.0",
+  "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "opscontext": "dist/cli.js",
+    "opscontext-mcp": "dist/cli.js",
+    "contextengine": "dist/cli.js",
+    "contextengine-mcp": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "node scripts/check-npm-token-expiry.mjs && npm run build",
+    "check-token": "node scripts/check-npm-token-expiry.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "claude",
+    "cursor",
+    "copilot",
+    "ai-agents",
+    "ops",
+    "observability",
+    "audit-log",
+    "compliance",
+    "soc2",
+    "iso27001",
+    "policy-as-code",
+    "git-hooks",
+    "pre-commit",
+    "secret-scanning",
+    "fleet",
+    "context",
+    "knowledge-base",
+    "developer-tools"
+  ],
+  "author": {
+    "name": "FASTPROD (PROD LLC)",
+    "url": "https://compr.fr"
+  },
+  "license": "BSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FASTPROD/ContextEngine.git"
+  },
+  "homepage": "https://compr.fr",
+  "bugs": {
+    "email": "yannick@compr.ch"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "!dist/test*",
+    "!dist/**/*.map",
+    "defaults/",
+    "skills/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "eslint": "^10.0.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  }
+}

package/skills/opscontext/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: opscontext
+description: "OpsContext for AI Agents — the ops + compliance layer Claude Code can't grow natively. Read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident hash-chained audit log (SOC2 CC7.2 / ISO 27001 A.12.4.1) + declarative policy-as-code git hooks (.contextengine/policy.json with secret_patterns, doc_coverage, deploy_verify_hosts, bypass_tokens) + persistent learnings + hybrid BM25/semantic search. Use when: (1) searching project documentation or context files, (2) collecting operational insights from workspaces, (3) storing and retrieving persistent learnings across sessions, (4) auditing project compliance or AI-readiness, (5) managing session data, (6) verifying the audit log chain, (7) authoring/validating policy.json. Zero API keys — runs 100% locally with CPU embeddings."
+homepage: https://www.npmjs.com/package/@compr/opscontext-mcp
+metadata: { "openclaw": { "emoji": "🧭", "requires": { "bins": ["npx"] }, "homepage": "https://www.npmjs.com/package/@compr/opscontext-mcp" } }
+---
+
+# OpsContext for AI Agents — Knowledge Base + Ops + Compliance
+
+ContextEngine turns your project documentation into a **queryable knowledge base** with hybrid BM25 keyword + semantic vector search. Zero API keys required — embeddings run locally on CPU.
+
+## Quick Start
+
+### 1. Initialize (one-time per project)
+
+```bash
+npx @compr/contextengine-mcp init
+```
+
+Creates `contextengine.json` config + `.github/copilot-instructions.md` template in the current directory.
+
+### 2. Search your knowledge base
+
+```bash
+# Ask the agent to search for context
+search_context "deployment docker nginx setup"
+```
+
+ContextEngine auto-discovers documentation files from 7 common patterns:
+- `.github/copilot-instructions.md`
+- `.github/SKILLS.md`
+- `CLAUDE.md`
+- `.cursorrules`
+- `.cursor/rules`
+- `AGENTS.md`
+
+## CLI Usage (no MCP required)
+
+ContextEngine also works as a standalone CLI tool — no MCP client needed:
+
+```bash
+npx @compr/contextengine-mcp search "docker nginx"    # Search knowledge base
+npx @compr/contextengine-mcp list-sources              # Show indexed sources
+npx @compr/contextengine-mcp list-projects             # Discover all projects
+npx @compr/contextengine-mcp score                     # AI-readiness score
+npx @compr/contextengine-mcp score --html               # Visual HTML report
+npx @compr/contextengine-mcp list-learnings security   # List learnings by category
+npx @compr/contextengine-mcp audit                     # Compliance audit
+npx @compr/contextengine-mcp help                      # Show all commands
+```
+
+## MCP Server Setup
+
+ContextEngine runs as an **MCP server** via stdio transport. Configure it in your MCP client:
+
+### VS Code (Per-Workspace)
+
+Add to `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "contextengine": {
+      "command": "npx",
+      "args": ["-y", "@compr/contextengine-mcp"],
+      "env": {
+        "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to Claude Desktop MCP config:
+
+```json
+{
+  "mcpServers": {
+    "contextengine": {
+      "command": "npx",
+      "args": ["-y", "@compr/contextengine-mcp"],
+      "env": {
+        "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw MCP Config
+
+Add to your OpenClaw `openclaw.json` MCP servers section:
+
+```json
+{
+  "mcpServers": {
+    "contextengine": {
+      "command": "npx",
+      "args": ["-y", "@compr/contextengine-mcp"],
+      "env": {
+        "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
+      }
+    }
+  }
+}
+```
+
+## Available Tools (17)
+
+| Tool | Description |
+|------|-------------|
+| `search_context` | Hybrid BM25+semantic search with temporal decay. Modes: hybrid, keyword, semantic |
+| `list_sources` | Show all indexed sources with chunk counts and embedding status |
+| `read_source` | Read full content of a knowledge source by name |
+| `reindex` | Force full re-index of all sources |
+| `list_projects` | Discover and analyze all projects (tech stack, git, docker, pm2) |
+| `check_ports` | Scan all projects for port conflicts |
+| `run_audit` | Compliance agent — git remotes, hooks, .env, Docker, PM2, versions |
+| `score_project` | AI-readiness scoring 0-100% with anti-gaming v2 (symlink/ghost config detection) |
+| `save_session` | Save key-value entry to a named session for cross-session persistence |
+| `load_session` | Load all entries from a named session |
+| `list_sessions` | List all saved sessions with entry counts and timestamps |
+| `end_session` | Pre-flight checklist — checks uncommitted git changes + doc freshness |
+| `save_learning` | Save a permanent operational rule — auto-surfaces in search results |
+| `list_learnings` | List all permanent learnings, optionally filtered by category |
+| `import_learnings` | Bulk-import learnings from Markdown or JSON files |
+| `activate` | Activate a Pro license on this machine |
+| `activation_status` | Check current license activation status |
+
+## Core Capabilities
+
+### Hybrid Search
+
+Combines three signals for optimal relevance:
+- **40% BM25 keyword search** — IDF-weighted, rare terms rank higher
+- **60% semantic similarity** — cosine distance via MiniLM-L6-v2 (22MB, local CPU)
+- **Temporal decay** — 90-day half-life boosts recent content
+
+```bash
+# Search with mode selection
+search_context "docker nginx proxy" --mode hybrid
+search_context "deployment steps" --mode keyword
+search_context "how to configure SSL" --mode semantic
+```
+
+### Operational Data Collection
+
+Auto-collects from your projects (no setup needed):
+- **Git**: branches, remotes, recent commits, hooks
+- **package.json / composer.json**: dependencies, scripts
+- **Docker**: Dockerfile, docker-compose services
+- **PM2**: process list, ecosystem config
+- **Nginx**: server blocks, proxy configs
+- **.env**: variable names (never values)
+- **Cron**: scheduled tasks
+
+### Persistent Learnings
+
+Save reusable patterns, bug fixes, and operational rules that auto-surface in search results:
+
+```bash
+# Save a learning
+save_learning --category "deployment" --rule "Always use --platform linux/amd64 for cross-arch Docker builds" --context "Apple Silicon to AMD64 server"
+
+# List by category
+list_learnings --category "security"
+```
+
+16 categories: architecture, security, bug-patterns, deployment, testing, api, frontend, backend, infrastructure, tooling, devops, git, data, dependencies, performance, accessibility.
+
+### Session Persistence
+
+Save and restore key-value data across sessions via MCP tools (NOT files in the project):
+
+```bash
+# Sessions are stored centrally in ~/.contextengine/sessions/ — NOT in the project directory
+# Use the MCP tool or CLI command — do NOT create session files manually
+
+save_session --name "project-x" --key "current_task" --value "Implementing auth flow"
+load_session --name "project-x"
+```
+
+**Important**: "Save session" means calling the `save_session` MCP tool or CLI command. It does NOT mean creating a markdown file. Sessions are stored in `~/.contextengine/sessions/` and auto-loaded on MCP startup.
+
+## Configuration
+
+Create `contextengine.json` in your project root (or run `npx @compr/contextengine-mcp init`):
+
+```json
+{
+  "sources": ["docs/architecture.md", "RUNBOOK.md"],
+  "workspaces": ["/home/user/projects"],
+  "patterns": [".github/copilot-instructions.md", "CLAUDE.md"],
+  "codeDirs": ["src", "lib"]
+}
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CONTEXTENGINE_CONFIG` | Path to contextengine.json config file |
+| `CONTEXTENGINE_WORKSPACES` | Colon-separated list of workspace directories |
+
+## Architecture
+
+- **Embeddings**: all-MiniLM-L6-v2 via @huggingface/transformers (22MB, local CPU, no API key)
+- **Transport**: MCP SDK v1.26 via stdio
+- **Chunking**: Markdown heading-based with 4-line overlap + code chunker (TS/JS/Python)
+- **Dedup**: SHA-256 content hashing prevents duplicate chunks
+- **Caching**: Embedding cache to disk (~/.contextengine/embedding-cache.json)
+- **File watching**: fs.watch with 500ms debounce → auto re-index on changes
+- **Non-blocking**: Keyword search available instantly, embeddings load in background
+
+## Notes
+
+- Requires **Node.js 18+**
+- First run downloads the embedding model (~22MB) — subsequent runs use cache
+- Keyword search is available instantly at startup; semantic search becomes available once the model loads
+- License: BSL-1.1 (Business Source License)
+- npm: `@compr/contextengine-mcp`
+
+### Post-Commit Verification
+
+After every `git push`, call `end_session` to verify nothing was missed:
+
+- **MCP tool**: `end_session` — use when ContextEngine MCP server is connected
+- **CLI fallback**: `npx @compr/contextengine-mcp end-session` — use when MCP is not connected (Cursor, Copilot, terminal sessions)
+
+Resolve any FAIL items before finishing. Workflow: `commit → push → end_session → verify → fix anything it catches → re-commit if needed`.
+
+## Lock Markers — Do Not Touch Verified Code
+
+ContextEngine detects **lock markers** in source files and documentation. When a chunk contains a lock marker, search results display a `🔒 LOCKED` prefix — this means the code has been verified and **must not be modified, deleted, or re-implemented**.
+
+### Recognized patterns
+
+```
+// LOCKED                          // in JS/TS/C/Go
+/* LOCKED */                       // block comment variant
+# LOCKED                           // Python/Shell/YAML
+<!-- LOCKED -->                    // HTML/Markdown
+LOCKED — verified <date>           // prose
+DO NOT RE-AUDIT                    // audit skip signal
+ALREADY IMPLEMENTED                // status marker
+VERIFIED — DO NOT                  // verified block
+```
+
+### Rules for agents
+
+1. **Never delete or rewrite** code that contains a lock marker or sits within a locked section
+2. **Never re-implement** functionality described in an `ALREADY IMPLEMENTED` block
+3. **When you finish implementing a feature**, add a lock marker to signal future sessions:
+   ```ts
+   // LOCKED — verified March 3 2026 — GA4 tag injection
+   ```
+4. **When you see `🔒 LOCKED` in search results**, treat it as read-only context — do not open the file to "fix" or "improve" it
+5. **If you must modify locked code** (user explicitly requests it), remove the lock marker first and add a new one after verification