bci-mcp 0.1.0__tar.gz

bci_mcp-0.1.0/.cursor/rules/git-commits.mdc

@@ -0,0 +1,22 @@
+---
+description: Git commit rules — never add Co-authored-by trailers
+alwaysApply: true
+---
+
+# Git commits
+
+**Never add `Co-authored-by` trailers to commit messages.**
+
+This includes and is not limited to:
+
+- `Co-authored-by: Cursor <cursoragent@cursor.com>`
+- `Co-authored-by: Claude ...`
+- Any other AI or agent co-author line
+
+When committing:
+
+1. Write the commit message yourself in a HEREDOC or `-m` flag — do not rely on tooling that auto-appends co-authors.
+2. Before pushing, verify with `git log -1 --format='%B'` that no `Co-authored-by:` line is present.
+3. If one appears, amend the commit and remove it before pushing.
+
+The repository owner does not want AI tools listed as co-authors in git history.

bci_mcp-0.1.0/.env

@@ -0,0 +1 @@
+UV_PUBLISH_TOKEN=pypi-AgEIcHlwaS5vcmcCJDU2NzI1YzFjLWViNDUtNGY4Ni05ZTg4LWE5NjQ0MDRhNjczNAACKlszLCI5NGNmMDIzNS0yMTM1LTRhZTItOGE2Zi1lM2QyYjgyMDNlZjUiXQAABiAhWpMnw6i6SL9CmArvgm-LGvjsp-LQnOj8SOB1FndIew

bci_mcp-0.1.0/.githooks/prepare-commit-msg

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Strip AI co-author trailers that Cursor/IDE tooling may inject.
+tmp=$(mktemp)
+sed \
+  -e '/^Co-authored-by: Cursor <cursoragent@cursor.com>$/d' \
+  -e '/^Co-authored-by: Claude /d' \
+  "$1" > "$tmp" && mv "$tmp" "$1"

bci_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev,docs]"
+      - run: ruff check src tests
+      - run: python -m pytest
+      - run: mkdocs build --strict

bci_mcp-0.1.0/.github/workflows/deploy-pages.yml

@@ -0,0 +1,46 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'hooks.py'
+      - 'llms.txt'
+      - '.nojekyll'
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/deploy-pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

bci_mcp-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+venv/
+env/
+.env/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Data files
+recordings/
+*.npz
+*.csv
+*.pkl
+
+# Logs
+logs/
+*.log
+
+# Generated documentation
+site/
+
+# OS specific files
+.DS_Store
+Thumbs.db

bci_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,36 @@
+# Agent instructions (Cursor, Claude Code, Copilot, etc.)
+
+Read this file before making git commits or opening PRs in this repository.
+
+## Git commits — mandatory
+
+**Do not add `Co-authored-by` trailers to any commit message.**
+
+Forbidden examples:
+
+```
+Co-authored-by: Cursor <cursoragent@cursor.com>
+Co-authored-by: Claude Opus ... <noreply@anthropic.com>
+```
+
+The human author is the only author. AI assistants may help write code and commit messages, but must not be credited in git metadata.
+
+Before every push:
+
+```bash
+git log -1 --format='%B' | rg 'Co-authored-by'
+```
+
+If that matches anything, amend the commit and remove the trailer before pushing.
+
+**Cursor injects `Co-authored-by: Cursor <cursoragent@cursor.com>` automatically.** This repo sets `core.hooksPath` to `.githooks/` so `prepare-commit-msg` strips those lines on every commit. After cloning, run:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+## Other conventions
+
+- Run `ruff check src tests && python -m pytest` before PRs.
+- Docs: `pip install -e ".[docs]" && mkdocs build --strict`.
+- See [CLAUDE.md](CLAUDE.md) for architecture and package layout.

bci_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+- Device-agnostic EEG acquisition: synthetic, NeuroFocus (serial + BLE), OpenBCI/Muse via BrainFlow, LSL, generic serial, recording playback.
+- DSP pipeline: band powers (δ θ α β γ), focus/calm/attention/engagement/fatigue/meditation metrics, signal quality + artifacts, calibration.
+- Real Model Context Protocol server (FastMCP, stdio) with tools, resources, and a prompt.
+- CLI: devices, stream, record, play, neurofeedback, dashboard, serve.
+- Recording (CSV/npz/EDF) + replay, neurofeedback trainer, LSL publisher, FastAPI web dashboard.

bci_mcp-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use BCI-MCP in your research, please cite it."
+title: "BCI-MCP: Plug your brain into any AI"
+abstract: "A Model Context Protocol server that streams live EEG brain state from any EEG device into AI assistants."
+authors:
+  - family-names: Ganbold
+    given-names: Enkhbold
+repository-code: "https://github.com/enkhbold470/bci-mcp"
+url: "https://enkhbold470.github.io/bci-mcp/"
+license: MIT
+keywords:
+  - EEG
+  - brain-computer interface
+  - Model Context Protocol
+  - neurofeedback
+  - BrainFlow

bci_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Git commits
+
+**Never add `Co-authored-by` trailers** (Cursor, Claude, or any AI). See [AGENTS.md](AGENTS.md). Verify with `git log -1 --format='%B'` before pushing.
+
+## What this project is
+
+**BCI-MCP** is a Python package (`src/bci_mcp/`) that provides:
+
+- **Device-agnostic EEG acquisition** via a URI registry (synthetic, NeuroFocus serial+BLE, BrainFlow/OpenBCI/Muse, LSL, generic serial, recording playback).
+- **A real MCP server** built on the official MCP Python SDK (`mcp` on PyPI, `FastMCP`), exposing live brain state to Claude Desktop and any MCP client over stdio.
+- **A DSP pipeline** that turns raw EEG into `BrainState` (focus, calm, attention, engagement, fatigue, meditation + δθαβγ band powers + signal quality).
+- **A Rich CLI** with commands: `devices`, `stream`, `record`, `play`, `neurofeedback`, `dashboard`, `serve`.
+- **Recording** (CSV/npz/EDF) + replay, neurofeedback trainer, LSL publisher, FastAPI web dashboard.
+
+## Package layout
+
+```
+src/bci_mcp/
+├── __init__.py            # triggers device registration; __version__ = "0.1.0"
+├── cli.py                 # Typer CLI (entry point: bci-mcp)
+├── pipeline.py            # Pipeline: Device → Stream → DSP → BrainState
+├── core/
+│   ├── device.py          # Device ABC, Chunk, DeviceInfo dataclasses
+│   ├── registry.py        # URI registry (register/create_device/discover)
+│   ├── ringbuffer.py      # RingBuffer
+│   └── stream.py          # Stream (background thread polling device.read())
+├── devices/
+│   ├── synthetic.py       # SyntheticDevice — no hardware needed
+│   ├── neurofocus.py      # NeuroFocus v4 (serial + BLE)
+│   ├── brainflow_device.py # BrainFlow (OpenBCI, Muse, ...)
+│   ├── lsl_device.py      # LSL consumer
+│   ├── serial_device.py   # Generic serial (1 int/line)
+│   └── playback.py        # PlaybackDevice (npz/csv/edf replay)
+├── dsp/
+│   ├── filters.py         # bandpass + notch (zero-phase, scipy.signal.filtfilt)
+│   ├── bands.py           # band_powers() via Welch PSD, relative_band_powers()
+│   ├── metrics.py         # raw_metrics() — focus/calm/attention/engagement/fatigue/meditation
+│   ├── state.py           # BrainState dataclass
+│   ├── quality.py         # assess_quality() — signal score + artifact flags
+│   └── calibration.py     # Calibration — personalized min/max scaling
+├── mcp/
+│   ├── server.py          # FastMCP tools/resources/prompt + serve()
+│   └── service.py         # BrainService — testable core (server.py wraps this)
+├── recording/
+│   ├── recorder.py        # Recorder stream consumer
+│   ├── writer.py          # save_recording() — npz/csv/edf
+│   └── reader.py          # load_recording() → Recording dataclass
+├── neurofeedback/
+│   └── trainer.py         # NeurofeedbackSession
+├── lsl/
+│   └── publisher.py       # LSL outlet publisher
+└── dashboard/
+    └── server.py          # FastAPI web dashboard
+```
+
+## Install and run
+
+```bash
+pip install -e ".[all,dev]"          # all extras + dev tools
+
+bci-mcp devices                      # list URI schemes + discovered hardware
+bci-mcp stream --device synthetic:// # live terminal brain-meter
+bci-mcp stream --device synthetic:// --once   # single snapshot (good for CI smoke)
+bci-mcp record --device synthetic:// --seconds 10 --out session.npz
+bci-mcp play session.npz
+bci-mcp serve                        # MCP server (stdio)
+```
+
+## Tests
+
+```bash
+ruff check src tests       # linter (must be clean before commit)
+python -m pytest           # runs all tests (80+ hardware-free tests)
+```
+
+All tests are **hardware-free**: synthetic device, recording playback, in-process LSL, BrainFlow synthetic board. No EEG headset needed.
+
+## Architecture
+
+```
+Device.read() → Chunk → Stream (background thread) → RingBuffer
+                                                          │
+Pipeline.current_state() pulls latest N samples, runs:   │
+  filters.bandpass + filters.notch                        │
+  → bands.band_powers (Welch PSD)                         │
+  → metrics.raw_metrics                                   │
+  → calibration.apply → BrainState                        │
+                                                          │
+Consumers: CLI brain-meter, FastMCP server, FastAPI dashboard,
+           Recorder (→ npz/csv/edf), LSL publisher, NeurofeedbackSession
+```
+
+## Device URI registry
+
+Every device backend calls `bci_mcp.core.registry.register(scheme, factory)` at import time. `create_device(uri)` parses the URI and calls the factory. Schemes: `synthetic`, `neurofocus`, `brainflow`, `lsl`, `serial`, `playback`.
+
+## MCP server
+
+`bci_mcp.mcp.server` uses `FastMCP` from the official MCP Python SDK. It runs over **stdio** (the standard for Claude Desktop). Tools: `list_devices`, `connect`, `disconnect`, `get_brain_state`, `get_band_powers`, `get_signal_quality`, `calibrate`, `record`, `start_neurofeedback`, `get_neurofeedback_score`, `mark_event`, `stream_summary`. Resources: `brain://state`, `brain://device`. Prompt: `interpret_brain_state`.
+
+## Design docs
+
+Specs and implementation plans live under `docs/superpowers/`.

bci_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to BCI-MCP
+
+Thanks for your interest! BCI-MCP is a Python project (3.10+).
+
+## Setup
+
+```bash
+python -m pip install -e ".[all,dev]"
+git config core.hooksPath .githooks
+```
+
+The hooks path enables `prepare-commit-msg`, which strips unwanted AI `Co-authored-by` trailers from commits. See [AGENTS.md](AGENTS.md).
+
+## Develop
+
+- Source lives in `src/bci_mcp/`, tests in `tests/`.
+- All tests are hardware-free (synthetic device, recording playback, in-process LSL, BrainFlow synthetic board), so you can run the full suite with no headset.
+- Before opening a PR:
+
+```bash
+ruff check src tests
+python -m pytest
+```
+
+## Adding a device backend
+
+Implement `bci_mcp.core.device.Device`, return `Chunk(data=(channels, n) float32 µV, timestamps=(n,))`, and register a URI scheme via `bci_mcp.core.registry.register(...)`. See `devices/synthetic.py` for the simplest example and `devices/neurofocus.py` for a real-hardware one.
+
+## Design docs
+
+Specs and implementation plans live under `docs/superpowers/`.

bci_mcp-0.1.0/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create directory for recordings
+RUN mkdir -p /app/recordings && chmod 777 /app/recordings
+
+# Create a non-root user to run the application
+RUN useradd -m bciuser && chown -R bciuser:bciuser /app
+USER bciuser
+
+# Default command - start the MCP server
+CMD ["python", "src/main.py", "--server"]
+
+# Expose the WebSocket port
+EXPOSE 8765

bci_mcp-0.1.0/LICENSE

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