mne-mcp 0.2.0__tar.gz

mne_mcp-0.2.0/.env.example

@@ -0,0 +1,10 @@
+# MNE MCP configuration (optional). Copy to `.env` and edit.
+
+# Per-operation timeout in seconds. Raise for ICA, time-frequency, large files.
+MNE_MCP_TIMEOUT=300
+
+# Where figures (PNG) and exported objects are saved.
+# MNE_MCP_RESULTS_DIR=C:\Users\you\AppData\Local\Temp\mne-mcp\results
+
+# Default directory that `mne_list_files` scans for data.
+# MNE_MCP_DATA_DIR=F:\data\eeg

mne_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Report a problem with the MNE-MCP server, a tool, or a skill
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug and what you expected instead.
+
+**Environment**
+- OS:
+- Python version:
+- MNE-MCP version (`mne-mcp version`):
+- `mne-mcp status` output (MNE / scikit-learn / numpy versions):
+
+**To reproduce**
+The tool call(s) or natural-language request, the recording format (FIF/EDF/BDF/…), and any error
+message or traceback. For analysis issues, please include whether it reproduces via `mne_run_code`.
+
+**Additional context**
+Logs, screenshots of figures, or a minimal dataset if shareable.

mne_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new tool, analysis skill, or improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**Problem / use case**
+What neurophysiology workflow are you trying to support, and what is missing today?
+
+**Proposed solution**
+A new structured tool, an analysis skill, or a change to an existing one. If it's an analysis
+method, note the MNE-Python API it would wrap.
+
+**Alternatives**
+Can this already be done via `mne_run_code`? If so, what would a dedicated tool/skill add?
+
+**Additional context**
+References, papers, or examples.

mne_mcp-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What & why
+
+<!-- What does this change and why? Link any related issue. -->
+
+## Changes
+
+<!-- Bullet the notable changes. -->
+
+## Checklist
+
+- [ ] `pytest -q` passes locally
+- [ ] `black src tests` and `isort --profile black src tests` are clean
+- [ ] Added/updated tests (regression test for any bug fixed)
+- [ ] Updated `CHANGELOG.md`
+- [ ] Docs/README updated if behavior or tools changed

mne_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  unit:
+    name: unit · ${{ matrix.os }} · py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[ica,dev]"
+      - name: Compile check
+        run: python -m compileall src/mne_mcp
+      - name: Unit tests (with coverage)
+        run: pytest -q --cov=mne_mcp --cov-report=term-missing --cov-fail-under=65
+
+  numpy-compat:
+    name: numpy compat · ${{ matrix.numpy }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Verify the package works on both the 1.x and 2.x NumPy lines. The 2.x leg is the
+        # regression guard for the alias bug (np.trapz/np.in1d removal) found on real data.
+        numpy: ["numpy>=1.26,<2", "numpy>=2.1"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[ica,dev]"
+      - name: Pin NumPy line
+        run: pip install "${{ matrix.numpy }}"
+      - run: python -c "import numpy; print('NumPy', numpy.__version__)"
+      - name: Regression + unit tests
+        run: pytest -q
+
+  real-data-smoke:
+    name: real eegbci smoke · ubuntu · py3.12
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Cache MNE datasets
+        uses: actions/cache@v4
+        with:
+          path: ~/mne_data
+          key: mne-eegbci-S001-r1r2
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[ica]"
+      - name: Real-data end-to-end (eyes-open vs eyes-closed alpha)
+        run: python tests/smoke_eegbci.py
+
+  lint:
+    name: lint (black + isort, check-only)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install black isort
+      - run: black --check src tests
+      - run: isort --check-only --profile black src tests

mne_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+# Build and publish to PyPI when a version tag is pushed.
+# Publishing uses PyPI Trusted Publishing (OIDC) — configure the publisher once at
+# https://pypi.org/manage/project/mne-mcp/settings/publishing/ (no stored token needed).
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - run: python -m pip install dist/*.whl && python -c "import mne_mcp; print(mne_mcp.__version__)"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mne_mcp-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Local config / secrets (ship .env.example, never .env)
+.env
+
+# Analysis outputs
+mne_result/
+*.spv
+demo_study/
+
+# MS Office lock files
+~$*
+
+# Reference material (input docs, not part of the package)
+SPSS-MCP*.docx
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

mne_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to MNE-MCP are documented here. The format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions are pre-1.0 and may move quickly.
+
+## [0.2.0] — 2026-06-05
+
+### Added
+- Test **coverage** in CI (pytest-cov); CLI, server-layer, and broad operation-layer tests lift
+  coverage to ~71%, with a 65% regression floor.
+- **`py.typed`** marker (PEP 561) — the package ships inline type hints.
+- **`CONTRIBUTING.md`**, GitHub issue/PR templates, and a **`release.yml`** workflow that publishes
+  to PyPI via Trusted Publishing on a version tag.
+- Opt GitHub Actions into **Node.js 24** (clears the Node 20 deprecation warning).
+- **Continuous integration** (`.github/workflows/ci.yml`): unit tests on Linux/macOS/Windows ×
+  Python 3.10/3.12; a **NumPy 1.x / 2.x compatibility matrix**; a **real-data eegbci smoke test**;
+  and a black/isort lint job.
+- **Real-data smoke test** (`tests/smoke_eegbci.py`): downloads PhysioNet eegbci S001 eyes-open vs
+  eyes-closed baselines and asserts the **Berger effect** (occipital alpha higher eyes-closed) end
+  to end through the operation layer — covering the real EDF-reading path the synthetic smoke test
+  never exercised.
+- **Regression tests** (`tests/test_regressions.py`) for the two bugs fixed below.
+- **Analysis skill suite** (`skills/`): `mne-methodology-critic` (shared methodology reviewer, also
+  shipped as a subagent in `agents/`), per-category skills (`mne-preprocess`, `mne-artifacts`,
+  `mne-erp`, `mne-spectral`, `mne-timefreq`, `mne-connectivity`, `mne-source`, `mne-decoding`,
+  `mne-stats`, `mne-advanced`), and `mne-writeup`; all installed by `mne-mcp setup`.
+
+### Fixed
+- **NumPy 2.x compatibility** (`mne_mcp/_compat.py`, applied at package import): restore aliases
+  removed in NumPy ≥ 2.0 (`np.trapz`→`trapezoid`, `np.in1d`→`isin`, `np.row_stack`→`vstack`, …)
+  that a transitive dependency still calls while reading EDF. Previously this raised
+  `AttributeError` and **blocked all recording loads under NumPy 2.x**.
+- **`picks` comma lists**: `plot_psd` / `plot_epochs_image` now accept `"O1,Oz,O2"` (split via
+  `operations._parse_picks`) instead of treating the whole string as one nonexistent channel.
+- Docs: corrected the unit-test count in `docs/INTRODUCTION.md` (31 → 39).
+
+## [0.1.0]
+
+- Initial release: 38-tool MCP server for MNE-Python (EEG/MEG/sEEG/ECoG/fNIRS), persistent
+  in-memory session, `mne_run_code` escape hatch, one-command multi-client setup, and the
+  `mne-analyst` + `mne-mcp-guard` skills.

mne_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to MNE-MCP
+
+Thanks for your interest in improving MNE-MCP. This guide covers the dev setup, the test/lint
+workflow, and how the project is released.
+
+## Development setup
+
+```bash
+git clone https://github.com/Exekiel179/MNE-MCP.git
+cd MNE-MCP
+python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[ica,dev]"                        # or ".[full,dev]" for the advanced tools
+```
+
+`status` confirms the environment:
+
+```bash
+mne-mcp status
+```
+
+## Tests
+
+```bash
+pytest -q                                          # fast unit tests (synthetic data, no downloads)
+pytest -q --cov=mne_mcp --cov-report=term-missing  # with coverage
+python tests/smoke_pipeline.py                     # synthetic end-to-end smoke
+python tests/smoke_eegbci.py                       # REAL-data smoke (downloads PhysioNet eegbci)
+```
+
+- Unit tests must stay fast and **offline** (synthetic data only).
+- The real-data smoke (`smoke_eegbci.py`) downloads a small public dataset; it **skips cleanly** if
+  the network is unavailable so it never flakes CI.
+- Advanced tools (connectivity, source, decoding) need the `[full]` extra; tests that require an
+  optional package guard it with `pytest.importorskip(...)`.
+
+## Lint / formatting
+
+The project uses **black** (line length 88) and **isort** (black profile). CI checks both:
+
+```bash
+black src tests
+isort --profile black src tests
+```
+
+## Adding an analysis skill
+
+Analysis skills live in `skills/` and follow the suite contract documented in
+`skills/MNE_ANALYSIS_SUITE.md`: a three-phase **GRILL → ANALYZE → CRITIC** workflow, with
+methodology review delegated to `mne-methodology-critic`. Use `mne-spectral` as the template, keep
+each skill self-contained (it is installed per-folder by `mne-mcp setup`), and add the skill name to
+`SKILL_NAMES` in `src/mne_mcp/claude_config.py`.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on every push/PR to `main`:
+
+- **unit** — Linux/macOS/Windows × Python 3.10/3.12 (with coverage)
+- **numpy-compat** — NumPy 1.x and 2.x
+- **real-data-smoke** — the eegbci Berger-effect end-to-end
+- **lint** — black + isort
+
+All jobs must be green to merge.
+
+## Releasing
+
+1. Update `CHANGELOG.md` and bump `src/mne_mcp/_version.py`.
+2. Tag the release: `git tag v0.x.y && git push --tags`.
+3. `.github/workflows/release.yml` builds the sdist/wheel and publishes to PyPI via
+   [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (configure the PyPI publisher for
+   this repo once, no stored token needed).
+
+## Reporting issues
+
+Use the issue templates under `.github/ISSUE_TEMPLATE/`. For analysis bugs, include the recording
+format, the `mne_check_status` output, and the failing tool call.

mne_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MNE MCP Contributors
+
+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.