OpsContext for AI Agents

AI that doesn't break what it can't see.

Claude Code, Cursor, and Copilot write code without seeing your servers — so they suggest the wrong port, restart the wrong service, deploy into the wrong env. OpsContext gives them eyes on what's actually running, plus a tamper-proof log of every change they make. Free core, no signup, runs entirely on your machine.

Previously published as @compr/contextengine-mcp. The 2.0 rename reflects what the project actually does: Claude Code sees the code, OpsContext sees the infra that runs it.

OpsContext is an MCP server. It runs locally, snapshots your live infra (PM2 processes, nginx config, Docker containers, git status, cron jobs, redacted env), and exposes it via tools your AI coding agents (Claude Code, Cursor, Copilot, Windsurf, OpenClaw) can call in real time. Everything stays on your machine — no telemetry, no code uploads.

🌐 Browser Capture (Phase 1, shipped 2026-06): OpsContext now captures prompts + assistant responses + tool calls from Claude.ai, ChatGPT.com, and your Claude Code terminal sessions into the same hash-chained audit log. Cross-surface drift detection becomes possible (e.g. catch when a model says one thing in the browser and another in the terminal). See Step 3 below.

Why

Claude Code already reads your CLAUDE.md, copilot-instructions.md, and source files. It has hooks, skills, and native memory. It does not — and structurally cannot — see what's running on your servers. Live process state, nginx routes, port conflicts across fleets, git working-tree drift across 30+ repos — that's the operational context AI agents lack.

OpsContext fills that gap, plus two compliance layers regulated industries demand from any agent stack:

1. Operational visibility (the moat) — collectors for PM2 / nginx / Docker / git / cron / .env (redacted) / composer / systemd. Cross-project + check_ports + fleet HTML scoring. Claude Code can't see this; we feed it cleanly.

2. Tamper-evident audit log (compliance) — hash-chained JSONL at ~/.contextengine/audit.log. Every state change recorded with prev_hash/hash. Designed to produce evidence aligned with SOC 2 CC7.2 (change monitoring) and ISO 27001 A.12.4.1 (event logging). These are evidence artifacts, not a certification. OpsContext is not itself SOC 2– or ISO 27001–certified; the audit log helps your org's auditor satisfy those controls.

3. Policy-as-code hooks (enforcement) — declarative .contextengine/policy.json for secret patterns (with paths scoping), diff-aware doc coverage (replaces the workaround-y 4-hour staleness gate), deploy-verify hosts, and signed bypass tokens. Runs as a pre-commit hook layer alongside gitleaks.

Plus the persistent-memory + search features carried forward from the contextengine era:

• 🔍 Hybrid Search — keyword (BM25) ships always; semantic re-ranking is opt-in

• 🧠 Semantic Search (optional) — all-MiniLM-L6-v2 runs locally on CPU, no API keys. Install with npm install @huggingface/transformers (~250MB, native onnxruntime). BM25 alone is plenty for most workspaces; turn semantic on when you have many similar projects and want fuzzy matches.

• 📁 Auto-discover — finds copilot-instructions.md, CLAUDE.md, .cursorrules, AGENTS.md across all projects

• 💻 Code Parsing — extracts functions, classes, interfaces from TS/JS/Python source files

• ⚙️ Operational Intelligence — collects git, Docker, PM2, nginx, cron, package.json data

• 🔒 Local-only — nothing leaves your machine

• ⚡ Instant startup — keyword search ready immediately, embeddings load in background

• 💾 Session Persistence — AI agents can save/restore context across conversations

• 💡 Learning Store — permanent operational rules that auto-surface in search results

• 🛡️ Protocol Firewall — progressive enforcement that ensures agents commit, document, and save learnings

• 🔌 Plugin Adapters — extend with custom data sources (Notion, Jira, RSS, etc.)

• 🧩 MCP native — works with any MCP-compatible client (VS Code, Claude, Cursor, OpenClaw)

What OpsContext is NOT

• Not a replacement for Claude Code, Cursor, or your IDE assistant. It runs alongside them as their ops/compliance backend. Code context = their job. Infra context + audit + policy = ours.

• Not a code quality tool — it checks project structure (CI, tests, Docker, docs) and validates content depth, but won't tell you if your code is good. An A+ score means "well-organized for AI agents," not "production-ready."

• Not required for tiny / solo projects — agents read copilot-instructions.md natively, and the audit log + policy gates earn their keep when there's more than one developer to coordinate or a compliance officer to answer to.

• Not worth chasing 100% score — invest in your PIPELINES.md and SKILLS docs instead of score-chasing. Those prevent costly mistakes; the score keeps you honest.

Related MCP server: roampal-core

Quick Start

1. Scaffold config (optional)

npx @compr/opscontext-mcp init

Detects your project type, creates contextengine.json + .github/copilot-instructions.md template.

2. Add to your MCP client

VS Code (recommended — per-project setup)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "contextengine": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@compr/opscontext-mcp"]
    }
  }
}

This activates ContextEngine when the workspace is open. Add this file to each project that needs it.

Note: VS Code deprecated MCP configuration in user settings.json. Use .vscode/mcp.json per workspace instead.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ContextEngine": {
      "command": "npx",
      "args": ["-y", "@compr/opscontext-mcp"]
    }
  }
}

Cursor — add to MCP settings:

{
  "mcpServers": {
    "ContextEngine": {
      "command": "npx",
      "args": ["-y", "@compr/opscontext-mcp"]
    }
  }
}

OpenClaw — add ContextEngine as an MCP server in your OpenClaw config, or use the bundled skill:

# Option 1: Copy the skill to your OpenClaw workspace
cp -r node_modules/@compr/opscontext-mcp/skills/contextengine ~/.openclaw/workspace/skills/

# Option 2: Add as MCP server in openclaw.json

{
  "mcpServers": {
    "contextengine": {
      "command": "npx",
      "args": ["-y", "@compr/opscontext-mcp"],
      "env": { "CONTEXTENGINE_WORKSPACES": "~/Projects" }
    }
  }
}

3. Capture browser + Claude Code events (optional)

Phase-1 browser capture wires Claude.ai / ChatGPT.com / Claude Code into the same hash-chained audit log the MCP server already writes to. Three small commands; each one is independent.

3a. Generate the browser extension secret

npx @compr/opscontext-mcp init-extension-secret

Writes a 32-byte hex token to ~/.contextengine/extension-secret (mode 0600). The Chrome extension authenticates to your local MCP server with this secret — nobody else on your network can post events.

Verify:

ls -la ~/.contextengine/extension-secret    # → -rw------- (0600)

Then load the unpacked extension and paste the secret into its Options page. Full install steps (build, load unpacked, paste secret): chrome-extension/README.md. (Chrome Web Store listing coming.)

3b. Auto-start the local server (macOS)

npx @compr/opscontext-mcp install-autostart

Installs a LaunchAgent so OpsContext binds 127.0.0.1:7842 on every login — that's the port the browser extension and the Claude Code hook both post to.

Verify:

curl http://127.0.0.1:7842/health           # → {"ok":true,...}

Companion commands: uninstall-autostart, autostart-status.

3c. Wire Claude Code terminal sessions

npm i -g @compr/opscontext-mcp && opscontext install-claude-hook

(Prefer the global install here: the hook scripts keep absolute paths to the CLI, and an npx cache copy can be pruned.)

Adds UserPromptSubmit, PostToolUse, and SessionStart hook entries to ~/.claude/settings.json so every Claude Code prompt + tool call lands in the same audit log as the browser events, plus a Stop entry: the session gate (2.7.0). A Claude Code turn cannot end while the repo's OpsContext session is older than the last commit; the agent is told which session to save, which session doc to update, and how far the agent docs are behind. No more "did you save the session?" at the end of a day. Details: npx @compr/opscontext-mcp session-gate --help.

Verify:

npx @compr/opscontext-mcp watch --once       # → tails recent events; should show claude_code_* kinds after one prompt

4. Pin your config (recommended)

If you have a contextengine.json with custom sources, add this to your shell profile (~/.zshrc or ~/.bashrc):

export CONTEXTENGINE_CONFIG="$HOME/path/to/contextengine.json"

Without this, ContextEngine falls back to auto-discovery (finds copilot-instructions.md etc.) but won't load your explicit sources, code dirs, or custom patterns.

That's it. ContextEngine auto-discovers your docs in ~/Projects.

📦 VS Code Extension

ContextEngine has a free VS Code extension that provides proactive enforcement — no MCP setup required:

• 📊 Value meter — shows what ContextEngine saved you this session: learnings recalled, learnings saved, estimated time saved. Falls back to git status when no MCP session is active

• 📈 Live stats dashboard — click ℹ️ to see real-time session metrics (tool calls, recalls, nudges, truncations, time saved)

• @contextengine chat — /status, /commit, /search, /remind, /sync in Copilot Chat

• Escalating notifications — warns when files accumulate without commits

• Terminal watcher — monitors commands with smart classification (git, deploy, database, python, build, test), credential redaction in logs, and stuck-pattern detection (alerts after 3+ consecutive failures)

• One-click commit — commit all changes across all repos

The extension reads live metrics from the MCP server (via ~/.contextengine/session-stats.json). For search, learnings, sessions, and scoring — it uses the MCP server (npx @compr/opscontext-mcp).

⭐ PRO Features

OpsContext is source-available with a free tier. The free tier covers everything agents need — search, memory, sessions, and compliance enforcement. PRO adds team and ops intelligence across multiple projects. Licensed under BSL-1.1, which is not OSI-approved open source (converts to AGPL-3.0 on 2030-02-22). See docs/about.md for the full publisher disclosure and licensing intent.

Pricing

→ Get PRO · Annual plans save 17%

# Activate after purchase
npx @compr/opscontext-mcp activate

CLI Usage (no MCP required)

ContextEngine also works as a standalone CLI tool — no MCP client setup needed:

# Search across all your project knowledge
npx @compr/opscontext-mcp search "docker nginx"
npx @compr/opscontext-mcp search "rate limiting" -n 10

# List all indexed sources
npx @compr/opscontext-mcp list-sources

# Discover and analyze all projects
npx @compr/opscontext-mcp list-projects

# AI-readiness score — no argument scores the CURRENT project only
npx @compr/opscontext-mcp score
npx @compr/opscontext-mcp score ContextEngine          # by project name
npx @compr/opscontext-mcp score ~/Projects/PLANK.io    # or by path

# Score every discovered project (writes a SCORE.md into each — opt in explicitly)
npx @compr/opscontext-mcp score --all
npx @compr/opscontext-mcp score --all --no-save        # scan without writing

# Visual HTML report (opens in browser)
npx @compr/opscontext-mcp score --html
npx @compr/opscontext-mcp score ContextEngine --html

# List permanent learnings (optionally by category)
npx @compr/opscontext-mcp list-learnings
npx @compr/opscontext-mcp list-learnings security

# Show live MCP session stats (value meter)
npx @compr/opscontext-mcp stats

# Run compliance audit across all projects
npx @compr/opscontext-mcp audit

# Scaffold config for a new project
npx @compr/opscontext-mcp init

# Show all commands
npx @compr/opscontext-mcp help

CLI mode uses keyword search (BM25) which is instant — no model loading required.

Tools (20)

All tools are wrapped by the Protocol Firewall — a built-in enforcement layer that ensures agents save learnings, persist sessions, and commit code. No action needed from users; it's automatic.

Configuration

ContextEngine works zero-config — it auto-discovers documentation files in ~/Projects.

For full control, create a contextengine.json:

{
  "sources": [
    { "name": "Team Runbook", "path": "./docs/RUNBOOK.md" },
    { "name": "Architecture", "path": "./docs/ARCHITECTURE.md" }
  ],
  "workspaces": ["~/Projects"],
  "patterns": [
    ".github/copilot-instructions.md",
    "CLAUDE.md",
    ".cursorrules",
    "AGENTS.md"
  ],
  "codeDirs": ["src"],
  "adapters": [
    { "name": "feeds", "module": "./adapters/rss-adapter.js", "config": { "feeds": ["https://blog.example.com/rss.xml"] } }
  ]
}

Auto-discovered patterns

Config resolution order

Which config file is read (both the search corpus and the project fleet):

Which project fleet is scanned — this is what score --all, audit, list_projects and check_ports operate on:

The env var wins. It is set per-invocation, so it is the most specific statement of intent — and it is what the MCP config blocks in this README set. Use it to scope a run:

CONTEXTENGINE_WORKSPACES=/tmp/sandbox npx @compr/opscontext-mcp score --all

Note: the search corpus (search, reindex, list-sources) still prefers the config file's workspaces over the env var. If you rely on the env var to scope indexing, set CONTEXTENGINE_CONFIG to a config without workspaces, or unset workspaces there.

Plugin Adapters

Extend ContextEngine with custom data sources via the adapter interface. Adapters are ES modules that collect data and return searchable chunks.

{
  "adapters": [
    {
      "name": "notion",
      "module": "./adapters/notion-adapter.js",
      "config": { "token": "$NOTION_API_TOKEN" }
    },
    {
      "name": "feeds",
      "module": "./adapters/rss-adapter.js",
      "config": { "feeds": ["https://blog.example.com/rss.xml"], "maxItems": 20 }
    }
  ]
}

Creating an Adapter

An adapter is a JS/TS module that exports an object with a collect() method:

// my-adapter.js
export default {
  name: "my-source",
  description: "Fetches data from My Source",

  validate(config) {
    if (!config?.apiKey) return "Missing apiKey";
    return null;
  },

  async collect(config) {
    // Fetch data and return Chunk[]
    return [{
      source: "my-source",
      section: "## Title",
      content: "Content to index...",
      lineStart: 1,
      lineEnd: 1,
    }];
  },
};

See examples/adapters/ for complete Notion and RSS adapter examples.

Adapter Features

• Environment variable resolution — use "$ENV_VAR" syntax in config

• Factory pattern — export createAdapter(config) for per-instance configuration

• Validation — optional validate() method checks config before collection

• Lifecycle hooks — optional init() and destroy() for setup/cleanup

• Safe execution — adapter failures never crash the server

How It Works

Your Project Files           ContextEngine              AI Agent
+-----------------+    +-------------------+    +---------------+
| copilot-        |    | 1. Parse & chunk  |    | GitHub        |
|  instructions   |--->| 2. Embed vectors  |<-->|  Copilot      |
| CLAUDE.md       |    | 3. Hybrid search  |    | Claude        |
| source code     |    | 4. Return top-k   |    | Cursor        |
| git/docker/pm2  |    | 5. Persist state  |    | Windsurf      |
+-----------------+    +-------------------+    +---------------+
                            stdio (MCP)

1. Parse — chunks markdown + extracts functions from source code

2. Embed — sentence embeddings run locally on CPU (no API keys)

3. Search — hybrid keyword + semantic scoring

4. Collect — operational data from git, package.json, Docker, PM2, nginx

5. Audit — compliance checks, port conflicts, AI-readiness scoring

Scoring

The score command evaluates project AI-readiness across documentation, infrastructure, code quality, and security — producing a letter grade from A+ to F.

Grade scale: A+ (90%+) · A (80%+) · B (70%+) · C (60%+) · D (50%+) · F (<50%)

What gets scored, and what gets written

score writes a SCORE.md into each project it scores. Because that is a write into your repositories, the scope is never inferred:

A project argument may be a name (PLANK.io) or a path (~/Projects/PLANK.io, ../PLANK.io, or an absolute path). A path also works for projects outside your configured workspaces.

Project Naming & Structure Tips

The scorer discovers projects from your configured workspaces directories (default: ~/Projects). Each subdirectory is treated as a separate project. For best results:

• Use descriptive folder names — the folder name becomes the project name in reports

• Keep one project per directory — monorepos should have a root copilot-instructions.md

• Real files over symlinks — each project should have its own configs with project-specific content

• Install your tools — a linting config without the linter installed doesn't count as linting

Architecture

TypeScript monorepo — MCP server + CLI + search engine + operational collectors.

See the npm package for installation and usage.

Development

npm install @compr/opscontext-mcp
npx @compr/opscontext-mcp help

Requirements

• Node.js 18+

• No API keys needed — embeddings run locally

Contributing

Feedback, feature requests, and bug reports welcome — email yannick@compr.ch.

If you're using ContextEngine, we'd love to hear about it.

Privacy & Data Security

ContextEngine runs 100% on your machine. Your code, your data, your rules.

Everything happens locally — search, scoring, learnings, sessions, embeddings. No project data is ever sent to an external server.

What stays on your machine (always)

What the activation server receives (PRO only)

That is the complete list. The activation request sends exactly six fields and the heartbeat exactly three — enforced by a lock comment in src/activation.ts that forbids adding a seventh field reflecting usage.

The server never receives: project names, file contents, learnings, sessions, git history, dependencies, code, .env variables, or anything about your actual work.

These are the only two network calls the tool makes. activate and heartbeat, both in src/activation.ts. Nothing else in the codebase opens a connection — verify it yourself with grep -rn "fetch(" src/.

What's obfuscated, and what isn't

One file in the published package is deliberately unreadable: dist/rubric.js, which holds the scoring thresholds (what earns which points). Those values are commercial IP under BSL-1.1, and knowing them exactly makes an AI-readiness score easy to game by padding files to hit a number rather than doing the work.

What that hides: values. What it does not hide: behaviour. No code path, network call, file access, or data flow is concealed anywhere in this package. The scoring logic itself, every collector, the search ranker, and both network calls above ship as readable JavaScript — and the full source is public at FASTPROD/ContextEngine. If a privacy claim on this page were false, the code that broke it would be right there to find.

Why this matters

Most AI coding tools (Copilot, Cursor, Codeium) send your code to external servers for processing. ContextEngine takes the opposite approach — embeddings run locally on CPU, search runs locally, and all persistent state stays in ~/.contextengine/ on your disk. The only network call is a lightweight license check for PRO users.

License

BSL-1.1 (Business Source License) — see LICENSE.

You may use ContextEngine for any purpose, including production, except offering it as a hosted/managed service competing with ContextEngine PRO/Team/Enterprise.

Converts to AGPL-3.0 on February 22, 2030.

For commercial licensing: yannick@compr.ch

Publisher

OpsContext is built by PROD LLC, an operating brand of CSS LLC (Cross Stream Solutions Sàrl), a Swiss company incorporated in 2005. The engineering team works under the FASTPROD name, which is also the GitHub organisation hosting this repository.

The VS Code Marketplace lists the extension under the legal-parent publisher ID css-llc; the npm package is published under the @compr scope. Both belong to the same entity.

PROD LLC also operates these products. The full, current list is on compr.fr.

Contact: yannick@compr.ch. Full corporate disclosure at docs/about.md.