mcp-context-optimizer 0.1.5 → 0.1.7

package/skills/pro/scripts/analyze-report.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * analyze-report.ts - Pro feature: Visualizes optimization reports from build_context
+ * 
+ * Usage: npx tsx scripts/analyze-report.ts <report.json>
+ * 
+ * This script parses the optimization report and displays:
+ * - Summary statistics
+ * - Top retained fragments
+ * - Omitted records and reasons
+ * - Token budget utilization
+ */
+
+import { readFileSync } from 'node:fs';
+
+interface ReportStats {
+  reduction?: number;
+  contextTokens?: number;
+  tokenBudget?: number;
+  utilization?: number;
+}
+
+interface ReportSource {
+  kind?: string;
+  selectionReason?: string;
+  score?: number;
+}
+
+interface OmittedRecord {
+  kind?: string;
+  reason?: string;
+}
+
+interface OptimizationReport {
+  stats?: ReportStats;
+  sources?: ReportSource[];
+  omitted?: OmittedRecord[];
+  warnings?: string[];
+}
+
+const reportPath: string = process.argv[2];
+const report: OptimizationReport = JSON.parse(readFileSync(reportPath, 'utf-8'));
+
+console.log('=== Optimization Report Analysis ===\n');
+
+// Summary
+console.log('Summary:');
+console.log(`  Reduction: ${report.stats?.reduction || 'N/A'}`);
+console.log(`  Context size: ${report.stats?.contextTokens || 'N/A'} tokens`);
+console.log(`  Budget: ${report.stats?.tokenBudget || 'N/A'} tokens`);
+console.log(`  Utilized: ${report.stats?.utilization || 'N/A'}%\n`);
+
+// Retained fragments
+console.log('Top retained fragments:');
+report.sources?.slice(0, 5).forEach((s: ReportSource, i: number) => {
+  console.log(`  ${i + 1}. [${s.kind || 'unknown'}] ${s.selectionReason || 'Retained'} (score: ${s.score || 'N/A'})`);
+});
+
+// Omissions
+console.log('\nOmitted records:');
+report.omitted?.forEach((o: OmittedRecord) => {
+  console.log(`  - [${o.kind || 'unknown'}] ${o.reason || 'Reason not specified'}`);
+});
+
+// Warnings
+if (report.warnings && report.warnings.length > 0) {
+  console.log('\nWarnings:');
+  report.warnings.forEach((w: string) => {
+    console.log(`  ⚠️  ${w}`);
+  });
+}
+
+console.log('\n=== Analysis complete ===');

package/skills/pro/scripts/prepare-context.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * prepare-context.ts - Pro feature: Prepares records from files before calling build_context
+ * 
+ * Usage: npx tsx scripts/prepare-context.ts <file1> <file2> ... [--task "Task description"]
+ * 
+ * This script reads specified files and generates ready-to-use record objects
+ * for ingest_records or build_context tools.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+interface FileRecord {
+  kind: 'file';
+  path: string;
+  content: string;
+  language: string;
+}
+
+const args: string[] = process.argv.slice(2);
+const taskIndex = args.indexOf('--task');
+const task: string = taskIndex > -1 ? args[taskIndex + 1] : 'Analyze the following code files';
+const files: string[] = args.filter(a => !a.startsWith('--') && (taskIndex === -1 || a !== args[taskIndex + 1]));
+
+if (files.length === 0) {
+  console.error('Usage: npx tsx scripts/prepare-context.ts <file1> <file2> ... [--task "Task description"]');
+  process.exit(1);
+}
+
+console.log('---');
+console.log('title: Preparing context records');
+console.log('tags: [workflow]');
+console.log('---\n');
+
+console.log(`Task: "${task}"\n`);
+console.log('Records to ingest:');
+
+const records: FileRecord[] = [];
+
+files.forEach((file: string) => {
+  const content = readFileSync(resolve(file), 'utf-8');
+  const record: FileRecord = {
+    kind: 'file',
+    path: file,
+    content: content.substring(0, 500) + (content.length > 500 ? '... (truncated)' : ''),
+    language: file.split('.').pop() || 'unknown'
+  };
+  records.push(record);
+  console.log(JSON.stringify(record, null, 2));
+});
+
+console.log('\n---');
+console.log('title: Ready to build context');
+console.log('---');
+console.log('\nNext steps:');
+console.log('1. Call `ingest_records` with the records above');
+console.log('2. Call `build_context` with your task description');
+console.log('3. Inspect the optimized context, sources, and omissions');

package/skills/pro/setup/INSTALLATION.md

@@ -0,0 +1,64 @@
+# Installation and setup
+
+This guide configures the MCP server separately from the Skill.
+
+## Requirements
+
+- Node.js 20+
+- An MCP-compatible client
+- Internet access during first-time package installation if using `npx`
+
+## Option A: MCP clients using `mcpServers`
+
+1. Copy `mcp-config.example.json` into the MCP configuration file used by your client.
+2. Merge the `mcpServers` entry into the existing configuration; do not overwrite other servers.
+3. Restart/reload the client or its MCP server connection.
+4. Confirm these tools appear: `ingest_records`, `search_context`, `get_decisions`, `get_relevant_errors`, `get_file_history`, `build_context`.
+
+The example uses `npx` to run the published package and make the MCP SDK dependencies available in the same invocation:
+
+```json
+{
+  "mcpServers": {
+    "mcp-context-optimizer": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "mcp-context-optimizer",
+        "-p",
+        "@modelcontextprotocol/server",
+        "-p",
+        "zod",
+        "mcp-ctx-optimizer"
+      ]
+    }
+  }
+}
+```
+
+This is a template for clients that accept the `mcpServers` key. Some clients use a different configuration schema or location; follow the host client's documentation and adapt the entry as needed.
+
+## Option B: Claude Code
+
+Run this command in a terminal:
+
+```bash
+claude mcp add mcp-context-optimizer -- npx -y -p mcp-context-optimizer -p @modelcontextprotocol/server -p zod mcp-ctx-optimizer
+```
+
+Then verify the server is listed in Claude Code and that its tools are available.
+
+## If the server does not start
+
+1. Check `node --version`; it should be 20 or newer.
+2. Check `npx --version`.
+3. Confirm the package/bin name is spelled `mcp-context-optimizer` / `mcp-ctx-optimizer` respectively.
+4. Check the client's MCP logs for package resolution or peer dependency errors.
+5. If the host requires a different config key or supports a different command runner, adapt the configuration to that host.
+
+Do not put API keys in this configuration: the optimizer does not require them.
+
+## Privacy and data handling
+
+The optimizer itself is designed for local operation and does not make network requests during processing. The initial `npx` command may download the package and dependencies. Only provide records that are relevant and that you are permitted to share with the agent. The default store is in memory; restarting the server clears it.

package/skills/pro/setup/claude-code-command.txt

@@ -0,0 +1 @@
+claude mcp add mcp-context-optimizer -- npx -y -p mcp-context-optimizer -p @modelcontextprotocol/server -p zod mcp-ctx-optimizer

package/skills/pro/setup/mcp-config.example.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "mcp-context-optimizer": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "mcp-context-optimizer",
+        "-p",
+        "@modelcontextprotocol/server",
+        "-p",
+        "zod",
+        "mcp-ctx-optimizer"
+      ]
+    }
+  }
+}