mne-docs-mcp 1.0.0 → 1.0.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 weiyongxu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 weiyongxu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,140 +1,157 @@
-# MNE Docs MCP Server
-
-MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum across the MNE ecosystem.
-
-## Quick Start
-
-```bash
-# Clone and install
-git clone https://github.com/weiyongxu/mne-docs-mcp.git
-cd mne-docs-mcp
-npm install
-
-# Set GitHub token (required)
-export MNE_GITHUB_TOKEN=ghp_your_token_here
-
-# Start server
-npm start
-```
-
-Server runs on `http://localhost:8000`. Verify with `curl http://localhost:8000/health`.
-
-## MCP Client Integration
-
-### Claude Desktop / Kiro / Claude Code
-
-Add to your MCP config (`claude_desktop_config.json`, `.kiro/settings/mcp.json`, or `~/.claude/settings.json`):
-
-```json
-{
-  "mcpServers": {
-    "mne-docs": {
-      "command": "node",
-      "args": ["/path/to/mne-docs-mcp/dist/index.js"],
-      "env": {
-        "MNE_GITHUB_TOKEN": "ghp_your_token_here",
-        "MNE_TRANSPORT": "stdio"
-      }
-    }
-  }
-}
-```
-
-> **Windows:** Add `"MNE_PYTHON_PATH": "python"` to env.
-
-### HTTP Mode
-
-```bash
-MNE_TRANSPORT=http npm start
-# Connect to http://localhost:8000/mcp
-```
-
-### Docker
-
-```bash
-docker run -p 8000:8000 -e MNE_GITHUB_TOKEN=ghp_your_token mne-docs-mcp
-```
-
-### Docker Compose
-
-```bash
-# Set your token
-export MNE_GITHUB_TOKEN=ghp_your_token_here
-
-# Start
-docker-compose up -d
-
-# View logs
-docker-compose logs -f
-```
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `list_mne_versions` | List available MNE releases |
-| `get_mne_file` | Fetch source code |
-| `get_mne_doc` | Get symbol documentation |
-| `find_mne_symbol` | Search for symbols |
-| `search_mne_docs` | Unified code/docs search |
-| `search_mne_issues` | Search GitHub issues |
-| `get_mne_issue` | Get issue details |
-| `get_mne_issue_comments` | Get issue comments |
-| `search_mne_forum` | Search community forum |
-| `get_mne_forum_topic` | Get full forum discussion |
-| `get_symbol_references` | Get callees/callers |
-| `get_related_symbols` | Find related functions |
-| `get_mne_changelog` | Get version changes |
-| `get_mne_example` | Get tutorial code |
-| `lookup_mne_error` | Diagnose MNE errors |
-
-All tools support a `package` parameter to query across the MNE ecosystem: `mne-python` (default), `mne-bids-pipeline`, `mne-bids`, `mne-connectivity`, `mne-nirs`, `mne-rsa`, `mne-icalabel`, `mne-realtime`, `mne-lsl`, `mne-gui-addons`.
-
-## Configuration
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MNE_GITHUB_TOKEN` | GitHub PAT (required) | - |
-| `MNE_PORT` | Server port | `8000` |
-| `MNE_TRANSPORT` | `http` or `stdio` | `http` |
-| `MNE_PYTHON_PATH` | Python executable | `python3` |
-| `MNE_LOG_LEVEL` | `debug`/`info`/`warn`/`error` | `info` |
-
-See `.env.example` for all options including cache TTLs and timeouts.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  TypeScript Server (Node.js)                            │
-│  ├─ MCP Tools (McpServer API, SDK v1.18+)              │
-│  ├─ GitHub Client (rate limiting, caching)             │
-│  └─ Python Parser Bridge ──┐                            │
-└────────────────────────────┼────────────────────────────┘
-                             ▼
-                    ┌─────────────────┐
-                    │  Python Parser  │
-                    │  (AST, stdlib)  │
-                    └─────────────────┘
-```
-
-Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
-
-## Development
-
-```bash
-npm run dev          # Watch mode
-npm run build        # Compile TypeScript
-npm test             # Run tests
-npm run lint         # ESLint
-```
-
-## Troubleshooting
-
-- **Rate limits:** Ensure `MNE_GITHUB_TOKEN` is set
-- **Parser fails:** Check Python 3 is installed; Windows users set `MNE_PYTHON_PATH=python`
-- **Test setup:** Run `npx tsx examples/mcp-client.ts` to verify
-
-## License
-
-MIT
+# MNE Docs MCP Server
+
+MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum across the MNE ecosystem.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/weiyongxu/mne-docs-mcp.git
+cd mne-docs-mcp
+npm install
+
+# Set GitHub token (required)
+export MNE_GITHUB_TOKEN=ghp_your_token_here
+
+# Start server
+npm start
+```
+
+Server runs on `http://localhost:8000`. Verify with `curl http://localhost:8000/health`.
+
+## MCP Client Integration
+
+### Claude Desktop / Kiro / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json`, `.kiro/settings/mcp.json`, or `~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "mne-docs": {
+      "command": "node",
+      "args": ["/path/to/mne-docs-mcp/dist/index.js"],
+      "env": {
+        "MNE_GITHUB_TOKEN": "ghp_your_token_here",
+        "MNE_TRANSPORT": "stdio"
+      }
+    }
+  }
+}
+```
+
+> **Windows:** Add `"MNE_PYTHON_PATH": "python"` to env.
+
+### HTTP Mode
+
+```bash
+MNE_TRANSPORT=http npm start
+# Connect to http://localhost:8000/mcp
+```
+
+### Docker
+
+```bash
+docker run -p 8000:8000 -e MNE_GITHUB_TOKEN=ghp_your_token mne-docs-mcp
+```
+
+### Docker Compose
+
+```bash
+# Set your token
+export MNE_GITHUB_TOKEN=ghp_your_token_here
+
+# Start
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_mne_versions` | List available MNE releases |
+| `get_mne_file` | Fetch source code |
+| `get_mne_doc` | Get symbol documentation |
+| `find_mne_symbol` | Search for symbols |
+| `search_mne_docs` | Unified code/docs search |
+| `search_mne_issues` | Search GitHub issues |
+| `get_mne_issue` | Get issue details |
+| `get_mne_issue_comments` | Get issue comments |
+| `search_mne_forum` | Search community forum |
+| `get_mne_forum_topic` | Get full forum discussion |
+| `get_symbol_references` | Get callees/callers |
+| `get_related_symbols` | Find related functions |
+| `get_mne_changelog` | Get version changes |
+| `get_mne_example` | Get tutorial code |
+| `lookup_mne_error` | Diagnose MNE errors |
+
+All tools support a `package` parameter to query across the MNE ecosystem: `mne-python` (default), `mne-bids-pipeline`, `mne-bids`, `mne-connectivity`, `mne-nirs`, `mne-rsa`, `mne-icalabel`, `mne-realtime`, `mne-lsl`, `mne-gui-addons`.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MNE_GITHUB_TOKEN` | GitHub PAT (required) | - |
+| `MNE_PORT` | Server port | `8000` |
+| `MNE_TRANSPORT` | `http` or `stdio` | `http` |
+| `MNE_PYTHON_PATH` | Python executable | `python3` |
+| `MNE_LOG_LEVEL` | `debug`/`info`/`warn`/`error` | `info` |
+
+See `.env.example` for all options including cache TTLs and timeouts.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  TypeScript Server (Node.js)                            │
+│  ├─ MCP Tools (McpServer API, SDK v1.18+)              │
+│  ├─ GitHub Client (rate limiting, caching)             │
+│  └─ Python Parser Bridge ──┐                            │
+└────────────────────────────┼────────────────────────────┘
+                             ▼
+                    ┌─────────────────┐
+                    │  Python Parser  │
+                    │  (AST, stdlib)  │
+                    └─────────────────┘
+```
+
+Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## Development
+
+```bash
+npm run dev          # Watch mode
+npm run build        # Compile TypeScript
+npm test             # Run tests
+npm run lint         # ESLint
+```
+
+## Releasing
+
+First-time setup (one-time only):
+```bash
+npm login
+npm publish
+```
+
+Then for all future releases:
+```bash
+npm run release:patch   # 1.0.0 → 1.0.1
+npm run release:minor   # 1.0.0 → 1.1.0
+npm run release:major   # 1.0.0 → 2.0.0
+```
+
+This bumps versions, commits, tags, and pushes. GitHub Actions then publishes to npm and MCP Registry automatically.
+
+## Troubleshooting
+
+- **Rate limits:** Ensure `MNE_GITHUB_TOKEN` is set
+- **Parser fails:** Check Python 3 is installed; Windows users set `MNE_PYTHON_PATH=python`
+- **Test setup:** Run `npx tsx examples/mcp-client.ts` to verify
+
+## License
+
+MIT

package/dist/tools/lookupMneError.js

@@ -137,91 +137,91 @@ function getSolutions(errorType, message, codeContext) {
     if (lower.includes('no events found')) {
         solutions.push({
             description: 'The events array is empty. Check your event detection parameters.',
-            codeExample: `# Check available events in your data
-events = mne.find_events(raw, stim_channel='STI 014')
-print(f"Found {len(events)} events")
-
-# If no events, try different parameters:
-events = mne.find_events(raw, stim_channel='STI 014', 
-                         min_duration=0.002,
-                         shortest_event=1)
-
-# Or check available stim channels:
+            codeExample: `# Check available events in your data
+events = mne.find_events(raw, stim_channel='STI 014')
+print(f"Found {len(events)} events")
+
+# If no events, try different parameters:
+events = mne.find_events(raw, stim_channel='STI 014', 
+                         min_duration=0.002,
+                         shortest_event=1)
+
+# Or check available stim channels:
 print(raw.info['ch_names'])  # Look for STI/STIM channels`,
         });
     }
     if (lower.includes('baseline period')) {
         solutions.push({
             description: 'Baseline period extends beyond epoch boundaries.',
-            codeExample: `# Ensure baseline is within tmin/tmax
-epochs = mne.Epochs(raw, events, 
-                    tmin=-0.2, tmax=0.5,
-                    baseline=(-0.2, 0))  # baseline must be within [-0.2, 0.5]
-
-# Or use None for no baseline correction:
+            codeExample: `# Ensure baseline is within tmin/tmax
+epochs = mne.Epochs(raw, events, 
+                    tmin=-0.2, tmax=0.5,
+                    baseline=(-0.2, 0))  # baseline must be within [-0.2, 0.5]
+
+# Or use None for no baseline correction:
 epochs = mne.Epochs(raw, events, tmin=-0.2, tmax=0.5, baseline=None)`,
         });
     }
     if (lower.includes('data not loaded') || lower.includes('preload')) {
         solutions.push({
             description: 'Data needs to be loaded into memory before this operation.',
-            codeExample: `# Load data into memory
-raw.load_data()
-
-# Or load when reading:
+            codeExample: `# Load data into memory
+raw.load_data()
+
+# Or load when reading:
 raw = mne.io.read_raw_fif('file.fif', preload=True)`,
         });
     }
     if (lower.includes('channel') && (lower.includes('not found') || lower.includes('missing'))) {
         solutions.push({
             description: 'The specified channel was not found in the data.',
-            codeExample: `# List available channels
-print(raw.ch_names)
-
-# Pick channels by type
-raw.pick_types(eeg=True, meg=False)
-
-# Or pick specific channels
+            codeExample: `# List available channels
+print(raw.ch_names)
+
+# Pick channels by type
+raw.pick_types(eeg=True, meg=False)
+
+# Or pick specific channels
 raw.pick_channels(['EEG 001', 'EEG 002'])`,
         });
     }
     if (lower.includes('filter') && (lower.includes('nyquist') || lower.includes('frequency'))) {
         solutions.push({
             description: 'Filter frequency exceeds Nyquist frequency (half the sampling rate).',
-            codeExample: `# Check sampling rate
-print(f"Sampling rate: {raw.info['sfreq']} Hz")
-print(f"Nyquist frequency: {raw.info['sfreq'] / 2} Hz")
-
-# Resample if needed before filtering
-raw.resample(sfreq=250)  # Resample to 250 Hz
+            codeExample: `# Check sampling rate
+print(f"Sampling rate: {raw.info['sfreq']} Hz")
+print(f"Nyquist frequency: {raw.info['sfreq'] / 2} Hz")
+
+# Resample if needed before filtering
+raw.resample(sfreq=250)  # Resample to 250 Hz
 raw.filter(l_freq=1, h_freq=40)`,
         });
     }
     if (lower.includes('memory') || lower.includes('memoryerror')) {
         solutions.push({
             description: 'Not enough memory for the operation.',
-            codeExample: `# Use preload=False to reduce memory
-raw = mne.io.read_raw_fif('file.fif', preload=False)
-
-# Decimate data to reduce size
-epochs.decimate(4)  # Keep every 4th sample
-
-# Or process in chunks
-for start in range(0, len(raw.times), chunk_size):
-    chunk = raw.get_data(start=start, stop=start+chunk_size)
+            codeExample: `# Use preload=False to reduce memory
+raw = mne.io.read_raw_fif('file.fif', preload=False)
+
+# Decimate data to reduce size
+epochs.decimate(4)  # Keep every 4th sample
+
+# Or process in chunks
+for start in range(0, len(raw.times), chunk_size):
+    chunk = raw.get_data(start=start, stop=start+chunk_size)
     # Process chunk...`,
         });
     }
     if (lower.includes('ica') && lower.includes('fit')) {
         solutions.push({
             description: 'ICA fitting issue - check data quality and parameters.',
-            codeExample: `# Ensure data is filtered before ICA
-raw.filter(l_freq=1, h_freq=None)
-
-# Use fewer components if data is short
-ica = ICA(n_components=15, random_state=97, max_iter='auto')
-
-# Fit on filtered data
+            codeExample: `# Ensure data is filtered before ICA
+raw.filter(l_freq=1, h_freq=None)
+
+# Use fewer components if data is short
+ica = ICA(n_components=15, random_state=97, max_iter='auto')
+
+# Fit on filtered data
 ica.fit(raw)`,
         });
     }
@@ -230,16 +230,16 @@ ica.fit(raw)`,
         if (lowerContext.includes('epochs') && lower.includes('baseline')) {
             solutions.unshift({
                 description: 'Baseline error in Epochs - check tmin/tmax and baseline parameters match.',
-                codeExample: `# Ensure baseline period is within epoch bounds
-# If tmin=-0.2, tmax=0.5, baseline must be within that range
+                codeExample: `# Ensure baseline period is within epoch bounds
+# If tmin=-0.2, tmax=0.5, baseline must be within that range
 epochs = mne.Epochs(raw, events, tmin=-0.2, tmax=0.5, baseline=(-0.2, 0))`,
             });
         }
         if (lowerContext.includes('raw') && lower.includes('preload')) {
             solutions.unshift({
                 description: 'Raw data needs to be loaded before this operation.',
-                codeExample: `# Load data into memory first
-raw.load_data()
+                codeExample: `# Load data into memory first
+raw.load_data()
 # Then perform your operation`,
             });
         }