@harivatsa/sirius-mcp-proxy 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @harivatsa/sirius-mcp-proxy
+
+MCP server that connects Claude to the Sirius index server and local repo-agent snippets.
+
+Install from npm with:
+
+```bash
+npm install -g @harivatsa/sirius-mcp-proxy
+```
+
+Point Claude at `sirius-mcp-proxy` after configuring the Sirius index URL, repo-agent URL, and token environment variables described in the root README.
+
+Snippet enrichment is bounded by `SIRIUS_MCP_ENRICH_CONCURRENCY`, which defaults to `16` and caps at `50`, matching the MCP tool `top_k` limit. Normal `top_k <= 16` searches fetch snippets in one wave; larger windows avoid unbounded local file-range fan-out.
+
+`semantic_code_search`, `hybrid_search`, `symbol_search`, `get_call_chain`, and `impact_analysis` compare indexed file hashes with local snippet hashes when `include_code=true`. With `auto_sync_stale=true`, stale snippets trigger one local repo-agent sync and then rerun the lookup.
+
+`get_call_chain` forwards `max_edges`, defaulting to `300`, and includes `edge_summary` when dense graph neighborhoods omit edges. It also forwards `max_unresolved`, defaulting to `200`; set it to `0` for compact graph-only responses when unresolved callees are not needed. `max_code_nodes` defaults to `50`, so large graph and impact-analysis responses keep all node metadata but only enrich the first N nodes with local source snippets.
+
+The package is published publicly on npm as `@harivatsa/sirius-mcp-proxy`.

package/dist/enrich.js

@@ -0,0 +1,168 @@
+import { agentPost } from "./http.js";
+import { isSafeLocalFilePath, LOCAL_FILE_PATH_RULE } from "./validation.js";
+// General rule: snippet enrichment should not fan out unbounded local file reads for large top_k calls.
+const DEFAULT_MCP_ENRICH_CONCURRENCY = 16;
+// General rule: callers may tune enrichment parallelism, but it should remain bounded by MCP tool limits.
+const MAX_MCP_ENRICH_CONCURRENCY = 50;
+// General rule: one snippet batch should fit the largest current MCP graph response without unbounded payloads.
+const MAX_MCP_SNIPPET_BATCH_SIZE = 200;
+// General rule: indexed file paths must be normalized repo-relative slash paths before local file lookup.
+const UNSAFE_SNIPPET_PATH_ERROR = LOCAL_FILE_PATH_RULE;
+// General rule: local snippet reads should be bound to the repo requested by the MCP tool call, not by index payloads.
+const MISMATCHED_SNIPPET_REPO_ERROR = "indexed result repo_id does not match requested repo_id";
+// General rule: local agent snippets must echo the requested repo and file before MCP returns source text.
+const MISMATCHED_LOCAL_SNIPPET_ERROR = "local snippet response does not match requested repo_id or file_path";
+export async function enrichSearchResults(repoId, results, includeCode) {
+    return enrichWithSnippets(results, includeCode, (result) => ({
+        repoId,
+        indexedRepoId: result.repo_id,
+        filePath: result.file_path,
+        startLine: result.start_line,
+        endLine: result.end_line,
+        expectedFileHash: result.file_hash
+    }));
+}
+export async function enrichSymbols(repoId, results, includeCode) {
+    return enrichWithSnippets(results, includeCode, (result) => ({
+        repoId,
+        indexedRepoId: result.repo_id,
+        filePath: result.file_path,
+        startLine: result.start_line,
+        endLine: result.end_line,
+        expectedFileHash: result.file_hash ?? undefined
+    }));
+}
+export async function enrichGraphNodes(repoId, nodes, includeCode, maxSnippetNodes = nodes.length) {
+    const snippetNodeCount = boundedItemCount(maxSnippetNodes, nodes.length);
+    const nodesWithSnippets = await enrichWithSnippets(nodes.slice(0, snippetNodeCount), includeCode, (node) => ({
+        repoId,
+        indexedRepoId: node.repo_id,
+        filePath: node.file_path,
+        startLine: node.start_line,
+        endLine: node.end_line,
+        expectedFileHash: node.file_hash ?? undefined
+    }));
+    return [...nodesWithSnippets, ...nodes.slice(snippetNodeCount)];
+}
+async function enrichWithSnippets(items, includeCode, lookupFor) {
+    if (!includeCode) {
+        return items;
+    }
+    const lookups = items.map(lookupFor);
+    const snippets = await getSnippetLookups(lookups);
+    return items.map((item, index) => {
+        const snippet = snippets[index]?.snippet;
+        if (snippet) {
+            return { ...item, snippet };
+        }
+        return { ...item, snippet_error: snippets[index]?.error ?? "local snippet lookup failed" };
+    });
+}
+async function getSnippetLookups(lookups) {
+    const results = new Array(lookups.length);
+    const safeIndexes = [];
+    lookups.forEach((lookup, index) => {
+        if (lookup.indexedRepoId !== undefined && lookup.indexedRepoId !== lookup.repoId) {
+            results[index] = { error: MISMATCHED_SNIPPET_REPO_ERROR };
+        }
+        else if (isSafeLocalFilePath(lookup.filePath)) {
+            safeIndexes.push(index);
+        }
+        else {
+            results[index] = { error: UNSAFE_SNIPPET_PATH_ERROR };
+        }
+    });
+    const batches = snippetBatches(lookups, safeIndexes);
+    await mapWithConcurrency(batches, mcpEnrichConcurrency(), async (batch) => {
+        try {
+            const response = await agentPost(`/repos/${encodeURIComponent(batch.repoId)}/file-ranges`, {
+                ranges: batch.indexes.map((index) => ({
+                    file_path: lookups[index].filePath,
+                    start_line: lookups[index].startLine,
+                    end_line: lookups[index].endLine
+                }))
+            });
+            if (!Array.isArray(response.results) || response.results.length !== batch.indexes.length) {
+                throw new Error("local repo agent returned an invalid file-ranges response");
+            }
+            if (response.repo_id !== batch.repoId) {
+                throw new Error(MISMATCHED_LOCAL_SNIPPET_ERROR);
+            }
+            response.results.forEach((item, offset) => {
+                const index = batch.indexes[offset];
+                const lookup = lookups[index];
+                if (item.ok) {
+                    if (item.range.repo_id !== batch.repoId || item.range.file_path !== lookup.filePath || !isSafeLocalFilePath(item.range.file_path)) {
+                        results[index] = { error: MISMATCHED_LOCAL_SNIPPET_ERROR };
+                        return;
+                    }
+                    results[index] = {
+                        snippet: {
+                            ...item.range,
+                            expected_file_hash: lookup.expectedFileHash,
+                            stale: lookup.expectedFileHash === undefined ? false : item.range.file_hash !== lookup.expectedFileHash
+                        }
+                    };
+                }
+                else {
+                    results[index] = { error: item.error ?? "local snippet lookup failed" };
+                }
+            });
+        }
+        catch (error) {
+            for (const index of batch.indexes) {
+                results[index] = { error: error.message };
+            }
+        }
+    });
+    return results;
+}
+function snippetBatches(lookups, lookupIndexes) {
+    const grouped = new Map();
+    lookupIndexes.forEach((index) => {
+        const lookup = lookups[index];
+        const indexes = grouped.get(lookup.repoId);
+        if (indexes) {
+            indexes.push(index);
+        }
+        else {
+            grouped.set(lookup.repoId, [index]);
+        }
+    });
+    const batches = [];
+    for (const [repoId, indexes] of grouped) {
+        for (let start = 0; start < indexes.length; start += MAX_MCP_SNIPPET_BATCH_SIZE) {
+            batches.push({ repoId, indexes: indexes.slice(start, start + MAX_MCP_SNIPPET_BATCH_SIZE) });
+        }
+    }
+    return batches;
+}
+export function mcpEnrichConcurrency() {
+    const configured = Number(process.env.SIRIUS_MCP_ENRICH_CONCURRENCY ?? String(DEFAULT_MCP_ENRICH_CONCURRENCY));
+    if (!Number.isFinite(configured) || configured < 1) {
+        return DEFAULT_MCP_ENRICH_CONCURRENCY;
+    }
+    return Math.min(Math.floor(configured), MAX_MCP_ENRICH_CONCURRENCY);
+}
+function boundedItemCount(value, max) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return 0;
+    }
+    return Math.min(Math.floor(value), max);
+}
+async function mapWithConcurrency(items, concurrency, mapper) {
+    if (items.length === 0) {
+        return [];
+    }
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await mapper(items[index], index);
+        }
+    }));
+    return results;
+}

package/dist/http.js

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+export const INDEX_URL = trimSlash(process.env.SIRIUS_INDEX_URL ?? "http://127.0.0.1:8000");
+export const AGENT_URL = trimSlash(process.env.SIRIUS_AGENT_URL ?? "http://127.0.0.1:3987");
+// General rule: MCP tool calls should fail fast enough for callers to recover from stalled index/agent HTTP paths.
+const DEFAULT_MCP_HTTP_TIMEOUT_MS = 30_000;
+// General rule: timeout overrides should remain bounded so a wedged dependency cannot pin the MCP process forever.
+const MAX_MCP_HTTP_TIMEOUT_MS = 300_000;
+// General rule: upstream error bodies may echo request credentials, so MCP-visible HTTP errors must redact them.
+const API_TOKEN_REDACTION_TEXT = "[redacted-token]";
+// General rule: local repo-agent calls should carry a non-CORS-simple header that browser forms/images cannot send.
+const AGENT_CLIENT_HEADER = "x-sirius-agent-client";
+const AGENT_CLIENT_HEADER_VALUE = "sirius";
+export async function indexGet(route) {
+    return requestJson(`${INDEX_URL}${route}`, { token: await resolveIndexApiToken() });
+}
+export async function indexPost(route, body) {
+    return requestJson(`${INDEX_URL}${route}`, {
+        method: "POST",
+        token: await resolveIndexApiToken(),
+        body
+    });
+}
+export async function indexDelete(route) {
+    return requestJson(`${INDEX_URL}${route}`, {
+        method: "DELETE",
+        token: await resolveIndexApiToken()
+    });
+}
+export async function agentGet(route) {
+    return requestJson(`${AGENT_URL}${route}`, { agentClient: true });
+}
+export async function agentPost(route, body) {
+    return requestJson(`${AGENT_URL}${route}`, {
+        method: "POST",
+        body,
+        agentClient: true
+    });
+}
+async function requestJson(url, options = {}) {
+    const headers = {};
+    let body;
+    if (options.body !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(options.body);
+    }
+    if (options.token) {
+        headers.authorization = `Bearer ${options.token}`;
+    }
+    if (options.agentClient) {
+        headers[AGENT_CLIENT_HEADER] = AGENT_CLIENT_HEADER_VALUE;
+    }
+    const timeoutMs = mcpHttpTimeoutMs();
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: options.method ?? "GET",
+            headers,
+            body,
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            const statusText = redactApiToken(response.statusText, options.token);
+            const text = redactApiToken(await response.text(), options.token);
+            throw new Error(`${response.status} ${statusText}: ${text}`);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        if (timedOut) {
+            throw new Error(`Sirius MCP HTTP request timed out after ${timeoutMs} ms: ${url}`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function redactApiToken(text, token) {
+    const trimmed = token?.trim();
+    if (!trimmed) {
+        return text;
+    }
+    return text
+        .split(`Bearer ${trimmed}`)
+        .join(`Bearer ${API_TOKEN_REDACTION_TEXT}`)
+        .split(trimmed)
+        .join(API_TOKEN_REDACTION_TEXT);
+}
+export async function resolveIndexApiToken() {
+    const configuredToken = firstNonEmpty(process.env.SIRIUS_API_TOKEN);
+    if (configuredToken) {
+        return configuredToken;
+    }
+    const configuredTokenFile = firstNonEmpty(process.env.SIRIUS_API_TOKEN_FILE);
+    if (!configuredTokenFile) {
+        return undefined;
+    }
+    return readApiTokenFile(configuredTokenFile);
+}
+async function readApiTokenFile(tokenFile) {
+    let raw;
+    try {
+        raw = await fs.readFile(tokenFile, "utf8");
+    }
+    catch {
+        throw new Error("Sirius API token file from SIRIUS_API_TOKEN_FILE is not readable");
+    }
+    const token = raw.trim();
+    if (!token) {
+        throw new Error("Sirius API token file from SIRIUS_API_TOKEN_FILE is empty");
+    }
+    return token;
+}
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed) {
+            return trimmed;
+        }
+    }
+    return undefined;
+}
+function mcpHttpTimeoutMs() {
+    const configured = Number(firstNonEmpty(process.env.SIRIUS_MCP_HTTP_TIMEOUT_MS, process.env.SIRIUS_API_TIMEOUT_MS) ??
+        String(DEFAULT_MCP_HTTP_TIMEOUT_MS));
+    if (!Number.isFinite(configured) || configured < 1) {
+        return DEFAULT_MCP_HTTP_TIMEOUT_MS;
+    }
+    return Math.min(Math.floor(configured), MAX_MCP_HTTP_TIMEOUT_MS);
+}
+function trimSlash(value) {
+    return value.replace(/\/+$/, "");
+}

package/dist/impact.js

@@ -0,0 +1,76 @@
+import { enrichGraphNodes, enrichSymbols } from "./enrich.js";
+import { agentPost, indexPost } from "./http.js";
+import { hasStaleSnippet } from "./search.js";
+export async function impactAnalysisWithOptionalStaleSync(options, dependencies = {}) {
+    const load = dependencies.load ??
+        (() => indexPost("/v1/analysis/impact", {
+            repo_id: options.repoId,
+            symbol: options.symbol,
+            depth: options.depth
+        }));
+    const sync = dependencies.sync ?? (() => agentPost(`/repos/${encodeURIComponent(options.repoId)}/sync`, { full: false }));
+    const enrich = (response) => enrichImpactResponse(response, options, dependencies);
+    const initial = await load();
+    const initialEnriched = await enrich(initial);
+    if (!options.includeCode || !options.autoSyncStale || !impactHasStaleSnippet(initialEnriched)) {
+        return initialEnriched;
+    }
+    try {
+        const syncResult = await sync();
+        const refreshed = await load();
+        return {
+            ...(await enrich(refreshed)),
+            sync_result: syncResult
+        };
+    }
+    catch (error) {
+        return {
+            ...initialEnriched,
+            sync_error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+async function enrichImpactResponse(response, options, dependencies) {
+    const enrichSymbol = dependencies.enrichSymbol ?? defaultEnrichSymbol;
+    const enrichNodes = dependencies.enrichNodes ?? enrichGraphNodes;
+    const callerNodes = [...response.direct_callers, ...response.indirect_callers];
+    const [symbol, enrichedCallers] = await Promise.all([
+        enrichSymbol(options.repoId, response.symbol, options.includeCode),
+        enrichNodes(options.repoId, callerNodes, options.includeCode, options.maxCodeNodes)
+    ]);
+    const directCount = response.direct_callers.length;
+    return {
+        ...response,
+        symbol,
+        direct_callers: enrichedCallers.slice(0, directCount),
+        indirect_callers: enrichedCallers.slice(directCount),
+        code_enrichment: impactCodeEnrichmentSummary(response, options)
+    };
+}
+async function defaultEnrichSymbol(repoId, symbol, includeCode) {
+    if (!symbol) {
+        return null;
+    }
+    const [enriched] = await enrichSymbols(repoId, [symbol], includeCode);
+    return enriched;
+}
+function impactHasStaleSnippet(response) {
+    const snippetAware = [
+        ...(response.symbol ? [response.symbol] : []),
+        ...response.direct_callers,
+        ...response.indirect_callers
+    ];
+    return hasStaleSnippet(snippetAware);
+}
+function impactCodeEnrichmentSummary(response, options) {
+    const maxCodeNodes = options.includeCode ? options.maxCodeNodes : 0;
+    const callerCount = response.direct_callers.length + response.indirect_callers.length;
+    const selectedCallers = Math.min(callerCount, maxCodeNodes);
+    const selectedRoot = response.symbol && options.includeCode ? 1 : 0;
+    return {
+        enabled: options.includeCode,
+        max_code_nodes: maxCodeNodes,
+        enriched_nodes: selectedRoot + selectedCallers,
+        omitted_nodes: Math.max(0, callerCount - selectedCallers)
+    };
+}

package/dist/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { enrichGraphNodes, enrichSearchResults, enrichSymbols } from "./enrich.js";
+import { agentGet, agentPost, indexDelete, indexGet, indexPost } from "./http.js";
+import { impactAnalysisWithOptionalStaleSync } from "./impact.js";
+import { hasStaleSnippet, searchWithOptionalStaleSync } from "./search.js";
+import { localFilePathSchema, publicRepoIdSchema } from "./validation.js";
+// General rule: package-installed CLIs need a no-session self-check path for install validation.
+const MCP_PROXY_VERSION = "0.1.0";
+// General rule: expanded call graphs can include many nodes, while source snippets dominate MCP payload size.
+const DEFAULT_CALL_CHAIN_CODE_NODE_LIMIT = 50;
+// General rule: graph snippet enrichment should stay bounded by the largest accepted call-chain graph window.
+const MAX_CALL_CHAIN_CODE_NODE_LIMIT = 200;
+// General rule: expanded call graphs should preserve a readable edge window without sending dense graph noise by default.
+const DEFAULT_CALL_CHAIN_EDGE_LIMIT = 300;
+// General rule: callers may inspect dense graph neighborhoods, but edge output should remain explicitly bounded.
+const MAX_CALL_CHAIN_EDGE_LIMIT = 2000;
+if (printCliMetadata(process.argv.slice(2))) {
+    process.exit(0);
+}
+const server = new McpServer({
+    name: "sirius-mcp",
+    version: MCP_PROXY_VERSION
+});
+server.registerTool("semantic_code_search", {
+    title: "Semantic Code Search",
+    description: "Find relevant code by meaning using the Sirius index, optionally returning local snippets.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        query: z.string().min(1),
+        top_k: z.number().int().min(1).max(50).default(10),
+        include_code: z.boolean().default(true),
+        auto_sync_stale: z.boolean().default(true)
+    }
+}, async ({ repo_id, query, top_k, include_code, auto_sync_stale }) => {
+    return asJson(await searchWithOptionalStaleSync({
+        includeCode: include_code,
+        autoSyncStale: auto_sync_stale,
+        search: () => indexPost("/v1/search/semantic", {
+            repo_id,
+            query,
+            top_k,
+            include_symbols: true
+        }),
+        enrich: (results, includeCode) => enrichSearchResults(repo_id, results, includeCode),
+        sync: () => agentPost(`/repos/${encodeURIComponent(repo_id)}/sync`, { full: false })
+    }));
+});
+server.registerTool("hybrid_search", {
+    title: "Hybrid Search",
+    description: "Combine semantic, symbol, and file-path relevance using the Sirius index, optionally returning local snippets.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        query: z.string().min(1),
+        top_k: z.number().int().min(1).max(50).default(10),
+        include_code: z.boolean().default(true),
+        auto_sync_stale: z.boolean().default(true)
+    }
+}, async ({ repo_id, query, top_k, include_code, auto_sync_stale }) => {
+    return asJson(await searchWithOptionalStaleSync({
+        includeCode: include_code,
+        autoSyncStale: auto_sync_stale,
+        search: () => indexPost("/v1/search/hybrid", {
+            repo_id,
+            query,
+            top_k,
+            include_graph_context: true
+        }),
+        enrich: (results, includeCode) => enrichSearchResults(repo_id, results, includeCode),
+        sync: () => agentPost(`/repos/${encodeURIComponent(repo_id)}/sync`, { full: false })
+    }));
+});
+server.registerTool("path_search", {
+    title: "Path Search",
+    description: "Find indexed files by path relevance.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        query: z.string().min(1),
+        top_k: z.number().int().min(1).max(100).default(10)
+    }
+}, async ({ repo_id, query, top_k }) => {
+    const response = await indexPost("/v1/search/path", { repo_id, query, top_k });
+    return asJson(response);
+});
+server.registerTool("symbol_search", {
+    title: "Symbol Search",
+    description: "Find functions, classes, types, methods, and modules by exact or fuzzy name.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        symbol: z.string().min(1),
+        kind: z.string().optional(),
+        top_k: z.number().int().min(1).max(50).default(10),
+        include_code: z.boolean().default(true),
+        auto_sync_stale: z.boolean().default(true)
+    }
+}, async ({ repo_id, symbol, kind, top_k, include_code, auto_sync_stale }) => {
+    return asJson(await searchWithOptionalStaleSync({
+        includeCode: include_code,
+        autoSyncStale: auto_sync_stale,
+        search: () => indexPost("/v1/search/symbol", {
+            repo_id,
+            symbol,
+            kind,
+            top_k
+        }),
+        enrich: (results, includeCode) => enrichSymbols(repo_id, results, includeCode),
+        sync: () => agentPost(`/repos/${encodeURIComponent(repo_id)}/sync`, { full: false })
+    }));
+});
+server.registerTool("get_file_range", {
+    title: "Get File Range",
+    description: "Fetch exact source lines from the local repo agent.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        file_path: localFilePathSchema,
+        start_line: z.number().int().min(1),
+        end_line: z.number().int().min(1)
+    }
+}, async ({ repo_id, file_path, start_line, end_line }) => {
+    const params = new URLSearchParams({
+        file_path,
+        start_line: String(start_line),
+        end_line: String(end_line)
+    });
+    const response = await agentGet(`/repos/${encodeURIComponent(repo_id)}/file-range?${params.toString()}`);
+    return asJson(response);
+});
+server.registerTool("get_call_chain", {
+    title: "Get Call Chain",
+    description: "Traverse caller/callee relationships for a symbol.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        symbol_id: z.string().optional(),
+        symbol: z.string().optional(),
+        direction: z.enum(["callers", "callees", "both"]).default("callers"),
+        depth: z.number().int().min(1).max(8).default(3),
+        max_nodes: z.number().int().min(1).max(200).default(50),
+        max_edges: z.number().int().min(0).max(MAX_CALL_CHAIN_EDGE_LIMIT).default(DEFAULT_CALL_CHAIN_EDGE_LIMIT),
+        max_unresolved: z.number().int().min(0).max(1000).default(200),
+        max_code_nodes: z.number().int().min(0).max(MAX_CALL_CHAIN_CODE_NODE_LIMIT).default(DEFAULT_CALL_CHAIN_CODE_NODE_LIMIT),
+        include_code: z.boolean().default(true),
+        auto_sync_stale: z.boolean().default(true)
+    }
+}, async ({ repo_id, symbol_id, symbol, direction, depth, max_nodes, max_edges, max_unresolved, max_code_nodes, include_code, auto_sync_stale }) => {
+    return asJson(await callChainWithOptionalStaleSync({
+        repoId: repo_id,
+        symbolId: symbol_id,
+        symbol,
+        direction,
+        depth,
+        maxNodes: max_nodes,
+        maxEdges: max_edges,
+        maxUnresolved: max_unresolved,
+        maxCodeNodes: max_code_nodes,
+        includeCode: include_code,
+        autoSyncStale: auto_sync_stale
+    }));
+});
+server.registerTool("impact_analysis", {
+    title: "Impact Analysis",
+    description: "Estimate blast radius for a symbol by traversing callers and related files.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        symbol: z.string().min(1),
+        depth: z.number().int().min(1).max(8).default(3),
+        max_code_nodes: z.number().int().min(0).max(MAX_CALL_CHAIN_CODE_NODE_LIMIT).default(DEFAULT_CALL_CHAIN_CODE_NODE_LIMIT),
+        include_code: z.boolean().default(true),
+        auto_sync_stale: z.boolean().default(true)
+    }
+}, async ({ repo_id, symbol, depth, max_code_nodes, include_code, auto_sync_stale }) => {
+    return asJson(await impactAnalysisWithOptionalStaleSync({
+        repoId: repo_id,
+        symbol,
+        depth,
+        maxCodeNodes: max_code_nodes,
+        includeCode: include_code,
+        autoSyncStale: auto_sync_stale
+    }));
+});
+server.registerTool("ripgrep_search", {
+    title: "Ripgrep Search",
+    description: "Run exact text search locally inside a registered repo.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        pattern: z.string().min(1),
+        glob: z.string().optional(),
+        max_results: z.number().int().min(1).max(200).default(50)
+    }
+}, async ({ repo_id, pattern, glob, max_results }) => {
+    const response = await agentPost(`/repos/${encodeURIComponent(repo_id)}/ripgrep`, {
+        pattern,
+        glob,
+        max_results
+    });
+    return asJson(response);
+});
+server.registerTool("sync_repo", {
+    title: "Sync Repo",
+    description: "Trigger a manual incremental or full sync through the local repo agent.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema,
+        full: z.boolean().default(false)
+    }
+}, async ({ repo_id, full }) => {
+    const response = await agentPost(`/repos/${encodeURIComponent(repo_id)}/sync`, { full });
+    return asJson(response);
+});
+server.registerTool("sync_status", {
+    title: "Sync Status",
+    description: "Return local repo-agent status and server index status.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema
+    }
+}, async ({ repo_id }) => {
+    const [serverStatus, agentStatus] = await Promise.allSettled([
+        indexGet(`/v1/repos/${encodeURIComponent(repo_id)}/status`),
+        agentGet(`/repos/${encodeURIComponent(repo_id)}/status`)
+    ]);
+    return asJson({
+        server: settledValue(serverStatus),
+        agent: settledValue(agentStatus)
+    });
+});
+server.registerTool("delete_repo_index", {
+    title: "Delete Repo Index",
+    description: "Purge derived index data for a repo from the index server.",
+    inputSchema: {
+        repo_id: publicRepoIdSchema
+    }
+}, async ({ repo_id }) => {
+    const response = await indexDelete(`/v1/repos/${encodeURIComponent(repo_id)}`);
+    return asJson(response);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+function asJson(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2)
+            }
+        ]
+    };
+}
+function settledValue(result) {
+    if (result.status === "fulfilled") {
+        return result.value;
+    }
+    return { error: result.reason instanceof Error ? result.reason.message : String(result.reason) };
+}
+async function callChainWithOptionalStaleSync(options) {
+    const load = () => indexPost("/v1/graph/call-chain", {
+        repo_id: options.repoId,
+        symbol_id: options.symbolId,
+        symbol: options.symbol,
+        direction: options.direction,
+        depth: options.depth,
+        max_nodes: options.maxNodes,
+        max_edges: options.maxEdges,
+        max_unresolved: options.maxUnresolved
+    });
+    const initial = await load();
+    const initialNodes = await enrichGraphNodes(options.repoId, initial.nodes, options.includeCode, options.maxCodeNodes);
+    if (!options.includeCode || !options.autoSyncStale || !hasStaleSnippet(initialNodes)) {
+        return { ...initial, nodes: initialNodes, code_enrichment: codeEnrichmentSummary(initial.nodes.length, options) };
+    }
+    try {
+        const syncResult = await agentPost(`/repos/${encodeURIComponent(options.repoId)}/sync`, { full: false });
+        const refreshed = await load();
+        return {
+            ...refreshed,
+            nodes: await enrichGraphNodes(options.repoId, refreshed.nodes, options.includeCode, options.maxCodeNodes),
+            code_enrichment: codeEnrichmentSummary(refreshed.nodes.length, options),
+            sync_result: syncResult
+        };
+    }
+    catch (error) {
+        return {
+            ...initial,
+            nodes: initialNodes,
+            code_enrichment: codeEnrichmentSummary(initial.nodes.length, options),
+            sync_error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function codeEnrichmentSummary(nodeCount, options) {
+    const maxCodeNodes = options.includeCode ? options.maxCodeNodes : 0;
+    const enrichedNodes = Math.min(nodeCount, maxCodeNodes);
+    return {
+        enabled: options.includeCode,
+        max_code_nodes: maxCodeNodes,
+        enriched_nodes: enrichedNodes,
+        omitted_nodes: Math.max(0, nodeCount - enrichedNodes)
+    };
+}
+function printCliMetadata(args) {
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(MCP_PROXY_VERSION);
+        return true;
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log([
+            "Usage: sirius-mcp-proxy [--version] [--help]",
+            "",
+            "Runs the Sirius MCP stdio proxy.",
+            "Configure SIRIUS_INDEX_URL, SIRIUS_AGENT_URL, and SIRIUS_API_TOKEN_FILE as needed."
+        ].join("\n"));
+        return true;
+    }
+    return false;
+}

package/dist/search.js

@@ -0,0 +1,24 @@
+export async function searchWithOptionalStaleSync(options) {
+    const initial = await options.search();
+    const initialResults = await options.enrich(initial.results, options.includeCode);
+    if (!options.includeCode || !options.autoSyncStale || !hasStaleSnippet(initialResults)) {
+        return { results: initialResults };
+    }
+    try {
+        const syncResult = await options.sync();
+        const refreshed = await options.search();
+        return {
+            results: await options.enrich(refreshed.results, options.includeCode),
+            sync_result: syncResult
+        };
+    }
+    catch (error) {
+        return {
+            results: initialResults,
+            sync_error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export function hasStaleSnippet(results) {
+    return results.some((result) => result.snippet?.stale === true);
+}

package/dist/types.js

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

package/dist/validation.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+// General rule: public repo ids must not collide with scoped storage keys or path routing.
+const PUBLIC_REPO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+// General rule: local file reads must use normalized repo-relative slash paths.
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:/;
+export const PUBLIC_REPO_ID_RULE = "use 1-128 ASCII letters, digits, dots, underscores, or hyphens, starting with a letter or digit";
+export const LOCAL_FILE_PATH_RULE = "file_path must be a relative path inside the repo";
+export const publicRepoIdSchema = z.string().regex(PUBLIC_REPO_ID_PATTERN, PUBLIC_REPO_ID_RULE);
+export const localFilePathSchema = z.string().refine(isSafeLocalFilePath, LOCAL_FILE_PATH_RULE);
+export function isSafeLocalFilePath(filePath) {
+    if (!filePath ||
+        filePath.includes("\0") ||
+        filePath.includes("\\") ||
+        filePath.startsWith("/") ||
+        WINDOWS_DRIVE_PATH_PATTERN.test(filePath)) {
+        return false;
+    }
+    return filePath.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@harivatsa/sirius-mcp-proxy",
+  "version": "0.1.0",
+  "description": "MCP proxy that joins Sirius index metadata with local source snippets.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "keywords": [
+    "sirius",
+    "mcp",
+    "code-search",
+    "claude"
+  ],
+  "bin": {
+    "sirius-mcp-proxy": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.test.json --noEmit && node --import tsx --test \"test/*.test.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}