mne-docs-mcp 1.0.0

package/dist/utils/docstring.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Utility for expanding MNE docstring placeholders.
+ * MNE uses %(param_name)s placeholders that reference shared documentation.
+ */
+/**
+ * Expand %(placeholder)s patterns in a docstring using common expansions.
+ */
+export declare function expandDocstring(docstring: string): string;
+/**
+ * Check if a docstring has unexpanded placeholders.
+ */
+export declare function hasPlaceholders(docstring: string): boolean;
+/**
+ * Get list of placeholder names in a docstring.
+ */
+export declare function getPlaceholders(docstring: string): string[];
+/**
+ * Extract "See Also" references from a numpy-style docstring.
+ * Returns an array of symbol names mentioned in the See Also section.
+ */
+export declare function extractSeeAlso(docstring: string): string[];
+/**
+ * Format See Also references with links to MNE documentation.
+ */
+export declare function formatSeeAlsoWithLinks(seeAlso: string[], version: string): string;
+//# sourceMappingURL=docstring.d.ts.map

package/dist/utils/docstring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docstring.d.ts","sourceRoot":"","sources":["../../src/utils/docstring.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoMH;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAc3D;AAGD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAqC1D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUjF"}

package/dist/utils/docstring.js

@@ -0,0 +1,261 @@
+/**
+ * Utility for expanding MNE docstring placeholders.
+ * MNE uses %(param_name)s placeholders that reference shared documentation.
+ */
+/**
+ * Common parameter expansions for MNE docstrings.
+ * These are the most frequently used placeholders.
+ */
+const COMMON_EXPANSIONS = {
+    'verbose': `verbose : bool | str | int | None
+    Control verbosity of the logging output. If None, use the default
+    verbosity level. See the logging documentation and mne.verbose for
+    details. Should only be passed as a keyword argument.`,
+    'preload': `preload : bool | str
+    Preload data into memory for data manipulation and faster indexing.
+    If True, the data will be preloaded into memory (fast, requires
+    large amount of memory). If preload is a string, preload is the
+    file name of a memory-mapped file which is used to store the data
+    on the hard drive (slower, requires less memory).`,
+    'picks_all': `picks : str | array-like | slice | None
+    Channels to include. Slices and lists of integers will be interpreted as
+    channel indices. In lists, channel type strings (e.g., ['meg', 'eeg'])
+    will pick channels of those types, channel name strings will pick the
+    given channels. Can also be the string values "all" to pick all channels,
+    or "data" to pick data channels. None (default) will pick all channels.`,
+    'picks_nostr': `picks : list | slice | None
+    Channels to include. Slices and lists of integers will be interpreted as
+    channel indices. None (default) will pick all channels.`,
+    'n_jobs': `n_jobs : int | None
+    The number of jobs to run in parallel. If -1, it is set
+    to the number of CPU cores. Requires the joblib package.
+    None (default) is a marker for 'unset' that will be interpreted
+    as n_jobs=1 (sequential execution) unless the call is performed under
+    a joblib.parallel_config context manager that sets another value for
+    n_jobs.`,
+    'n_jobs_fir': `n_jobs : int | str
+    Number of jobs to run in parallel. Can be 'cuda' if cupy
+    is installed properly and method='fir'.`,
+    'random_state': `random_state : None | int | instance of RandomState
+    A seed for the NumPy random number generator (RNG). If None (default),
+    the global numpy.random.default_rng() is used.
+    If int, random_state is used to seed a new RNG.
+    If already a RandomState instance, the given instance is used.`,
+    'info_not_none': `info : mne.Info
+    The mne.Info object with information about the sensors and methods of measurement.`,
+    'baseline_epochs': `baseline : None | tuple of length 2
+    The time interval to consider as "baseline" when applying baseline
+    correction. If None, do not apply baseline correction.
+    If a tuple (a, b), the interval is between a and b (in seconds),
+    including the endpoints.
+    If a is None, the beginning of the data is used; and if b is None,
+    it is set to the end of the data.`,
+    'tmin': `tmin : float | None
+    Start time of selection in seconds.`,
+    'tmax': `tmax : float | None
+    End time of selection in seconds.`,
+    'reject_epochs': `reject : dict | None
+    Reject epochs based on maximum peak-to-peak signal amplitude (PTP),
+    i.e. the absolute difference between the lowest and the highest
+    signal value. In each individual epoch, the PTP is calculated for
+    every channel. If the PTP of any one channel exceeds the rejection
+    threshold, the respective epoch will be dropped.
+
+    The dictionary keys correspond to the different channel types;
+    valid keys can be any channel type present in the object.
+
+    Example::
+
+        reject = dict(grad=4000e-13,  # T / m (gradiometers)
+                      mag=4e-12,      # T (magnetometers)
+                      eeg=40e-6,      # V (EEG channels)
+                      eog=250e-6)     # V (EOG channels)`,
+    'flat': `flat : dict | None
+    Reject epochs based on minimum peak-to-peak signal amplitude (PTP).
+    Valid keys can be any channel type present in the object. The values
+    are floats that set the minimum acceptable PTP. If the PTP is smaller
+    than this threshold, the epoch will be dropped. If None then no
+    rejection is performed based on flatness of the signal.`,
+    'proj_epochs': `proj : bool | 'delayed'
+    Apply SSP projection vectors. If proj is 'delayed' and reject is not
+    None the single epochs will be projected before the rejection
+    decision, but used in unprojected state if they are kept.
+    This way deciding which projection vectors are good can be postponed
+    to the average stage without resulting in lower epoch counts and
+    without producing results different from early SSP application
+    given comparable samples. Note that in this case baselining, detrending
+    and temporal decimation will be postponed.
+    If proj is False no projections will be applied which is the
+    recommended value if SSPs are not used for cleaning the data.`,
+    'decim': `decim : int
+    Factor by which to subsample the data.
+    
+    .. warning:: Low-pass filtering is not performed, this simply selects
+                 every Nth sample (where N is the value passed to decim),
+                 i.e., it compresses the signal (see Notes).
+                 If the data are not properly filtered, aliasing artifacts
+                 may occur.`,
+    'method_fir': `method : str
+    'fir' will use overlap-add FIR filtering, 'iir' will use IIR
+    forward-backward filtering (via filtfilt).`,
+    'phase': `phase : str
+    Phase of the filter.
+    Symmetric linear-phase FIR filters are constructed, and if phase='zero'
+    (default), the delay of this filter is compensated for, making it
+    non-causal. If phase='zero-double', then this filter is applied
+    twice, once forward, and once backward (also making it non-causal).
+    If 'minimum', then a minimum-phase filter will be constructed and applied,
+    which is causal but has weaker stop-band suppression.`,
+    'l_freq': `l_freq : float | None
+    For FIR filters, the lower pass-band edge; for IIR filters, the lower
+    cutoff frequency. If None the data are only low-pass filtered.`,
+    'h_freq': `h_freq : float | None
+    For FIR filters, the upper pass-band edge; for IIR filters, the upper
+    cutoff frequency. If None the data are only high-pass filtered.`,
+    'filter_length': `filter_length : str | int
+    Length of the FIR filter to use (if applicable):
+
+    * 'auto' (default): The filter length is chosen based on the size
+      of the transition regions.
+    * str: A human-readable time in units of "s" or "ms".
+    * int: The specified number of samples.`,
+    'iir_params': `iir_params : dict | None
+    Dictionary of parameters to use for IIR filtering.
+    If iir_params is None and method="iir", 4th order Butterworth will be used.`,
+    'fir_window': `fir_window : str
+    The window to use in FIR design, can be "hamming" (default),
+    "hann", or "blackman".`,
+    'fir_design': `fir_design : str
+    Can be "firwin" (default) to use scipy.signal.firwin,
+    or "firwin2" to use scipy.signal.firwin2.`,
+    // Time-frequency related
+    'freqs_tfr_array': `freqs : array-like
+    The frequencies of interest in Hz.`,
+    'n_cycles_tfr': `n_cycles : int | array-like
+    Number of cycles in the wavelet, either a fixed number or one per frequency.
+    The number of cycles defines the time-frequency trade-off.`,
+    'decim_tfr': `decim : int | slice
+    To reduce memory usage, decimation factor during time-frequency decomposition.
+    Default is 1 (no decimation). If int, uses every Nth sample after convolution.
+    If slice, decimates using slice(start, stop, step).`,
+    'average_tfr': `average : bool
+    If True (default), return an AverageTFR instance. If False, return an EpochsTFR.`,
+    'morlet_reference': `The Morlet wavelet is a sinusoid windowed by a Gaussian.`,
+    'temporal_window_tfr_intro': `Time-frequency analysis uses wavelets to decompose the signal.`,
+    'temporal_window_tfr_morlet_notes': `The wavelet duration depends on the frequency and number of cycles.`,
+    // Info and data related
+    'info': `info : mne.Info
+    The mne.Info object with information about the sensors and methods of measurement.`,
+    'subjects_dir': `subjects_dir : path-like | None
+    The path to the directory containing the FreeSurfer subjects reconstructions.
+    If None, defaults to the SUBJECTS_DIR environment variable.`,
+    'subject': `subject : str
+    The FreeSurfer subject name.`,
+    'seed': `seed : None | int | instance of RandomState
+    A seed for the NumPy random number generator (RNG).`,
+    // Rank related
+    'rank_none': `rank : None | 'info' | 'full' | dict
+    This controls the rank computation that can be read from the measurement info
+    or estimated from the data. See Notes for details.`,
+    'rank_info': `rank : None | 'info' | 'full' | dict
+    This controls the rank computation. See Notes for details.`,
+};
+/**
+ * Expand %(placeholder)s patterns in a docstring using common expansions.
+ */
+export function expandDocstring(docstring) {
+    if (!docstring)
+        return docstring;
+    // Find all %(name)s patterns
+    const placeholderPattern = /%\(([^)]+)\)s/g;
+    let expanded = docstring;
+    let match;
+    while ((match = placeholderPattern.exec(docstring)) !== null) {
+        const placeholder = match[0];
+        const paramName = match[1];
+        // Try to find expansion
+        const expansion = COMMON_EXPANSIONS[paramName];
+        if (expansion) {
+            expanded = expanded.replace(placeholder, expansion);
+        }
+        else {
+            // Mark unexpanded placeholders for visibility
+            expanded = expanded.replace(placeholder, `[${paramName}: see MNE docs]`);
+        }
+    }
+    return expanded;
+}
+/**
+ * Check if a docstring has unexpanded placeholders.
+ */
+export function hasPlaceholders(docstring) {
+    if (!docstring)
+        return false;
+    return /%\([^)]+\)s/.test(docstring);
+}
+/**
+ * Get list of placeholder names in a docstring.
+ */
+export function getPlaceholders(docstring) {
+    if (!docstring)
+        return [];
+    const placeholders = [];
+    const pattern = /%\(([^)]+)\)s/g;
+    let match;
+    while ((match = pattern.exec(docstring)) !== null) {
+        if (!placeholders.includes(match[1])) {
+            placeholders.push(match[1]);
+        }
+    }
+    return placeholders;
+}
+/**
+ * Extract "See Also" references from a numpy-style docstring.
+ * Returns an array of symbol names mentioned in the See Also section.
+ */
+export function extractSeeAlso(docstring) {
+    if (!docstring)
+        return [];
+    const seeAlso = [];
+    const lines = docstring.split('\n');
+    let inSeeAlso = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Check for See Also section header
+        if (trimmed === 'See Also' || trimmed === 'See also') {
+            inSeeAlso = true;
+            continue;
+        }
+        // Skip separator line
+        if (inSeeAlso && trimmed.startsWith('---')) {
+            continue;
+        }
+        // Check for end of See Also section (next section header)
+        if (inSeeAlso && /^[A-Z][a-z]+$/.test(trimmed) && !trimmed.includes('.')) {
+            break;
+        }
+        if (inSeeAlso && trimmed) {
+            // Extract symbol names (typically in format: mne.symbol or just symbol)
+            // They can be followed by a colon and description
+            const match = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_.]*)/);
+            if (match) {
+                seeAlso.push(match[1]);
+            }
+        }
+    }
+    return seeAlso;
+}
+/**
+ * Format See Also references with links to MNE documentation.
+ */
+export function formatSeeAlsoWithLinks(seeAlso, version) {
+    if (seeAlso.length === 0)
+        return '';
+    const docsVersion = version === 'latest' ? 'stable' : version;
+    return seeAlso.map(symbol => {
+        // Construct docs URL
+        const docsUrl = `https://mne.tools/${docsVersion}/generated/${symbol}.html`;
+        return `- ${symbol}: ${docsUrl}`;
+    }).join('\n');
+}
+//# sourceMappingURL=docstring.js.map

package/dist/utils/docstring.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,19 @@
+import { Config } from '../config.js';
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+declare class Logger {
+    private level;
+    private json;
+    private useStderr;
+    constructor(level?: LogLevel, json?: boolean, useStderr?: boolean);
+    private shouldLog;
+    private format;
+    private log;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export declare function initLogger(config: Config): void;
+export declare function getLogger(): Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD,cAAM,MAAM;IACR,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,SAAS,CAAU;gBAEf,KAAK,GAAE,QAAiB,EAAE,IAAI,GAAE,OAAe,EAAE,SAAS,GAAE,OAAe;IAMvF,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,GAAG;IAwBX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIrD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIpD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIpD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGxD;AAID,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,QAIxC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAMlC"}

package/dist/utils/logger.js

@@ -0,0 +1,73 @@
+class Logger {
+    level;
+    json;
+    useStderr;
+    constructor(level = 'info', json = false, useStderr = false) {
+        this.level = level;
+        this.json = json;
+        this.useStderr = useStderr;
+    }
+    shouldLog(level) {
+        const levels = ['debug', 'info', 'warn', 'error'];
+        return levels.indexOf(level) >= levels.indexOf(this.level);
+    }
+    format(level, message, meta) {
+        const timestamp = new Date().toISOString();
+        if (this.json) {
+            return JSON.stringify({ timestamp, level, message, ...meta });
+        }
+        const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+        return `[${timestamp}] [${level.toUpperCase()}] ${message}${metaStr}`;
+    }
+    log(level, message, meta) {
+        if (!this.shouldLog(level))
+            return;
+        const formatted = this.format(level, message, meta);
+        // In stdio mode, always use stderr to avoid corrupting the MCP protocol
+        if (this.useStderr) {
+            process.stderr.write(formatted + '\n');
+        }
+        else {
+            switch (level) {
+                case 'debug':
+                    console.debug(formatted);
+                    break;
+                case 'info':
+                    console.info(formatted);
+                    break;
+                case 'warn':
+                    console.warn(formatted);
+                    break;
+                case 'error':
+                    console.error(formatted);
+                    break;
+            }
+        }
+    }
+    debug(message, meta) {
+        this.log('debug', message, meta);
+    }
+    info(message, meta) {
+        this.log('info', message, meta);
+    }
+    warn(message, meta) {
+        this.log('warn', message, meta);
+    }
+    error(message, meta) {
+        this.log('error', message, meta);
+    }
+}
+let loggerInstance = null;
+export function initLogger(config) {
+    // Use stderr for logging when in stdio transport mode to avoid corrupting MCP protocol
+    const useStderr = config.transport === 'stdio';
+    loggerInstance = new Logger(config.logLevel, config.logJson, useStderr);
+}
+export function getLogger() {
+    if (!loggerInstance) {
+        // Fallback if not initialized
+        loggerInstance = new Logger();
+    }
+    return loggerInstance;
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/metrics.d.ts

@@ -0,0 +1,38 @@
+interface MetricsData {
+    toolCalls: Record<string, number>;
+    cache: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        entries: number;
+    };
+    github: {
+        requestsTotal: number;
+        rateLimitRemaining: number;
+    };
+    parser: {
+        invocations: number;
+        averageLatencyMs: number;
+    };
+    uptimeSeconds: number;
+}
+declare class Metrics {
+    private startTime;
+    private toolCalls;
+    private cacheHits;
+    private cacheMisses;
+    private githubRequests;
+    private githubRateLimitRemaining;
+    private parserInvocations;
+    private parserTotalLatency;
+    constructor();
+    recordToolCall(toolName: string): void;
+    recordCacheHit(): void;
+    recordCacheMiss(): void;
+    recordGithubRequest(remaining?: number): void;
+    recordParserInvocation(latencyMs: number): void;
+    getMetrics(): MetricsData;
+}
+export declare const metrics: Metrics;
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/utils/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/utils/metrics.ts"],"names":[],"mappings":"AAAA,UAAU,WAAW;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,KAAK,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,EAAE;QACJ,aAAa,EAAE,MAAM,CAAC;QACtB,kBAAkB,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,MAAM,EAAE;QACJ,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,cAAM,OAAO;IACT,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,wBAAwB,CAAK;IACrC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,kBAAkB,CAAK;;IAM/B,cAAc,CAAC,QAAQ,EAAE,MAAM;IAI/B,cAAc;IAId,eAAe;IAIf,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM;IAOtC,sBAAsB,CAAC,SAAS,EAAE,MAAM;IAKxC,UAAU,IAAI,WAAW;CAwB5B;AAED,eAAO,MAAM,OAAO,SAAgB,CAAC"}

package/dist/utils/metrics.js

@@ -0,0 +1,57 @@
+class Metrics {
+    startTime;
+    toolCalls = {};
+    cacheHits = 0;
+    cacheMisses = 0;
+    githubRequests = 0;
+    githubRateLimitRemaining = 0;
+    parserInvocations = 0;
+    parserTotalLatency = 0;
+    constructor() {
+        this.startTime = Date.now();
+    }
+    recordToolCall(toolName) {
+        this.toolCalls[toolName] = (this.toolCalls[toolName] || 0) + 1;
+    }
+    recordCacheHit() {
+        this.cacheHits++;
+    }
+    recordCacheMiss() {
+        this.cacheMisses++;
+    }
+    recordGithubRequest(remaining) {
+        this.githubRequests++;
+        if (remaining !== undefined) {
+            this.githubRateLimitRemaining = remaining;
+        }
+    }
+    recordParserInvocation(latencyMs) {
+        this.parserInvocations++;
+        this.parserTotalLatency += latencyMs;
+    }
+    getMetrics() {
+        const totalCacheOps = this.cacheHits + this.cacheMisses;
+        const hitRate = totalCacheOps > 0 ? this.cacheHits / totalCacheOps : 0;
+        const avgParserLatency = this.parserInvocations > 0 ? this.parserTotalLatency / this.parserInvocations : 0;
+        return {
+            toolCalls: { ...this.toolCalls },
+            cache: {
+                hits: this.cacheHits,
+                misses: this.cacheMisses,
+                hitRate,
+                entries: 0 // To be filled by cache manager
+            },
+            github: {
+                requestsTotal: this.githubRequests,
+                rateLimitRemaining: this.githubRateLimitRemaining
+            },
+            parser: {
+                invocations: this.parserInvocations,
+                averageLatencyMs: avgParserLatency
+            },
+            uptimeSeconds: (Date.now() - this.startTime) / 1000
+        };
+    }
+}
+export const metrics = new Metrics();
+//# sourceMappingURL=metrics.js.map

package/dist/utils/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/utils/metrics.ts"],"names":[],"mappings":"AAmBA,MAAM,OAAO;IACD,SAAS,CAAS;IAClB,SAAS,GAA2B,EAAE,CAAC;IACvC,SAAS,GAAG,CAAC,CAAC;IACd,WAAW,GAAG,CAAC,CAAC;IAChB,cAAc,GAAG,CAAC,CAAC;IACnB,wBAAwB,GAAG,CAAC,CAAC;IAC7B,iBAAiB,GAAG,CAAC,CAAC;IACtB,kBAAkB,GAAG,CAAC,CAAC;IAE/B;QACI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,CAAC;IAED,cAAc,CAAC,QAAgB;QAC3B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,cAAc;QACV,IAAI,CAAC,SAAS,EAAE,CAAC;IACrB,CAAC;IAED,eAAe;QACX,IAAI,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IAED,mBAAmB,CAAC,SAAkB;QAClC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,wBAAwB,GAAG,SAAS,CAAC;QAC9C,CAAC;IACL,CAAC;IAED,sBAAsB,CAAC,SAAiB;QACpC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,kBAAkB,IAAI,SAAS,CAAC;IACzC,CAAC;IAED,UAAU;QACN,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC;QACxD,MAAM,OAAO,GAAG,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QAE3G,OAAO;YACH,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE;YAChC,KAAK,EAAE;gBACH,IAAI,EAAE,IAAI,CAAC,SAAS;gBACpB,MAAM,EAAE,IAAI,CAAC,WAAW;gBACxB,OAAO;gBACP,OAAO,EAAE,CAAC,CAAC,gCAAgC;aAC9C;YACD,MAAM,EAAE;gBACJ,aAAa,EAAE,IAAI,CAAC,cAAc;gBAClC,kBAAkB,EAAE,IAAI,CAAC,wBAAwB;aACpD;YACD,MAAM,EAAE;gBACJ,WAAW,EAAE,IAAI,CAAC,iBAAiB;gBACnC,gBAAgB,EAAE,gBAAgB;aACrC;YACD,aAAa,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI;SACtD,CAAC;IACN,CAAC;CACJ;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function getVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,IAAI,MAAM,CAWnC"}

package/dist/version.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+let version = '';
+export function getVersion() {
+    if (!version) {
+        try {
+            const dir = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(resolve(dir, '../package.json'), 'utf-8'));
+            version = pkg.version || '2.0.0';
+        }
+        catch {
+            version = '2.0.0';
+        }
+    }
+    return version;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAExC,IAAI,OAAO,GAAG,EAAE,CAAC;AAEjB,MAAM,UAAU,UAAU;IACtB,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YAC/E,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,GAAG,OAAO,CAAC;QACtB,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "mne-docs-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.weiyongxu/mne-docs",
+  "description": "MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mne-docs-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "python/*.py",
+    "python/requirements.txt",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mne",
+    "mne-python",
+    "neuroscience",
+    "eeg",
+    "meg",
+    "documentation",
+    "ai-assistant",
+    "claude",
+    "llm"
+  ],
+  "author": "weiyongxu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiyongxu/mne-docs-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/weiyongxu/mne-docs-mcp/issues"
+  },
+  "homepage": "https://github.com/weiyongxu/mne-docs-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "express": "^4.18.2",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "@vitest/coverage-v8": "^4.0.14",
+    "eslint": "^8.55.0",
+    "tsx": "^4.6.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.14"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}