oioxo-mcp 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,122 @@
+/**
+ * OIOXO MCP server — exposes the on-device context engine to ANY MCP-capable
+ * agent (Claude Code, Copilot, Cursor, Windsurf, …) over stdio.
+ *
+ * Tool design notes:
+ *  - `get_context` is THE tool: descriptions tell the agent to call it BEFORE
+ *    reading files, which is what makes OIOXO fire first on every prompt.
+ *  - Retrieval tools are gated by the OIOXO plan via the server-authoritative
+ *    save-tokens meter (gate/account.ts): anon → sign in, free → monthly
+ *    allowance, Pro → unlimited. Memory tools stay ungated (they save no
+ *    tokens; they make the engine sticky).
+ *  - Code is indexed in-memory and NEVER uploaded. Only the saved-token COUNT
+ *    is reported to oioxo.com for metering.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadProject } from '../core/files.js';
+import { Bm25Index } from '../core/bm25.js';
+import { buildCapsule } from '../core/capsule.js';
+import { buildGraph } from '../core/code-graph.js';
+import { fileSkeleton } from '../core/skeleton.js';
+import { readProjectContext, rememberFact, contextBlock } from '../core/memory.js';
+import { saveMeter, isLoggedIn, LOGIN_HINT, UPGRADE_URL } from '../gate/account.js';
+const VERSION = '0.1.0';
+const REINDEX_MS = 60_000;
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+async function checkGate() {
+    if (!(await isLoggedIn())) {
+        return {
+            ok: false,
+            message: `OIOXO context engine is linked to an OIOXO account.\n${LOGIN_HINT}\n` +
+                `Free accounts include a monthly context allowance; OIOXO Pro is unlimited → ${UPGRADE_URL}`,
+        };
+    }
+    const state = await saveMeter('check');
+    if (!state) {
+        // Server unreachable → fail toward the gate, with an honest message.
+        return { ok: false, message: 'OIOXO could not verify your plan (oioxo.com unreachable). Retrieval is paused until the connection returns.' };
+    }
+    if (!state.optimize) {
+        if (state.tier === 'anon') {
+            return { ok: false, message: `Your OIOXO session expired. ${LOGIN_HINT}` };
+        }
+        return {
+            ok: false,
+            message: `Your OIOXO Free monthly context allowance is used (${state.savedThisMonth.toLocaleString()} tokens saved this month).\n` +
+                `It resets ${new Date(state.resetsAt).toUTCString()}. OIOXO Pro is unlimited → ${UPGRADE_URL}`,
+        };
+    }
+    return { ok: true, state };
+}
+export async function startServer(root) {
+    const server = new McpServer({ name: 'oioxo', version: VERSION });
+    // ---- on-device index (lazy build, time-based refresh) ----
+    let files = [];
+    const index = new Bm25Index();
+    let indexedAt = 0;
+    let indexing = null;
+    const ensureIndex = async () => {
+        if (Date.now() - indexedAt < REINDEX_MS && files.length)
+            return;
+        if (!indexing) {
+            indexing = (async () => {
+                files = await loadProject(root);
+                index.build(files);
+                indexedAt = Date.now();
+            })().finally(() => { indexing = null; });
+        }
+        return indexing;
+    };
+    server.tool('get_context', 'ALWAYS call this FIRST, before reading or searching files yourself. Returns the minimal relevant slice of this codebase for a task: the exact code in play plus the API surface of its real dependencies — typically 10-20x fewer tokens than reading the files. Powered by OIOXO, 100% on-device.', { query: z.string().describe('The task or question, in natural language (include identifiers/error text when you have them).') }, async ({ query }) => {
+        const gate = await checkGate();
+        if (!gate.ok)
+            return text(gate.message);
+        await ensureIndex();
+        const capsule = buildCapsule(query, files, index);
+        if (!capsule.text)
+            return text('No relevant code found for that query in this workspace.');
+        // Report the savings (server clamps; Pro stays unlimited — the report only feeds stats).
+        if (capsule.savedTokens > 0)
+            void saveMeter('report', capsule.savedTokens);
+        const ctx = contextBlock(await readProjectContext(root));
+        const header = `OIOXO context capsule — files: ${capsule.files.join(', ')} (≈${capsule.savedTokens.toLocaleString()} tokens saved vs reading full files)`;
+        return text([header, ctx, capsule.text].filter(Boolean).join('\n\n'));
+    });
+    server.tool('get_skeleton', 'The API surface of one file — signatures, no implementation bodies. Use to learn how to CALL code without paying for its full text.', { path: z.string().describe('Workspace-relative file path.') }, async ({ path: rel }) => {
+        const gate = await checkGate();
+        if (!gate.ok)
+            return text(gate.message);
+        await ensureIndex();
+        const f = files.find((x) => x.path === rel.replace(/\\/g, '/'));
+        if (!f)
+            return text(`File not found in the OIOXO index: ${rel}`);
+        const skel = fileSkeleton(f.path, f.content);
+        const saved = Math.max(0, Math.round((f.content.length - skel.length) / 4));
+        if (saved > 0)
+            void saveMeter('report', saved);
+        return text(skel);
+    });
+    server.tool('get_impact', 'Blast radius of a file: what it imports and everything that imports IT. Call before refactoring or deleting to know what may break.', { path: z.string().describe('Workspace-relative file path.') }, async ({ path: rel }) => {
+        const gate = await checkGate();
+        if (!gate.ok)
+            return text(gate.message);
+        await ensureIndex();
+        const p = rel.replace(/\\/g, '/');
+        const graph = buildGraph(files);
+        const deps = graph.deps.get(p) ?? [];
+        const dependents = graph.dependents.get(p) ?? [];
+        return text(`OIOXO impact graph for ${p}\n\nIMPORTS (its dependencies):\n${deps.map((d) => `  ${d}`).join('\n') || '  (none in-project)'}\n\nIMPORTED BY (changing ${p} may break these):\n${dependents.map((d) => `  ${d}`).join('\n') || '  (none — no in-project callers)'}`);
+    });
+    server.tool('remember', 'Save one durable fact about THIS project to .oioxo/memory.md (on-device, shared with the OIOXO IDEs). Use for decisions, conventions, gotchas worth keeping.', { fact: z.string().describe('The fact, one concise sentence.') }, async ({ fact }) => {
+        await rememberFact(root, fact);
+        return text('Saved to .oioxo/memory.md.');
+    });
+    server.tool('recall', "This project's rules and learned memory from .oioxo/ (same files the OIOXO IDEs maintain). Call when starting work in an unfamiliar repo.", {}, async () => {
+        const block = contextBlock(await readProjectContext(root));
+        return text(block || 'No .oioxo/rules.md or memory.md in this project yet.');
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/test/core.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/core.test.js

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for the OIOXO context engine core. Run via `npm test`
+ * (tsc build → node --test on the compiled output).
+ */
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { Bm25Index, tokenize } from '../core/bm25.js';
+import { importSpecifiers, resolveImport, buildGraph, expandContext } from '../core/code-graph.js';
+import { extractSignatures, fileSkeleton } from '../core/skeleton.js';
+import { buildCapsule } from '../core/capsule.js';
+import { rememberFact, readProjectContext, contextBlock } from '../core/memory.js';
+import { loadProject } from '../core/files.js';
+// ---------- tokenizer ----------
+test('tokenize splits camelCase and snake_case identifiers', () => {
+    const toks = tokenize('getUserAuthToken par_ser');
+    assert.ok(toks.includes('user'));
+    assert.ok(toks.includes('auth'));
+    assert.ok(toks.includes('par'));
+    assert.ok(toks.includes('ser'));
+});
+// ---------- BM25 ----------
+const FILES = [
+    { path: 'src/auth/login.ts', content: 'export function loginUser(email: string, password: string) {\n  return checkPassword(email, password);\n}\nfunction checkPassword(e: string, p: string) { return e && p; }\n' },
+    { path: 'src/billing/invoice.ts', content: 'import { loginUser } from "../auth/login";\nexport function createInvoice(total: number) {\n  loginUser("a", "b");\n  return { total };\n}\n' },
+    { path: 'src/util/math.ts', content: 'export const add = (a: number, b: number) => a + b;\n' },
+];
+test('BM25 retrieves the chunk about the query topic', () => {
+    const idx = new Bm25Index();
+    const st = idx.build(FILES);
+    assert.equal(st.files, 3);
+    assert.ok(st.chunks >= 3);
+    const hits = idx.retrieve('login password check', 3);
+    assert.ok(hits.length > 0);
+    assert.equal(hits[0].path, 'src/auth/login.ts');
+});
+// ---------- code graph ----------
+test('importSpecifiers finds all import forms', () => {
+    const specs = importSpecifiers(`import a from './a';\nimport './b';\nconst c = require('./c');\nexport { d } from './d';\nconst e = import('./e');`);
+    assert.deepEqual(specs.sort(), ['./a', './b', './c', './d', './e']);
+});
+test('resolveImport tries extensions and /index', () => {
+    const set = new Set(['src/a.ts', 'src/lib/index.ts']);
+    assert.equal(resolveImport('./a', 'src/main.ts', set), 'src/a.ts');
+    assert.equal(resolveImport('./lib', 'src/main.ts', set), 'src/lib/index.ts');
+    assert.equal(resolveImport('react', 'src/main.ts', set), null);
+});
+test('buildGraph + expandContext reach real dependencies', () => {
+    const graph = buildGraph(FILES);
+    assert.deepEqual(graph.deps.get('src/billing/invoice.ts'), ['src/auth/login.ts']);
+    assert.deepEqual(graph.dependents.get('src/auth/login.ts'), ['src/billing/invoice.ts']);
+    const slice = expandContext(graph, ['src/billing/invoice.ts'], { hops: 2, max: 5 });
+    assert.ok(slice.includes('src/auth/login.ts'));
+    assert.ok(!slice.includes('src/util/math.ts')); // unconnected decoy stays out
+});
+// ---------- skeleton ----------
+test('extractSignatures gets TS functions/classes without bodies', () => {
+    const sigs = extractSignatures('a.ts', 'export async function fetchUser(id: string): Promise<User> {\n  return db.get(id);\n}\nexport class UserStore {\n  private x = 1;\n}\nexport interface User { id: string }\n');
+    const names = sigs.map((s) => s.name);
+    assert.ok(names.includes('fetchUser'));
+    assert.ok(names.includes('UserStore'));
+    assert.ok(names.includes('User'));
+    const fn = sigs.find((s) => s.name === 'fetchUser');
+    assert.ok(!fn.signature.includes('db.get'));
+});
+test('extractSignatures handles python', () => {
+    const sigs = extractSignatures('a.py', 'class Parser:\n    pass\n\ndef parse_file(path):\n    return path\n');
+    assert.deepEqual(sigs.map((s) => s.name).sort(), ['Parser', 'parse_file']);
+});
+test('fileSkeleton is much smaller than the file', () => {
+    const big = 'export function f1(a: number) {\n' + '  // body\n'.repeat(200) + '}\n';
+    const skel = fileSkeleton('big.ts', big);
+    assert.ok(skel.length < big.length / 5);
+});
+// ---------- capsule ----------
+test('buildCapsule ships anchors full + neighbors as skeletons + counts savings', () => {
+    const idx = new Bm25Index();
+    idx.build(FILES);
+    const cap = buildCapsule('create invoice total', FILES, idx);
+    assert.ok(cap.files.includes('src/billing/invoice.ts'));
+    assert.ok(cap.text.includes('createInvoice'));
+    assert.ok(cap.savedTokens >= 0);
+    assert.ok(cap.text.length > 0);
+});
+// ---------- memory ----------
+test('rememberFact dedups and bounds; contextBlock formats', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-mem-'));
+    await rememberFact(root, 'uses pnpm not npm');
+    await rememberFact(root, 'uses pnpm not npm'); // dup
+    await rememberFact(root, 'API lives under /api/v2');
+    const ctx = await readProjectContext(root);
+    const bullets = ctx.memory.split('\n').filter((l) => l.startsWith('- '));
+    assert.equal(bullets.length, 2);
+    assert.ok(contextBlock(ctx).includes('PROJECT MEMORY'));
+    await fs.rm(root, { recursive: true, force: true });
+});
+// ---------- file walking ----------
+test('loadProject respects excludes and extensions', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-files-'));
+    await fs.mkdir(path.join(root, 'node_modules', 'x'), { recursive: true });
+    await fs.writeFile(path.join(root, 'node_modules', 'x', 'index.js'), 'ignored');
+    await fs.writeFile(path.join(root, 'app.ts'), 'export const a = 1;');
+    await fs.writeFile(path.join(root, 'photo.png'), 'binaryish');
+    const files = await loadProject(root);
+    assert.deepEqual(files.map((f) => f.path), ['app.ts']);
+    await fs.rm(root, { recursive: true, force: true });
+});

package/dist/test/e2e.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/e2e.test.js

@@ -0,0 +1,100 @@
+/**
+ * End-to-end smoke test: spawn the real MCP server over stdio (exactly how
+ * Claude Code / Copilot / Cursor will) with the official SDK client, then:
+ *   - list tools (all 5 present),
+ *   - call the UNGATED memory tools (remember → recall round-trip),
+ *   - call the GATED get_context with no credential → expect the OIOXO
+ *     sign-in gate message, NOT code (monetization is the product rule).
+ *
+ * Hermetic: OIOXO_HOME points at a temp dir (no credential), and the control
+ * plane points at a dead port so even a mis-read credential can't pass the gate.
+ */
+import { test } from 'node:test';
+import * as assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', 'cli', 'index.js');
+const textOf = (r) => {
+    const c = r.content ?? [];
+    return c.filter((x) => x.type === 'text').map((x) => x.text ?? '').join('\n');
+};
+test('MCP server end-to-end over stdio', async () => {
+    // Fixture workspace the server will index.
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-e2e-'));
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-home-'));
+    await fs.writeFile(path.join(root, 'cart.ts'), 'import { tax } from "./tax";\nexport function cartTotal(items: number[]) {\n  return items.reduce((a, b) => a + b, 0) * tax();\n}\n');
+    await fs.writeFile(path.join(root, 'tax.ts'), 'export function tax() { return 1.13; }\n');
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [CLI, 'serve'],
+        cwd: root,
+        env: {
+            ...process.env,
+            OIOXO_HOME: home,
+            OIOXO_CONTROL_PLANE: 'http://127.0.0.1:9', // dead — gate must hold offline
+        },
+    });
+    const client = new Client({ name: 'oioxo-e2e', version: '0.0.1' });
+    await client.connect(transport);
+    try {
+        // 1) Tool inventory.
+        const tools = await client.listTools();
+        const names = tools.tools.map((t) => t.name).sort();
+        assert.deepEqual(names, ['get_context', 'get_impact', 'get_skeleton', 'recall', 'remember']);
+        // 2) Ungated memory round-trip.
+        await client.callTool({ name: 'remember', arguments: { fact: 'tax rate is 13 percent' } });
+        const recall = textOf(await client.callTool({ name: 'recall', arguments: {} }));
+        assert.ok(recall.includes('tax rate is 13 percent'));
+        const memOnDisk = await fs.readFile(path.join(root, '.oioxo', 'memory.md'), 'utf8');
+        assert.ok(memOnDisk.includes('- tax rate is 13 percent'));
+        // 3) Gated retrieval without a credential → OIOXO gate message, no code.
+        const gated = textOf(await client.callTool({ name: 'get_context', arguments: { query: 'cart total tax' } }));
+        assert.ok(gated.includes('oioxo-mcp login'), `expected login gate, got: ${gated.slice(0, 200)}`);
+        assert.ok(!gated.includes('cartTotal'), 'gated call must not leak retrieval');
+    }
+    finally {
+        await client.close().catch(() => { });
+        await fs.rm(root, { recursive: true, force: true });
+        await fs.rm(home, { recursive: true, force: true });
+    }
+});
+test('init writes + merges agent configs (project + global)', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-init-'));
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'oioxo-inithome-'));
+    // Pre-existing VS Code MCP config that must survive the merge.
+    await fs.mkdir(path.join(root, '.vscode'), { recursive: true });
+    await fs.writeFile(path.join(root, '.vscode', 'mcp.json'), JSON.stringify({ servers: { other: { command: 'x' } } }));
+    // "Installed" Windsurf + Gemini + Codex on the fake machine.
+    await fs.mkdir(path.join(home, '.codeium', 'windsurf'), { recursive: true });
+    await fs.mkdir(path.join(home, '.gemini'), { recursive: true });
+    await fs.mkdir(path.join(home, '.codex'), { recursive: true });
+    await fs.writeFile(path.join(home, '.codex', 'config.toml'), 'model = "o4"\n');
+    const { initAgents } = await import('../cli/agents.js');
+    await initAgents(root, { all: true, command: 'oioxo-mcp', home });
+    const vsc = JSON.parse(await fs.readFile(path.join(root, '.vscode', 'mcp.json'), 'utf8'));
+    assert.ok(vsc.servers.other, 'existing server entry preserved');
+    assert.equal(vsc.servers.oioxo.command, 'oioxo-mcp');
+    const claude = JSON.parse(await fs.readFile(path.join(root, '.mcp.json'), 'utf8'));
+    assert.equal(claude.mcpServers.oioxo.command, 'oioxo-mcp');
+    const cursor = JSON.parse(await fs.readFile(path.join(root, '.cursor', 'mcp.json'), 'utf8'));
+    assert.equal(cursor.mcpServers.oioxo.command, 'oioxo-mcp');
+    // Globals: written because detected; TOML appended without clobbering.
+    const windsurf = JSON.parse(await fs.readFile(path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), 'utf8'));
+    assert.equal(windsurf.mcpServers.oioxo.command, 'oioxo-mcp');
+    const gemini = JSON.parse(await fs.readFile(path.join(home, '.gemini', 'settings.json'), 'utf8'));
+    assert.equal(gemini.mcpServers.oioxo.command, 'oioxo-mcp');
+    const codex = await fs.readFile(path.join(home, '.codex', 'config.toml'), 'utf8');
+    assert.ok(codex.startsWith('model = "o4"'), 'existing TOML preserved');
+    assert.ok(codex.includes('[mcp_servers.oioxo]'));
+    // Idempotent: second run must not duplicate the TOML section.
+    await initAgents(root, { all: true, command: 'oioxo-mcp', home });
+    const codex2 = await fs.readFile(path.join(home, '.codex', 'config.toml'), 'utf8');
+    assert.equal(codex2.match(/\[mcp_servers\.oioxo\]/g)?.length, 1);
+    await fs.rm(root, { recursive: true, force: true });
+    await fs.rm(home, { recursive: true, force: true });
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "oioxo-mcp",
+  "version": "0.1.0",
+  "description": "OIOXO context engine for AI coding agents — feeds Claude Code, Copilot, Cursor and any MCP-capable agent the minimal relevant slice of your codebase, on-device, so your tokens go further.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "bin": {
+    "oioxo-mcp": "dist/cli/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aradsoftca/oioxo-mcp.git"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/core.test.js dist/test/e2e.test.js",
+    "serve": "node dist/cli/index.js serve"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "context-engine",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "oioxo",
+    "token-saver"
+  ],
+  "homepage": "https://oioxo.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}