madcat-os 0.1.2__tar.gz

madcat_os-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version-file: .python-version
+
+      - name: Install
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Smoke test
+        run: uv run madcat mcp list > /dev/null
+
+  build:
+    name: Build distributions
+    needs: check
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version-file: .python-version
+
+      - name: Tag must match project version
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${version}"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/madcat-os
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

madcat_os-0.1.2/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+.env

madcat_os-0.1.2/.python-version

@@ -0,0 +1 @@
+3.13

madcat_os-0.1.2/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: madcat-os
+Version: 0.1.2
+Summary: MADCAT MCP server and CLI — stdio and Streamable HTTP transports, Typer command line
+Author: Adam Ladachowski
+License-Expression: MIT
+Requires-Python: >=3.13
+Requires-Dist: mcp>=1.12
+Requires-Dist: pydantic-settings>=2.8
+Requires-Dist: pydantic>=2.10
+Requires-Dist: rich>=13.9
+Requires-Dist: starlette>=0.46
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# madcat-os (binary: `madcat`)
+
+MADCAT MCP server and command line in Python. The installed binary is `madcat`; one package, three faces:
+
+- `madcat mcp serve` — MCP over **stdio** (default) or **Streamable HTTP** at `/mcp`
+- `madcat mcp list` / `mcp call <tool> '<json>'` — drive the tool registry from the shell
+- `madcat status` — effective config and tool count
+
+Functionality is being moved here from the Rust `madcat` binary; command shapes match it.
+
+## Quick start
+
+```bash
+uv sync
+uv run madcat status
+uv run madcat mcp list
+uv run madcat mcp call server_info
+uv run madcat mcp serve --transport http --token t --bind 127.0.0.1:4197
+```
+
+Then POST an `initialize` to `http://127.0.0.1:4197/mcp` with `Authorization: Bearer t` and
+`Accept: application/json, text/event-stream`; reuse the returned `mcp-session-id`.
+
+## Claude Code
+
+stdio:
+
+```json
+{ "mcpServers": { "madcat": { "command": "uv", "args": ["run", "--directory", "/path/to/madcat-os", "madcat", "mcp", "serve"] } } }
+```
+
+http:
+
+```json
+{ "mcpServers": { "madcat": { "type": "http", "url": "http://127.0.0.1:4097/mcp",
+  "headers": { "Authorization": "Bearer ${MADCAT_MCP_TOKEN}" } } } }
+```
+
+## Configuration
+
+Environment, prefix `MADCAT_MCP_` (or a `.env` file): `HOST` (127.0.0.1), `PORT` (4097), `TOKEN`, `LOG_LEVEL`.
+`--bind` and `--token` on `mcp serve` override.
+
+## Adding a tool
+
+Create `src/madcat_os/tools/<module>.py` with `register(mcp: MCPServer)` and `@mcp.tool()` handlers
+(docstring per tool, type hints per argument), then add `<module>.register` to `MODULES` in
+`src/madcat_os/tools/__init__.py`. Human output goes to stderr; stdout is the stdio wire.
+
+## Layout
+
+```
+src/madcat_os/
+  cli.py        Typer app: status, mcp list|call|serve
+  server.py     build_server(), HTTP app with bearer auth + /health, stdio/http runners
+  config.py     Settings (pydantic-settings)
+  tools/        registry; one module per tool family
+tests/
+justfile
+```

madcat_os-0.1.2/README.md

@@ -0,0 +1,60 @@
+# madcat-os (binary: `madcat`)
+
+MADCAT MCP server and command line in Python. The installed binary is `madcat`; one package, three faces:
+
+- `madcat mcp serve` — MCP over **stdio** (default) or **Streamable HTTP** at `/mcp`
+- `madcat mcp list` / `mcp call <tool> '<json>'` — drive the tool registry from the shell
+- `madcat status` — effective config and tool count
+
+Functionality is being moved here from the Rust `madcat` binary; command shapes match it.
+
+## Quick start
+
+```bash
+uv sync
+uv run madcat status
+uv run madcat mcp list
+uv run madcat mcp call server_info
+uv run madcat mcp serve --transport http --token t --bind 127.0.0.1:4197
+```
+
+Then POST an `initialize` to `http://127.0.0.1:4197/mcp` with `Authorization: Bearer t` and
+`Accept: application/json, text/event-stream`; reuse the returned `mcp-session-id`.
+
+## Claude Code
+
+stdio:
+
+```json
+{ "mcpServers": { "madcat": { "command": "uv", "args": ["run", "--directory", "/path/to/madcat-os", "madcat", "mcp", "serve"] } } }
+```
+
+http:
+
+```json
+{ "mcpServers": { "madcat": { "type": "http", "url": "http://127.0.0.1:4097/mcp",
+  "headers": { "Authorization": "Bearer ${MADCAT_MCP_TOKEN}" } } } }
+```
+
+## Configuration
+
+Environment, prefix `MADCAT_MCP_` (or a `.env` file): `HOST` (127.0.0.1), `PORT` (4097), `TOKEN`, `LOG_LEVEL`.
+`--bind` and `--token` on `mcp serve` override.
+
+## Adding a tool
+
+Create `src/madcat_os/tools/<module>.py` with `register(mcp: MCPServer)` and `@mcp.tool()` handlers
+(docstring per tool, type hints per argument), then add `<module>.register` to `MODULES` in
+`src/madcat_os/tools/__init__.py`. Human output goes to stderr; stdout is the stdio wire.
+
+## Layout
+
+```
+src/madcat_os/
+  cli.py        Typer app: status, mcp list|call|serve
+  server.py     build_server(), HTTP app with bearer auth + /health, stdio/http runners
+  config.py     Settings (pydantic-settings)
+  tools/        registry; one module per tool family
+tests/
+justfile
+```

madcat_os-0.1.2/justfile

@@ -0,0 +1,101 @@
+# madcat — python MCP server and CLI
+
+default:
+    @just --list
+
+# Bump the version everywhere: just bump <major|minor|patch> [dry]
+# Edits files only: no commit, no tag. Every file must match exactly once or
+# nothing is written. `dry` prints the plan without touching anything.
+bump part dry="":
+    #!/usr/bin/env python3
+    import pathlib
+    import re
+    import sys
+
+    part, dry = "{{part}}", "{{dry}}"
+    if part not in ("major", "minor", "patch"):
+        sys.exit(f"bump: part must be major, minor or patch (got {part!r})")
+    if dry not in ("", "dry"):
+        sys.exit(f"bump: second argument must be 'dry' or omitted (got {dry!r})")
+
+    root = pathlib.Path(".")
+    m = re.search(r'^version = "(\d+)\.(\d+)\.(\d+)"$', (root / "pyproject.toml").read_text(), re.M)
+    if not m:
+        sys.exit("bump: no X.Y.Z version found in pyproject.toml")
+    major, minor, patch = map(int, m.groups())
+    old = f"{major}.{minor}.{patch}"
+    if part == "major":
+        major, minor, patch = major + 1, 0, 0
+    elif part == "minor":
+        minor, patch = minor + 1, 0
+    else:
+        patch += 1
+    new = f"{major}.{minor}.{patch}"
+    o = re.escape(old)
+
+    # (file, pattern). Group 1 and 2 are the text around the version.
+    # uv.lock is tracked and CI runs `uv sync --locked`, so it must move with pyproject.
+    targets = [
+        ("pyproject.toml", rf'^(version = "){o}(")$'),
+        ("uv.lock", rf'(name = "madcat-os"\nversion = "){o}(")'),
+    ]
+
+    pending = []
+    for name, pattern in targets:
+        path = root / name
+        if not path.exists():
+            sys.exit(f"bump: missing {name}")
+        out, n = re.subn(pattern, lambda mm: mm.group(1) + new + mm.group(2), path.read_text(), flags=re.M)
+        if n != 1:
+            sys.exit(f"bump: {name}: expected 1 match for {old}, found {n}; nothing written")
+        pending.append((path, out, name))
+
+    print(f"{old} -> {new} ({part}){' [dry run]' if dry else ''}")
+    for path, out, name in pending:
+        print(f"  update   {name}")
+        if not dry:
+            path.write_text(out)
+    if not dry:
+        print(f"\nNext: commit, then: git tag -a v{new} -m 'madcat-os {new}' && git push origin main v{new}")
+
+# Install the environment (runtime + dev)
+sync:
+    uv sync
+
+# Lint and format check
+lint:
+    uv run ruff check .
+    uv run ruff format --check .
+
+# Auto-fix lint and format
+fmt:
+    uv run ruff check --fix .
+    uv run ruff format .
+
+# Tests
+test:
+    uv run pytest -q
+
+# Everything that must pass before a push
+check: lint test
+    uv run madcat mcp list >/dev/null
+
+# Tool inventory
+tools:
+    uv run madcat mcp list
+
+# Call one tool locally: just call ping '{}'
+call name args='{}':
+    uv run madcat mcp call {{name}} '{{args}}'
+
+# Serve over stdio
+stdio:
+    uv run madcat mcp serve
+
+# Serve over HTTP on 127.0.0.1:4097 (set MADCAT_MCP_TOKEN)
+http:
+    uv run madcat mcp serve --transport http
+
+# Install as a uv tool (puts madcat on PATH)
+install:
+    uv tool install --force --editable .

madcat_os-0.1.2/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "madcat-os"
+version = "0.1.2"
+description = "MADCAT MCP server and CLI — stdio and Streamable HTTP transports, Typer command line"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [{ name = "Adam Ladachowski" }]
+dependencies = [
+    "mcp>=1.12",
+    "typer>=0.15",
+    "rich>=13.9",
+    "uvicorn>=0.34",
+    "starlette>=0.46",
+    "pydantic>=2.10",
+    "pydantic-settings>=2.8",
+]
+
+[project.scripts]
+madcat = "madcat_os.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "httpx>=0.28",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/madcat_os"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

madcat_os-0.1.2/src/madcat_os/__init__.py

@@ -0,0 +1,10 @@
+"""MADCAT MCP — server and command line."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("madcat-os")
+except PackageNotFoundError:  # running from a checkout without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

madcat_os-0.1.2/src/madcat_os/cli.py

@@ -0,0 +1,189 @@
+"""madcat — the MADCAT command line.
+
+madcat mcp serve [--transport stdio|http] [--bind HOST:PORT] [--token T]
+madcat mcp list
+madcat mcp call <tool> ['<json>']
+madcat status
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.json import JSON
+from rich.panel import Panel
+from rich.table import Table
+
+from madcat_os import __version__
+from madcat_os.config import SERVER_NAME, Settings, settings
+from madcat_os.server import build_server
+
+app = typer.Typer(
+    name="madcat",
+    help="MADCAT — MCP server and tools, stdio or Streamable HTTP.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+mcp_app = typer.Typer(help="MCP server and tool registry", no_args_is_help=True)
+app.add_typer(mcp_app, name="mcp")
+
+# stdout is the MCP wire on stdio; everything human goes to stderr.
+console = Console(stderr=True)
+out = Console()
+
+
+class Transport(StrEnum):
+    stdio = "stdio"
+    http = "http"
+
+
+def _version(value: bool) -> None:
+    if value:
+        out.print(f"madcat {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=_version, is_eager=True, help="Print version")
+    ] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Debug logging")] = False,
+) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        stream=sys.stderr,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+
+@app.command()
+def status() -> None:
+    """Show effective configuration and tool count."""
+    cfg = settings()
+    mcp = build_server(cfg)
+    tools = asyncio.run(mcp.list_tools())
+    table = Table(box=box.SIMPLE, show_header=False)
+    table.add_column(style="bold cyan")
+    table.add_column()
+    table.add_row("server", f"{SERVER_NAME} {__version__}")
+    table.add_row("python", sys.version.split()[0])
+    table.add_row("http bind", f"{cfg.host}:{cfg.port}")
+    table.add_row("token", "[green]set[/]" if cfg.token else "[yellow]none[/]")
+    table.add_row("tools", str(len(tools)))
+    out.print(Panel(table, title="madcat", border_style="cyan"))
+
+
+@mcp_app.command("list")
+def mcp_list(
+    as_json: Annotated[bool, typer.Option("--json", help="Machine-readable output")] = False,
+) -> None:
+    """Tool inventory."""
+    mcp = build_server()
+    tools = asyncio.run(mcp.list_tools())
+    if as_json:
+        out.print_json(json.dumps([t.model_dump(mode="json") for t in tools]))
+        return
+    table = Table(title=f"{SERVER_NAME} tools ({len(tools)})", box=box.SIMPLE_HEAD)
+    table.add_column("tool", style="bold cyan", no_wrap=True)
+    table.add_column("description")
+    for t in tools:
+        table.add_row(t.name, (t.description or "").strip().splitlines()[0] if t.description else "")
+    out.print(table)
+
+
+@mcp_app.command("call")
+def mcp_call(
+    name: Annotated[str, typer.Argument(help="Tool name")],
+    args: Annotated[str, typer.Argument(help="JSON object of arguments")] = "{}",
+) -> None:
+    """Run one tool locally, no MCP client needed."""
+    try:
+        parsed = json.loads(args)
+    except json.JSONDecodeError as e:
+        console.print(f"[red]bad JSON arguments:[/] {e}")
+        raise typer.Exit(2) from None
+    if not isinstance(parsed, dict):
+        console.print("[red]arguments must be a JSON object[/]")
+        raise typer.Exit(2)
+
+    mcp = build_server()
+    try:
+        result = asyncio.run(mcp.call_tool(name, parsed))
+    except Exception as e:  # noqa: BLE001 — surface the tool error, then exit non-zero
+        console.print(f"[red]{name} failed:[/] {e}")
+        raise typer.Exit(1) from None
+
+    if result.structured_content is not None:
+        out.print(JSON.from_data(result.structured_content))
+        return
+    for block in result.content:
+        text = getattr(block, "text", None)
+        if text is None:
+            out.print(block)
+            continue
+        try:
+            out.print(JSON(text))
+        except Exception:  # noqa: BLE001 — plain text, not JSON
+            out.print(text)
+
+
+@mcp_app.command("serve")
+def mcp_serve(
+    transport: Annotated[
+        Transport, typer.Option("--transport", "-t", help="stdio or http")
+    ] = Transport.stdio,
+    bind: Annotated[str | None, typer.Option("--bind", help="HOST:PORT for http (default from env)")] = None,
+    token: Annotated[
+        str | None, typer.Option("--token", help="Bearer token for http", envvar="MADCAT_MCP_TOKEN")
+    ] = None,
+) -> None:
+    """Run the MCP server."""
+    overrides: dict = {}
+    if bind:
+        host, _, port = bind.rpartition(":")
+        if not host or not port.isdigit():
+            console.print(f"[red]--bind must be HOST:PORT, got {bind!r}[/]")
+            raise typer.Exit(2)
+        overrides.update(host=host, port=int(port))
+    if token:
+        overrides["token"] = token
+    cfg = Settings(**overrides) if overrides else settings()
+    mcp = build_server(cfg)
+
+    if transport is Transport.stdio:
+        from madcat_os.server import serve_stdio
+
+        console.print(f"[dim]{SERVER_NAME} {__version__} serving on stdio[/]")
+        serve_stdio(mcp)
+        return
+
+    from madcat_os.server import serve_http
+
+    console.print(
+        Panel(
+            f"[bold]{SERVER_NAME}[/] {__version__}\n"
+            f"http://{cfg.host}:{cfg.port}/mcp\n"
+            f"token: {'[green]set[/]' if cfg.token else '[yellow]none[/]'}",
+            title="madcat serve",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+    serve_http(mcp, cfg)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

madcat_os-0.1.2/src/madcat_os/config.py

@@ -0,0 +1,32 @@
+"""Runtime settings. Everything comes from the environment (prefix MADCAT_MCP_) or a .env file.
+
+Tools never read os.environ directly; they take a Settings instance.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+SERVER_NAME = "madcat"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MADCAT_MCP_", env_file=".env", extra="ignore")
+
+    host: str = Field(default="127.0.0.1", description="HTTP bind address")
+    port: int = Field(default=4097, description="HTTP bind port")
+    token: str | None = Field(default=None, description="Static bearer token for the HTTP transport")
+    allowed_hosts: list[str] = Field(
+        default_factory=list,
+        description="Host headers accepted by the HTTP transport (DNS-rebinding guard). "
+        "Empty: only the bind host when binding loopback, any host otherwise.",
+    )
+    log_level: str = Field(default="info", description="uvicorn / logging level")
+
+
+@lru_cache(maxsize=1)
+def settings() -> Settings:
+    return Settings()