mne-docs-mcp 1.0.29 → 1.0.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +137 -176
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,32 +1,55 @@
1
1
  # MNE Docs MCP Server
2
2
 
3
- MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum across the MNE ecosystem.
3
+ MCP server for MNE ecosystem docs, source code, issues, and forum content.
4
4
 
5
- ## Quick Start
5
+ ## What You Get
6
+
7
+ - 15 read-only MCP tools for docs/code/issues/forum/error lookup
8
+ - HTTP transport (`/mcp`) and stdio transport
9
+ - Python AST-based symbol parsing (no extra Python packages required)
10
+ - Built-in caching and GitHub rate-limit aware behavior
11
+ - Multi-package support across the MNE ecosystem for most code/docs tools
12
+
13
+ ## Requirements
14
+
15
+ - Node.js `>=20`
16
+ - Python 3 (`python` on Windows, `python3` on Linux/macOS)
17
+ - GitHub token (`MNE_GITHUB_TOKEN`) with access to public repositories
18
+
19
+ ## Quick Start (Local HTTP)
6
20
 
7
21
  ```bash
8
- # Clone and install
9
22
  git clone https://github.com/weiyongxu/mne-docs-mcp.git
10
23
  cd mne-docs-mcp
11
24
  npm install
25
+ npm run build
26
+ ```
12
27
 
13
- # Set GitHub token (required)
14
- export MNE_GITHUB_TOKEN=ghp_your_token_here # Linux/macOS
15
- $env:MNE_GITHUB_TOKEN="ghp_your_token_here" # Windows PowerShell
28
+ Set token:
16
29
 
17
- # Start server
18
- npm start
30
+ ```bash
31
+ # Linux/macOS
32
+ export MNE_GITHUB_TOKEN=ghp_your_token_here
33
+
34
+ # Windows PowerShell
35
+ $env:MNE_GITHUB_TOKEN="ghp_your_token_here"
19
36
  ```
20
37
 
21
- Server runs on `http://127.0.0.1:8000` by default. Verify with `curl http://localhost:8000/health`.
38
+ Start server:
39
+
40
+ ```bash
41
+ npm start
42
+ ```
22
43
 
23
- > **Prerequisites:** Node.js ≥ 20 and Python 3 (used for AST parsing — no pip packages required).
44
+ Default endpoint: `http://127.0.0.1:8000/mcp`
45
+ Health check: `http://127.0.0.1:8000/health`
46
+ Metrics: `http://127.0.0.1:8000/metrics`
24
47
 
25
48
  ## MCP Client Integration
26
49
 
27
- ### Claude Desktop / Kiro / Claude Code
50
+ ### Stdio Mode (Claude Desktop / Kiro / Claude Code)
28
51
 
29
- Add to your MCP config (`claude_desktop_config.json`, `.kiro/settings/mcp.json`, or `~/.claude/settings.json`):
52
+ Use `dist/index.js` and set `MNE_TRANSPORT=stdio`:
30
53
 
31
54
  ```json
32
55
  {
@@ -43,18 +66,8 @@ Add to your MCP config (`claude_desktop_config.json`, `.kiro/settings/mcp.json`,
43
66
  }
44
67
  ```
45
68
 
46
- > **Note:** On Windows, `MNE_PYTHON_PATH` defaults to `python` automatically.
47
-
48
- ### Remote HTTP Server
49
-
50
- If you're running the server on a VPS or remote host:
51
-
52
- **Claude Code CLI:**
53
- ```bash
54
- claude mcp add --transport http mne-docs https://your-server.com/mcp
55
- ```
69
+ ### Remote HTTP Mode
56
70
 
57
- **Config file** (`.mcp.json` or `~/.claude.json`):
58
71
  ```json
59
72
  {
60
73
  "mcpServers": {
@@ -66,199 +79,147 @@ claude mcp add --transport http mne-docs https://your-server.com/mcp
66
79
  }
67
80
  ```
68
81
 
69
- ### Local HTTP Mode
82
+ ## Docker
70
83
 
71
84
  ```bash
72
- MNE_TRANSPORT=http npm start
73
- # Connect to http://localhost:8000/mcp
85
+ docker run -p 8000:8000 \
86
+ -e MNE_GITHUB_TOKEN=ghp_your_token_here \
87
+ ghcr.io/weiyongxu/mne-docs-mcp:latest
74
88
  ```
75
89
 
76
- **HTTP endpoints:**
77
-
78
- | Endpoint | Description |
79
- |----------|-------------|
80
- | `POST /mcp` | MCP protocol (JSON-RPC) |
81
- | `GET /health` | Health check — returns `{"status":"healthy"}` |
82
- | `GET /metrics` | Runtime metrics (request counts, cache hit rate, GitHub rate limit) |
83
-
84
- ### Docker
90
+ Or use the included `docker-compose.yml`:
85
91
 
86
92
  ```bash
87
- docker run -p 8000:8000 -e MNE_GITHUB_TOKEN=ghp_your_token ghcr.io/weiyongxu/mne-docs-mcp:latest
88
- ```
89
-
90
- Multi-arch images available for both `linux/amd64` and `linux/arm64`.
91
-
92
- ### Docker Compose
93
+ # Linux/macOS
94
+ export MNE_GITHUB_TOKEN=ghp_your_token_here
93
95
 
94
- Create a `docker-compose.yml`:
96
+ # Windows PowerShell
97
+ $env:MNE_GITHUB_TOKEN="ghp_your_token_here"
95
98
 
96
- ```yaml
97
- services:
98
- mne-docs-mcp:
99
- image: ghcr.io/weiyongxu/mne-docs-mcp:latest
100
- container_name: mne-docs-mcp
101
- ports:
102
- - "8000:8000"
103
- environment:
104
- - MNE_GITHUB_TOKEN=${MNE_GITHUB_TOKEN:?MNE_GITHUB_TOKEN is required}
105
- restart: unless-stopped
99
+ docker compose pull
100
+ docker compose up -d
106
101
  ```
107
102
 
108
- Then run:
103
+ The compose file only requires `MNE_GITHUB_TOKEN`. Other settings use image defaults.
104
+
105
+ ## Tool List
106
+
107
+ - `list_mne_versions`
108
+ - `get_mne_file`
109
+ - `get_mne_doc`
110
+ - `find_mne_symbol`
111
+ - `search_mne_docs`
112
+ - `search_mne_issues`
113
+ - `get_mne_issue`
114
+ - `get_mne_issue_comments`
115
+ - `search_mne_forum`
116
+ - `get_mne_forum_topic`
117
+ - `get_symbol_references`
118
+ - `get_related_symbols`
119
+ - `get_mne_changelog`
120
+ - `get_mne_example`
121
+ - `lookup_mne_error`
122
+
123
+ ## Package Support
124
+
125
+ Supported packages:
126
+
127
+ - `mne-python` (default)
128
+ - `mne-bids-pipeline`
129
+ - `mne-bids`
130
+ - `mne-connectivity`
131
+ - `mne-nirs`
132
+ - `mne-rsa`
133
+ - `mne-icalabel`
134
+ - `mne-realtime`
135
+ - `mne-lsl`
136
+ - `mne-gui-addons`
137
+
138
+ `package` parameter is supported by code/docs/issues/changelog/example/symbol tools.
139
+ Forum tools (`search_mne_forum`, `get_mne_forum_topic`) and `lookup_mne_error` do not take a `package` parameter.
109
140
 
110
- ```bash
111
- export MNE_GITHUB_TOKEN=ghp_your_token_here
112
- docker-compose up -d
113
- docker-compose logs -f
114
- ```
141
+ ## Configuration
115
142
 
116
- ## Tools
117
-
118
- | Tool | Description |
119
- |------|-------------|
120
- | `list_mne_versions` | List available MNE releases |
121
- | `get_mne_file` | Fetch source code |
122
- | `get_mne_doc` | Get symbol documentation |
123
- | `find_mne_symbol` | Search for symbols |
124
- | `search_mne_docs` | Unified code/docs search |
125
- | `search_mne_issues` | Search GitHub issues |
126
- | `get_mne_issue` | Get issue details |
127
- | `get_mne_issue_comments` | Get issue comments |
128
- | `search_mne_forum` | Search community forum |
129
- | `get_mne_forum_topic` | Get full forum discussion |
130
- | `get_symbol_references` | Get callees/callers |
131
- | `get_related_symbols` | Find related functions |
132
- | `get_mne_changelog` | Get version changes |
133
- | `get_mne_example` | Get tutorial code |
134
- | `lookup_mne_error` | Diagnose MNE errors |
135
-
136
- 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`.
143
+ Key environment variables:
137
144
 
138
- ## Configuration
145
+ | Variable | Default | Notes |
146
+ |---|---|---|
147
+ | `MNE_GITHUB_TOKEN` | — | Required |
148
+ | `MNE_TRANSPORT` | `http` | `http` or `stdio` |
149
+ | `MNE_HOST` | `127.0.0.1` | Use `0.0.0.0` in containers |
150
+ | `MNE_PORT` | `8000` | HTTP mode port |
151
+ | `MNE_ALLOWED_ORIGINS` | `*` | CORS/Origin allowlist |
152
+ | `MNE_DEFAULT_PACKAGE` | `mne-python` | Default package |
153
+ | `MNE_PYTHON_PATH` | `python` (Win) / `python3` (Unix) | Parser executable |
154
+ | `MNE_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
155
+ | `MNE_LOG_JSON` | `false` | Structured logs |
139
156
 
140
- | Variable | Description | Default |
141
- |----------|-------------|---------|
142
- | `MNE_GITHUB_TOKEN` | GitHub PAT (**required**) | — |
143
- | `MNE_PORT` | Server port (HTTP mode) | `8000` |
144
- | `MNE_HOST` | Bind address (use `0.0.0.0` in Docker) | `127.0.0.1` |
145
- | `MNE_TRANSPORT` | `http` or `stdio` | `http` |
146
- | `MNE_ALLOWED_ORIGINS` | Comma-separated origins for CORS (use `*` to allow all) | `*` |
147
- | `MNE_DEFAULT_PACKAGE` | Default MNE package | `mne-python` |
148
- | `MNE_PYTHON_PATH` | Python executable path | `python` (Win) / `python3` (Unix) |
149
- | `MNE_LOG_LEVEL` | `debug` / `info` / `warn` / `error` | `info` |
150
- | `MNE_LOG_JSON` | Emit logs as JSON (useful for log aggregators) | `false` |
157
+ See [.env.example](.env.example) for a minimal local template.
151
158
 
152
- See `.env.example` for advanced options: cache TTLs (`MNE_CACHE_TTL_MINUTES`, `MNE_SYMBOL_CACHE_TTL_MINUTES`, `MNE_FILE_CACHE_TTL_MINUTES`), timeouts (`MNE_GITHUB_TIMEOUT`, `MNE_PARSER_TIMEOUT`, `MNE_FORUM_TIMEOUT`), and API base URLs.
159
+ ## Testing and Diagnostics
153
160
 
154
- ## Architecture
161
+ Full tool test run:
155
162
 
163
+ ```bash
164
+ node scripts/run-tests.mjs
156
165
  ```
157
- ┌─────────────────────────────────────────────────────────┐
158
- │ TypeScript Server (Node.js) │
159
- │ ├─ MCP Tools (McpServer API, SDK v1.18+) │
160
- │ │ · Tool annotations (readOnly, idempotent, etc.) │
161
- │ │ · Structured output + resource_link content │
162
- │ ├─ GitHub Client (rate limiting, caching) │
163
- │ └─ Python Parser Bridge ──┐ │
164
- └────────────────────────────┼────────────────────────────┘
165
- ▼
166
- ┌─────────────────┐
167
- │ Python Parser │
168
- │ (AST, stdlib) │
169
- └─────────────────┘
170
- ```
171
-
172
- Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk). This server conforms to the [Model Context Protocol specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) (tool annotations, structured output, resource links, Origin validation, Streamable HTTP).
173
166
 
174
- ## Development
167
+ Against another endpoint:
175
168
 
176
169
  ```bash
177
- npm run dev # Watch mode
178
- npm run build # Compile TypeScript
179
- npm test # Run tests
180
- npm run lint # ESLint
170
+ MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-tests.mjs
181
171
  ```
182
172
 
183
- ## Releasing
184
-
185
- ### One-command release
173
+ Add timeout guard:
186
174
 
187
175
  ```bash
188
- npm run release:patch # 1.0.0 → 1.0.1 (bug fixes)
189
- npm run release:minor # 1.0.0 → 1.1.0 (new features)
190
- npm run release:major # 1.0.0 → 2.0.0 (breaking changes)
176
+ MNE_TOOL_TIMEOUT_MS=20000 node scripts/run-tests.mjs
191
177
  ```
192
178
 
193
- This script (`scripts/release.js`) does everything locally:
194
- 1. Bumps version in `package.json` and `server.json`
195
- 2. Commits both files
196
- 3. Creates a `v*` git tag
197
- 4. Pushes the commit and tag
198
-
199
- Pushing the tag triggers the release pipeline automatically — no further action needed.
179
+ Stable benchmark mode (for slow/stuck investigation):
200
180
 
201
- ### CI/CD pipeline
181
+ ```bash
182
+ node scripts/run-tests.mjs --benchmark-stable --warm-pass --stable-runs 3
183
+ ```
202
184
 
203
- Two GitHub Actions workflows handle all automation:
185
+ ## Development
204
186
 
205
- **`ci.yml`** — runs on every push and pull request:
206
- - TypeScript type checking + ESLint
207
- - Full test suite (Vitest)
208
- - Build verification
209
- - Docker image build test (no push)
187
+ ```bash
188
+ npm run dev
189
+ npm run typecheck
190
+ npm run lint
191
+ npm test
192
+ npm run build
193
+ ```
210
194
 
211
- **`release.yml`** — runs only when a `v*` tag is pushed:
195
+ ## Release
212
196
 
213
- ```
214
- test ──┬── docker (linux/amd64) ──┐
215
- │ ├── docker manifest (semver tags) ──┐
216
- │── docker (linux/arm64) ──┘ ├── GitHub Release
217
- │ │
218
- ├── npm publish ── MCP Registry ──────────────────────────────┘
197
+ ```bash
198
+ npm run release:patch # or :minor / :major
219
199
  ```
220
200
 
221
- Published artefacts per release:
201
+ The release script:
222
202
 
223
- | Platform | Tag / identifier |
224
- |----------|-----------------|
225
- | GHCR Docker | `ghcr.io/weiyongxu/mne-docs-mcp:1.x.y`, `:1.x`, `:latest` |
226
- | npm | `mne-docs-mcp@1.x.y` |
227
- | MCP Registry | `io.github.weiyongxu/mne-docs@1.x.y` |
228
- | GitHub Releases | auto-generated changelog |
203
+ 1. Bumps version (`package.json`)
204
+ 2. Updates `server.json`
205
+ 3. Stages `package.json`, `package-lock.json`, `server.json`
206
+ 4. Commits (`Release vX.Y.Z`)
207
+ 5. Tags (`vX.Y.Z`)
208
+ 6. Pushes commit and tag
229
209
 
230
- ### Required repository secrets
210
+ Tag push triggers `release.yml`, which publishes:
231
211
 
232
- | Secret | Purpose |
233
- |--------|---------|
234
- | `NPM_TOKEN` | Publish to npm registry |
235
- | `GITHUB_TOKEN` | Push Docker to GHCR + create GitHub Release (auto-provided) |
236
-
237
- OIDC is used for MCP Registry authentication (no extra secret needed).
212
+ - GHCR Docker image
213
+ - npm package
214
+ - MCP Registry entry
215
+ - GitHub Release
238
216
 
239
217
  ## Troubleshooting
240
218
 
241
- - **Rate limits:** Ensure `MNE_GITHUB_TOKEN` is set
242
- - **Parser fails:** Check Python 3 is installed (path auto-detected per platform)
243
- - **Test setup:** Run `node scripts/run-tests.mjs` to verify (requires the server running on your MCP endpoint)
244
- - By default the test runner targets `http://localhost:8000/mcp`
245
- - Override with `MNE_MCP_BASE`, e.g.:
246
-
247
- ```bash
248
- # Local server on a non-default port
249
- MNE_MCP_BASE=http://localhost:8004/mcp node scripts/run-tests.mjs
250
-
251
- # Remote HTTP server
252
- MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-tests.mjs
253
- ```
254
-
255
- ## Security
256
-
257
- - GitHub token needs only `public_repo` scope — never commit tokens to version control
258
- - Python parser uses `ast.parse()` only (no code execution)
259
- - HTTP mode validates the `Origin` header when `MNE_ALLOWED_ORIGINS` is set (comma-separated list); use `*` to allow all (default)
260
- - By default the server binds to `127.0.0.1`; set `MNE_HOST=0.0.0.0` only when needed (e.g. in Docker)
261
- - For production: restrict outbound to `api.github.com` and `mne.discourse.group`, don't expose to public internet
219
+ - `401` / `Bad credentials`: verify `MNE_GITHUB_TOKEN`
220
+ - slow code-search tools: use benchmark mode and check `/metrics`
221
+ - parser failures: verify Python path (`MNE_PYTHON_PATH`)
222
+ - endpoint check: `/health` should return `status=healthy`
262
223
 
263
224
  ## License
264
225
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mne-docs-mcp",
3
- "version": "1.0.29",
3
+ "version": "1.0.30",
4
4
  "mcpName": "io.github.weiyongxu/mne-docs",
5
5
  "description": "MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum",
6
6
  "type": "module",