mne-docs-mcp 1.0.18 → 1.0.20

package/README.md

@@ -11,7 +11,8 @@ cd mne-docs-mcp
 npm install
 
 # Set GitHub token (required)
-export MNE_GITHUB_TOKEN=ghp_your_token_here
+export MNE_GITHUB_TOKEN=ghp_your_token_here   # Linux/macOS
+$env:MNE_GITHUB_TOKEN="ghp_your_token_here"   # Windows PowerShell
 
 # Start server
 npm start
@@ -19,6 +20,8 @@ npm start
 
 Server runs on `http://localhost:8000`. Verify with `curl http://localhost:8000/health`.
 
+> **Prerequisites:** Node.js ≥ 20 and Python 3 (used for AST parsing — no pip packages required).
+
 ## MCP Client Integration
 
 ### Claude Desktop / Kiro / Claude Code
@@ -70,6 +73,14 @@ MNE_TRANSPORT=http npm start
 # Connect to http://localhost:8000/mcp
 ```
 
+**HTTP endpoints:**
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /mcp` | MCP protocol (JSON-RPC) |
+| `GET /health` | Health check — returns `{"status":"ok"}` |
+| `GET /metrics` | Runtime metrics (request counts, cache hit rate, GitHub rate limit) |
+
 ### Docker
 
 ```bash
@@ -128,14 +139,15 @@ All tools support a `package` parameter to query across the MNE ecosystem: `mne-
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MNE_GITHUB_TOKEN` | GitHub PAT (required) | - |
-| `MNE_PORT` | Server port | `8000` |
+| `MNE_GITHUB_TOKEN` | GitHub PAT (**required**) | — |
+| `MNE_PORT` | Server port (HTTP mode) | `8000` |
 | `MNE_TRANSPORT` | `http` or `stdio` | `http` |
 | `MNE_DEFAULT_PACKAGE` | Default MNE package | `mne-python` |
-| `MNE_PYTHON_PATH` | Python executable | `python` (Win) / `python3` (Unix) |
-| `MNE_LOG_LEVEL` | `debug`/`info`/`warn`/`error` | `info` |
+| `MNE_PYTHON_PATH` | Python executable path | `python` (Win) / `python3` (Unix) |
+| `MNE_LOG_LEVEL` | `debug` / `info` / `warn` / `error` | `info` |
+| `MNE_LOG_JSON` | Emit logs as JSON (useful for log aggregators) | `false` |
 
-See `.env.example` for all options including cache TTLs and timeouts.
+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.
 
 ## Architecture
 
@@ -166,26 +178,65 @@ npm run lint         # ESLint
 
 ## Releasing
 
-First-time setup (one-time only):
+### One-command release
+
 ```bash
-npm login
-npm publish
+npm run release:patch   # 1.0.0 → 1.0.1  (bug fixes)
+npm run release:minor   # 1.0.0 → 1.1.0  (new features)
+npm run release:major   # 1.0.0 → 2.0.0  (breaking changes)
 ```
 
-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 script (`scripts/release.js`) does everything locally:
+1. Bumps version in `package.json` and `server.json`
+2. Commits both files
+3. Creates a `v*` git tag
+4. Pushes the commit and tag
+
+Pushing the tag triggers the release pipeline automatically — no further action needed.
+
+### CI/CD pipeline
+
+Two GitHub Actions workflows handle all automation:
+
+**`ci.yml`** — runs on every push and pull request:
+- TypeScript type checking + ESLint
+- Full test suite (Vitest)
+- Build verification
+- Docker image build test (no push)
+
+**`release.yml`** — runs only when a `v*` tag is pushed:
+
+```
+test ──┬── docker (linux/amd64) ──┐
+       │                          ├── docker manifest (semver tags) ──┐
+       │── docker (linux/arm64) ──┘                                   ├── GitHub Release
+       │                                                              │
+       ├── npm publish ── MCP Registry ──────────────────────────────┘
 ```
 
-This bumps versions, commits, tags, and pushes. GitHub Actions then publishes to npm and MCP Registry automatically.
+Published artefacts per release:
+
+| Platform | Tag / identifier |
+|----------|-----------------|
+| GHCR Docker | `ghcr.io/weiyongxu/mne-docs-mcp:1.x.y`, `:1.x`, `:latest` |
+| npm | `mne-docs-mcp@1.x.y` |
+| MCP Registry | `io.github.weiyongxu/mne-docs@1.x.y` |
+| GitHub Releases | auto-generated changelog |
+
+### Required repository secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `NPM_TOKEN` | Publish to npm registry |
+| `GITHUB_TOKEN` | Push Docker to GHCR + create GitHub Release (auto-provided) |
+
+OIDC is used for MCP Registry authentication (no extra secret needed).
 
 ## Troubleshooting
 
 - **Rate limits:** Ensure `MNE_GITHUB_TOKEN` is set
 - **Parser fails:** Check Python 3 is installed (path auto-detected per platform)
-- **Test setup:** Run `npx tsx examples/mcp-client.ts` to verify
+- **Test setup:** Run `npx tsx examples/mcp-client.ts` to verify (requires dev dependencies — run `npm install` first)
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mne-docs-mcp",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "mcpName": "io.github.weiyongxu/mne-docs",
   "description": "MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum",
   "type": "module",