@compr/contextengine-mcp 1.9.44

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FASTPROD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# ContextEngine
+
+**An MCP server that turns your project documentation into a queryable knowledge base for AI agents.**
+
+ContextEngine indexes your `copilot-instructions.md`, `SKILLS.md`, `CLAUDE.md`, runbooks, and source code — then exposes it via the [Model Context Protocol](https://modelcontextprotocol.io) so AI coding assistants (GitHub Copilot, Claude, Cursor, Windsurf) can search your accumulated knowledge in real time.
+
+## Why
+
+AI coding agents are powerful — but they forget everything between sessions. Your team's hard-won knowledge lives in scattered markdown files that agents can't search.
+
+ContextEngine fixes this: **zero-config, fully local, privacy-first.**
+
+- 🔍 **Hybrid Search** — keyword + semantic (vector embeddings) across all your docs
+- 🧠 **Semantic Search** — `all-MiniLM-L6-v2` runs locally on CPU (no API keys)
+- 📁 **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
+- 🔌 **MCP native** — works with any MCP-compatible client
+
+## Quick Start
+
+### 1. Scaffold config (optional)
+
+```bash
+npx contextengine-mcp init
+```
+
+Detects your project type, creates `contextengine.json` + `.github/copilot-instructions.md` template.
+
+### 2. Add to your MCP client
+
+**VS Code** — add to `~/.vscode/mcp.json` (global) or `.vscode/mcp.json` (per-project):
+
+```json
+{
+  "servers": {
+    "ContextEngine": {
+      "command": "npx",
+      "args": ["contextengine-mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ContextEngine": {
+      "command": "npx",
+      "args": ["contextengine-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — add to MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ContextEngine": {
+      "command": "npx",
+      "args": ["contextengine-mcp"]
+    }
+  }
+}
+```
+
+That's it. ContextEngine auto-discovers your docs in `~/Projects`.
+
+## Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `search_context` | Hybrid keyword+semantic search with mode selector |
+| `list_sources` | Show all indexed sources with chunk counts |
+| `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, hooks, .env, Docker, PM2, versions |
+| `score_project` | AI-readiness scoring 0-100% with letter grades (A+ to F) |
+| `save_session` | Save key-value entry to a named session |
+| `load_session` | Load all entries from a named session |
+| `list_sessions` | List all saved sessions |
+
+## Configuration
+
+ContextEngine works **zero-config** — it auto-discovers documentation files in `~/Projects`.
+
+For full control, create a `contextengine.json`:
+
+```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"]
+}
+```
+
+### Auto-discovered patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `.github/copilot-instructions.md` | GitHub Copilot project instructions |
+| `.github/SKILLS.md` | Team skills inventory |
+| `CLAUDE.md` | Claude Code project instructions |
+| `.cursorrules` | Cursor AI rules |
+| `.cursor/rules` | Cursor AI rules (folder format) |
+| `AGENTS.md` | Multi-agent instructions |
+
+### Config resolution order
+
+| Priority | Source |
+|----------|--------|
+| 1 | `CONTEXTENGINE_CONFIG` env var |
+| 2 | `./contextengine.json` |
+| 3 | `~/.contextengine.json` |
+| 4 | `CONTEXTENGINE_WORKSPACES` env var |
+| 5 | `~/Projects` auto-discover |
+
+## 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** — markdown heading-based chunker + code parser (TS/JS/Python)
+2. **Embed** — `all-MiniLM-L6-v2` sentence embeddings (384-dim, local CPU)
+3. **Search** — hybrid scoring: 40% keyword overlap + 60% cosine similarity
+4. **Collect** — operational data from git, package.json, Docker, PM2, nginx, cron
+5. **Audit** — compliance checks, port conflicts, AI-readiness scoring
+
+### Performance
+
+| Metric | Value |
+|--------|-------|
+| Startup (keyword ready) | Instant |
+| Startup (semantic ready) | ~200ms from cache, ~15s first run |
+| Embedding speed | ~50 chunks/sec (Apple Silicon) |
+| Embedding cache | `~/.contextengine/embedding-cache.json` |
+| Session storage | `~/.contextengine/sessions/` |
+
+## Architecture
+
+```
+src/
+├── cli.ts           # CLI - init scaffolding, help, routes to MCP
+├── index.ts         # MCP server - 11 tools, resources, file watcher
+├── config.ts        # Config loading, auto-discovery, 7 patterns
+├── ingest.ts        # Markdown heading-based chunker
+├── search.ts        # Keyword search - term overlap scoring
+├── embeddings.ts    # MiniLM-L6-v2 - vector search, cosine similarity
+├── cache.ts         # Embedding cache - SHA-256 hash invalidation
+├── code-chunker.ts  # Code parser - TS/JS/Python function extraction
+├── collectors.ts    # 11 operational data collectors
+├── agents.ts        # Compliance auditor, port checker, AI scorer
+└── sessions.ts      # Session persistence - key-value store
+```
+
+## Development
+
+```bash
+git clone https://github.com/FASTPROD/ContextEngine.git
+cd ContextEngine
+npm install
+npm run build
+npm start
+```
+
+## Requirements
+
+- Node.js 18+
+- No API keys needed — embeddings run locally
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/agents.d.ts

@@ -0,0 +1,127 @@
+import type { ProjectDirectory } from "./config.js";
+/**
+ * Multi-Agent Architecture — Phase 1: Foundation + Compliance Agent
+ *
+ * Implements the plan-and-approve workflow described in
+ * FASTPROD/docs/MULTI_AGENT_ARCHITECTURE_PLAN.md
+ *
+ * Risk levels:
+ * 🟢 Read-only (auto-approve) — ls, cat, SELECT, status checks
+ * 🟡 Non-destructive write — git commit, config edit (needs review)
+ * 🔴 Destructive — DELETE, DROP, rm, deploy, reload (needs confirm)
+ */
+export interface ProjectInfo {
+    name: string;
+    path: string;
+    type: string;
+    framework: string;
+    runtime: string;
+    hasGit: boolean;
+    gitRemotes: string[];
+    hasDocker: boolean;
+    hasPm2: boolean;
+    deps: Record<string, string>;
+}
+export interface PlanStep {
+    action: string;
+    description: string;
+    command?: string;
+    risk: "green" | "yellow" | "red";
+    reversible: boolean;
+    estimatedTime: string;
+}
+export interface AuditFinding {
+    check: string;
+    status: "pass" | "warn" | "fail";
+    message: string;
+    project?: string;
+    severity: "info" | "low" | "medium" | "high" | "critical";
+    remediation?: string;
+    command?: string;
+}
+export interface AuditPlan {
+    agent: string;
+    timestamp: string;
+    trigger: string;
+    scope: string;
+    findings: AuditFinding[];
+    steps: PlanStep[];
+    summary: {
+        pass: number;
+        warn: number;
+        fail: number;
+        critical: number;
+    };
+}
+/**
+ * Analyze a project directory and determine its type, framework, runtime.
+ */
+export declare function analyzeProject(dir: ProjectDirectory): ProjectInfo;
+/**
+ * List all projects with tech analysis.
+ */
+export declare function listProjects(projectDirs: ProjectDirectory[]): ProjectInfo[];
+interface PortUsage {
+    port: number;
+    project: string;
+    source: string;
+    details: string;
+}
+/**
+ * Scan all projects for port declarations and detect conflicts.
+ */
+export declare function checkPorts(projectDirs: ProjectDirectory[]): {
+    ports: PortUsage[];
+    conflicts: Array<{
+        port: number;
+        usages: PortUsage[];
+    }>;
+};
+/**
+ * Run the full compliance audit across all projects.
+ * Returns a structured plan document.
+ */
+export declare function runComplianceAudit(projectDirs: ProjectDirectory[]): AuditPlan;
+/**
+ * Format an audit plan as a readable Markdown document.
+ */
+export declare function formatPlan(plan: AuditPlan): string;
+/**
+ * Format project list as a readable summary.
+ */
+export declare function formatProjectList(projects: ProjectInfo[]): string;
+/**
+ * Format port map as a readable table.
+ */
+export declare function formatPortMap(ports: PortUsage[], conflicts: Array<{
+    port: number;
+    usages: PortUsage[];
+}>): string;
+export interface ScoreCheck {
+    name: string;
+    category: string;
+    points: number;
+    maxPoints: number;
+    status: "pass" | "partial" | "fail";
+    detail: string;
+}
+export interface ProjectScore {
+    project: string;
+    path: string;
+    score: number;
+    maxScore: number;
+    percentage: number;
+    grade: string;
+    checks: ScoreCheck[];
+}
+/**
+ * Score a project's AI-readiness (0-100%).
+ * Checks how well-prepared a project is for AI coding agents.
+ */
+export declare function scoreProject(dir: ProjectDirectory): ProjectScore;
+/**
+ * Format a project score report as Markdown.
+ */
+export declare function formatScoreReport(scores: ProjectScore[]): string;
+export {};
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}