@minhpnq1807/contextos 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.7
+
+- Filters documentation-only AGENTS entries such as MCP tool headings, HTML comments, generic "Key Tools" headings, and tool reference tables before scoring.
+- Keeps actionable tool instructions, for example `Use detect_changes for code review`, measurable through MCP telemetry.
+
+## 0.1.6
+
+- Adds a transparent stdio MCP telemetry proxy that records `tools/call` events while forwarding requests to the original MCP server.
+- `ctx install` now wraps supported local MCP servers, including `code-review-graph` and `agentmemory`, so runtime-only tool rules can be measured from real MCP usage.
+
 ## 0.1.5
 
 - Sanitizes stale Stop reports at display time so previously recorded system-user rules no longer appear in `ctx report` or `ctx evidence` after upgrading.

package/README.md

@@ -105,6 +105,7 @@ node bin/ctx.js install
 3. Downloads and caches the required local MiniLM embedding model under `~/.ctx/contextos/models`.
 4. Warms `~/.ctx/contextos/embeddings.db` for AGENTS rules and project file paths.
 5. Registers the `ctx-mcp` MCP server and merges ContextOS global hooks into `$CODEX_HOME/hooks.json`.
+6. Wraps supported local MCP servers, currently `code-review-graph` and `agentmemory`, with a transparent telemetry proxy so `tools/call` events can be measured.
 
 Restart Codex after installing.
 
@@ -289,6 +290,8 @@ unknown  = the rule was relevant, but the diff does not prove either way
 
 For runtime-only rules, ContextOS also checks `telemetry.jsonl` for hook-visible tool names, MCP server names, and command metadata. A rule like "use code-review-graph before reading files" can be marked `followed` when telemetry contains a matching `code-review-graph` signal.
 
+`ctx install` wraps supported stdio MCP servers with a transparent proxy. The proxy forwards MCP JSON-RPC unchanged, but records `tools/call` requests such as `code-review-graph.detect_changes_tool` to workspace telemetry. This is what lets ContextOS prove runtime rules that cannot be seen in git diff.
+
 Host/session setup rules such as "run shell commands as user X", `sudo su - user`, `sudo -i -u user`, and `sudo -u user` are filtered before scoring. They are not injected and do not count toward `unknown` outcomes because they describe the agent runtime environment rather than project behavior.
 
 ## Development

package/bin/ctx.js

@@ -14,6 +14,7 @@ import { modelCacheDir, warmRuleEmbeddings } from "../plugins/ctx/lib/embedding-
 import { warmFileEmbeddings } from "../plugins/ctx/lib/file-embedding-retriever.js";
 import { scoreContext } from "../plugins/ctx/lib/score-context.js";
 import { defaultDataRoot, workspaceDataDir, workspaceMarkerPath } from "../plugins/ctx/lib/workspace-data.js";
+import { installMcpTelemetryProxies } from "../plugins/ctx/lib/mcp-proxy-install.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -101,6 +102,7 @@ async function install({ copy = false, inject = true } = {}) {
   runCodex(["plugin", "marketplace", "add", marketplaceRoot]);
   runCodex(["plugin", "add", "ctx@contextos"]);
   runCodex(["mcp", "add", "ctx-mcp", "--", "node", path.join(marketplaceRoot, "plugins", "ctx", "mcp", "server.js")]);
+  const proxyResult = installMcpTelemetryProxies({ codexHome: codexHome(), marketplaceRoot });
   const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
   console.log("Preparing required local embedding model...");
@@ -109,6 +111,7 @@ async function install({ copy = false, inject = true } = {}) {
   console.log(`Stable marketplace root: ${marketplaceRoot}`);
   console.log(`Installed ContextOS global hooks to ${hooksPath}`);
   console.log("Installed ctx-mcp MCP server.");
+  console.log(`MCP telemetry proxies: ${proxyResult.wrapped.length ? proxyResult.wrapped.map((item) => item.name).join(", ") : "none changed"}`);
   console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
   console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
   console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.1.0",
+  "version": "0.1.6",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/analyzer.js

@@ -62,6 +62,25 @@ const SYSTEM_USER_RULE_PATTERNS = [
   /\bminh_dev\b/i
 ];
 
+const DOCUMENTATION_HEADING_PATTERNS = [
+  /^mcp\s+tools?\s*:/i,
+  /^key\s+tools?$/i,
+  /^workflow$/i,
+  /^tools?$/i
+];
+
+const TOOL_REFERENCE_TOKENS = new Set([
+  "detect_changes",
+  "get_review_context",
+  "get_impact_radius",
+  "get_affected_flows",
+  "query_graph",
+  "semantic_search_nodes",
+  "get_architecture_overview",
+  "refactor_tool",
+  "list_communities"
+]);
+
 export function tokenize(value) {
   const normalized = String(value || "")
     .toLowerCase()
@@ -155,6 +174,7 @@ export function parseRules(markdown) {
 export function filterActionableRules(rules = []) {
   return rules
     .filter((rule) => !isSystemUserRule(rule))
+    .filter((rule) => !isDocumentationOnlyRule(rule))
     .map((rule, index) => ({ ...rule, id: `r${index + 1}`, originalOrder: index }));
 }
 
@@ -163,6 +183,32 @@ export function isSystemUserRule(rule) {
   return SYSTEM_USER_RULE_PATTERNS.some((pattern) => pattern.test(String(content || "")));
 }
 
+export function isDocumentationOnlyRule(rule) {
+  const content = String(typeof rule === "string" ? rule : rule?.content || "").trim();
+  const normalized = stripMarkdownEmphasis(content);
+  if (!normalized) return true;
+  if (/^<!--.*-->$/.test(normalized)) return true;
+  if (DOCUMENTATION_HEADING_PATTERNS.some((pattern) => pattern.test(normalized))) return true;
+  if (isMarkdownTableRule(normalized)) return true;
+  return false;
+}
+
+function stripMarkdownEmphasis(content) {
+  return String(content || "")
+    .replace(/^#+\s+/, "")
+    .replace(/^\*\*(.*)\*\*$/, "$1")
+    .trim();
+}
+
+function isMarkdownTableRule(content) {
+  if (!content.includes("|")) return false;
+  const pipeCount = (content.match(/\|/g) || []).length;
+  if (pipeCount < 4) return false;
+  const lower = content.toLowerCase();
+  const toolReferenceCount = [...TOOL_REFERENCE_TOKENS].filter((token) => lower.includes(token)).length;
+  return /\btool\b/.test(lower) && /\buse\s+when\b/.test(lower) && toolReferenceCount >= 2;
+}
+
 function dedupeRules(rules) {
   const seen = new Set();
   return rules.filter((rule) => {

package/plugins/ctx/lib/mcp-proxy-install.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_TARGETS = new Set(["code-review-graph", "agentmemory"]);
+
+export function installMcpTelemetryProxies({ codexHome, marketplaceRoot, targets = DEFAULT_TARGETS } = {}) {
+  const configPath = path.join(codexHome, "config.toml");
+  if (!fs.existsSync(configPath)) return { wrapped: [], skipped: [], configPath };
+
+  const original = fs.readFileSync(configPath, "utf8");
+  const proxyPath = path.join(marketplaceRoot, "plugins", "ctx", "mcp", "proxy.js");
+  const result = rewriteMcpTelemetryProxies(original, { proxyPath, targets });
+  if (result.content !== original) {
+    fs.writeFileSync(configPath, result.content, "utf8");
+  }
+  return { ...result, configPath };
+}
+
+export function rewriteMcpTelemetryProxies(toml, { proxyPath, targets = DEFAULT_TARGETS } = {}) {
+  const lines = String(toml || "").split(/\r?\n/);
+  const sections = findMcpServerSections(lines);
+  const wrapped = [];
+  const skipped = [];
+
+  for (const section of sections.reverse()) {
+    if (!targets.has(section.name)) {
+      skipped.push({ name: section.name, reason: "not-targeted" });
+      continue;
+    }
+
+    const body = lines.slice(section.start + 1, section.end);
+    const command = findStringValue(body, "command");
+    const args = findArrayValue(body, "args") || [];
+    if (!command) {
+      skipped.push({ name: section.name, reason: "missing-command" });
+      continue;
+    }
+    if (command === "node" && args[0] === proxyPath) {
+      skipped.push({ name: section.name, reason: "already-wrapped" });
+      continue;
+    }
+
+    const nextBody = replaceOrInsertServerField(
+      replaceOrInsertServerField(body, "command", tomlString("node")),
+      "args",
+      tomlArray([proxyPath, "--name", section.name, "--", command, ...args])
+    );
+    lines.splice(section.start + 1, section.end - section.start - 1, ...nextBody);
+    wrapped.push({ name: section.name, command, args });
+  }
+
+  return { content: lines.join("\n"), wrapped: wrapped.reverse(), skipped: skipped.reverse() };
+}
+
+function findMcpServerSections(lines) {
+  const sections = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\[mcp_servers\.([^\].]+)\]\s*$/);
+    if (!match) continue;
+    let end = lines.length;
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      if (/^\[/.test(lines[cursor])) {
+        end = cursor;
+        break;
+      }
+    }
+    sections.push({ name: unquoteTomlKey(match[1]), start: index, end });
+  }
+  return sections;
+}
+
+function replaceOrInsertServerField(body, key, value) {
+  const next = [...body];
+  const index = next.findIndex((line) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(line));
+  const line = `${key} = ${value}`;
+  if (index >= 0) next[index] = line;
+  else next.unshift(line);
+  return next;
+}
+
+function findStringValue(lines, key) {
+  const line = lines.find((item) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(item));
+  if (!line) return null;
+  const match = line.match(/=\s*"((?:\\.|[^"\\])*)"/);
+  return match ? unescapeTomlString(match[1]) : null;
+}
+
+function findArrayValue(lines, key) {
+  const line = lines.find((item) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(item));
+  if (!line) return null;
+  const arrayMatch = line.match(/=\s*\[(.*)\]\s*$/);
+  if (!arrayMatch) return null;
+  const values = [];
+  const pattern = /"((?:\\.|[^"\\])*)"/g;
+  let match;
+  while ((match = pattern.exec(arrayMatch[1]))) values.push(unescapeTomlString(match[1]));
+  return values;
+}
+
+function tomlArray(values) {
+  return `[${values.map(tomlString).join(", ")}]`;
+}
+
+function tomlString(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function unescapeTomlString(value) {
+  return String(value).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+
+function unquoteTomlKey(value) {
+  return value.replace(/^"|"$/g, "");
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/plugins/ctx/mcp/proxy.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import { appendTelemetry } from "../lib/telemetry.js";
+import { workspaceDataDir } from "../lib/workspace-data.js";
+
+const { serverName, command, args } = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+const telemetryPath = path.join(workspaceDataDir({ cwd }), "telemetry.jsonl");
+let inspectBuffer = "";
+
+const child = spawn(command, args, {
+  cwd,
+  env: process.env,
+  stdio: ["pipe", "pipe", "pipe"]
+});
+
+process.stdin.on("data", (chunk) => {
+  inspectClientChunk(chunk);
+  child.stdin.write(chunk);
+});
+
+process.stdin.on("end", () => {
+  child.stdin.end();
+});
+
+child.stdout.on("data", (chunk) => {
+  process.stdout.write(chunk);
+});
+
+child.stderr.on("data", (chunk) => {
+  process.stderr.write(chunk);
+});
+
+child.on("error", (error) => {
+  process.stderr.write(`contextos mcp proxy failed to start ${serverName}: ${error?.message || String(error)}\n`);
+  process.exitCode = 1;
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});
+
+function inspectClientChunk(chunk) {
+  inspectBuffer += chunk.toString("utf8");
+  const lines = inspectBuffer.split(/\r?\n/);
+  inspectBuffer = lines.pop() || "";
+  for (const line of lines.filter(Boolean)) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (message?.method !== "tools/call") continue;
+    const toolName = message.params?.name || "unknown";
+    appendTelemetry({
+      telemetryPath,
+      event: "McpToolCall",
+      payload: {
+        cwd,
+        mcp: serverName,
+        server: serverName,
+        toolName: `${serverName}.${toolName}`,
+        tool: toolName,
+        method: message.method
+      }
+    });
+  }
+}
+
+function parseArgs(argv) {
+  const separator = argv.indexOf("--");
+  if (separator < 0) usage();
+
+  const before = argv.slice(0, separator);
+  const after = argv.slice(separator + 1);
+  const nameIndex = before.indexOf("--name");
+  const serverName = nameIndex >= 0 ? before[nameIndex + 1] : null;
+  const command = after[0];
+  const args = after.slice(1);
+
+  if (!serverName || !command) usage();
+  return { serverName, command, args };
+}
+
+function usage() {
+  process.stderr.write("Usage: node proxy.js --name <mcp-server-name> -- <command> [...args]\n");
+  process.exit(2);
+}