smart-context-mcp 0.8.0

package/src/mcp-server.js

@@ -0,0 +1,3 @@
+import { runDevctxServer } from './server.js';
+
+await runDevctxServer();

package/src/metrics.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { countTokens } from './tokenCounter.js';
+import { devctxRoot, projectRoot } from './utils/paths.js';
+
+const defaultMetricsDir = () => path.join(projectRoot, '.devctx');
+const defaultMetricsFile = () => path.join(defaultMetricsDir(), 'metrics.jsonl');
+const legacyMetricsFile = path.join(devctxRoot, '.devctx', 'metrics.jsonl');
+
+export const getMetricsFilePath = () => process.env.DEVCTX_METRICS_FILE ?? defaultMetricsFile();
+export const getLegacyMetricsFilePath = () => legacyMetricsFile;
+
+let lastEnsuredDir = null;
+
+const ensureMetricsDir = async (filePath) => {
+  const dir = path.dirname(filePath);
+  if (dir === lastEnsuredDir) return;
+  await fs.mkdir(dir, { recursive: true });
+  lastEnsuredDir = dir;
+};
+
+export const buildMetrics = ({ tool, target, rawText, compressedText }) => {
+  const rawTokens = countTokens(rawText);
+  const compressedTokens = countTokens(compressedText);
+  const savedTokens = Math.max(0, rawTokens - compressedTokens);
+  const savingsPct = rawTokens === 0 ? 0 : Number(((savedTokens / rawTokens) * 100).toFixed(2));
+
+  return {
+    tool,
+    target,
+    rawTokens,
+    compressedTokens,
+    savedTokens,
+    savingsPct,
+    timestamp: new Date().toISOString(),
+  };
+};
+
+export const MAX_METRICS_BYTES = 1024 * 1024;
+export const KEEP_LINES_AFTER_ROTATION = 500;
+
+const rotateIfNeeded = async (filePath) => {
+  try {
+    const stat = await fs.stat(filePath);
+    if (stat.size <= MAX_METRICS_BYTES) return;
+
+    const content = await fs.readFile(filePath, 'utf8');
+    const lines = content.trim().split('\n');
+    const kept = lines.slice(-KEEP_LINES_AFTER_ROTATION).join('\n') + '\n';
+    await fs.writeFile(filePath, kept, 'utf8');
+  } catch {
+    // file might not exist yet
+  }
+};
+
+export const persistMetrics = async (entry) => {
+  try {
+    const filePath = getMetricsFilePath();
+    await ensureMetricsDir(filePath);
+    await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, 'utf8');
+    await rotateIfNeeded(filePath);
+  } catch {
+    // best-effort — never fail a tool call for metrics
+  }
+};

package/src/server.js

@@ -0,0 +1,143 @@
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { buildIndex, buildIndexIncremental, persistIndex } from './index.js';
+import { smartRead } from './tools/smart-read.js';
+import { smartSearch } from './tools/smart-search.js';
+import { smartContext } from './tools/smart-context.js';
+import { smartReadBatch } from './tools/smart-read-batch.js';
+import { smartShell } from './tools/smart-shell.js';
+import { projectRoot, projectRootSource } from './utils/paths.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+export const asTextResult = (result) => ({
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify(result, null, 2),
+    },
+  ],
+});
+
+export const createDevctxServer = () => {
+  const server = new McpServer({
+    name: 'devctx',
+    version,
+  });
+
+  server.tool(
+    'smart_read',
+    'Read a file with token-efficient modes. outline/signatures: compact structure (~90% savings). range: specific line range with line numbers. symbol: extract function/class/method by name (string or array for batch). full: file content capped at 12k chars. maxTokens: token budget — auto-selects the most detailed mode that fits (full -> outline -> signatures -> truncated). context=true (symbol mode only): includes callers, tests, and referenced types from the dependency graph; returns graphCoverage (imports/tests: full|partial|none) so the agent knows how reliable the cross-file context is. Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
+    {
+      filePath: z.string(),
+      mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol']).optional(),
+      startLine: z.number().optional(),
+      endLine: z.number().optional(),
+      symbol: z.union([z.string(), z.array(z.string())]).optional(),
+      maxTokens: z.number().int().min(1).optional(),
+      context: z.boolean().optional(),
+    },
+    async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, context }) =>
+      asTextResult(await smartRead({ filePath, mode, startLine, endLine, symbol, maxTokens, context })),
+  );
+
+  server.tool(
+    'smart_read_batch',
+    'Read multiple files in one call. Each item accepts path, mode, symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
+    {
+      files: z.array(z.object({
+        path: z.string(),
+        mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol']).optional(),
+        symbol: z.union([z.string(), z.array(z.string())]).optional(),
+        startLine: z.number().optional(),
+        endLine: z.number().optional(),
+        maxTokens: z.number().int().min(1).optional(),
+      })).min(1).max(20),
+      maxTokens: z.number().int().min(1).optional(),
+    },
+    async ({ files, maxTokens }) =>
+      asTextResult(await smartReadBatch({ files, maxTokens })),
+  );
+
+  server.tool(
+    'smart_search',
+    'Search code across the project using ripgrep (with filesystem fallback). Returns grouped, ranked results. Optional intent (implementation/debug/tests/config/docs/explore) adjusts ranking: tests boosts test files, config boosts config files, docs reduces penalty on READMEs. Includes a unified confidence block: { level, indexFreshness } plus retrievalConfidence and provenance metadata.',
+    {
+      query: z.string(),
+      cwd: z.string().optional(),
+      intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
+    },
+    async ({ query, cwd = '.', intent }) => asTextResult(await smartSearch({ query, cwd, intent })),
+  );
+
+  server.tool(
+    'smart_context',
+    'Get curated context for a task in one call. Combines smart_search + smart_read + graph expansion. Returns relevant files, evidence for why each file was included, related tests, dependencies, symbol previews from the index, and symbol details — optimized for tokens. Includes a unified confidence block: { indexFreshness, graphCoverage } indicating index state and how complete the relational context is. Replaces the manual search → read → read cycle. Optional intent override, token budget, diff mode (pass diff=true for HEAD or diff="main" to scope context to changed files only), detail mode (minimal=index+signatures+snippets, balanced=default, deep=full content), and include array to control which fields are returned (["content","graph","hints","symbolDetail"]).',
+    {
+      task: z.string(),
+      intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
+      maxTokens: z.number().optional(),
+      entryFile: z.string().optional(),
+      diff: z.union([z.boolean(), z.string()]).optional(),
+      detail: z.enum(['minimal', 'balanced', 'deep']).optional(),
+      include: z.array(z.enum(['content', 'graph', 'hints', 'symbolDetail'])).optional(),
+    },
+    async ({ task, intent, maxTokens, entryFile, diff, detail, include }) =>
+      asTextResult(await smartContext({ task, intent, maxTokens, entryFile, diff, detail, include })),
+  );
+
+  server.tool(
+    'smart_shell',
+    'Run a diagnostic shell command from an allowlist. Allowed: pwd, ls, find, rg, git (status/diff/show/log/branch/rev-parse), npm/pnpm/yarn/bun (test/run/lint/build/typecheck/check). Blocks shell operators, pipes, and unsafe commands. Includes a unified confidence block: { blocked, timedOut }.',
+    {
+      command: z.string(),
+    },
+    async ({ command }) => asTextResult(await smartShell({ command })),
+  );
+
+  server.tool(
+    'build_index',
+    'Build a lightweight symbol index for the project. Speeds up smart_search ranking and smart_read symbol lookups. Pass incremental=true to only reindex files with changed mtime (much faster for large repos). Without incremental, rebuilds from scratch.',
+    {
+      incremental: z.boolean().optional(),
+    },
+    async ({ incremental }) => {
+      if (incremental) {
+        const { index, stats } = buildIndexIncremental(projectRoot);
+        await persistIndex(index, projectRoot);
+        const symbolCount = Object.values(index.files).reduce((sum, f) => sum + f.symbols.length, 0);
+        return asTextResult({ status: 'ok', files: stats.total, symbols: symbolCount, ...stats });
+      }
+
+      const index = buildIndex(projectRoot);
+      await persistIndex(index, projectRoot);
+      const fileCount = Object.keys(index.files).length;
+      const symbolCount = Object.values(index.files).reduce((sum, f) => sum + f.symbols.length, 0);
+      return asTextResult({ status: 'ok', files: fileCount, symbols: symbolCount });
+    },
+  );
+
+  return server;
+};
+
+export const runDevctxServer = async () => {
+  if (process.env.DEVCTX_DEBUG === '1') {
+    process.stderr.write(`devctx project root (${projectRootSource}): ${projectRoot}\n`);
+  }
+
+  const server = createDevctxServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  const shutdown = () => {
+    transport.close().catch(() => {}).finally(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return server;
+};

package/src/tokenCounter.js

@@ -0,0 +1,12 @@
+import { encodingForModel } from 'js-tiktoken';
+
+const fallbackModel = 'gpt-4o-mini';
+const encoder = encodingForModel(fallbackModel);
+
+export const countTokens = (text = '') => {
+  if (!text) {
+    return 0;
+  }
+
+  return encoder.encode(String(text)).length;
+};