muscle-memory-mcp 0.1.0__tar.gz

muscle_memory_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+.venv/

muscle_memory_mcp-0.1.0/LICENSE

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

muscle_memory_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: muscle-memory-mcp
+Version: 0.1.0
+Summary: MCP server that gives your agent a library of its own tested, reusable scripts.
+Project-URL: Homepage, https://github.com/johannesloor/muscle-memory
+Project-URL: Repository, https://github.com/johannesloor/muscle-memory
+Project-URL: Issues, https://github.com/johannesloor/muscle-memory/issues
+Author: Johannes Loor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,automation,claude-code,codex,cursor,mcp,mcp-server,model-context-protocol
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+![A tied shoelace bow next to the words Muscle Memory MCP Server](https://raw.githubusercontent.com/johannesloor/muscle-memory/main/assets/banner.png)
+
+# Muscle Memory MCP Server
+
+[![PyPI](https://img.shields.io/pypi/v/muscle-memory-mcp?style=flat-square)](https://pypi.org/project/muscle-memory-mcp/) [![Tests](https://img.shields.io/github/actions/workflow/status/johannesloor/muscle-memory/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/johannesloor/muscle-memory/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+<!-- mcp-name: io.github.johannesloor/muscle-memory -->
+
+Your agent solves problems by writing scripts, then throws them away like they're nothing. Tomorrow it writes the same script again. Like having to figure out how to tie your shoelaces every morning. It lacks muscle memory.
+
+The Muscle Memory MCP server gives your agent an empty library that it fills with its own tested scripts.
+
+## Install
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=muscle-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22muscle-memory-mcp%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=muscle-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22muscle-memory-mcp%22%5D%7D&quality=insiders) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=muscle-memory&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtdXNjbGUtbWVtb3J5LW1jcCJdfQ%3D%3D) [![Install in LM Studio](https://img.shields.io/badge/LM_Studio-Install_Server-4F46E5?style=flat-square)](https://lmstudio.ai/install-mcp?name=muscle-memory&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtdXNjbGUtbWVtb3J5LW1jcCJdfQ%3D%3D)
+
+**Hermes**
+
+```sh
+hermes mcp add muscle-memory --command uvx --args muscle-memory-mcp
+```
+
+**Claude Code**
+
+```sh
+claude mcp add muscle-memory -s user -- uvx muscle-memory-mcp
+```
+
+To keep the library somewhere other than the default, set `MUSCLE_MEMORY_DIR` in the server's environment.
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.muscle-memory]
+command = "uvx"
+args = ["muscle-memory-mcp"]
+# env = { MUSCLE_MEMORY_DIR = "/absolute/path/to/library" }
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "muscle-memory": {
+      "command": "uvx",
+      "args": ["muscle-memory-mcp"]
+    }
+  }
+}
+```
+
+
+## Add to your AGENTS.md
+
+Add this standing rule to your `AGENTS.md`, `CLAUDE.md`, `SOUL.md` or equivalent agent instructions:
+
+```text
+Before writing helper code, check muscle-memory with mm_list and run a match with mm_run.
+After giving the user the result, save reusable new helpers with mm_save.
+Skip this for code that is itself the deliverable.
+```
+
+Tool descriptions contain the safety and testing specifics for each operation.
+
+## First run and storage
+
+The server exposes `mm_list`, `mm_run`, `mm_save` and `mm_setup`. If the personal library has not been set up, the tools guide the agent to ask you once where it should live and then call `mm_setup`.
+
+The personal library defaults to `~/.muscle-memory` (`%USERPROFILE%\.muscle-memory` on Windows); `MUSCLE_MEMORY_DIR` selects another location. Scripts in the personal library are available across projects.
+
+An optional `.muscle-memory/` project library holds scripts specific to one codebase. Project-root detection depends on the MCP client's working directory. Set `MUSCLE_MEMORY_PROJECT_DIR` to the project's absolute path in the server environment to override detection explicitly. When a script name exists in both libraries, the project copy takes precedence; listings mark the personal copy as shadowed.
+
+For personal libraries, saves write files locally if the folder is not in git. If the library is a git repo, each saved script is committed. Setup asks whether to also push scripts to the git remote automatically; run setup again to change your answer. Project libraries are never committed or pushed automatically: you commit them with your own work. On first project setup, the agent asks whether the library should be shared through git or kept private.
+
+## Tools
+
+- **`mm_list(area?)`** — list available areas and script counts, or list scripts in one area.
+- **`mm_run(script, args)`** — run a saved script, passing through arguments.
+- **`mm_save(name, code, test, area, usage, ...)`** — save or update a script after its test passes. Supports runner, test selection, and personal/project scope options; see the tool description for the full schema and safety behavior.
+- **`mm_setup(target, ...)`** — set up a personal library or optional project library. Ask the user before setup; see the tool description for modes and options.
+
+## Advanced: languages and tests
+
+The runner is picked by file extension: Python, bash/zsh, Node, Ruby, Perl, PHP, Swift, Go, Lua, R, PowerShell, and `.cmd`/`.bat` on Windows. Other languages need an explicit runner argv when saved. Runtimes are never installed for you; a missing one gives an error naming the command.
+
+By default a script's test uses the same extension and runner. `test_name` and `test_runner` allow independent test selection. Tests live under `tests/test_<stem>.<ext>`; selection metadata is stored beside the script. Tests receive `MM_SCRIPT` (absolute script path) and `MM_LIBRARY` (library root). Exit status 0 passes; failed tests prevent saving. Replacing a test extension removes the prior test only after the replacement passes.
+
+## Advanced: CLI
+
+The same command is also a CLI:
+
+```sh
+uvx muscle-memory-mcp list [AREA]
+uvx muscle-memory-mcp run SCRIPT [ARGS...]
+uvx muscle-memory-mcp save NAME --code FILE --test FILE --area AREA --usage TEXT
+uvx muscle-memory-mcp setup [--target personal|project] [OPTIONS]
+uvx muscle-memory-mcp test [NAME]
+uvx muscle-memory-mcp trust --project
+```
+
+With no arguments it starts the MCP server over stdio. `--help` lists the options.
+
+## Security and limits
+
+- Scripts and tests run as you, with your environment and no sandbox. Passing tests is not a security review.
+- A project library runs only after you approve the project once with `uvx muscle-memory-mcp trust --project`.
+- Project-library detection depends on the client's working directory; set `MUSCLE_MEMORY_PROJECT_DIR` if needed.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

muscle_memory_mcp-0.1.0/README.md

@@ -0,0 +1,116 @@
+![A tied shoelace bow next to the words Muscle Memory MCP Server](https://raw.githubusercontent.com/johannesloor/muscle-memory/main/assets/banner.png)
+
+# Muscle Memory MCP Server
+
+[![PyPI](https://img.shields.io/pypi/v/muscle-memory-mcp?style=flat-square)](https://pypi.org/project/muscle-memory-mcp/) [![Tests](https://img.shields.io/github/actions/workflow/status/johannesloor/muscle-memory/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/johannesloor/muscle-memory/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+<!-- mcp-name: io.github.johannesloor/muscle-memory -->
+
+Your agent solves problems by writing scripts, then throws them away like they're nothing. Tomorrow it writes the same script again. Like having to figure out how to tie your shoelaces every morning. It lacks muscle memory.
+
+The Muscle Memory MCP server gives your agent an empty library that it fills with its own tested scripts.
+
+## Install
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=muscle-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22muscle-memory-mcp%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=muscle-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22muscle-memory-mcp%22%5D%7D&quality=insiders) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=muscle-memory&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtdXNjbGUtbWVtb3J5LW1jcCJdfQ%3D%3D) [![Install in LM Studio](https://img.shields.io/badge/LM_Studio-Install_Server-4F46E5?style=flat-square)](https://lmstudio.ai/install-mcp?name=muscle-memory&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtdXNjbGUtbWVtb3J5LW1jcCJdfQ%3D%3D)
+
+**Hermes**
+
+```sh
+hermes mcp add muscle-memory --command uvx --args muscle-memory-mcp
+```
+
+**Claude Code**
+
+```sh
+claude mcp add muscle-memory -s user -- uvx muscle-memory-mcp
+```
+
+To keep the library somewhere other than the default, set `MUSCLE_MEMORY_DIR` in the server's environment.
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.muscle-memory]
+command = "uvx"
+args = ["muscle-memory-mcp"]
+# env = { MUSCLE_MEMORY_DIR = "/absolute/path/to/library" }
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "muscle-memory": {
+      "command": "uvx",
+      "args": ["muscle-memory-mcp"]
+    }
+  }
+}
+```
+
+
+## Add to your AGENTS.md
+
+Add this standing rule to your `AGENTS.md`, `CLAUDE.md`, `SOUL.md` or equivalent agent instructions:
+
+```text
+Before writing helper code, check muscle-memory with mm_list and run a match with mm_run.
+After giving the user the result, save reusable new helpers with mm_save.
+Skip this for code that is itself the deliverable.
+```
+
+Tool descriptions contain the safety and testing specifics for each operation.
+
+## First run and storage
+
+The server exposes `mm_list`, `mm_run`, `mm_save` and `mm_setup`. If the personal library has not been set up, the tools guide the agent to ask you once where it should live and then call `mm_setup`.
+
+The personal library defaults to `~/.muscle-memory` (`%USERPROFILE%\.muscle-memory` on Windows); `MUSCLE_MEMORY_DIR` selects another location. Scripts in the personal library are available across projects.
+
+An optional `.muscle-memory/` project library holds scripts specific to one codebase. Project-root detection depends on the MCP client's working directory. Set `MUSCLE_MEMORY_PROJECT_DIR` to the project's absolute path in the server environment to override detection explicitly. When a script name exists in both libraries, the project copy takes precedence; listings mark the personal copy as shadowed.
+
+For personal libraries, saves write files locally if the folder is not in git. If the library is a git repo, each saved script is committed. Setup asks whether to also push scripts to the git remote automatically; run setup again to change your answer. Project libraries are never committed or pushed automatically: you commit them with your own work. On first project setup, the agent asks whether the library should be shared through git or kept private.
+
+## Tools
+
+- **`mm_list(area?)`** — list available areas and script counts, or list scripts in one area.
+- **`mm_run(script, args)`** — run a saved script, passing through arguments.
+- **`mm_save(name, code, test, area, usage, ...)`** — save or update a script after its test passes. Supports runner, test selection, and personal/project scope options; see the tool description for the full schema and safety behavior.
+- **`mm_setup(target, ...)`** — set up a personal library or optional project library. Ask the user before setup; see the tool description for modes and options.
+
+## Advanced: languages and tests
+
+The runner is picked by file extension: Python, bash/zsh, Node, Ruby, Perl, PHP, Swift, Go, Lua, R, PowerShell, and `.cmd`/`.bat` on Windows. Other languages need an explicit runner argv when saved. Runtimes are never installed for you; a missing one gives an error naming the command.
+
+By default a script's test uses the same extension and runner. `test_name` and `test_runner` allow independent test selection. Tests live under `tests/test_<stem>.<ext>`; selection metadata is stored beside the script. Tests receive `MM_SCRIPT` (absolute script path) and `MM_LIBRARY` (library root). Exit status 0 passes; failed tests prevent saving. Replacing a test extension removes the prior test only after the replacement passes.
+
+## Advanced: CLI
+
+The same command is also a CLI:
+
+```sh
+uvx muscle-memory-mcp list [AREA]
+uvx muscle-memory-mcp run SCRIPT [ARGS...]
+uvx muscle-memory-mcp save NAME --code FILE --test FILE --area AREA --usage TEXT
+uvx muscle-memory-mcp setup [--target personal|project] [OPTIONS]
+uvx muscle-memory-mcp test [NAME]
+uvx muscle-memory-mcp trust --project
+```
+
+With no arguments it starts the MCP server over stdio. `--help` lists the options.
+
+## Security and limits
+
+- Scripts and tests run as you, with your environment and no sandbox. Passing tests is not a security review.
+- A project library runs only after you approve the project once with `uvx muscle-memory-mcp trust --project`.
+- Project-library detection depends on the client's working directory; set `MUSCLE_MEMORY_PROJECT_DIR` if needed.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

muscle_memory_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "muscle-memory-mcp"
+dynamic = ["version"]
+description = "MCP server that gives your agent a library of its own tested, reusable scripts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Johannes Loor" }]
+dependencies = []
+keywords = ["mcp", "mcp-server", "model-context-protocol", "ai-agents", "claude-code", "codex",
+            "cursor", "automation"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/johannesloor/muscle-memory"
+Repository = "https://github.com/johannesloor/muscle-memory"
+Issues = "https://github.com/johannesloor/muscle-memory/issues"
+
+[project.scripts]
+muscle-memory-mcp = "muscle_memory_mcp.cli:main"
+
+[tool.hatch.version]
+path = "src/muscle_memory_mcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/muscle_memory_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml", "server.json"]

muscle_memory_mcp-0.1.0/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.johannesloor/muscle-memory",
+  "description": "MCP server that gives your agent a library of its own tested, reusable scripts.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/johannesloor/muscle-memory",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "muscle-memory-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

muscle_memory_mcp-0.1.0/src/muscle_memory_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""muscle-memory-mcp: a personal library of tested, reusable scripts exposed over MCP."""
+
+__version__ = "0.1.0"

muscle_memory_mcp-0.1.0/src/muscle_memory_mcp/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from . import cli
+
+sys.exit(cli.main())

muscle_memory_mcp-0.1.0/src/muscle_memory_mcp/cli.py

@@ -0,0 +1,138 @@
+"""Command-line interface for muscle-memory-mcp.
+
+  muscle-memory-mcp                     run the MCP server (stdio)
+  muscle-memory-mcp list [AREA]          without AREA: all areas with script counts; with AREA: its scripts
+  muscle-memory-mcp run SCRIPT [ARGS...] run a library script, passing ARGS through
+  muscle-memory-mcp save NAME --code F --test F --area AREA --usage TEXT [--new-area] [--no-push]
+                                         add a script + test, run the suite, index, commit
+  muscle-memory-mcp setup [--target personal|project] [options]  set up a library
+  muscle-memory-mcp test [NAME]         without NAME: run every script's own test; with NAME: just that one
+"""
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from . import core, onboarding, paths, server, testing
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    for stream in (sys.stdout, sys.stderr):  # scripts may print any Unicode; never crash on a code page
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    if not argv:
+        server.main()
+        return 0
+    ap = argparse.ArgumentParser(prog="muscle-memory-mcp", description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("list"); s.add_argument("area", nargs="*")
+    r = sub.add_parser("run"); r.add_argument("script"); r.add_argument("args", nargs=argparse.REMAINDER)
+    v = sub.add_parser("save"); v.add_argument("name")
+    v.add_argument("--code", required=True); v.add_argument("--test", required=True)
+    v.add_argument("--area", required=True); v.add_argument("--usage", required=True)
+    v.add_argument("--scope", choices=("personal", "project"), default="personal")
+    v.add_argument("--replace", action="store_true")
+    push_options = v.add_mutually_exclusive_group()
+    push_options.add_argument("--push", action="store_true", help="push this save even if setup chose not to")
+    push_options.add_argument("--no-push", action="store_true", help="don't push this save even if setup chose to")
+    v.add_argument("--new-area", action="store_true", help="allow creating AREA if it does not exist")
+    v.add_argument("--test-name")
+    v.add_argument("--test-runner", help="JSON argv for the test interpreter")
+    v.add_argument("--runner", help="JSON array argv for a custom interpreter, e.g. '[\"bash\"]' or "
+                                    "'[\"deno\", \"run\"]'; only needed for extensions with no built-in runner")
+    setup = sub.add_parser("setup")
+    setup.add_argument("--target", choices=("personal", "project"), default="personal")
+    setup.add_argument("--mode", choices=("local", "existing", "clone"))
+    setup.add_argument("--path"); setup.add_argument("--remote")
+    setup.add_argument("--git", action="store_true")
+    setup.add_argument("--shared", action=argparse.BooleanOptionalAction, default=None,
+                       help="project library: --shared commits it with the project, --no-shared keeps it private")
+    setup.add_argument("--push", action=argparse.BooleanOptionalAction, default=None,
+                       help="personal git library: push scripts to the git remote automatically")
+    t = sub.add_parser("test"); t.add_argument("name", nargs="?",
+                                                help="one script's file name; omit to test every saved script")
+    trust_cmd = sub.add_parser("trust", help="review and explicitly approve a project library")
+    trust_cmd.add_argument("--project", action="store_true", required=True)
+    a = ap.parse_args(argv)
+    try:
+        if a.cmd == "trust":
+            project = paths.project_root()
+            if project is None:
+                raise ValueError("no project library here")
+            root = (project / ".muscle-memory").resolve()
+            if not (root / "INDEX.md").is_file():
+                raise ValueError("no project library here")
+            from . import trust
+            trust.approve(root)
+            print(f"Trusted project library {root}.")
+            return 0
+        if a.cmd == "setup":
+            print(server.call("mm_setup", {"target": a.target, "mode": a.mode, "path": a.path,
+                                            "remote": a.remote, "git": a.git, "shared": a.shared,
+                                            "push": a.push})[0])
+            return 0
+        if a.cmd == "list":
+            text = core.list_areas() if not a.area else core.list_area(" ".join(a.area))
+            print(text)
+            return 3 if text == onboarding.NOT_SET_UP else 0
+        if a.cmd == "run":
+            code, out, err = core.run(a.script, a.args)
+            sys.stdout.write(out); sys.stderr.write(err)
+            return code
+        if a.cmd == "test":
+            if a.name:
+                lib, _ = core.resolve(a.name)
+                jobs = [(lib, a.name)]
+            else:
+                jobs = []
+                for lib in paths.libraries():
+                    scripts_dir = lib.root / "scripts"
+                    if not scripts_dir.exists():
+                        continue
+                    names = sorted(p.name for p in scripts_dir.iterdir()
+                                    if p.is_file() and not p.name.startswith("test_")
+                                    and not p.name.endswith(".runner.json") and not p.name.endswith(".test.json"))
+                    jobs.extend((lib, n) for n in names)
+            passed, failed = 0, []
+            for lib, n in jobs:
+                ok, msg = testing.run_test(lib.root, n)
+                if ok:
+                    passed += 1
+                else:
+                    failed.append(n)
+                    print(f"FAIL {n}\n{msg}")
+            print(f"{passed} passed" + (f", {len(failed)} failed" if failed else ""))
+            return 1 if failed else 0
+        runner = None
+        test_runner = None
+        for option, raw in (("--runner", a.runner), ("--test-runner", a.test_runner)):
+            if raw:
+                try:
+                    parsed = json.loads(raw)
+                except json.JSONDecodeError as e:
+                    raise ValueError(f"{option} must be a JSON array of strings: {e}")
+                if option == "--runner": runner = parsed
+                else: test_runner = parsed
+        ok, msg = core.save(a.name, Path(a.code).read_text(encoding="utf-8"),
+                            Path(a.test).read_text(encoding="utf-8"), a.area, a.usage,
+                            scope=a.scope, new_area=a.new_area, runner=runner,
+                            test_name=a.test_name, test_runner=test_runner,
+                            replace=a.replace, push=True if a.push else False if a.no_push else None)
+        print(msg)
+        if msg == onboarding.NOT_SET_UP:
+            return 3
+        return 0 if ok else 1
+    except (ValueError, OSError, subprocess.SubprocessError) as e:
+        if str(e) == onboarding.NOT_SET_UP:
+            print(onboarding.NOT_SET_UP)
+            return 3
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

muscle_memory_mcp-0.1.0/src/muscle_memory_mcp/core.py

@@ -0,0 +1,158 @@
+"""Core library: list, run and save scripts in the muscle-memory library.
+
+Personal library dir: $MUSCLE_MEMORY_DIR or ~/.muscle-memory; optional project library at the
+project root's .muscle-memory/ (see paths.py). Both have scripts/ and tests/. This module is
+standard library only. Scripts may be in any language: common ones are picked up by file
+extension (see runners.LANGUAGE_RUNNERS); anything else needs an explicit --runner argv.
+Each script's test runs in the script's own language, via testing.run_test() (see testing.py).
+
+list_areas()/list_area()/resolve() see both the personal and (if present) project library,
+labelled by scope, with the project library taking precedence on a name clash. areas()/
+area_lines()/format_areas() are lower-level, single-library helpers. Save behaviour lives in store.py;
+core.save() is retained as a compatibility re-export.
+"""
+import os
+from pathlib import Path
+
+from . import paths, runners
+from .onboarding import NOT_SET_UP
+from .index import add_index_line, parse_index  # noqa: F401 (re-exported; moved from here)
+
+def lib_dir():
+    return paths.personal_root()
+
+
+def _read_index_text(root):
+    """root's INDEX.md as UTF-8, newline='' preserved (empty string if it doesn't exist).
+
+    Path.read_text() only gained a newline= parameter in Python 3.13; this module supports
+    Python >=3.10, so open() is used directly instead.
+    """
+    p = Path(root) / "INDEX.md"
+    if not p.exists():
+        return ""
+    with open(p, encoding="utf-8", newline="") as f:
+        return f.read()
+
+
+def read_index():
+    return _read_index_text(lib_dir())
+
+
+def areas(text=None):
+    """[(area, script count)] in index order, for a single library's index text."""
+    counts = {}
+    for e in parse_index(read_index() if text is None else text):
+        counts[e["area"]] = counts.get(e["area"], 0) + 1
+    return list(counts.items())
+
+
+def area_lines(area, text=None):
+    """All index lines in one area (case-insensitive name); ValueError lists the areas if unknown."""
+    text = read_index() if text is None else text
+    known = [a for a, _ in areas(text)]
+    match = next((a for a in known if a.lower() == area.strip().lower()), None)
+    if match is None:
+        raise ValueError(f"no area '{area}'. Areas: {', '.join(known) or '(library is empty)'}")
+    return match, [e["line"] for e in parse_index(text) if e["area"] == match]
+
+
+def format_areas(pairs):
+    if not pairs:
+        return "The library is empty. Do the task, answer, then save a script if the step is reusable."
+    return "Areas (script count):\n" + "\n".join(f"- {a} ({n})" for a, n in pairs)
+
+
+def list_areas():
+    """Areas from every visible library (project first), each labelled with its scope."""
+    if not paths.personal_root().is_dir():
+        return NOT_SET_UP
+    triples = []  # (area, count, scope)
+    for lib in paths.libraries():
+        for area, count in areas(_read_index_text(lib.root)):
+            triples.append((area, count, lib.scope))
+    if not triples:
+        return "The library is empty. Do the task, answer, then save a script if the step is reusable."
+    lines = "\n".join(f"- {a} ({n}, {s})" for a, n, s in triples)
+    return "Areas (script count):\n" + lines
+
+
+def list_area(area):
+    """One area's lines from every library that has it, each under its own '## Area (scope)'.
+
+    A personal line whose script also exists in the project library's scripts/ (so mm_run
+    would pick the project one, per resolve()'s precedence) is marked '(shadowed)'.
+    """
+    if not paths.personal_root().is_dir():
+        return NOT_SET_UP
+    libs = paths.libraries()
+    project_lib = next((lib for lib in libs if lib.scope == "project"), None)
+    project_scripts = set()
+    if project_lib is not None and (project_lib.root / "scripts").is_dir():
+        project_scripts = {p.name for p in (project_lib.root / "scripts").iterdir() if p.is_file()}
+
+    sections, known = [], []
+    for lib in libs:
+        text = _read_index_text(lib.root)
+        lib_known = [a for a, _ in areas(text)]
+        known.extend(a for a in lib_known if a not in known)
+        match = next((a for a in lib_known if a.lower() == area.strip().lower()), None)
+        if match is None:
+            continue
+        lines = []
+        for e in parse_index(text):
+            if e["area"] != match:
+                continue
+            line = e["line"]
+            if lib.scope == "personal" and e["script"] in project_scripts:
+                line += " (shadowed)"
+            lines.append(line)
+        sections.append(f"## {match} ({lib.scope})\n" + "\n".join(lines))
+    if not sections:
+        raise ValueError(f"no area '{area}'. Areas: {', '.join(known) or '(library is empty)'}")
+    return "\n\n".join(sections)
+
+
+def resolve(script):
+    """(Library, Path) for script, checked project-first then personal; same name => project wins."""
+    for lib in paths.libraries():
+        d = (lib.root / "scripts").resolve()
+        p = (d / script).resolve()
+        if (p.parent == d and p.is_file() and not p.name.startswith("test_")
+                and not p.name.endswith(".runner.json") and not p.name.endswith(".test.json")):
+            return lib, p
+    raise ValueError(f"not a library script: {script}")
+
+
+def run(script, args, timeout=300):
+    if not paths.personal_root().is_dir():
+        raise ValueError(NOT_SET_UP)
+    lib, p = resolve(script)
+    if lib.scope == "project":
+        from . import trust
+        trust.require(lib.root)
+    if p.suffix.lower() in runners.WINDOWS_ONLY_EXTENSIONS:
+        runners.check_cmd_args(p, ["cmd"], args)  # before runner_for, which refuses .bat off Windows
+    argv = runners.runner_for(p)
+    runners.check_cmd_args(p, argv, args)
+    cmd = [*argv, str(p), *args]
+    try:
+        return runners.run_process(cmd, cwd=Path(os.getcwd()), env=None, timeout=timeout)
+    except FileNotFoundError as e:
+        raise ValueError(f"failed to launch '{argv[0]}' for {p.name}: {e}")
+
+
+def save(name, code, test, area, usage, *, scope="personal", new_area=False, runner=None,
+         test_name=None, test_runner=None, replace=False, push=None):
+    """Compatibility wrapper; new callers should use store.save.
+
+    Returns NOT_SET_UP for any scope when the personal library folder is missing, matching
+    mm_list/mm_run/mm_save's MCP behaviour (Task 6 review, finding 4): a project-scope save
+    still needs the personal folder to exist, since that's what marks first-run setup done.
+    """
+    from .store import save as store_save
+    if not paths.personal_root().is_dir():
+        return False, NOT_SET_UP
+    return store_save(name, code, test, area, usage, scope=scope, new_area=new_area,
+                      runner=runner, test_name=test_name, test_runner=test_runner,
+                      replace=replace, push=push)