@suco/su-auggie-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * suco-auggie-mcp CLI
+ * MCP server exposing Augment Code context engine capabilities
+ */
+import { Command } from 'commander';
+import { startServer } from './server.js';
+import { createLogger } from './logger.js';
+import { setDebugMode, setPersistenceEnabled } from './config.js';
+const logger = createLogger('CLI');
+/** Parse workspace paths from CLI argument (supports comma-separated) */
+function parseWorkspacePaths(value, previous) {
+    const paths = value.split(',').map((p) => p.trim()).filter(Boolean);
+    return previous.concat(paths);
+}
+/** Main entry point */
+async function main() {
+    const program = new Command();
+    program
+        .name('suco-auggie-mcp')
+        .description('MCP server exposing Augment Code context engine capabilities')
+        .version('0.1.0')
+        .option('-w, --workspace <path>', 'Add workspace path (can be repeated or comma-separated)', parseWorkspacePaths, [])
+        .option('--ignore-roots', 'Ignore MCP roots and CWD fallback, use only -w workspaces')
+        .option('--debug', 'Enable debug mode (logging capability + debug tool)')
+        .option('-n, --no-persistent', 'Disable index persistence (in-memory only, re-indexes on restart)')
+        .parse();
+    const options = program.opts();
+    // Set debug mode before anything else
+    if (options.debug) {
+        setDebugMode(true);
+        logger.info('Debug mode enabled');
+    }
+    // Set persistence mode (--no-persistent sets persistent to false)
+    if (options.persistent === false) {
+        setPersistenceEnabled(false);
+        logger.info('Persistence disabled (in-memory only)');
+    }
+    // Pass CLI options to server - workspace resolution happens after MCP connect
+    const cliOptions = {
+        workspaces: options.workspace,
+        ignoreRoots: options.ignoreRoots ?? false,
+    };
+    if (cliOptions.workspaces.length > 0) {
+        logger.info(`CLI workspaces: ${cliOptions.workspaces.join(', ')}`);
+    }
+    // Start MCP server (workspace resolution happens after connect)
+    await startServer(cliOptions);
+}
+main().catch((err) => {
+    logger.error('Fatal error', err);
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Debug logger for suco-auggie-mcp
+ */
+/** Logger interface */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Create a logger with optional prefix */
+export declare function createLogger(prefix?: string): Logger;
+/** Default logger instance */
+export declare const logger: Logger;

package/dist/logger.js

@@ -0,0 +1,32 @@
+/**
+ * Debug logger for suco-auggie-mcp
+ */
+import { isDebugMode } from './config.js';
+/** Create a logger with optional prefix */
+export function createLogger(prefix) {
+    const formatMessage = (level, message) => {
+        const timestamp = new Date().toISOString();
+        const prefixStr = prefix ? `[${prefix}] ` : '';
+        return `${timestamp} ${level} ${prefixStr}${message}`;
+    };
+    return {
+        debug(message, ...args) {
+            if (isDebugMode()) {
+                console.error(formatMessage('DEBUG', message), ...args);
+            }
+        },
+        info(message, ...args) {
+            if (isDebugMode()) {
+                console.error(formatMessage('INFO', message), ...args);
+            }
+        },
+        warn(message, ...args) {
+            console.error(formatMessage('WARN', message), ...args);
+        },
+        error(message, ...args) {
+            console.error(formatMessage('ERROR', message), ...args);
+        },
+    };
+}
+/** Default logger instance */
+export const logger = createLogger();

package/dist/mcp-notifications.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MCP notification utilities - send logging messages and notifications to connected client
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Log levels supported by MCP */
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+/** Set the MCP server reference (called during startup) */
+export declare function setMcpServer(server: McpServer): void;
+/** Get the MCP server reference */
+export declare function getMcpServer(): McpServer | null;
+/**
+ * Send a logging message to the connected MCP client.
+ * Safe to call even if server is not connected - will silently fail.
+ */
+export declare function sendLogToClient(level: McpLogLevel, message: string, data?: unknown): Promise<void>;
+/**
+ * Check if client supports elicitation
+ */
+export declare function clientSupportsElicitation(): boolean;
+/** Elicitation schema property types */
+type ElicitPropertyType = {
+    type: 'string';
+    description?: string;
+    title?: string;
+    default?: string;
+} | {
+    type: 'string';
+    enum: string[];
+    description?: string;
+    title?: string;
+    enumNames?: string[];
+    default?: string;
+} | {
+    type: 'boolean';
+    description?: string;
+    title?: string;
+    default?: boolean;
+} | {
+    type: 'number' | 'integer';
+    description?: string;
+    title?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+};
+/** Elicitation request parameters */
+export interface ElicitParams {
+    message: string;
+    requestedSchema: {
+        type: 'object';
+        properties: Record<string, ElicitPropertyType>;
+        required?: string[];
+    };
+}
+/**
+ * Elicit input from user (only if client supports it)
+ */
+export declare function elicitInput(params: ElicitParams): Promise<{
+    action: 'accept' | 'decline' | 'cancel';
+    content?: Record<string, unknown>;
+} | null>;
+export {};

package/dist/mcp-notifications.js

@@ -0,0 +1,54 @@
+/**
+ * MCP notification utilities - send logging messages and notifications to connected client
+ */
+/** Singleton reference to the MCP server */
+let mcpServer = null;
+/** Set the MCP server reference (called during startup) */
+export function setMcpServer(server) {
+    mcpServer = server;
+}
+/** Get the MCP server reference */
+export function getMcpServer() {
+    return mcpServer;
+}
+/**
+ * Send a logging message to the connected MCP client.
+ * Safe to call even if server is not connected - will silently fail.
+ */
+export async function sendLogToClient(level, message, data) {
+    if (!mcpServer)
+        return;
+    try {
+        await mcpServer.server.sendLoggingMessage({
+            level,
+            logger: 'suco-auggie',
+            data: data !== undefined ? { message, ...data } : message,
+        });
+    }
+    catch {
+        // Silently ignore - client might not support logging or be disconnected
+    }
+}
+/**
+ * Check if client supports elicitation
+ */
+export function clientSupportsElicitation() {
+    if (!mcpServer)
+        return false;
+    const caps = mcpServer.server.getClientCapabilities();
+    return caps?.elicitation !== undefined;
+}
+/**
+ * Elicit input from user (only if client supports it)
+ */
+export async function elicitInput(params) {
+    if (!mcpServer || !clientSupportsElicitation())
+        return null;
+    try {
+        const result = await mcpServer.server.elicitInput(params);
+        return result;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Server setup with stdio transport
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CLIOptions } from './index.js';
+/** Create and configure the MCP server */
+export declare function createServer(): McpServer;
+/** Start the MCP server with stdio transport */
+export declare function startServer(options: CLIOptions): Promise<void>;

package/dist/server.js

@@ -0,0 +1,226 @@
+/**
+ * MCP Server setup with stdio transport
+ */
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createLogger } from './logger.js';
+import { isDebugMode } from './config.js';
+import { workspaceManager } from './workspace-manager.js';
+import { hasCredentials, startSessionWatcher, stopSessionWatcher, onAuthChange, } from './auth.js';
+import { setMcpServer, clientSupportsElicitation, elicitInput, sendLogToClient, } from './mcp-notifications.js';
+import { CODEBASE_TOOL_NAME, CODEBASE_TOOL_DESCRIPTION, CODEBASE_PARAMS_SHAPE, handleCodebaseTool, } from './tools/codebase.js';
+import { INDEX_TOOL_NAME, INDEX_TOOL_DESCRIPTION, INDEX_PARAMS_SHAPE, handleIndexTool, } from './tools/index-tool.js';
+import { DEBUG_TOOL_NAME, DEBUG_TOOL_DESCRIPTION, DEBUG_PARAMS_SHAPE, handleDebugTool, } from './tools/debug.js';
+const logger = createLogger('Server');
+/** Create and configure the MCP server */
+export function createServer() {
+    const server = new McpServer({
+        name: 'suco-auggie-mcp',
+        version: '0.1.0',
+    });
+    // Register codebase tool
+    server.tool(CODEBASE_TOOL_NAME, CODEBASE_TOOL_DESCRIPTION, CODEBASE_PARAMS_SHAPE, async (args) => {
+        try {
+            const result = await handleCodebaseTool(args);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`Codebase tool error: ${message}`);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+    // Register index tool
+    server.tool(INDEX_TOOL_NAME, INDEX_TOOL_DESCRIPTION, INDEX_PARAMS_SHAPE, async (args) => {
+        try {
+            const result = await handleIndexTool(args);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`Index tool error: ${message}`);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+    // Register debug tool (only in debug mode)
+    if (isDebugMode()) {
+        logger.info('Registering debug tool (debug mode enabled)');
+        server.tool(DEBUG_TOOL_NAME, DEBUG_TOOL_DESCRIPTION, DEBUG_PARAMS_SHAPE, async (args) => {
+            try {
+                const result = await handleDebugTool(args);
+                return { content: [{ type: 'text', text: result }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.error(`Debug tool error: ${message}`);
+                return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+            }
+        });
+    }
+    return server;
+}
+/** Try to get credentials via elicitation if client supports it */
+async function tryElicitCredentials() {
+    if (!clientSupportsElicitation()) {
+        logger.debug('Client does not support elicitation');
+        return false;
+    }
+    logger.info('Requesting API token via elicitation...');
+    sendLogToClient('info', 'Augment API token required. Please provide your credentials.');
+    const result = await elicitInput({
+        message: 'Augment API token is required for codebase indexing and search.\n\n' +
+            'You can get a token from the Augment dashboard or use an existing one from ~/.auggie/session.json',
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                apiToken: {
+                    type: 'string',
+                    title: 'API Token',
+                    description: 'Your Augment API token',
+                },
+            },
+            required: ['apiToken'],
+        },
+    });
+    if (result?.action === 'accept' && result.content?.apiToken) {
+        const token = result.content.apiToken;
+        process.env.AUGMENT_API_TOKEN = token;
+        logger.info('API token received via elicitation');
+        sendLogToClient('info', 'API token configured successfully');
+        return true;
+    }
+    logger.warn('Elicitation cancelled or declined');
+    return false;
+}
+/**
+ * Check if client supports MCP roots capability
+ */
+function clientSupportsRoots(server) {
+    const caps = server.server.getClientCapabilities();
+    return caps?.roots !== undefined;
+}
+/**
+ * Get roots from MCP client (returns empty array if not supported or fails)
+ */
+async function getMcpRoots(server) {
+    if (!clientSupportsRoots(server)) {
+        logger.debug('Client does not support roots capability');
+        return [];
+    }
+    try {
+        const result = await server.server.listRoots();
+        const roots = [];
+        for (const root of result.roots) {
+            // Root URI is file:// URL, convert to path
+            if (root.uri.startsWith('file://')) {
+                const filePath = fileURLToPath(root.uri);
+                roots.push(filePath);
+                logger.debug(`MCP root: ${root.name ?? root.uri} -> ${filePath}`);
+            }
+            else {
+                logger.warn(`Ignoring non-file root: ${root.uri}`);
+            }
+        }
+        return roots;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`Failed to get MCP roots: ${message}`);
+        return [];
+    }
+}
+/**
+ * Resolve workspaces in priority order:
+ * 1. CLI -w workspaces (always added if provided)
+ * 2. MCP roots OR CWD fallback (if not --ignore-roots)
+ *
+ * Result: -w + (roots OR cwd)
+ * With --ignore-roots: only -w
+ */
+async function resolveWorkspaces(server, options) {
+    // 1. Add CLI workspaces first (always)
+    if (options.workspaces.length > 0) {
+        logger.info(`Adding ${options.workspaces.length} workspace(s) from CLI`);
+        await workspaceManager.addWorkspaces(options.workspaces);
+    }
+    // If --ignore-roots, skip MCP roots and CWD fallback
+    if (options.ignoreRoots) {
+        if (!workspaceManager.hasWorkspaces()) {
+            throw new Error('No workspaces configured. Use -w to specify workspace paths when using --ignore-roots.');
+        }
+        return;
+    }
+    // 2. Try MCP roots, fallback to CWD if empty
+    const mcpRoots = await getMcpRoots(server);
+    if (mcpRoots.length > 0) {
+        logger.info(`Adding ${mcpRoots.length} workspace(s) from MCP roots`);
+        await workspaceManager.addWorkspaces(mcpRoots);
+    }
+    else {
+        // CWD is fallback for roots (regardless of -w)
+        logger.info('No MCP roots available, using current directory as fallback');
+        await workspaceManager.addWorkspace(process.cwd());
+    }
+    if (!workspaceManager.hasWorkspaces()) {
+        throw new Error('No workspaces configured. Use -w to specify workspace paths.');
+    }
+}
+/** Start the MCP server with stdio transport */
+export async function startServer(options) {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    // Make server available for notifications
+    setMcpServer(server);
+    // Register auth change callback to reinitialize errored workspaces
+    onAuthChange(async (hasAuth) => {
+        if (hasAuth) {
+            logger.info('Auth credentials detected, reinitializing errored workspaces');
+            await workspaceManager.reinitializeErrored();
+        }
+        else {
+            logger.warn('Auth credentials removed - operations may fail');
+            sendLogToClient('warning', 'Augment credentials removed. Run `auggie login` to re-authenticate.');
+        }
+    });
+    // Start watching session file for auth changes
+    startSessionWatcher();
+    /** Graceful shutdown per MCP protocol */
+    async function shutdown() {
+        logger.info('Shutting down...');
+        // Stop session watcher
+        stopSessionWatcher();
+        // Close workspaces (saves state, stops watchers)
+        await workspaceManager.close();
+        // Close MCP server/transport per protocol
+        await server.close();
+        process.exit(0);
+    }
+    // Handle shutdown signals
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    logger.info('Starting MCP server...');
+    await server.connect(transport);
+    logger.info('MCP server connected');
+    // Resolve workspaces AFTER connect (MCP roots require connection)
+    try {
+        await resolveWorkspaces(server, options);
+        logger.info(`Configured ${workspaceManager.count} workspace(s)`);
+        sendLogToClient('info', `Indexing ${workspaceManager.count} workspace(s)...`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Workspace resolution failed: ${message}`);
+        sendLogToClient('error', message);
+        // Don't exit - allow user to provide workspaces via other means
+    }
+    // After workspace resolution, check credentials and try elicitation if needed
+    if (!hasCredentials()) {
+        logger.warn('No Augment API token found in environment');
+        sendLogToClient('warning', 'No Augment API token found. Indexing will fail without credentials.');
+        const gotCredentials = await tryElicitCredentials();
+        if (!gotCredentials) {
+            sendLogToClient('error', 'No API token provided. Set AUGMENT_API_TOKEN environment variable or provide via elicitation.');
+        }
+    }
+}

package/dist/tools/codebase.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Codebase tool - semantic search and Q&A over indexed code
+ */
+import { z } from 'zod';
+/** Tool name */
+export declare const CODEBASE_TOOL_NAME = "codebase";
+/** Tool description */
+export declare const CODEBASE_TOOL_DESCRIPTION = "Semantic search and Q&A over indexed code.\n\nModes:\n- search: Find relevant code snippets using natural language\n- ask: Search and get an LLM-generated answer about the code\n\nParameters:\n- mode: \"search\" or \"ask\" (required)\n- query: Natural language search query (required)\n- prompt: Additional prompt for ask mode (optional, defaults to query)\n- root: Workspace root path to search (optional, defaults to first workspace)";
+/** Input schema for zod validation */
+export declare const codebaseInputSchema: z.ZodObject<{
+    mode: z.ZodEnum<["search", "ask"]>;
+    query: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    mode: "search" | "ask";
+    query: string;
+    prompt?: string | undefined;
+    root?: string | undefined;
+}, {
+    mode: "search" | "ask";
+    query: string;
+    prompt?: string | undefined;
+    root?: string | undefined;
+}>;
+/** Zod schema shape for MCP tool registration */
+export declare const CODEBASE_PARAMS_SHAPE: {
+    mode: z.ZodEnum<["search", "ask"]>;
+    query: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
+};
+/** Handle codebase tool call */
+export declare function handleCodebaseTool(input: unknown): Promise<string>;

package/dist/tools/codebase.js

@@ -0,0 +1,83 @@
+/**
+ * Codebase tool - semantic search and Q&A over indexed code
+ */
+import { z } from 'zod';
+import { workspaceManager } from '../workspace-manager.js';
+import { createLogger } from '../logger.js';
+const logger = createLogger('CodebaseTool');
+/** Tool name */
+export const CODEBASE_TOOL_NAME = 'codebase';
+/** Tool description */
+export const CODEBASE_TOOL_DESCRIPTION = `Semantic search and Q&A over indexed code.
+
+Modes:
+- search: Find relevant code snippets using natural language
+- ask: Search and get an LLM-generated answer about the code
+
+Parameters:
+- mode: "search" or "ask" (required)
+- query: Natural language search query (required)
+- prompt: Additional prompt for ask mode (optional, defaults to query)
+- root: Workspace root path to search (optional, defaults to first workspace)`;
+/** Input schema for zod validation */
+export const codebaseInputSchema = z.object({
+    mode: z.enum(['search', 'ask']),
+    query: z.string().min(1),
+    prompt: z.string().optional(),
+    root: z.string().optional(),
+});
+/** Zod schema shape for MCP tool registration */
+export const CODEBASE_PARAMS_SHAPE = {
+    mode: z.enum(['search', 'ask']).describe('Operation mode: search for code or ask a question'),
+    query: z.string().min(1).describe('Natural language search query'),
+    prompt: z.string().optional().describe('Additional prompt for ask mode (optional)'),
+    root: z.string().optional().describe('Workspace root path (optional, defaults to first workspace)'),
+};
+/** Handle codebase tool call */
+export async function handleCodebaseTool(input) {
+    // Validate input
+    const parsed = codebaseInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`Invalid input: ${parsed.error.message}`);
+    }
+    const { mode, query, prompt, root } = parsed.data;
+    // Get workspace
+    const workspace = workspaceManager.resolveWorkspace(root);
+    const status = workspace.getStatus();
+    // Check if workspace is ready
+    if (status.status === 'error') {
+        throw new Error(`Workspace error: ${status.error}`);
+    }
+    if (status.indexed === 0) {
+        if (status.status === 'indexing') {
+            const progress = status.progress;
+            if (progress) {
+                const pct = progress.discovered > 0
+                    ? Math.round((progress.indexed / progress.discovered) * 100)
+                    : 0;
+                const discoveringNote = progress.discovering ? ' (still discovering)' : '';
+                return `Workspace is still indexing: ${progress.indexed}/${progress.discovered} files (${pct}%)${discoveringNote}. Please wait and try again.`;
+            }
+            return 'Workspace is still indexing. Please wait and try again.';
+        }
+        return 'No files indexed yet. The workspace may still be initializing.';
+    }
+    logger.debug(`${mode} query: "${query}" in ${workspace.root}`);
+    let result;
+    if (mode === 'search') {
+        result = await workspace.search(query);
+    }
+    else {
+        result = await workspace.searchAndAsk(query, prompt);
+    }
+    // Add note if indexing is in progress
+    if (status.status === 'indexing' && status.progress) {
+        const pct = status.progress.discovered > 0
+            ? Math.round((status.progress.indexed / status.progress.discovered) * 100)
+            : 0;
+        const discoveringNote = status.progress.discovering ? ', still discovering' : '';
+        const note = `Note: Indexing in progress (${status.progress.indexed}/${status.progress.discovered} files, ${pct}%${discoveringNote}). Results may be incomplete.\n\n`;
+        result = note + result;
+    }
+    return result;
+}

package/dist/tools/debug.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Debug tool - inspect internal server state (only available with --debug)
+ */
+import { z } from 'zod';
+/** Tool name */
+export declare const DEBUG_TOOL_NAME = "debug";
+/** Tool description */
+export declare const DEBUG_TOOL_DESCRIPTION = "Inspect internal server state for troubleshooting.\n\nActions:\n- state: Dump full internal state (contexts, watchers, queues)\n- stats: Index statistics (file counts, sizes, timings)\n- config: Show current configuration values\n- capabilities: Show client MCP capabilities (elicitation, logging, etc.)\n- emit: Test MCP client notifications (logging or elicitation)\n\nParameters:\n- action: Required action to perform\n- root: Workspace root path for workspace-specific info (optional)\n- type: For emit action: \"logging\" or \"elicitation\"\n- message: Message for emit action (optional)";
+/** Input schema for zod validation */
+export declare const debugInputSchema: z.ZodObject<{
+    action: z.ZodEnum<["state", "stats", "config", "capabilities", "emit"]>;
+    root: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["logging", "elicitation"]>>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "config" | "capabilities" | "state" | "stats" | "emit";
+    type?: "elicitation" | "logging" | undefined;
+    message?: string | undefined;
+    root?: string | undefined;
+}, {
+    action: "config" | "capabilities" | "state" | "stats" | "emit";
+    type?: "elicitation" | "logging" | undefined;
+    message?: string | undefined;
+    root?: string | undefined;
+}>;
+/** Zod schema shape for MCP tool registration */
+export declare const DEBUG_PARAMS_SHAPE: {
+    action: z.ZodEnum<["state", "stats", "config", "capabilities", "emit"]>;
+    root: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["logging", "elicitation"]>>;
+    message: z.ZodOptional<z.ZodString>;
+};
+/** Handle debug tool call */
+export declare function handleDebugTool(input: unknown): Promise<string>;