mcpmon 0.1.0

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,50 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish --access public
+
+  build-binaries:
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: write
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+          - os: macos-latest
+            target: darwin-arm64
+          - os: macos-13
+            target: darwin-x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Build binary
+        run: bun build --compile mcpmon.ts --outfile mcpmon-${{ matrix.target }}
+
+      - name: Upload to release
+        run: gh release upload ${{ github.ref_name }} mcpmon-${{ matrix.target }} --clobber
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

package/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: 'Version bump type'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Get current version
+        id: current
+        run: |
+          VERSION=$(grep -Po '(?<=version = ")[^"]+' pyproject.toml)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Bump version
+        id: bump
+        run: |
+          IFS='.' read -r major minor patch <<< "${{ steps.current.outputs.version }}"
+          case "${{ inputs.bump }}" in
+            major) major=$((major + 1)); minor=0; patch=0 ;;
+            minor) minor=$((minor + 1)); patch=0 ;;
+            patch) patch=$((patch + 1)) ;;
+          esac
+          NEW_VERSION="$major.$minor.$patch"
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          sed -i "s/version = \"${{ steps.current.outputs.version }}\"/version = \"$NEW_VERSION\"/" pyproject.toml
+
+      - name: Commit and tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "(release): v${{ steps.bump.outputs.version }}"
+          git tag "v${{ steps.bump.outputs.version }}"
+          git push && git push --tags
+
+      - name: Create release
+        run: gh release create "v${{ steps.bump.outputs.version }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -0,0 +1,67 @@
+# mcpmon
+
+Hot reload for MCP servers. Like nodemon, but for MCP.
+
+## Install
+
+```bash
+# Bun (recommended)
+bunx mcpmon
+
+# Or install globally
+bun install -g mcpmon
+
+# Python alternative
+pip install mcpmon
+
+# Or download binary from GitHub releases (no dependencies)
+```
+
+## Usage
+
+```bash
+mcpmon --watch src/ -- python -m my_mcp_server
+```
+
+### Options
+
+- `--watch, -w` - Directory to watch (default: current directory)
+- `--ext, -e` - File extensions to watch, comma-separated (default: py)
+
+### Examples
+
+```bash
+# Watch current directory for .py changes
+mcpmon -- python server.py
+
+# Watch src/ for .py and .json changes
+mcpmon --watch src/ --ext py,json -- python -m myserver
+
+# With crucible-mcp
+mcpmon --watch src/crucible/ -- crucible-mcp
+
+# With sage-mcp
+mcpmon --watch ~/.sage/ --ext py,yaml -- sage-mcp
+```
+
+## MCP Config
+
+Use mcpmon in your `.mcp.json` for hot reload during development:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "mcpmon",
+      "args": ["--watch", "src/", "--", "python", "-m", "my_server"]
+    }
+  }
+}
+```
+
+## How it works
+
+1. Starts your MCP server as a subprocess
+2. Watches specified directory for file changes
+3. On change: SIGTERM → wait 2s → SIGKILL → restart
+4. Claude Code automatically reconnects to the restarted server

package/mcpmon.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""mcpmon: Hot reload for MCP servers. Like nodemon, but for MCP."""
+
+import argparse
+import subprocess
+import signal
+import sys
+from pathlib import Path
+
+from watchfiles import watch, Change
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Hot reload wrapper for MCP servers",
+        usage="mcpmon --watch <dir> [--ext <ext>] -- <command>",
+    )
+    parser.add_argument(
+        "--watch", "-w",
+        type=str,
+        default=".",
+        help="Directory to watch (default: current directory)",
+    )
+    parser.add_argument(
+        "--ext", "-e",
+        type=str,
+        default="py",
+        help="File extensions to watch, comma-separated (default: py)",
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command to run (after --)",
+    )
+    args = parser.parse_args()
+
+    # Remove leading -- from command if present
+    if args.command and args.command[0] == "--":
+        args.command = args.command[1:]
+
+    if not args.command:
+        parser.error("No command specified. Use: mcpmon --watch src/ -- <command>")
+
+    return args
+
+
+def terminate_process(proc: subprocess.Popen) -> None:
+    """Gracefully terminate process: SIGTERM, wait 2s, SIGKILL."""
+    if proc.poll() is not None:
+        return
+
+    proc.terminate()
+    try:
+        proc.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+
+
+def start_process(command: list[str]) -> subprocess.Popen:
+    """Start the MCP server process."""
+    return subprocess.Popen(command)
+
+
+def should_reload(changes: set, extensions: set[str]) -> bool:
+    """Check if any changed file matches our extensions."""
+    for change_type, path in changes:
+        if change_type in (Change.added, Change.modified):
+            if Path(path).suffix.lstrip(".") in extensions:
+                return True
+    return False
+
+
+def main():
+    args = parse_args()
+
+    watch_path = Path(args.watch).resolve()
+    extensions = {ext.strip().lstrip(".") for ext in args.ext.split(",")}
+    command = args.command
+
+    print(f"[mcpmon] Watching {watch_path} for .{', .'.join(extensions)} changes")
+    print(f"[mcpmon] Running: {' '.join(command)}")
+
+    proc = start_process(command)
+
+    # Handle Ctrl+C gracefully
+    def signal_handler(signum, frame):
+        print("\n[mcpmon] Shutting down...")
+        terminate_process(proc)
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    try:
+        for changes in watch(watch_path):
+            if should_reload(changes, extensions):
+                changed_files = [p for _, p in changes]
+                print(f"[mcpmon] Change detected: {', '.join(changed_files)}")
+                print("[mcpmon] Restarting...")
+
+                terminate_process(proc)
+                proc = start_process(command)
+
+                print("[mcpmon] Server restarted")
+    except KeyboardInterrupt:
+        pass
+    finally:
+        terminate_process(proc)
+
+
+if __name__ == "__main__":
+    main()

package/mcpmon.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+/**
+ * mcpmon: Hot reload for MCP servers. Like nodemon, but for MCP.
+ */
+
+import { watch } from "fs";
+import { spawn, type Subprocess } from "bun";
+import { parseArgs } from "util";
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    watch: { type: "string", short: "w", default: "." },
+    ext: { type: "string", short: "e", default: "py" },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  allowPositionals: true,
+  strict: false,
+});
+
+if (values.help || positionals.length === 0) {
+  console.log(`mcpmon - Hot reload for MCP servers
+
+Usage: mcpmon [options] -- <command>
+
+Options:
+  -w, --watch <dir>   Directory to watch (default: .)
+  -e, --ext <exts>    Extensions to watch, comma-separated (default: py)
+  -h, --help          Show this help
+
+Examples:
+  mcpmon -- python server.py
+  mcpmon --watch src/ --ext py,json -- python -m myserver
+  mcpmon --watch src/crucible/ -- crucible-mcp
+`);
+  process.exit(0);
+}
+
+// Remove leading "--" if present
+const command = positionals[0] === "--" ? positionals.slice(1) : positionals;
+
+if (command.length === 0) {
+  console.error("[mcpmon] Error: No command specified");
+  process.exit(1);
+}
+
+const watchDir = values.watch as string;
+const extensions = new Set((values.ext as string).split(",").map(e => e.trim().replace(/^\./, "")));
+
+let proc: Subprocess | null = null;
+
+function startServer(): void {
+  console.log(`[mcpmon] Starting: ${command.join(" ")}`);
+  proc = spawn({
+    cmd: command,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+  });
+}
+
+async function stopServer(): Promise<void> {
+  if (!proc || proc.exitCode !== null) return;
+
+  proc.kill("SIGTERM");
+
+  // Wait up to 2 seconds for graceful shutdown
+  const timeout = setTimeout(() => {
+    if (proc && proc.exitCode === null) {
+      proc.kill("SIGKILL");
+    }
+  }, 2000);
+
+  await proc.exited;
+  clearTimeout(timeout);
+}
+
+async function restartServer(): Promise<void> {
+  await stopServer();
+  startServer();
+}
+
+function shouldReload(filename: string | null): boolean {
+  if (!filename) return false;
+  const ext = filename.split(".").pop() || "";
+  return extensions.has(ext);
+}
+
+// Start server
+console.log(`[mcpmon] Watching ${watchDir} for .${[...extensions].join(", .")} changes`);
+startServer();
+
+// Watch for changes
+const watcher = watch(watchDir, { recursive: true }, async (event, filename) => {
+  if (event === "change" && shouldReload(filename)) {
+    console.log(`[mcpmon] ${filename} changed, restarting...`);
+    await restartServer();
+  }
+});
+
+// Handle shutdown
+process.on("SIGINT", async () => {
+  console.log("\n[mcpmon] Shutting down...");
+  watcher.close();
+  await stopServer();
+  process.exit(0);
+});
+
+process.on("SIGTERM", async () => {
+  watcher.close();
+  await stopServer();
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mcpmon",
+  "version": "0.1.0",
+  "description": "Hot reload for MCP servers. Like nodemon, but for MCP.",
+  "type": "module",
+  "main": "mcpmon.ts",
+  "bin": {
+    "mcpmon": "mcpmon.ts"
+  },
+  "scripts": {
+    "build": "bun build --compile mcpmon.ts --outfile dist/mcpmon"
+  },
+  "keywords": ["mcp", "hot-reload", "nodemon", "bun", "development"],
+  "author": "be.nvy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/b17z/mcpmon"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcpmon"
+version = "0.1.0"
+description = "Hot reload for MCP servers. Like nodemon, but for MCP."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "be.nvy" }]
+keywords = ["mcp", "hot-reload", "development", "nodemon"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "watchfiles>=0.20.0",
+]
+
+[project.scripts]
+mcpmon = "mcpmon:main"
+
+[project.urls]
+Homepage = "https://github.com/b17z/mcpmon"