ctxjev-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x96x64
+
+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,24 @@
+# ctxjev-mcp
+
+MCP server exposing [Jev](https://typesafe.ai)-based context scoring/pruning (`score_relevance`,
+`prune_history`) as tools for any MCP-capable agent host — Claude Code, Codex CLI, GitHub Copilot.
+
+**Claude Code:**
+
+```bash
+claude mcp add ctxjev --env TYPESAFE_API_KEY=... -- npx ctxjev-mcp
+```
+
+**Codex CLI:**
+
+```bash
+codex mcp add ctxjev --env TYPESAFE_API_KEY=... -- npx ctxjev-mcp
+```
+
+Get a key at [console.typesafe.ai/settings/keys](https://console.typesafe.ai/settings/keys) (no
+waitlist). Full docs, design notes, and per-host setup live in the main repo:
+**[github.com/x96x64/ctxjev](https://github.com/x96x64/ctxjev)**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    if (!process.env.TYPESAFE_API_KEY) {
+        console.error('ctxjev-mcp: TYPESAFE_API_KEY is not set — get one at console.typesafe.ai/settings/keys');
+        process.exit(1);
+    }
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,wFAAwF,CAAC,CAAA;QACvG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;IAC7B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAA;AAClD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/schemas.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+export declare const entrySchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    toolName: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export declare const scoreRelevanceInput: {
+    goal: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        toolName: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
+        timestamp: z.ZodNumber;
+    }, z.core.$strip>>;
+    recencyWeight: z.ZodOptional<z.ZodNumber>;
+};
+export declare const pruneHistoryInput: {
+    dropBelow: z.ZodOptional<z.ZodNumber>;
+    summarizeBelow: z.ZodOptional<z.ZodNumber>;
+    goal: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        toolName: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
+        timestamp: z.ZodNumber;
+    }, z.core.$strip>>;
+    recencyWeight: z.ZodOptional<z.ZodNumber>;
+};

package/dist/schemas.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const entrySchema = z.object({
+    id: z.string(),
+    role: z.enum(['user', 'assistant', 'tool']),
+    toolName: z.string().optional(),
+    content: z.string(),
+    timestamp: z.number(),
+});
+export const scoreRelevanceInput = {
+    goal: z.string().describe('The current task/goal to judge each entry\'s relevance against.'),
+    entries: z.array(entrySchema).describe('The agent history entries to score.'),
+    recencyWeight: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('How much an entry\'s position in the batch (recency) should factor into its score, 0-1. Defaults to 0.1.'),
+};
+export const pruneHistoryInput = {
+    ...scoreRelevanceInput,
+    dropBelow: z.number().min(0).max(1).optional().describe('Combined-score floor below which an entry is dropped. Defaults to 0.25.'),
+    summarizeBelow: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Combined-score floor below which an entry is summarized rather than kept verbatim. Defaults to 0.6.'),
+};
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iEAAiE,CAAC;IAC5F,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAC7E,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,0GAA0G,CAAC;CACxH,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,mBAAmB;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yEAAyE,CAAC;IAClI,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,qGAAqG,CAAC;CACnH,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,22 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { pruneHistoryInput, scoreRelevanceInput } from './schemas.js';
+import { pruneHistoryTool, scoreRelevanceTool } from './tools.js';
+export function createServer() {
+    const server = new McpServer({ name: 'ctxjev', version: '0.0.0' });
+    server.registerTool('score_relevance', {
+        description: "Score a batch of AI agent history entries for relevance to a goal, using Jev. Doesn't decide what to do about it — see prune_history for that.",
+        inputSchema: scoreRelevanceInput,
+    }, async (args) => {
+        const result = await scoreRelevanceTool(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    server.registerTool('prune_history', {
+        description: 'Score a batch of AI agent history entries against a goal and decide what to keep, drop, or summarize.',
+        inputSchema: pruneHistoryInput,
+    }, async (args) => {
+        const result = await pruneHistoryTool(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEjE,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IAElE,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,gJAAgJ;QAClJ,WAAW,EAAE,mBAAmB;KACjC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,CAAA;QAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;IAC/E,CAAC,CACF,CAAA;IAED,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EAAE,uGAAuG;QACpH,WAAW,EAAE,iBAAiB;KAC/B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC3C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;IAC/E,CAAC,CACF,CAAA;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+import { type Entry, type JevUsage } from 'ctxjev-core';
+export type ScoreRelevanceArgs = {
+    goal: string;
+    entries: Entry[];
+    recencyWeight?: number;
+};
+export declare function scoreRelevanceTool({ goal, entries, recencyWeight }: ScoreRelevanceArgs): Promise<{
+    scored: import("ctxjev-core").ScoredEntry[];
+    usage: JevUsage;
+}>;
+export type PruneHistoryArgs = ScoreRelevanceArgs & {
+    dropBelow?: number;
+    summarizeBelow?: number;
+};
+export declare function pruneHistoryTool({ goal, entries, recencyWeight, dropBelow, summarizeBelow }: PruneHistoryArgs): Promise<{
+    decisions: import("ctxjev-core").PruneDecision[];
+    savings: import("ctxjev-core").SavingsReport;
+    usage: JevUsage;
+}>;

package/dist/tools.js

@@ -0,0 +1,32 @@
+import { DEFAULT_POLICY, pruneContext, scoreEntries, summarizeSavings } from 'ctxjev-core';
+/**
+ * Plain functions wrapping ctxjev-core, kept independent of the MCP framework so they're
+ * testable without spinning up a server. src/server.ts adapts these into MCP tool handlers.
+ */
+function newUsageAccumulator() {
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    return {
+        usage,
+        onUsage: (u) => {
+            usage.inputTokens += u.inputTokens;
+            usage.outputTokens += u.outputTokens;
+        },
+    };
+}
+export async function scoreRelevanceTool({ goal, entries, recencyWeight }) {
+    const { usage, onUsage } = newUsageAccumulator();
+    const scored = await scoreEntries(entries, goal, recencyWeight ?? DEFAULT_POLICY.recencyWeight, { onUsage });
+    return { scored, usage };
+}
+export async function pruneHistoryTool({ goal, entries, recencyWeight, dropBelow, summarizeBelow }) {
+    const policy = {
+        dropBelow: dropBelow ?? DEFAULT_POLICY.dropBelow,
+        summarizeBelow: summarizeBelow ?? DEFAULT_POLICY.summarizeBelow,
+        recencyWeight: recencyWeight ?? DEFAULT_POLICY.recencyWeight,
+    };
+    const { usage, onUsage } = newUsageAccumulator();
+    const decisions = await pruneContext(entries, goal, policy, { onUsage });
+    const savings = summarizeSavings(entries, decisions);
+    return { decisions, savings, usage };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAiD,MAAM,aAAa,CAAA;AAEzI;;;GAGG;AAEH,SAAS,mBAAmB;IAC1B,MAAM,KAAK,GAAa,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IAC3D,OAAO;QACL,KAAK;QACL,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YACb,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,CAAA;YAClC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,CAAA;QACtC,CAAC;KACF,CAAA;AACH,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAsB;IAC3F,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,mBAAmB,EAAE,CAAA;IAChD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,aAAa,IAAI,cAAc,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IAC5G,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAoB;IAClH,MAAM,MAAM,GAAkB;QAC5B,SAAS,EAAE,SAAS,IAAI,cAAc,CAAC,SAAS;QAChD,cAAc,EAAE,cAAc,IAAI,cAAc,CAAC,cAAc;QAC/D,aAAa,EAAE,aAAa,IAAI,cAAc,CAAC,aAAa;KAC7D,CAAA;IAED,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,mBAAmB,EAAE,CAAA;IAChD,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IACxE,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IACpD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ctxjev-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing ctxjev's Jev-based context scoring/pruning as tools for any MCP-capable agent host.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x96x64/ctxjev.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/x96x64/ctxjev/tree/main/packages/mcp-server#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "ctxjev-mcp": "./dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5",
+    "ctxjev-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}