ai-prompt-guide-mcp 1.0.0

package/dist/server/server-factory.js

@@ -0,0 +1,135 @@
+/**
+ * Server factory for creating and configuring MCP server with dependency inversion
+ */
+import { formatLogError } from '../utils/error-formatter.js';
+import { mergeDependencies } from './default-dependencies.js';
+/**
+ * Create and configure MCP server with dependency injection
+ *
+ * This factory function creates a fully configured MCP server using the
+ * dependency inversion principle. All external dependencies can be injected
+ * for testing or customization, while maintaining backward compatibility
+ * through default implementations.
+ *
+ * @param options Configuration options and dependency overrides
+ * @returns Promise resolving to configured server with control methods
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (backward compatible)
+ * const serverResult = await createMCPServer();
+ * await serverResult.start();
+ *
+ * // With custom dependencies for testing
+ * const serverResult = await createMCPServer({
+ *   dependencies: {
+ *     config: mockConfigProvider,
+ *     logger: mockLoggerProvider
+ *   }
+ * });
+ * ```
+ */
+export async function createMCPServer(options = {}) {
+    // Merge custom dependencies with defaults
+    const dependencies = mergeDependencies(options.dependencies);
+    // Load configuration through dependency
+    const serverConfig = dependencies.config.loadConfig();
+    // Initialize logger through dependency
+    const logger = dependencies.logger.createLogger(serverConfig);
+    dependencies.logger.setGlobalLogger(logger);
+    logger.info('Starting Spec-Docs MCP Server', {
+        name: serverConfig.serverName,
+        version: serverConfig.serverVersion,
+        docsPath: serverConfig.workspaceBasePath,
+        logLevel: serverConfig.logLevel,
+    });
+    // Ensure docs directory exists through dependency
+    await dependencies.fileSystem.ensureDirectoryExists(serverConfig.workspaceBasePath);
+    logger.debug('Docs directory ready', { path: serverConfig.workspaceBasePath });
+    // Load workflow prompts from filesystem
+    const { loadWorkflowPrompts } = await import('../prompts/workflow-prompts.js');
+    const prompts = await loadWorkflowPrompts();
+    logger.debug('Workflow prompts loaded', { count: prompts.length });
+    // Create server instance through dependency
+    const server = dependencies.server.createServer(serverConfig.serverName, serverConfig.serverVersion);
+    // Create session store through dependency
+    const sessionStore = dependencies.session.getSessionStore();
+    // Register all handlers through dependency
+    dependencies.handlers.registerToolHandlers(server, sessionStore, serverConfig);
+    // Create transport through dependency
+    const transport = dependencies.server.createTransport();
+    // Handle graceful shutdown
+    const shutdown = async () => {
+        logger.info('Shutting down server...');
+        try {
+            await server.close();
+            logger.info('Server shutdown complete');
+        }
+        catch (error) {
+            logger.error('Error during shutdown', { error });
+        }
+        process.exit(0);
+    };
+    // Configure process signal handling if enabled
+    const handleProcessSignals = options.handleProcessSignals ?? true;
+    if (handleProcessSignals) {
+        process.on('SIGINT', () => { void shutdown(); });
+        process.on('SIGTERM', () => { void shutdown(); });
+    }
+    // Configure unhandled error handling if enabled
+    const handleUnhandledErrors = options.handleUnhandledErrors ?? true;
+    if (handleUnhandledErrors) {
+        process.on('unhandledRejection', (reason, promise) => {
+            logger.error('Unhandled promise rejection', { reason, promise });
+            process.exit(1);
+        });
+        process.on('uncaughtException', (error) => {
+            logger.error('Uncaught exception', { error });
+            process.exit(1);
+        });
+    }
+    logger.info('Server initialization complete');
+    // Create server result with all dependencies injected
+    const serverResult = {
+        server,
+        transport,
+        config: serverConfig,
+        logger,
+        start: async () => {
+            try {
+                logger.info('Connecting to MCP transport...');
+                await server.connect(transport);
+                logger.info('MCP server connected and running');
+            }
+            catch (error) {
+                const { message, context } = formatLogError(error, 'server_startup');
+                logger.error(message, context);
+                process.exit(1);
+            }
+        },
+        close: async () => {
+            await shutdown();
+        },
+    };
+    return serverResult;
+}
+/**
+ * Backward compatibility wrapper for the original createMCPServer API
+ *
+ * This function maintains the exact same interface as the original implementation
+ * while using the new dependency injection system internally. This ensures that
+ * existing code continues to work without any changes.
+ *
+ * @returns Promise resolving to server components for backward compatibility
+ * @deprecated Use createMCPServer() directly for better type safety and additional features
+ */
+export async function createMCPServerLegacy() {
+    const result = await createMCPServer();
+    return {
+        server: result.server,
+        transport: result.transport,
+        start: result.start,
+        close: result.close,
+    };
+}
+//# sourceMappingURL=server-factory.js.map

package/dist/server/server-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-factory.js","sourceRoot":"","sources":["../../src/server/server-factory.ts"],"names":[],"mappings":"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"}

package/dist/server/transport/stdio-transport.d.ts

@@ -0,0 +1,9 @@
+/**
+ * STDIO transport configuration
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/**
+ * Create and configure STDIO transport
+ */
+export declare function createStdioTransport(): StdioServerTransport;
+//# sourceMappingURL=stdio-transport.d.ts.map

package/dist/server/transport/stdio-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-transport.d.ts","sourceRoot":"","sources":["../../../src/server/transport/stdio-transport.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CAE3D"}

package/dist/server/transport/stdio-transport.js

@@ -0,0 +1,11 @@
+/**
+ * STDIO transport configuration
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/**
+ * Create and configure STDIO transport
+ */
+export function createStdioTransport() {
+    return new StdioServerTransport();
+}
+//# sourceMappingURL=stdio-transport.js.map

package/dist/server/transport/stdio-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-transport.js","sourceRoot":"","sources":["../../../src/server/transport/stdio-transport.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,oBAAoB,EAAE,CAAC;AACpC,CAAC"}

package/dist/session/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Session management module exports
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/session/index.js

@@ -0,0 +1,7 @@
+/**
+ * Session management module exports
+ */
+export {};
+// Note: All session imports are done directly from specific files
+// No re-exports needed as they are not used via this index
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;GAEG;;AAEH,kEAAkE;AAClE,2DAA2D"}

package/dist/session/session-store.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Session state management for MCP connections
+ */
+import type { SessionState } from './types.js';
+/**
+ * Get the global SessionStore singleton instance
+ */
+export declare function getGlobalSessionStore(): SessionStore;
+/**
+ * Manages per-session state with TTL and LRU eviction
+ */
+export declare class SessionStore {
+    private readonly sessions;
+    private readonly sessionLastAccess;
+    private readonly MAX_SESSIONS;
+    private readonly SESSION_TTL;
+    private cleanupInterval;
+    constructor();
+    /**
+     * Get or create session state for the given session ID
+     *
+     * Retrieves existing session state or creates a new one if it doesn't exist.
+     * Automatically updates the last access timestamp for TTL tracking and
+     * enforces the maximum session limit using LRU eviction.
+     *
+     * @param sessionId - Unique identifier for the session
+     * @returns Session state object with current stage information
+     */
+    getSession(sessionId: string): SessionState;
+    /**
+     * Update session state with partial updates
+     *
+     * Merges the provided updates into the existing session state.
+     * Creates a new session if one doesn't exist for the given ID.
+     *
+     * @param sessionId - Unique identifier for the session
+     * @param updates - Partial session state updates (excluding sessionId)
+     */
+    updateSession(sessionId: string, updates: Partial<Omit<SessionState, 'sessionId'>>): void;
+    /**
+     * Reset session state for testing purposes
+     *
+     * Completely removes the session and its access tracking.
+     * Primarily used in test scenarios to ensure clean state.
+     *
+     * @param sessionId - Unique identifier for the session to reset
+     */
+    reset(sessionId: string): void;
+    /**
+     * Get all active sessions for debugging and monitoring
+     *
+     * Returns a snapshot of all current session states.
+     * Useful for debugging, monitoring, and diagnostics.
+     *
+     * @returns Array of all active session state objects
+     */
+    getAllSessions(): SessionState[];
+    /**
+     * Clean up expired sessions based on TTL
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Evict the oldest session (LRU)
+     */
+    private evictOldestSession;
+    /**
+     * Destroy session store and clean up all resources
+     *
+     * Stops the cleanup interval timer and clears all session data.
+     * Should be called when shutting down the server to prevent resource leaks.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=session-store.d.ts.map

package/dist/session/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../src/session/session-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,YAAY,CAGpD;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IACnD,OAAO,CAAC,eAAe,CAA+B;;IAStD;;;;;;;;;OASG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAuB3C;;;;;;;;OAQG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG,IAAI;IAKzF;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;OAOG;IACH,cAAc,IAAI,YAAY,EAAE;IAIhC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAQhB"}

package/dist/session/session-store.js

@@ -0,0 +1,150 @@
+/**
+ * Session state management for MCP connections
+ */
+// Global singleton instance
+let globalSessionStore = null;
+/**
+ * Get the global SessionStore singleton instance
+ */
+export function getGlobalSessionStore() {
+    globalSessionStore ??= new SessionStore();
+    return globalSessionStore;
+}
+/**
+ * Manages per-session state with TTL and LRU eviction
+ */
+export class SessionStore {
+    sessions = new Map();
+    sessionLastAccess = new Map();
+    MAX_SESSIONS = 1000;
+    SESSION_TTL = 24 * 60 * 60 * 1000; // 24 hours
+    cleanupInterval = null;
+    constructor() {
+        // Start periodic cleanup every hour
+        this.cleanupInterval = setInterval(() => {
+            this.cleanupExpiredSessions();
+        }, 60 * 60 * 1000);
+    }
+    /**
+     * Get or create session state for the given session ID
+     *
+     * Retrieves existing session state or creates a new one if it doesn't exist.
+     * Automatically updates the last access timestamp for TTL tracking and
+     * enforces the maximum session limit using LRU eviction.
+     *
+     * @param sessionId - Unique identifier for the session
+     * @returns Session state object with current stage information
+     */
+    getSession(sessionId) {
+        if (!this.sessions.has(sessionId)) {
+            // Enforce maximum session limit with LRU eviction
+            if (this.sessions.size >= this.MAX_SESSIONS) {
+                this.evictOldestSession();
+            }
+            this.sessions.set(sessionId, {
+                sessionId,
+                createDocumentStage: 0, // Start at discovery stage
+            });
+        }
+        // Update last access time for TTL tracking
+        this.sessionLastAccess.set(sessionId, Date.now());
+        const session = this.sessions.get(sessionId);
+        if (session == null) {
+            throw new Error(`Session ${sessionId} not found - this should not happen`);
+        }
+        return session;
+    }
+    /**
+     * Update session state with partial updates
+     *
+     * Merges the provided updates into the existing session state.
+     * Creates a new session if one doesn't exist for the given ID.
+     *
+     * @param sessionId - Unique identifier for the session
+     * @param updates - Partial session state updates (excluding sessionId)
+     */
+    updateSession(sessionId, updates) {
+        const session = this.getSession(sessionId);
+        Object.assign(session, updates);
+    }
+    /**
+     * Reset session state for testing purposes
+     *
+     * Completely removes the session and its access tracking.
+     * Primarily used in test scenarios to ensure clean state.
+     *
+     * @param sessionId - Unique identifier for the session to reset
+     */
+    reset(sessionId) {
+        this.sessions.delete(sessionId);
+        this.sessionLastAccess.delete(sessionId);
+    }
+    /**
+     * Get all active sessions for debugging and monitoring
+     *
+     * Returns a snapshot of all current session states.
+     * Useful for debugging, monitoring, and diagnostics.
+     *
+     * @returns Array of all active session state objects
+     */
+    getAllSessions() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Clean up expired sessions based on TTL
+     */
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        const expiredSessions = [];
+        // Find all expired sessions
+        for (const [sessionId, lastAccess] of this.sessionLastAccess.entries()) {
+            if (now - lastAccess > this.SESSION_TTL) {
+                expiredSessions.push(sessionId);
+            }
+        }
+        // Remove expired sessions
+        for (const sessionId of expiredSessions) {
+            this.sessions.delete(sessionId);
+            this.sessionLastAccess.delete(sessionId);
+        }
+        // Log cleanup only if sessions were removed (informational warning)
+        if (expiredSessions.length > 0) {
+            console.warn(`[SessionStore] Cleaned up ${expiredSessions.length} expired sessions`);
+        }
+    }
+    /**
+     * Evict the oldest session (LRU)
+     */
+    evictOldestSession() {
+        let oldestSessionId = null;
+        let oldestAccess = Date.now();
+        // Find session with oldest last access time
+        for (const [sessionId, lastAccess] of this.sessionLastAccess.entries()) {
+            if (lastAccess < oldestAccess) {
+                oldestAccess = lastAccess;
+                oldestSessionId = sessionId;
+            }
+        }
+        // Evict oldest session
+        if (oldestSessionId != null) {
+            this.sessions.delete(oldestSessionId);
+            this.sessionLastAccess.delete(oldestSessionId);
+            console.warn(`[SessionStore] Evicted oldest session: ${oldestSessionId} (max sessions: ${this.MAX_SESSIONS})`);
+        }
+    }
+    /**
+     * Destroy session store and clean up all resources
+     *
+     * Stops the cleanup interval timer and clears all session data.
+     * Should be called when shutting down the server to prevent resource leaks.
+     */
+    destroy() {
+        if (this.cleanupInterval != null) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.sessions.clear();
+        this.sessionLastAccess.clear();
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/session/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/session/session-store.ts"],"names":[],"mappings":"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"}

package/dist/session/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Session-related type definitions for the Spec-Docs MCP server
+ *
+ * This module defines session management interfaces for tracking state across
+ * MCP connection lifecycles, enabling progressive discovery workflows and
+ * stateful tool interactions.
+ */
+/**
+ * Session state tracking for each MCP connection
+ *
+ * Maintains session-specific state to enable progressive discovery patterns,
+ * where tools reveal parameters and capabilities based on previous interactions.
+ * Each session is isolated and maintains independent state throughout the
+ * connection lifecycle.
+ *
+ * @example Basic session initialization
+ * ```typescript
+ * const sessionStore = getGlobalSessionStore();
+ * const newSession: SessionState = {
+ *   sessionId: 'session_' + Date.now(),
+ *   createDocumentStage: 0
+ * };
+ * sessionStore.createSession(newSession.sessionId, newSession);
+ * ```
+ *
+ * @example Progressive discovery workflow
+ * ```typescript
+ * // Stage 0: User provides namespace
+ * let session = sessionStore.getSession(sessionId);
+ * session.createDocumentStage = 0; // Show namespace parameter only
+ *
+ * // Stage 1: After namespace provided, show title parameter
+ * session.createDocumentStage = 1; // Show namespace + title
+ *
+ * // Stage 2.5: After title provided, show overview parameter
+ * session.createDocumentStage = 2.5; // Show namespace + title + overview
+ *
+ * // Stage 3: Full schema with all parameters
+ * session.createDocumentStage = 3; // Show all parameters
+ * ```
+ *
+ * @example Session state management
+ * ```typescript
+ * function updateSessionStage(
+ *   sessionId: string,
+ *   newStage: number,
+ *   onStageChange?: () => void
+ * ): void {
+ *   const sessionStore = getGlobalSessionStore();
+ *   const session = sessionStore.getSession(sessionId);
+ *
+ *   if (session.createDocumentStage !== newStage) {
+ *     session.createDocumentStage = newStage;
+ *     sessionStore.updateSession(sessionId, session);
+ *
+ *     // Notify tool registry to update schema
+ *     onStageChange?.();
+ *   }
+ * }
+ * ```
+ *
+ * @example Multi-tool session state
+ * ```typescript
+ * interface ExtendedSessionState extends SessionState {
+ *   createDocumentStage: number;
+ *   browseDocumentsFilters?: string[];
+ *   lastViewedDocument?: string;
+ *   preferredNamespace?: string;
+ * }
+ * ```
+ *
+ * @see {@link SessionStore} Session storage implementation
+ * @see {@link getGlobalSessionStore} Global session store access
+ */
+export interface SessionState {
+    /** Unique identifier for this session connection */
+    sessionId: string;
+    /**
+     * Progressive discovery stage for create_document tool
+     *
+     * Controls which parameters are revealed in the tool schema:
+     * - Stage 0: namespace only
+     * - Stage 1: namespace + title
+     * - Stage 2.5: namespace + title + overview
+     * - Stage 3: full schema with all parameters
+     *
+     * @example Stage progression
+     * ```typescript
+     * // User provides namespace -> advance to stage 1
+     * // User provides title -> advance to stage 2.5
+     * // User provides overview -> advance to stage 3
+     * ```
+     */
+    createDocumentStage: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/session/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B"}

package/dist/session/types.js

@@ -0,0 +1,9 @@
+/**
+ * Session-related type definitions for the Spec-Docs MCP server
+ *
+ * This module defines session management interfaces for tracking state across
+ * MCP connection lifecycles, enabling progressive discovery workflows and
+ * stateful tool interactions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/shared/__tests__/addressing-system.batch-cache.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests for batch-scoped caching in addressing system
+ *
+ * This test suite verifies that the AddressCache:
+ * 1. Only caches within batch scope (not persistent)
+ * 2. Clears cache after batch operations
+ * 3. Provides batch statistics for debugging
+ * 4. Handles errors gracefully
+ * 5. Maintains backward compatibility
+ */
+export {};
+//# sourceMappingURL=addressing-system.batch-cache.test.d.ts.map

package/dist/shared/__tests__/addressing-system.batch-cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing-system.batch-cache.test.d.ts","sourceRoot":"","sources":["../../../src/shared/__tests__/addressing-system.batch-cache.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}