ai-prompt-guide-mcp 1.0.0

package/dist/utils/path-handler.js

@@ -0,0 +1,129 @@
+/**
+ * Centralized path handling utilities for MCP server
+ */
+import { join, resolve, dirname, extname, basename } from 'path';
+import { promises as fs } from 'node:fs';
+import { FOLDER_NAMES } from '../shared/namespace-constants.js';
+/**
+ * Path validation and normalization utilities
+ */
+export class PathHandler {
+    workspaceBasePath;
+    archivedBasePath;
+    constructor(workspaceBasePath, archivedBasePath) {
+        this.workspaceBasePath = resolve(workspaceBasePath);
+        this.archivedBasePath = archivedBasePath != null ? resolve(archivedBasePath) : undefined;
+    }
+    /**
+     * Normalize and validate a user-provided path
+     */
+    normalizePath(userPath) {
+        // Remove leading/trailing whitespace
+        let cleanPath = userPath.trim();
+        // Remove leading slash if present
+        if (cleanPath.startsWith('/')) {
+            cleanPath = cleanPath.slice(1);
+        }
+        // If path ends with '/', treat as folder
+        const isFolder = cleanPath.endsWith('/');
+        if (isFolder) {
+            // Remove trailing slash for consistency
+            cleanPath = cleanPath.slice(0, -1);
+            return `/${cleanPath}`;
+        }
+        // Handle file paths - add .md if no extension provided
+        const extension = extname(cleanPath);
+        if (extension === '') {
+            cleanPath = `${cleanPath}.md`;
+        }
+        else if (extension !== '.md') {
+            throw new Error(`Only .md files are supported. Got: ${extension}`);
+        }
+        return `/${cleanPath}`;
+    }
+    /**
+     * Validate that a path is within the allowed docs directory
+     */
+    validatePath(normalizedPath) {
+        const absolutePath = this.getAbsolutePath(normalizedPath);
+        const resolvedPath = resolve(absolutePath);
+        // Ensure path is within docs directory (prevent directory traversal)
+        if (!resolvedPath.startsWith(this.workspaceBasePath)) {
+            throw new Error(`Path outside allowed directory: ${normalizedPath}`);
+        }
+    }
+    /**
+     * Get absolute filesystem path from normalized path
+     */
+    getAbsolutePath(normalizedPath) {
+        const relativePath = normalizedPath.startsWith('/') ? normalizedPath.slice(1) : normalizedPath;
+        return join(this.workspaceBasePath, relativePath);
+    }
+    /**
+     * Check if a path represents a folder (ends with / or has no extension)
+     */
+    isFolder(normalizedPath) {
+        return normalizedPath.endsWith('/') || extname(normalizedPath) === '';
+    }
+    /**
+     * Get the parent directory path
+     */
+    getParentPath(normalizedPath) {
+        const parentDir = dirname(normalizedPath);
+        return parentDir === '/' ? '/' : parentDir;
+    }
+    /**
+     * Generate unique archive path to handle duplicates
+     */
+    async generateUniqueArchivePath(normalizedPath) {
+        // Use archivedBasePath if provided, otherwise fall back to workspace/archived
+        const archiveBase = this.archivedBasePath ?? join(this.workspaceBasePath, FOLDER_NAMES.ARCHIVED);
+        const relativePath = normalizedPath.startsWith('/') ? normalizedPath.slice(1) : normalizedPath;
+        let archivePath = join(archiveBase, relativePath);
+        let counter = 1;
+        // Keep trying until we find a unique path
+        // Use fs.access directly since archivePath is already an absolute path
+        // and doesn't need fsio validation
+        while (await this.checkFileExists(archivePath)) {
+            const dir = dirname(archivePath);
+            const ext = extname(archivePath);
+            const name = basename(archivePath, ext);
+            archivePath = join(dir, `${name}_${counter}${ext}`);
+            counter++;
+        }
+        return archivePath;
+    }
+    /**
+     * Check if file exists using direct fs.access (for internal use with absolute paths)
+     */
+    async checkFileExists(absolutePath) {
+        try {
+            await fs.access(absolutePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Normalize and validate path in one call
+     */
+    processUserPath(userPath) {
+        const normalized = this.normalizePath(userPath);
+        this.validatePath(normalized);
+        return normalized;
+    }
+    /**
+     * Get workspace base path
+     */
+    getWorkspaceBasePath() {
+        return this.workspaceBasePath;
+    }
+    /**
+     * Get archived base path (if configured)
+     */
+    getArchivedBasePath() {
+        return this.archivedBasePath;
+    }
+}
+//# sourceMappingURL=path-handler.js.map

package/dist/utils/path-handler.js.map

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

package/dist/utils/security-audit-logger.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Security Audit Logger for tracking security violations
+ *
+ * This module provides structured logging for security-related events
+ * with comprehensive context for incident response and forensic analysis.
+ *
+ * All security violations are logged with:
+ * - Event type classification
+ * - Operation context
+ * - Path information (attempted and resolved)
+ * - Timestamp
+ * - Optional session identifier
+ */
+/**
+ * Security event types for classification
+ */
+export type SecurityEventType = 'PATH_TRAVERSAL' | 'INVALID_EXTENSION' | 'DANGEROUS_CHARS';
+/**
+ * Security violation event data
+ */
+export interface SecurityViolationEvent {
+    /** Type of security violation */
+    readonly type: SecurityEventType;
+    /** Operation being performed when violation occurred */
+    readonly operation: string;
+    /** Path that triggered the violation (user-provided) */
+    readonly attemptedPath: string;
+    /** Resolved path if available (may differ from attempted) */
+    readonly resolvedPath?: string;
+    /** Session identifier if available */
+    readonly sessionId?: string;
+    /** ISO timestamp of violation */
+    readonly timestamp: string;
+}
+/**
+ * Security Audit Logger
+ *
+ * Provides structured logging for security violations with
+ * consistent formatting and comprehensive context.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const logger = new SecurityAuditLogger();
+ * logger.logSecurityViolation({
+ *   type: 'PATH_TRAVERSAL',
+ *   operation: 'readFile',
+ *   attemptedPath: '../../../etc/passwd',
+ *   resolvedPath: '/etc/passwd',
+ *   timestamp: new Date().toISOString()
+ * });
+ * ```
+ */
+export declare class SecurityAuditLogger {
+    /**
+     * Log a security violation with full context
+     *
+     * Outputs structured JSON log with [SECURITY_AUDIT] prefix
+     * for easy filtering and monitoring.
+     *
+     * @param event - Security violation event data
+     */
+    logSecurityViolation(event: SecurityViolationEvent): void;
+}
+//# sourceMappingURL=security-audit-logger.d.ts.map

package/dist/utils/security-audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-audit-logger.d.ts","sourceRoot":"","sources":["../../src/utils/security-audit-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,mBAAmB;IAC9B;;;;;;;OAOG;IACH,oBAAoB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI;CAe1D"}

package/dist/utils/security-audit-logger.js

@@ -0,0 +1,56 @@
+/**
+ * Security Audit Logger for tracking security violations
+ *
+ * This module provides structured logging for security-related events
+ * with comprehensive context for incident response and forensic analysis.
+ *
+ * All security violations are logged with:
+ * - Event type classification
+ * - Operation context
+ * - Path information (attempted and resolved)
+ * - Timestamp
+ * - Optional session identifier
+ */
+/**
+ * Security Audit Logger
+ *
+ * Provides structured logging for security violations with
+ * consistent formatting and comprehensive context.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const logger = new SecurityAuditLogger();
+ * logger.logSecurityViolation({
+ *   type: 'PATH_TRAVERSAL',
+ *   operation: 'readFile',
+ *   attemptedPath: '../../../etc/passwd',
+ *   resolvedPath: '/etc/passwd',
+ *   timestamp: new Date().toISOString()
+ * });
+ * ```
+ */
+export class SecurityAuditLogger {
+    /**
+     * Log a security violation with full context
+     *
+     * Outputs structured JSON log with [SECURITY_AUDIT] prefix
+     * for easy filtering and monitoring.
+     *
+     * @param event - Security violation event data
+     */
+    logSecurityViolation(event) {
+        // Construct structured log entry
+        const logEntry = {
+            severity: 'SECURITY_VIOLATION',
+            type: event.type,
+            operation: event.operation,
+            attemptedPath: event.attemptedPath,
+            ...(event.resolvedPath != null && { resolvedPath: event.resolvedPath }),
+            ...(event.sessionId != null && { sessionId: event.sessionId }),
+            timestamp: event.timestamp
+        };
+        // Log with security audit prefix for monitoring/alerting
+        console.warn('[SECURITY_AUDIT]', JSON.stringify(logEntry, null, 2));
+    }
+}
+//# sourceMappingURL=security-audit-logger.js.map

package/dist/utils/security-audit-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-audit-logger.js","sourceRoot":"","sources":["../../src/utils/security-audit-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyBH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;;;OAOG;IACH,oBAAoB,CAAC,KAA6B;QAChD,iCAAiC;QACjC,MAAM,QAAQ,GAAG;YACf,QAAQ,EAAE,oBAAoB;YAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;YACvE,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;YAC9D,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC;QAEF,yDAAyD;QACzD,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;CACF"}

package/dist/utils/virtual-path-resolver.d.ts

@@ -0,0 +1,126 @@
+/**
+ * VirtualPathResolver - Centralized path resolution for virtual document paths
+ *
+ * Handles routing of virtual paths (e.g., "/api/auth.md", "/coordinator/active.md")
+ * to absolute filesystem paths with automatic docs/coordinator namespace detection.
+ *
+ * Design Principles:
+ * - Pure deterministic logic (no state, no cache)
+ * - Single Responsibility: virtual→absolute path resolution only
+ * - Thread-safe and performant (just string operations)
+ * - Easy to test in isolation
+ */
+/**
+ * Virtual path resolver for document routing
+ *
+ * @example
+ * const resolver = new VirtualPathResolver(
+ *   '/workspace/docs',
+ *   '/workspace/coordinator',
+ *   '/workspace/archived'
+ * );
+ *
+ * resolver.resolve('/api/auth.md')           // → /workspace/docs/api/auth.md
+ * resolver.resolve('/coordinator/active.md') // → /workspace/coordinator/active.md
+ * resolver.getArchivePath('/api/auth.md')    // → /workspace/archived/docs/api/auth.md
+ */
+export declare class VirtualPathResolver {
+    private readonly docsRoot;
+    private readonly coordinatorRoot;
+    private readonly archivedRoot;
+    /**
+     * Create a new VirtualPathResolver
+     *
+     * @param docsRoot - Absolute path to docs directory
+     * @param coordinatorRoot - Absolute path to coordinator directory
+     * @param archivedRoot - Absolute path to archived directory
+     */
+    constructor(docsRoot: string, coordinatorRoot: string, archivedRoot: string);
+    /**
+     * Resolve virtual path to absolute filesystem path
+     *
+     * Automatically routes to appropriate base directory:
+     * - Paths starting with "coordinator/" → coordinatorRoot
+     * - All other paths → docsRoot
+     *
+     * @param virtualPath - Virtual path (e.g., "/api/auth.md", "coordinator/active.md")
+     * @returns Absolute filesystem path
+     *
+     * @example
+     * resolve('/api/auth.md')           // → /workspace/docs/api/auth.md
+     * resolve('/coordinator/active.md') // → /workspace/coordinator/active.md
+     * resolve('api/auth.md')            // → /workspace/docs/api/auth.md (leading / optional)
+     */
+    resolve(virtualPath: string): string;
+    /**
+     * Check if virtual path targets coordinator namespace
+     *
+     * @param virtualPath - Virtual path to check
+     * @returns true if path is in coordinator namespace
+     *
+     * @example
+     * isCoordinatorPath('/coordinator/active.md')  // → true
+     * isCoordinatorPath('/api/auth.md')            // → false
+     */
+    isCoordinatorPath(virtualPath: string): boolean;
+    /**
+     * Get base root directory for virtual path
+     *
+     * @param virtualPath - Virtual path
+     * @returns Absolute path to base root (docs or coordinator)
+     *
+     * @example
+     * getBaseRoot('/api/auth.md')           // → /workspace/docs
+     * getBaseRoot('/coordinator/active.md') // → /workspace/coordinator
+     */
+    getBaseRoot(virtualPath: string): string;
+    /**
+     * Generate archive path for virtual path
+     *
+     * Preserves namespace structure in archive:
+     * - /api/auth.md → /archived/docs/api/auth.md
+     * - /coordinator/active.md → /archived/coordinator/active.md
+     *
+     * @param virtualPath - Virtual path to archive
+     * @returns Absolute archive path
+     *
+     * @example
+     * getArchivePath('/api/auth.md')           // → /workspace/archived/docs/api/auth.md
+     * getArchivePath('/coordinator/active.md') // → /workspace/archived/coordinator/active.md
+     */
+    getArchivePath(virtualPath: string): string;
+    /**
+     * Get relative path component (removes leading slash)
+     *
+     * @param virtualPath - Virtual path
+     * @returns Relative path without leading slash
+     */
+    getRelativePath(virtualPath: string): string;
+    /**
+     * Get path without namespace prefix
+     *
+     * For coordinator paths, removes "coordinator/" prefix
+     * For docs paths, returns as-is
+     *
+     * @param virtualPath - Virtual path
+     * @returns Path without namespace prefix
+     *
+     * @example
+     * getPathWithoutPrefix('/coordinator/active.md') // → active.md
+     * getPathWithoutPrefix('/api/auth.md')           // → api/auth.md
+     */
+    getPathWithoutPrefix(virtualPath: string): string;
+    /**
+     * Get configured docs root
+     */
+    getDocsRoot(): string;
+    /**
+     * Get configured coordinator root
+     */
+    getCoordinatorRoot(): string;
+    /**
+     * Get configured archived root
+     */
+    getArchivedRoot(): string;
+}
+//# sourceMappingURL=virtual-path-resolver.d.ts.map

package/dist/utils/virtual-path-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-path-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/virtual-path-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;;OAMG;gBACS,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAO3E;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAgBpC;;;;;;;;;OASG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAK/C;;;;;;;;;OASG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIxC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAY3C;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAI5C;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAUjD;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;OAEG;IACH,eAAe,IAAI,MAAM;CAG1B"}

package/dist/utils/virtual-path-resolver.js

@@ -0,0 +1,171 @@
+/**
+ * VirtualPathResolver - Centralized path resolution for virtual document paths
+ *
+ * Handles routing of virtual paths (e.g., "/api/auth.md", "/coordinator/active.md")
+ * to absolute filesystem paths with automatic docs/coordinator namespace detection.
+ *
+ * Design Principles:
+ * - Pure deterministic logic (no state, no cache)
+ * - Single Responsibility: virtual→absolute path resolution only
+ * - Thread-safe and performant (just string operations)
+ * - Easy to test in isolation
+ */
+import { join, resolve } from 'node:path';
+/**
+ * Virtual path resolver for document routing
+ *
+ * @example
+ * const resolver = new VirtualPathResolver(
+ *   '/workspace/docs',
+ *   '/workspace/coordinator',
+ *   '/workspace/archived'
+ * );
+ *
+ * resolver.resolve('/api/auth.md')           // → /workspace/docs/api/auth.md
+ * resolver.resolve('/coordinator/active.md') // → /workspace/coordinator/active.md
+ * resolver.getArchivePath('/api/auth.md')    // → /workspace/archived/docs/api/auth.md
+ */
+export class VirtualPathResolver {
+    docsRoot;
+    coordinatorRoot;
+    archivedRoot;
+    /**
+     * Create a new VirtualPathResolver
+     *
+     * @param docsRoot - Absolute path to docs directory
+     * @param coordinatorRoot - Absolute path to coordinator directory
+     * @param archivedRoot - Absolute path to archived directory
+     */
+    constructor(docsRoot, coordinatorRoot, archivedRoot) {
+        // Resolve all paths once at construction for consistency
+        this.docsRoot = resolve(docsRoot);
+        this.coordinatorRoot = resolve(coordinatorRoot);
+        this.archivedRoot = resolve(archivedRoot);
+    }
+    /**
+     * Resolve virtual path to absolute filesystem path
+     *
+     * Automatically routes to appropriate base directory:
+     * - Paths starting with "coordinator/" → coordinatorRoot
+     * - All other paths → docsRoot
+     *
+     * @param virtualPath - Virtual path (e.g., "/api/auth.md", "coordinator/active.md")
+     * @returns Absolute filesystem path
+     *
+     * @example
+     * resolve('/api/auth.md')           // → /workspace/docs/api/auth.md
+     * resolve('/coordinator/active.md') // → /workspace/coordinator/active.md
+     * resolve('api/auth.md')            // → /workspace/docs/api/auth.md (leading / optional)
+     */
+    resolve(virtualPath) {
+        const relativePath = virtualPath.startsWith('/') ? virtualPath.slice(1) : virtualPath;
+        // Check if this is a coordinator path
+        if (relativePath.startsWith('coordinator/') || relativePath === 'coordinator') {
+            // Use coordinator root and remove the 'coordinator/' prefix
+            const coordPath = relativePath === 'coordinator'
+                ? ''
+                : relativePath.slice('coordinator/'.length);
+            return join(this.coordinatorRoot, coordPath);
+        }
+        // Default to docs root
+        return join(this.docsRoot, relativePath);
+    }
+    /**
+     * Check if virtual path targets coordinator namespace
+     *
+     * @param virtualPath - Virtual path to check
+     * @returns true if path is in coordinator namespace
+     *
+     * @example
+     * isCoordinatorPath('/coordinator/active.md')  // → true
+     * isCoordinatorPath('/api/auth.md')            // → false
+     */
+    isCoordinatorPath(virtualPath) {
+        const relativePath = virtualPath.startsWith('/') ? virtualPath.slice(1) : virtualPath;
+        return relativePath.startsWith('coordinator/') || relativePath === 'coordinator';
+    }
+    /**
+     * Get base root directory for virtual path
+     *
+     * @param virtualPath - Virtual path
+     * @returns Absolute path to base root (docs or coordinator)
+     *
+     * @example
+     * getBaseRoot('/api/auth.md')           // → /workspace/docs
+     * getBaseRoot('/coordinator/active.md') // → /workspace/coordinator
+     */
+    getBaseRoot(virtualPath) {
+        return this.isCoordinatorPath(virtualPath) ? this.coordinatorRoot : this.docsRoot;
+    }
+    /**
+     * Generate archive path for virtual path
+     *
+     * Preserves namespace structure in archive:
+     * - /api/auth.md → /archived/docs/api/auth.md
+     * - /coordinator/active.md → /archived/coordinator/active.md
+     *
+     * @param virtualPath - Virtual path to archive
+     * @returns Absolute archive path
+     *
+     * @example
+     * getArchivePath('/api/auth.md')           // → /workspace/archived/docs/api/auth.md
+     * getArchivePath('/coordinator/active.md') // → /workspace/archived/coordinator/active.md
+     */
+    getArchivePath(virtualPath) {
+        const relativePath = virtualPath.startsWith('/') ? virtualPath.slice(1) : virtualPath;
+        if (this.isCoordinatorPath(virtualPath)) {
+            // Archive coordinator files under archived/coordinator/
+            return join(this.archivedRoot, relativePath);
+        }
+        // Archive docs files under archived/docs/
+        return join(this.archivedRoot, 'docs', relativePath);
+    }
+    /**
+     * Get relative path component (removes leading slash)
+     *
+     * @param virtualPath - Virtual path
+     * @returns Relative path without leading slash
+     */
+    getRelativePath(virtualPath) {
+        return virtualPath.startsWith('/') ? virtualPath.slice(1) : virtualPath;
+    }
+    /**
+     * Get path without namespace prefix
+     *
+     * For coordinator paths, removes "coordinator/" prefix
+     * For docs paths, returns as-is
+     *
+     * @param virtualPath - Virtual path
+     * @returns Path without namespace prefix
+     *
+     * @example
+     * getPathWithoutPrefix('/coordinator/active.md') // → active.md
+     * getPathWithoutPrefix('/api/auth.md')           // → api/auth.md
+     */
+    getPathWithoutPrefix(virtualPath) {
+        const relativePath = this.getRelativePath(virtualPath);
+        if (relativePath.startsWith('coordinator/')) {
+            return relativePath.slice('coordinator/'.length);
+        }
+        return relativePath;
+    }
+    /**
+     * Get configured docs root
+     */
+    getDocsRoot() {
+        return this.docsRoot;
+    }
+    /**
+     * Get configured coordinator root
+     */
+    getCoordinatorRoot() {
+        return this.coordinatorRoot;
+    }
+    /**
+     * Get configured archived root
+     */
+    getArchivedRoot() {
+        return this.archivedRoot;
+    }
+}
+//# sourceMappingURL=virtual-path-resolver.js.map

package/dist/utils/virtual-path-resolver.js.map

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

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "ai-prompt-guide-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for markdown CRUD operations on specification documents",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "SKIP_INTEGRATION_TESTS=true MOCK_ONLY_TESTS=true vitest run",
+    "test:all": "pnpm test:run && pnpm check:all",
+    "test:markdown": "tsx src/test-markdown-tools.ts",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check:dead-code": "ts-unused-exports tsconfig.analysis.json --excludePathsFromReport=dist/ --allowUnusedTypes --searchNamespaces --ignoreFiles='.*\\/(schemas|prompts|__tests__\\/setup|__tests__\\/mocks)\\/.*\\.ts$|.*\\/link-analysis\\.ts$'",
+    "check:all": "pnpm lint && pnpm typecheck && pnpm check:dead-code",
+    "prepare": "pnpm build",
+    "inspector": "npx --yes @modelcontextprotocol/inspector node dist/index.js",
+    "inspector:dev": "npx --yes @modelcontextprotocol/inspector tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "markdown",
+    "crud",
+    "documentation",
+    "specifications",
+    "server"
+  ],
+  "author": "",
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "ai-prompt-guide-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "chokidar": "^4.0.3",
+    "dotenv": "^16.4.7",
+    "github-slugger": "^2.0.0",
+    "gray-matter": "^4.0.3",
+    "mdast-util-heading-range": "^4.0.0",
+    "mdast-util-to-markdown": "^2.1.2",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit-parents": "^6.0.1",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.34.0",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.41.0",
+    "@typescript-eslint/parser": "^8.41.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.6.2",
+    "ts-unused-exports": "^11.0.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}