matimo-cli 0.1.0__tar.gz

matimo_cli-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+**/node_modules/
+package-lock.json
+yarn.lock
+
+# Build output
+**/dist/
+*.tsbuildinfo
+
+# Python compiled / build
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+**/build/
+**/.eggs/
+**/.venv/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.pytest_cache/
+
+# Test coverage
+**/coverage/
+**/.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+typescript/examples/mcp/matimo-tools/.matimo-approvals.json
+typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
+typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
+typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/matimo-health-check/SKILL.md
+typescript/examples/mcp/matimo-tools/skills/moltbook-identity/SKILL.md
+typescript/packages/cli/.matimo/certs/server.crt
+typescript/packages/cli/.matimo/certs/server.key
+typescript/examples/mcp/.matimo/certs/server.crt
+typescript/examples/mcp/.matimo/certs/server.key

matimo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: matimo-cli
+Version: 0.1.0
+Summary: Matimo CLI — tool package manager & MCP server launcher
+Author: Matimo
+License: MIT
+Keywords: ai-tools,cli,matimo,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: matimo-core[mcp]<0.2.0,>=0.1.0a14.post1
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# matimo-cli
+
+> Command-line interface for [Matimo](https://matimo.dev) — tool package manager & MCP server launcher.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-cli)](https://pypi.org/project/matimo-cli/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo-cli
+# or with uv
+uv add matimo-cli
+```
+
+---
+
+## Commands
+
+### `matimo install` — Install provider packages
+
+```bash
+matimo install slack github gmail         # install specific providers
+matimo install slack --upgrade            # upgrade an existing provider
+```
+
+### `matimo list` — List available tools
+
+```bash
+matimo list                               # all loaded tools
+matimo list --provider slack             # filter by provider
+matimo list --format json                # JSON output
+```
+
+### `matimo search` — Search for tools
+
+```bash
+matimo search email                       # text search over tool names + descriptions
+matimo search "send message"
+```
+
+### `matimo mcp` — Start MCP server
+
+Serve all loaded tools over the [Model Context Protocol](https://matimo.dev/docs/MCP) so Claude Desktop, Cursor, or any MCP client can access them.
+
+```bash
+matimo mcp                                # start on stdio (default)
+matimo mcp --transport http --port 3000   # start as HTTP server
+matimo mcp --name "my-agent"              # set server name
+```
+
+**Claude Desktop `claude_desktop_config.json`:**
+```json
+{
+  "mcpServers": {
+    "matimo": {
+      "command": "matimo",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### `matimo doctor` — Diagnose your setup
+
+```bash
+matimo doctor                             # check config, installed providers, connectivity
+matimo doctor --fix                       # attempt auto-repair
+```
+
+### `matimo review` — Review agent-created tool definitions
+
+```bash
+matimo review ./agent-tools/              # interactive review of draft tools
+```
+
+---
+
+## Configuration
+
+The CLI reads Matimo configuration from the environment or a `.matimo.yaml` file in the project root:
+
+```yaml
+# .matimo.yaml
+toolPaths:
+  - ./tools
+  - ./agent-tools
+logLevel: info
+```
+
+Environment variables:
+
+```bash
+export MATIMO_LOG_LEVEL=info        # silent | error | warn | info | debug
+export MATIMO_LOG_FORMAT=json       # json | simple
+export MATIMO_AUTO_APPROVE=true     # auto-approve tool approval prompts (CI/CD)
+```
+
+---
+
+## Documentation
+
+- [CLI Guide](https://matimo.dev/docs/user-guide/)
+- [MCP Guide](https://matimo.dev/docs/MCP)
+- [Getting Started](https://matimo.dev/docs/getting-started/QUICK_START)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-cli/
+- **Docs:** https://matimo.dev/docs
+- **GitHub:** https://github.com/tallclub/matimo
+

matimo_cli-0.1.0/README.md

@@ -0,0 +1,116 @@
+# matimo-cli
+
+> Command-line interface for [Matimo](https://matimo.dev) — tool package manager & MCP server launcher.
+
+[![PyPI](https://img.shields.io/pypi/v/matimo-cli)](https://pypi.org/project/matimo-cli/)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+
+---
+
+## Installation
+
+```bash
+pip install matimo-cli
+# or with uv
+uv add matimo-cli
+```
+
+---
+
+## Commands
+
+### `matimo install` — Install provider packages
+
+```bash
+matimo install slack github gmail         # install specific providers
+matimo install slack --upgrade            # upgrade an existing provider
+```
+
+### `matimo list` — List available tools
+
+```bash
+matimo list                               # all loaded tools
+matimo list --provider slack             # filter by provider
+matimo list --format json                # JSON output
+```
+
+### `matimo search` — Search for tools
+
+```bash
+matimo search email                       # text search over tool names + descriptions
+matimo search "send message"
+```
+
+### `matimo mcp` — Start MCP server
+
+Serve all loaded tools over the [Model Context Protocol](https://matimo.dev/docs/MCP) so Claude Desktop, Cursor, or any MCP client can access them.
+
+```bash
+matimo mcp                                # start on stdio (default)
+matimo mcp --transport http --port 3000   # start as HTTP server
+matimo mcp --name "my-agent"              # set server name
+```
+
+**Claude Desktop `claude_desktop_config.json`:**
+```json
+{
+  "mcpServers": {
+    "matimo": {
+      "command": "matimo",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### `matimo doctor` — Diagnose your setup
+
+```bash
+matimo doctor                             # check config, installed providers, connectivity
+matimo doctor --fix                       # attempt auto-repair
+```
+
+### `matimo review` — Review agent-created tool definitions
+
+```bash
+matimo review ./agent-tools/              # interactive review of draft tools
+```
+
+---
+
+## Configuration
+
+The CLI reads Matimo configuration from the environment or a `.matimo.yaml` file in the project root:
+
+```yaml
+# .matimo.yaml
+toolPaths:
+  - ./tools
+  - ./agent-tools
+logLevel: info
+```
+
+Environment variables:
+
+```bash
+export MATIMO_LOG_LEVEL=info        # silent | error | warn | info | debug
+export MATIMO_LOG_FORMAT=json       # json | simple
+export MATIMO_AUTO_APPROVE=true     # auto-approve tool approval prompts (CI/CD)
+```
+
+---
+
+## Documentation
+
+- [CLI Guide](https://matimo.dev/docs/user-guide/)
+- [MCP Guide](https://matimo.dev/docs/MCP)
+- [Getting Started](https://matimo.dev/docs/getting-started/QUICK_START)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-cli/
+- **Docs:** https://matimo.dev/docs
+- **GitHub:** https://github.com/tallclub/matimo
+

matimo_cli-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matimo-cli"
+version = "0.1.0"
+description = "Matimo CLI — tool package manager & MCP server launcher"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Matimo" }]
+keywords = ["matimo", "cli", "ai-tools", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "matimo-core[mcp]>=0.1.0a14.post1,<0.2.0",
+    "pyyaml>=6.0",
+    "mcp>=1.0",
+]
+
+[project.scripts]
+matimo = "matimo_cli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matimo_cli"]

matimo_cli-0.1.0/src/matimo_cli/__init__.py

@@ -0,0 +1 @@
+"""Matimo CLI — Tool package manager & MCP server launcher."""

matimo_cli-0.1.0/src/matimo_cli/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running ``python -m matimo_cli``."""
+from matimo_cli.cli import main
+
+main()

matimo_cli-0.1.0/src/matimo_cli/cli.py

@@ -0,0 +1,97 @@
+"""
+Matimo CLI — main command router.
+
+Mirrors: packages/cli/src/cli.ts
+
+Usage::
+
+    matimo install slack gmail
+    matimo list
+    matimo search slack
+    matimo mcp
+    matimo mcp setup
+    matimo doctor
+    matimo review list
+"""
+from __future__ import annotations
+
+import sys
+
+from matimo_cli.commands.doctor import doctor_command
+from matimo_cli.commands.install import install_command
+from matimo_cli.commands.list_cmd import list_command
+from matimo_cli.commands.mcp import mcp_command
+from matimo_cli.commands.review import review_command
+from matimo_cli.commands.search import search_command
+
+_VERSION = "0.1.0"  # also update in setup.py and pyproject.toml
+
+_HELP = f"""\
+🔨 Matimo CLI — Tool Package Manager  (v{_VERSION})
+
+Usage: matimo [command] [options]
+
+Commands:
+  install <tools...>    Install tool packages (pip install matimo-<name>)
+  list                  List installed Matimo tool packages
+  search <query>        Search for available tools
+  mcp                   Start MCP server (Model Context Protocol)
+  mcp setup             Generate config for Claude Desktop / Cursor
+  doctor                Diagnose your Matimo setup
+  review                Review agent-created tools awaiting approval
+  help                  Show this help message
+  version               Show version information
+
+Examples:
+  matimo install slack gmail
+  matimo list
+  matimo search email
+  matimo mcp
+  matimo mcp --transport http --port 3000
+  matimo mcp setup
+  matimo doctor
+  matimo review list
+  matimo review approve my_tool
+
+Documentation: https://github.com/tallclub/matimo#readme
+"""
+
+
+def main(cli_args: list[str] | None = None) -> None:
+    """Main CLI handler — parses commands and routes to handlers."""
+    args = cli_args if cli_args is not None else sys.argv[1:]
+    command = args[0] if args else None
+    params = args[1:] if args else []
+
+    if not command:
+        print(_HELP)
+        return
+
+    try:
+        match command.lower():
+            case "install":
+                install_command(params)
+            case "list":
+                list_command()
+            case "search":
+                search_command(params[0] if params else "")
+            case "mcp":
+                mcp_command(params)
+            case "doctor":
+                doctor_command()
+            case "review":
+                review_command(params)
+            case "help" | "-h" | "--help":
+                print(_HELP)
+            case "version" | "-v" | "--version":
+                print(f"matimo-cli v{_VERSION}")
+            case _:
+                print(f"❌ Unknown command: {command}", file=sys.stderr)
+                print('\nRun "matimo help" for available commands')
+                sys.exit(1)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(130)
+    except Exception as exc:
+        print(f"❌ Error: {exc}", file=sys.stderr)
+        sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Matimo CLI commands."""

matimo_cli-0.1.0/src/matimo_cli/commands/doctor.py

@@ -0,0 +1,140 @@
+"""
+``matimo doctor`` — diagnose Matimo setup.
+
+Mirrors: packages/cli/src/commands/doctor.ts
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+_AUTH_PATTERNS = {"TOKEN", "SECRET", "KEY", "PASSWORD", "CREDENTIAL", "AUTH"}
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _is_auth_var(name: str) -> bool:
+    upper = name.upper()
+    return any(p in upper for p in _AUTH_PATTERNS)
+
+
+def doctor_command() -> None:
+    issues: list[dict[str, str]] = []
+
+    def check(label: str, passed: bool, message: str, severity: str = "error") -> None:
+        icon = "✅" if passed else ("❌" if severity == "error" else "⚠️ ")
+        print(f"  {icon} {label}")
+        if not passed:
+            issues.append({"severity": severity, "message": message})
+            print(f"     {message}")
+
+    print("\n🩺 Matimo Doctor — Checking your setup…\n")
+
+    # 1. Python version
+    print("Python:")
+    v = sys.version_info
+    check(
+        f"Python {v.major}.{v.minor}.{v.micro}",
+        v >= (3, 11),
+        f"Python 3.11+ required. You are running {v.major}.{v.minor}. Upgrade: https://python.org",
+    )
+    print()
+
+    # 2. matimo package
+    print("matimo SDK:")
+    try:
+        import importlib.metadata
+
+        matimo_version = importlib.metadata.version("matimo")
+        check(f"matimo v{matimo_version}", True, "")
+    except importlib.metadata.PackageNotFoundError:
+        check("matimo", False, 'matimo package not installed. Run "pip install matimo".')
+    print()
+
+    # 3. Installed provider packages
+    print("matimo-* packages:")
+    try:
+        import importlib.metadata as md
+
+        providers = [
+            d
+            for d in md.distributions()
+            if d.metadata["Name"]
+            and d.metadata["Name"].startswith("matimo-")
+            and d.metadata["Name"] not in ("matimo-cli",)
+        ]
+
+        if not providers:
+            check(
+                "matimo-* providers",
+                False,
+                'No matimo-* packages installed. Run "matimo install slack" to get started.',
+                "warn",
+            )
+        else:
+            for dist in sorted(providers, key=lambda d: d.metadata["Name"]):
+                pkg_name = dist.metadata["Name"]
+                print(f"  📦 {pkg_name}")
+
+                # Try to find tools directory and scan for auth placeholders
+                for dist_file in dist.files or []:
+                    str_path = str(dist_file)
+                    if "tools/" in str_path and str_path.endswith("definition.yaml"):
+                        full_path = Path(str(dist.locate_file(dist_file)))
+                        if full_path.is_file():
+                            content = full_path.read_text(encoding="utf-8")
+                            missing = []
+                            for m in _PLACEHOLDER_RE.finditer(content):
+                                name = m.group(1)
+                                if _is_auth_var(name) and not os.environ.get(name):
+                                    missing.append(name)
+                            if missing:
+                                for v in missing:
+                                    print(f"     ❌ Missing env var: {v}")
+                                issues.append(
+                                    {
+                                        "severity": "error",
+                                        "message": f"{pkg_name}: missing env vars: {', '.join(missing)}",
+                                    }
+                                )
+                            else:
+                                print("     ✅ All required env vars are set")
+                print()
+    except Exception:
+        check("matimo-* scan", False, "Failed to scan installed packages.", "warn")
+    print()
+
+    # 4. MATIMO_APPROVAL_SECRET
+    print("Policy / Approval:")
+    has_secret = bool(os.environ.get("MATIMO_APPROVAL_SECRET"))
+    check(
+        "MATIMO_APPROVAL_SECRET",
+        has_secret,
+        "MATIMO_APPROVAL_SECRET is not set. Agent-created tool approvals will use a "
+        "random secret (not persistent across restarts). Set it in your .env file.",
+        "warn",
+    )
+    print()
+
+    # 5. Summary
+    errors = [i for i in issues if i["severity"] == "error"]
+    warnings = [i for i in issues if i["severity"] == "warn"]
+
+    print("─" * 60)
+    if not errors and not warnings:
+        print("\n✅ Matimo is ready! No issues found.\n")
+    else:
+        if errors:
+            print(f"\n❌ {len(errors)} error(s) found — fix before using Matimo:\n")
+            for idx, e in enumerate(errors, 1):
+                print(f"  {idx}. {e['message']}")
+            print()
+        if warnings:
+            print(f"⚠️  {len(warnings)} warning(s):\n")
+            for idx, w in enumerate(warnings, 1):
+                print(f"  {idx}. {w['message']}")
+            print()
+
+    if errors:
+        sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/install.py

@@ -0,0 +1,37 @@
+"""
+``matimo install`` — install Matimo tool packages via pip.
+
+Mirrors: packages/cli/src/commands/install.ts
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def install_command(tool_names: list[str]) -> None:
+    if not tool_names:
+        print("❌ Error: Please specify at least one tool to install", file=sys.stderr)
+        print("\nUsage: matimo install [tool1] [tool2] …")
+        print("Example: matimo install slack gmail stripe")
+        sys.exit(1)
+
+    packages = [f"matimo-{name}" for name in tool_names]
+
+    print(f"📦 Installing {', '.join(packages)}…")
+
+    try:
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", *packages],
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+    except subprocess.CalledProcessError:
+        print("❌ Installation failed.", file=sys.stderr)
+        sys.exit(1)
+
+    print("\n✅ Installation complete!")
+    print("\nNext steps:")
+    print("  from matimo import Matimo")
+    print("  matimo = await Matimo.init(auto_discover=True)")
+    print("\n📖 For more info: https://github.com/tallclub/matimo#readme")

matimo_cli-0.1.0/src/matimo_cli/commands/list_cmd.py

@@ -0,0 +1,44 @@
+"""
+``matimo list`` — list installed Matimo tool packages.
+
+Mirrors: packages/cli/src/commands/list.ts
+"""
+from __future__ import annotations
+
+import importlib.metadata
+import sys
+
+
+def list_command() -> None:
+    """List all installed matimo-* packages."""
+    try:
+        packages = [
+            dist
+            for dist in importlib.metadata.distributions()
+            if dist.metadata["Name"]
+            and dist.metadata["Name"].startswith("matimo-")
+            and dist.metadata["Name"] != "matimo-cli"
+        ]
+
+        if not packages:
+            print("⚠️  No Matimo tool packages installed yet")
+            print("\nInstall some tools:")
+            print("  matimo install slack gmail")
+            return
+
+        print("📦 Installed Matimo Packages:\n")
+
+        for dist in sorted(packages, key=lambda d: d.metadata["Name"]):
+            name = dist.metadata["Name"]
+            version = dist.metadata["Version"]
+            summary = dist.metadata.get("Summary", "")
+            print(f"  📍 {name}  (v{version})")
+            if summary:
+                print(f"     {summary}")
+            print()
+
+        print(f"Total: {len(packages)} package{'s' if len(packages) != 1 else ''} installed")
+
+    except Exception as exc:
+        print(f"❌ Error listing tools: {exc}", file=sys.stderr)
+        sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/mcp.py

@@ -0,0 +1,216 @@
+"""
+``matimo mcp`` — start the Matimo MCP server.
+
+Mirrors: packages/cli/src/commands/mcp.ts
+"""
+from __future__ import annotations
+
+import signal
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class McpArgs:
+    transport: str = "stdio"
+    port: int = 3000
+    tools: list[str] | None = None
+    exclude_tools: list[str] | None = None
+    secrets: list[str] | None = None
+    env_file: str | None = None
+    vault_path: str | None = None
+    aws_secret_id: str | None = None
+    token: str | None = None
+    tool_paths: list[str] | None = None
+    skill_paths: list[str] | None = None
+    https: bool = False
+    self_signed: bool = False
+    cert_path: str | None = None
+    key_path: str | None = None
+
+
+def _parse_args(params: list[str]) -> McpArgs:
+    args = McpArgs()
+    i = 0
+
+    def require_value(flag: str) -> str:
+        nonlocal i
+        if i + 1 >= len(params) or params[i + 1].startswith("-"):
+            print(f"❌ {flag} requires a value", file=sys.stderr)
+            sys.exit(1)
+        i += 1
+        return params[i]
+
+    while i < len(params):
+        flag = params[i]
+        match flag:
+            case "--transport" | "-t":
+                val = require_value("--transport")
+                if val not in ("stdio", "http"):
+                    print('❌ --transport must be "stdio" or "http"', file=sys.stderr)
+                    sys.exit(1)
+                args.transport = val
+            case "--port" | "-p":
+                val = require_value("--port")
+                try:
+                    args.port = int(val)
+                except ValueError:
+                    print("❌ --port must be a number", file=sys.stderr)
+                    sys.exit(1)
+            case "--tools":
+                args.tools = [s.strip() for s in require_value("--tools").split(",")]
+            case "--exclude":
+                args.exclude_tools = [s.strip() for s in require_value("--exclude").split(",")]
+            case "--secrets":
+                args.secrets = [s.strip() for s in require_value("--secrets").split(",")]
+            case "--env-file":
+                args.env_file = require_value("--env-file")
+            case "--vault-path":
+                args.vault_path = require_value("--vault-path")
+            case "--aws-secret-id":
+                args.aws_secret_id = require_value("--aws-secret-id")
+            case "--token":
+                args.token = require_value("--token")
+            case "--tool-paths":
+                args.tool_paths = [s.strip() for s in require_value("--tool-paths").split(",")]
+            case "--skill-paths":
+                args.skill_paths = [s.strip() for s in require_value("--skill-paths").split(",")]
+            case "--https":
+                args.https = True
+            case "--self-signed":
+                args.https = True
+                args.self_signed = True
+            case "--cert":
+                args.cert_path = require_value("--cert")
+                args.https = True
+            case "--key":
+                args.key_path = require_value("--key")
+                args.https = True
+            case "setup":
+                pass  # handled separately
+            case _:
+                if flag.startswith("-"):
+                    print(f"❌ Unknown flag: {flag}", file=sys.stderr)
+                    sys.exit(1)
+        i += 1
+
+    return args
+
+
+def _build_resolver_config(args: McpArgs) -> object:
+    """Build a SecretResolverChain from CLI args."""
+    from matimo.mcp.secrets import (
+        EnvSecretResolver,
+        DotenvSecretResolver,
+        VaultSecretResolver,
+        AwsSecretsManagerResolver,
+        SecretResolverChain,
+    )
+    
+    secret_types = args.secrets or ["env", "dotenv"]
+    resolvers: list[object] = []
+    
+    for t in secret_types:
+        match t:
+            case "env":
+                resolvers.append(EnvSecretResolver())
+            case "dotenv":
+                resolvers.append(DotenvSecretResolver(path=args.env_file or ".env"))
+            case "vault":
+                if args.vault_path:
+                    resolvers.append(VaultSecretResolver(secret_path=args.vault_path))
+            case "aws":
+                if args.aws_secret_id:
+                    resolvers.append(AwsSecretsManagerResolver(secret_id=args.aws_secret_id))
+            case _:
+                print("❌ Unknown secret resolver type. Use: env, dotenv, vault, aws", file=sys.stderr)
+                sys.exit(1)
+    
+    # Return None if no resolvers (let MCP server handle it) or a chain if we have resolvers
+    return SecretResolverChain(resolvers) if resolvers else None
+
+
+def mcp_command(params: list[str]) -> None:
+    # Handle 'setup' subcommand
+    if params and params[0] == "setup":
+        from matimo_cli.commands.mcp_setup import mcp_setup_command
+        mcp_setup_command()
+        return
+
+    import asyncio
+    asyncio.run(_mcp_command_async(params))
+
+
+async def _mcp_command_async(params: list[str]) -> None:
+    """Async implementation of the MCP server command."""
+    import os
+    import sysconfig
+    
+    args = _parse_args(params)
+
+    try:
+        from matimo import Matimo
+        from matimo.mcp import MCPServer, MCPServerOptions  # type: ignore[import-not-found]
+    except ImportError as e:
+        print("❌ matimo MCP server module not available.", file=sys.stderr)
+        print("   Make sure matimo is installed: pip install matimo", file=sys.stderr)
+        print(f"   Import error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Discover all matimo_* packages if no tool paths provided
+    tool_paths = args.tool_paths or []
+    if not tool_paths:
+        site_packages = sysconfig.get_path("purelib")
+        if site_packages and os.path.exists(site_packages):
+            for entry in os.listdir(site_packages):
+                if entry.startswith("matimo_") and not entry.endswith(".dist-info"):
+                    pkg_tools = os.path.join(site_packages, entry, "tools")
+                    if os.path.exists(pkg_tools):
+                        tool_paths.append(pkg_tools)
+
+    # Initialize Matimo with the given tool paths
+    matimo = await Matimo.init(
+        tool_paths=tool_paths if tool_paths else None,
+        skill_paths=args.skill_paths,
+        auto_discover=True,
+    )
+
+    # Create MCP server options
+    options = MCPServerOptions(
+        transport=args.transport,
+        port=args.port,
+        tools=args.tools,
+        exclude_tools=args.exclude_tools,
+        secret_resolver=_build_resolver_config(args),
+        mcp_token=args.token,
+        tool_paths=tool_paths if tool_paths else None,
+        skill_paths=args.skill_paths,
+        auto_discover=True,
+    )
+
+    # Create MCP server
+    server = MCPServer(matimo, options)
+
+    def _shutdown(signum: int, frame: object) -> None:
+        if args.transport == "stdio":
+            sys.stderr.write("\nShutting down Matimo MCP server…\n")
+        else:
+            print("\nShutting down Matimo MCP server…")
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _shutdown)
+    signal.signal(signal.SIGTERM, _shutdown)
+
+    try:
+        await server.start()
+
+        if args.transport == "http":
+            protocol = "https" if args.https else "http"
+            url = f"{protocol}://localhost:{args.port}/mcp"
+            print(f"\n🚀 Matimo MCP server running at {url}")
+            if args.https:
+                print("🔒 HTTPS enabled")
+            print("\n   Press Ctrl+C to stop\n")
+    except Exception as exc:
+        print(f"❌ Failed to start MCP server: {exc}", file=sys.stderr)
+        sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/mcp_setup.py

@@ -0,0 +1,104 @@
+"""
+``matimo mcp setup`` — generate MCP config for Claude Desktop / Cursor.
+
+Mirrors: packages/cli/src/commands/mcp-setup.ts
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+_AUTH_PATTERNS = {"TOKEN", "SECRET", "KEY", "PASSWORD", "CREDENTIAL", "AUTH"}
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _is_auth_var(name: str) -> bool:
+    upper = name.upper()
+    return any(p in upper for p in _AUTH_PATTERNS)
+
+
+def mcp_setup_command() -> None:
+    print("\n🔨 Matimo MCP Setup\n")
+    print("Scanning for installed tool packages…\n")
+
+    try:
+        from matimo.core.tool_loader import ToolLoader  # type: ignore[import-not-found]
+    except ImportError:
+        print("❌ matimo core not available. Install it first: pip install matimo", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        loader = ToolLoader()
+        tool_paths = loader.auto_discover_packages()
+
+        if not tool_paths:
+            print("No matimo-* tool packages found.")
+            print("Install tools first: matimo install slack github\n")
+            return
+
+        tools = loader.load_tools_from_multiple_paths(tool_paths)
+        print(f"Found {len(tools)} tools across {len(tool_paths)} package(s):\n")
+
+        # Group by provider
+        providers: dict[str, list[str]] = {}
+        auth_vars: set[str] = set()
+
+        for name, tool in tools.items():
+            provider = name.split("_")[0] if "_" in name else name.split("-")[0] if "-" in name else "core"
+            providers.setdefault(provider, []).append(name)
+
+            # Extract auth placeholders
+            exec_cfg = tool.execution
+            raw = str(exec_cfg.model_dump()) if hasattr(exec_cfg, "model_dump") else str(exec_cfg)
+            for m in _PLACEHOLDER_RE.finditer(raw):
+                if _is_auth_var(m.group(1)):
+                    auth_vars.add(m.group(1))
+
+        for provider, tool_names in sorted(providers.items()):
+            print(f"  📦 {provider} ({len(tool_names)} tools)")
+            for tn in tool_names[:5]:
+                print(f"     • {tn}")
+            if len(tool_names) > 5:
+                print(f"     … and {len(tool_names) - 5} more")
+
+        print()
+
+        # Display required env vars
+        if auth_vars:
+            print("🔐 Required environment variables:\n")
+            for v in sorted(auth_vars):
+                value = os.environ.get(v) or os.environ.get(f"MATIMO_{v}")
+                status = "✅" if value else "❌"
+                print(f"  {status} {v}")
+            print()
+
+        # Generate configs — always use placeholders to prevent secret leakage
+        env_block = {v: "<your-token>" for v in sorted(auth_vars)}
+
+        claude_config = {
+            "mcpServers": {
+                "matimo": {
+                    "command": "matimo",
+                    "args": ["mcp"],
+                    "env": env_block,
+                }
+            }
+        }
+
+        print("📋 Claude Desktop config (paste into Settings → Developer → MCP Servers):\n")
+        print(json.dumps(claude_config, indent=2))
+
+        print("\n📋 Cursor config (paste into .cursor/mcp.json):\n")
+        print(json.dumps(claude_config, indent=2))
+
+        print("\n📋 HTTP mode (for remote hosting / Docker):\n")
+        env_lines = "\n".join(f"  {v}=<your-token>" for v in sorted(auth_vars))
+        print(f"{env_lines}")
+        print("  MATIMO_MCP_TOKEN=<your-server-secret>")
+        print("  matimo mcp --transport http --port 3000\n")
+
+    except Exception as exc:
+        print(f"❌ Setup failed: {exc}", file=sys.stderr)
+        sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/review.py

@@ -0,0 +1,171 @@
+"""
+``matimo review`` — human oversight for agent-created tools.
+
+Mirrors: packages/cli/src/commands/review.ts
+
+Subcommands:
+  matimo review list              Show all tools awaiting approval
+  matimo review approve <name>    Approve a pending tool
+  matimo review reject  <name>    Reject / revoke a tool
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def _resolve_manifest_dir() -> str:
+    tool_dir = os.environ.get("MATIMO_TOOL_DIR")
+    return str(Path(tool_dir).resolve()) if tool_dir else os.getcwd()
+
+
+def _try_load_manifest(directory: str):
+    """Try to import ApprovalManifest from matimo core."""
+    try:
+        from matimo.policy.approval_manifest import ApprovalManifest  # type: ignore[import-not-found]
+        return ApprovalManifest(directory)
+    except ImportError:
+        return None
+
+
+def _print_table(headers: list[str], rows: list[list[str]]) -> None:
+    cols = len(headers)
+    widths = [
+        max(len(h), *(len(r[i]) if i < len(r) else 0 for r in rows))
+        for i, h in enumerate(headers)
+    ]
+    def fmt(row):
+        return "│ " + " │ ".join(c.ljust(w) for c, w in zip(row, widths)) + " │"
+
+    print("┌" + "┬".join("─" * (w + 2) for w in widths) + "┐")
+    print(fmt(headers))
+    print("├" + "┼".join("─" * (w + 2) for w in widths) + "┤")
+    for row in rows:
+        padded = (row + [""] * cols)[:cols]
+        print(fmt(padded))
+    print("└" + "┴".join("─" * (w + 2) for w in widths) + "┘")
+
+
+def _list_pending(directory: str) -> None:
+    manifest = _try_load_manifest(directory)
+    if manifest is None:
+        print("❌ matimo core is not available. Run `pip install matimo` first.", file=sys.stderr)
+        sys.exit(1)
+
+    pending = manifest.get_pending_tools()
+    approved = manifest.list_approved()
+
+    if not pending and not approved:
+        print("ℹ️  No tools are pending or approved.")
+        return
+
+    if pending:
+        print("\n⏳ Pending approval:\n")
+        rows = [[name, "pending", "—", "—"] for name in pending]
+        _print_table(["Tool name", "Status", "Approved by", "Approved at"], rows)
+
+    if approved:
+        print("\n✅ Approved tools:\n")
+        rows = []
+        for name in approved:
+            rec = manifest.get_approval(name) or {}
+            rows.append([name, "approved", rec.get("approved_by", "—"), rec.get("approved_at", "—")])
+        _print_table(["Tool name", "Status", "Approved by", "Approved at"], rows)
+
+    if pending:
+        print('\nRun "matimo review approve <tool-name>" to approve, '
+              'or "matimo review reject <tool-name>" to reject.')
+
+
+def _approve_tool(tool_name: str, directory: str) -> None:
+    if not tool_name:
+        print("❌ Usage: matimo review approve <tool-name>", file=sys.stderr)
+        sys.exit(1)
+
+    manifest = _try_load_manifest(directory)
+    if manifest is None:
+        print("❌ matimo core is not available.", file=sys.stderr)
+        sys.exit(1)
+
+    pending = manifest.get_pending_tools()
+    if tool_name not in pending:
+        approved = manifest.list_approved()
+        if tool_name in approved:
+            print(f'ℹ️  "{tool_name}" is already approved.')
+            return
+        print(f'❌ No pending tool named "{tool_name}". Run "matimo review list" to see pending tools.', file=sys.stderr)
+        sys.exit(1)
+
+    secret = os.environ.get("MATIMO_APPROVAL_SECRET")
+    if not secret:
+        print("❌ MATIMO_APPROVAL_SECRET is not set.", file=sys.stderr)
+        print("   Set it to approve tools: export MATIMO_APPROVAL_SECRET=<your-secret>")
+        sys.exit(1)
+
+    yaml_path = Path(directory) / tool_name / "definition.yaml"
+    if not yaml_path.is_file():
+        print(f'❌ Cannot find definition.yaml for tool "{tool_name}" at:\n   {yaml_path}', file=sys.stderr)
+        sys.exit(1)
+
+    content = yaml_path.read_text(encoding="utf-8")
+
+    # Promote status to "approved"
+    try:
+        parsed = yaml.safe_load(content) or {}
+        if isinstance(parsed, dict) and parsed.get("status") != "approved":
+            parsed["status"] = "approved"
+            content = yaml.dump(parsed, default_flow_style=False)
+            tmp_path = yaml_path.with_suffix(".yaml.tmp")
+            tmp_path.write_text(content, encoding="utf-8")
+            tmp_path.rename(yaml_path)
+            print("   📝 Updated status: draft → approved in definition.yaml")
+    except Exception:
+        print("⚠️  Failed to update status in definition.yaml; proceeding with manifest approval only.")
+
+    hash_val = manifest.compute_hash(content)
+    approved_by = os.environ.get("USER") or os.environ.get("USERNAME") or "cli"
+    manifest.approve(tool_name, hash_val, approved_by)
+    print(f'✅ Tool "{tool_name}" approved.')
+
+
+def _reject_tool(tool_name: str, directory: str) -> None:
+    if not tool_name:
+        print("❌ Usage: matimo review reject <tool-name>", file=sys.stderr)
+        sys.exit(1)
+
+    manifest = _try_load_manifest(directory)
+    if manifest is None:
+        print("❌ matimo core is not available.", file=sys.stderr)
+        sys.exit(1)
+
+    was_approved = manifest.revoke(tool_name)
+    pending = manifest.get_pending_tools()
+    was_pending = tool_name in pending
+
+    if not was_approved and not was_pending:
+        print(f'ℹ️  No record of tool "{tool_name}". Nothing to reject.')
+        return
+
+    print(f'🗑  Tool "{tool_name}" has been rejected/revoked.')
+    if was_approved:
+        print("   (Approval signature removed — the tool will be blocked until re-approved.)")
+
+
+def review_command(args: list[str]) -> None:
+    sub = args[0] if args else None
+    directory = _resolve_manifest_dir()
+
+    match sub:
+        case "list" | None:
+            _list_pending(directory)
+        case "approve":
+            _approve_tool(args[1] if len(args) > 1 else "", directory)
+        case "reject":
+            _reject_tool(args[1] if len(args) > 1 else "", directory)
+        case _:
+            print(f'❌ Unknown review subcommand: "{sub}"', file=sys.stderr)
+            print("Usage: matimo review [list|approve|reject] [tool-name]")
+            sys.exit(1)

matimo_cli-0.1.0/src/matimo_cli/commands/search.py

@@ -0,0 +1,139 @@
+"""
+``matimo search`` — search for available Matimo tool packages.
+
+Mirrors: packages/cli/src/commands/search.ts
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+
+def search_command(query: str) -> None:
+    if not query:
+        print("❌ Error: Please specify a search query", file=sys.stderr)
+        print("\nUsage: matimo search <query>")
+        print("Example: matimo search slack")
+        sys.exit(1)
+
+    # Try to find packages in the repo first, then fall back to installed
+    repo_root = _find_repo_root(Path.cwd())
+    available: list[dict[str, object]] = []
+    context: str
+
+    if repo_root is not None:
+        packages_dir = repo_root / "python" / "providers"
+        if packages_dir.is_dir():
+            context = "repository"
+            available = _scan_directory(packages_dir)
+        else:
+            packages_dir = repo_root / "packages"
+            if packages_dir.is_dir():
+                context = "repository"
+                available = _scan_directory(packages_dir, skip={"core", "cli"})
+            else:
+                context = "installed"
+                available = _scan_installed()
+    else:
+        context = "installed"
+        available = _scan_installed()
+
+    if not available:
+        print("❌ No Matimo packages found.", file=sys.stderr)
+        print("Install packages: pip install matimo-slack")
+        sys.exit(1)
+
+    q = query.lower()
+    results = [
+        p
+        for p in available
+        if q in str(p["name"]).lower() or q in str(p.get("description", "")).lower()
+    ]
+
+    if not results:
+        print(f'❌ No packages found matching "{query}"')
+        print(f"\n📦 Available Packages (from {context}):")
+        for p in available:
+            print(f"  • {p['name']} ({p['tools']} tools)")
+        return
+
+    print(f'🔍 Search results for "{query}" ({context}):\n')
+    for p in results:
+        print(f"✅ {p['name']}")
+        print(f"   {p.get('description', '')}")
+        print(f"   Tools: {p['tools']}")
+        if context == "installed":
+            print("   Already installed")
+        else:
+            name_part = str(p["name"]).replace("matimo-", "")
+            print(f"   Install: matimo install {name_part}")
+        print()
+
+    print(f"Total: {len(results)} package{'s' if len(results) != 1 else ''} found")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_repo_root(start: Path) -> Path | None:
+    current = start
+    while current != current.parent:
+        if (current / "pnpm-workspace.yaml").is_file() or (current / "pyproject.toml").is_file():
+            if (current / "python").is_dir() or (current / "packages").is_dir():
+                return current
+        current = current.parent
+    return None
+
+
+def _scan_directory(
+    packages_dir: Path,
+    skip: set[str] | None = None,
+) -> list[dict[str, object]]:
+    results: list[dict[str, object]] = []
+    skip = skip or set()
+
+    for entry in sorted(packages_dir.iterdir()):
+        if not entry.is_dir() or entry.name in skip or entry.name.startswith("."):
+            continue
+
+        tools_dir = entry / "tools"
+        tool_count = 0
+        if tools_dir.is_dir():
+            tool_count = sum(1 for t in tools_dir.iterdir() if t.is_dir())
+
+        # Try to extract description from pyproject.toml
+        desc = ""
+        pyproject = entry / "pyproject.toml"
+        if pyproject.is_file():
+            try:
+                import tomllib
+
+                data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+                desc = data.get("project", {}).get("description", "")
+            except Exception:
+                pass
+
+        name = entry.name
+        results.append({"name": name, "description": desc, "tools": tool_count})
+
+    return results
+
+
+def _scan_installed() -> list[dict[str, object]]:
+    import importlib.metadata
+
+    results: list[dict[str, object]] = []
+    for dist in importlib.metadata.distributions():
+        pkg_name = dist.metadata["Name"]
+        if pkg_name and pkg_name.startswith("matimo-") and pkg_name != "matimo-cli":
+            results.append(
+                {
+                    "name": pkg_name,
+                    "description": dist.metadata.get("Summary", ""),
+                    "tools": 0,
+                }
+            )
+    return results