harnessmith 0.1.0__py3-none-any.whl

harnessmith/__init__.py

@@ -0,0 +1,3 @@
+"""HarnessSmith — forge your own agent harness (config-to-code generator)."""
+
+__version__ = "0.1.0"

harnessmith/catalog/__init__.py

@@ -0,0 +1,166 @@
+"""Static MCP server catalog — a generation-time convenience datasource (Slice 6).
+
+Loaded by ``harnessmith new --mcp-server <name>`` and by presets to PREFILL the
+generated repo's runtime ``config.yaml`` (``mcp.servers`` + the tool allowlist).
+It is **not** a security gate and is **not** part of :class:`HarnessSpec` or its
+snapshot — the real gate is the runtime allowlist + per-tool risk markers.
+Secrets are referenced by env-var NAME only, never stored as values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+CATALOG_PATH = Path(__file__).parent / "mcp_servers.yaml"
+
+SAFE = "safe"
+HIGH = "high"
+
+
+class CatalogError(Exception):
+    """Raised when the catalog file or a requested server is invalid/missing."""
+
+
+@dataclass(frozen=True)
+class CatalogTool:
+    name: str
+    risk: str = HIGH
+    default_enabled: bool = False
+
+
+@dataclass(frozen=True)
+class CatalogServer:
+    """One curated MCP server entry (transport + tools + provenance)."""
+
+    name: str
+    description: str = ""
+    transport: str = "stdio"  # "stdio" | "remote"
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    env: list[str] = field(default_factory=list)  # env-var NAMES (secrets, from .env)
+    env_const: dict[str, str] = field(default_factory=dict)  # literal non-secret env (e.g. MODE=stdio)
+    url: str | None = None
+    auth_env: str | None = None
+    requires: str | None = None  # runtime prerequisite: "uv" | "node" | None
+    source: str = ""
+    updated: str = ""
+    tools: list[CatalogTool] = field(default_factory=list)
+
+    @property
+    def safe_tools(self) -> list[str]:
+        """Unprefixed names of read-only/low-risk tools (offered to plan/ask)."""
+        return [t.name for t in self.tools if t.risk == SAFE]
+
+    @property
+    def uvx_package(self) -> str | None:
+        """The pip/uvx package name for a uvx-launched server (else ``None``).
+
+        Handles both ``uvx <pkg>`` and ``uvx --from <pkg> <entrypoint>`` (used when
+        the package's console-script name differs from the package name) by taking
+        the first non-flag arg — matching the runtime warm path (``_warm_argv``)."""
+        if self.command == "uvx":
+            return next((a for a in self.args if not a.startswith("-")), None)
+        return None
+
+    def server_entry(self) -> dict:
+        """A ``config.yaml`` ``mcp.servers`` entry (env-var NAMES only)."""
+        entry: dict = {"name": self.name}
+        if self.description:
+            entry["description"] = self.description
+        if self.command:
+            entry["command"] = self.command
+            entry["args"] = list(self.args)
+            if self.env:
+                entry["env"] = list(self.env)
+            if self.env_const:
+                entry["env_const"] = dict(self.env_const)
+        else:
+            entry["url"] = self.url
+            if self.auth_env:
+                entry["auth_env"] = self.auth_env
+        if self.safe_tools:
+            entry["safe_tools"] = self.safe_tools
+        return entry
+
+    def allowlist_entries(self) -> list[dict]:
+        """``config.yaml`` ``tools`` allowlist entry for this server.
+
+        A single ``<server>__*`` wildcard that enables EVERY tool the server
+        exposes (present and future), so the full toolset is available by default
+        without listing each tool by name. Per-tool risk still comes from
+        ``safe_tools`` (read-only tools stay ``safe``; the rest are ``high``), and
+        any tool can be turned off individually later from ``config.yaml`` / the web
+        Tools panel.
+        """
+        return [{"name": f"{self.name}__*", "enabled": True}]
+
+
+def _coerce_server(name: str, data: dict) -> CatalogServer:
+    tools = [
+        CatalogTool(
+            name=t["name"],
+            risk=t.get("risk", HIGH),
+            default_enabled=bool(t.get("default_enabled", False)),
+        )
+        for t in (data.get("tools") or [])
+    ]
+    return CatalogServer(
+        name=name,
+        description=data.get("description", ""),
+        transport=data.get("transport", "stdio"),
+        command=data.get("command"),
+        args=list(data.get("args") or []),
+        env=list(data.get("env") or []),
+        env_const={str(k): str(v) for k, v in (data.get("env_const") or {}).items()},
+        url=data.get("url"),
+        auth_env=data.get("auth_env"),
+        requires=data.get("requires"),
+        source=data.get("source", ""),
+        updated=str(data.get("updated", "")),
+        tools=tools,
+    )
+
+
+def load_catalog(path: str | Path = CATALOG_PATH) -> dict[str, CatalogServer]:
+    """Load the catalog into a name -> :class:`CatalogServer` mapping."""
+    path = Path(path)
+    if not path.exists():
+        raise CatalogError(f"catalog file not found: {path}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    servers = data.get("servers") or {}
+    if not isinstance(servers, dict):
+        raise CatalogError("catalog 'servers' must be a mapping of name -> entry")
+    return {name: _coerce_server(name, entry) for name, entry in servers.items()}
+
+
+def available_servers() -> list[str]:
+    """Names of curated catalog servers."""
+    return sorted(load_catalog())
+
+
+def get_server(name: str) -> CatalogServer:
+    """Resolve a catalog server by name (raises :class:`CatalogError`)."""
+    catalog = load_catalog()
+    if name not in catalog:
+        known = ", ".join(sorted(catalog)) or "(none)"
+        raise CatalogError(f"unknown MCP server {name!r}; catalog has: {known}")
+    return catalog[name]
+
+
+def resolve_servers(names: list[str]) -> list[CatalogServer]:
+    """Resolve catalog server names, de-duplicated, preserving first-seen order."""
+    catalog = load_catalog()
+    resolved: list[CatalogServer] = []
+    seen: set[str] = set()
+    for name in names:
+        if name in seen:
+            continue
+        if name not in catalog:
+            known = ", ".join(sorted(catalog)) or "(none)"
+            raise CatalogError(f"unknown MCP server {name!r}; catalog has: {known}")
+        resolved.append(catalog[name])
+        seen.add(name)
+    return resolved

harnessmith/catalog/mcp_servers.yaml

@@ -0,0 +1,185 @@
+# Curated MCP server catalog (HarnessSmith, Slice 6).
+#
+# A *generation-time convenience datasource* — used by `harnessmith new
+# --mcp-server <name>` and by presets to PREFILL the generated repo's runtime
+# config.yaml (mcp.servers + tool allowlist). It is NOT a security gate and is
+# NOT part of HarnessSpec or its snapshot: the real gate is the runtime tool
+# allowlist + per-tool risk markers (high-risk tools default OFF). Secrets are
+# referenced by env-var NAME only — never values.
+#
+# Because the generated harness ships no built-in productivity tools, these MCP
+# presets double as the *capability baseline*. Each prefilled server is enabled by
+# a single `<server>__*` wildcard in config.yaml — its WHOLE toolset (read +
+# mutating/shell) is on by default (narrow it after generation if you want).
+# uvx-based servers (requires: uv) can be prewarmed at generation and baked into
+# the Docker image for offline use; Node-based servers (requires: node) need
+# Node/npx on the host.
+#
+# Per-tool `risk`: safe = read-only / low-impact (offered even to read-only
+# paradigms like plan/ask); high = mutating / shell / network side effects
+# (agent-only). `risk` feeds `safe_tools` (risk grading); the per-tool
+# `default_enabled` flag is retained as documentation but the prefill now enables
+# every tool via the wildcard regardless.
+version: 1
+
+servers:
+  fetch:
+    description: Fetch a URL from the internet and extract its content as markdown.
+    transport: stdio
+    command: uvx
+    args: [mcp-server-fetch]
+    requires: uv
+    source: https://pypi.org/project/mcp-server-fetch/
+    updated: "2026-06-04"
+    tools:
+      - {name: fetch, risk: safe, default_enabled: true}
+
+  web-search:
+    # Default web-search server: a keyless, multi-engine scraper that probes each
+    # engine for reachability and FAILS OVER between them (Bing / Baidu / DuckDuckGo
+    # / Brave / Sogou / …), so it keeps working when any single engine is slow or
+    # unreachable on a given network — much more resilient than a single-engine
+    # scraper. Node-based (npx); launched directly from a stable per-server install
+    # (see harness/mcp.py `_node_*`), never the ephemeral npx cache. `MODE=stdio`
+    # (env_const) keeps it a pure stdio MCP server — without it the default `both`
+    # mode also binds an HTTP port. Pinned (NOT @latest) so warm-on-first-run
+    # installs the exact version the later connect launches; bump it + `updated:`
+    # together when refreshing. Still an HTML scraper, so an engine layout change
+    # can degrade a single engine (the failover absorbs it).
+    description: >-
+      Multi-engine web search (Bing, Baidu, DuckDuckGo, Brave, Sogou, and more)
+      with automatic failover; keyless. Returns title, URL, and snippet per
+      result, and can fetch a result page's content. Some engines may be
+      unreachable on certain networks — it falls back across engines automatically.
+    transport: stdio
+    command: npx
+    args: ["-y", "open-websearch@2.1.11"]
+    env_const: {MODE: stdio}
+    requires: node
+    source: https://github.com/Aas-ee/open-webSearch
+    updated: "2026-06-14"
+    tools:
+      # All read-only network reads (search + fetch a page) -> safe, so the
+      # read-only plan/ask paradigms can search/read too.
+      - {name: search, risk: safe, default_enabled: true}
+      - {name: fetchWebContent, risk: safe, default_enabled: true}
+      - {name: fetchGithubReadme, risk: safe, default_enabled: true}
+      - {name: fetchCsdnArticle, risk: safe, default_enabled: false}
+      - {name: fetchLinuxDoArticle, risk: safe, default_enabled: false}
+      - {name: fetchJuejinArticle, risk: safe, default_enabled: false}
+
+  ddg-search:
+    # uvx-based (no Node) keyless fallback. DuckDuckGo is unreachable on some
+    # networks — prefer `web-search` (multi-engine) there; this stays as a
+    # lightweight uvx alternative for hosts without Node, or where DuckDuckGo is
+    # reachable. Add with `--mcp-server ddg-search`.
+    description: >-
+      Web search via DuckDuckGo (keyless) plus fetching a result page as
+      markdown. A uvx-based alternative (no Node); DuckDuckGo is unreachable on
+      some networks, where web-search is the better default.
+    transport: stdio
+    command: uvx
+    args: [duckduckgo-mcp-server]
+    requires: uv
+    source: https://github.com/nickclyde/duckduckgo-mcp-server
+    updated: "2026-06-14"
+    tools:
+      - {name: search, risk: safe, default_enabled: true}
+      - {name: fetch_content, risk: safe, default_enabled: true}
+
+  git:
+    description: Inspect and operate on local Git repositories (read tools on; write tools off).
+    transport: stdio
+    command: uvx
+    # No --repository pin on purpose: every git tool already takes a required
+    # `repo_path` arg, so pinning adds no default — it ONLY restricts which repo is
+    # reachable, AND makes mcp-server-git EXIT at startup when launched outside a
+    # git repo (it surfaces as the server going "unreachable: Connection closed").
+    # The server's health should reflect the tool, not the cwd; unpinned it stays
+    # up and the agent operates on whatever repo it points `repo_path` at.
+    args: [mcp-server-git]
+    requires: uv
+    source: https://pypi.org/project/mcp-server-git/
+    updated: "2026-06-04"
+    tools:
+      - {name: git_status, risk: safe, default_enabled: true}
+      - {name: git_diff_unstaged, risk: safe, default_enabled: true}
+      - {name: git_diff_staged, risk: safe, default_enabled: true}
+      - {name: git_diff, risk: safe, default_enabled: true}
+      - {name: git_log, risk: safe, default_enabled: true}
+      - {name: git_show, risk: safe, default_enabled: true}
+      - {name: git_branch, risk: safe, default_enabled: true}
+      - {name: git_add, risk: high, default_enabled: false}
+      - {name: git_reset, risk: high, default_enabled: false}
+      - {name: git_commit, risk: high, default_enabled: false}
+      - {name: git_create_branch, risk: high, default_enabled: false}
+      - {name: git_checkout, risk: high, default_enabled: false}
+      - {name: git_init, risk: high, default_enabled: false}
+
+  desktop-commander:
+    description: Terminal command execution + full filesystem read/write/edit (powerful; read tools safe, write/shell high-risk).
+    transport: stdio
+    command: npx
+    # `--silent` keeps npm OUT of the child's stdout. A stdio MCP child's stdout
+    # must be PURE JSON-RPC, but on first launch `npx` installs the package and
+    # (on older npm) leaks its `added N packages ...` summary to stdout — which the
+    # MCP reader then tries to parse as protocol, spamming parse tracebacks. npm
+    # logs/warnings go to stderr (captured separately), and `--silent` does NOT
+    # touch the launched server's own stdout, so the protocol stream is unaffected.
+    # Pinned (NOT @latest) on purpose: warm-on-first-run pre-fetches THIS exact
+    # version into the npx cache, and a pin is what makes the later connect a true
+    # offline cache hit — `@latest` would re-hit the registry to re-resolve and could
+    # miss the warmed copy. Bump the version + `updated:` together when refreshing.
+    args: ["--silent", "-y", "@wonderwhy-er/desktop-commander@0.2.42"]
+    requires: node
+    source: https://github.com/wonderwhy-er/DesktopCommanderMCP
+    updated: "2026-06-14"
+    # A representative subset (Desktop Commander exposes ~26 tools). The prefilled
+    # `desktop-commander__*` wildcard enables the WHOLE discovered set (needs Node);
+    # the per-tool `risk` below grades it. Read-only tools are `safe` so the
+    # read-only plan/ask paradigms can use them too (without them, plan/ask get NO
+    # filesystem access at all — see Slice 5); write/shell/config-mutating tools are
+    # `high` (agent-only, HITL-gated). Risk grading matches the discovered tools BY
+    # NAME, so naming the real read-only tools here is what lets plan/ask read files.
+    tools:
+      # Read-only (safe): also offered to the read-only plan/ask paradigms.
+      - {name: read_file, risk: safe, default_enabled: false}
+      - {name: read_multiple_files, risk: safe, default_enabled: false}
+      - {name: list_directory, risk: safe, default_enabled: false}
+      - {name: get_file_info, risk: safe, default_enabled: false}
+      - {name: start_search, risk: safe, default_enabled: false}
+      - {name: get_more_search_results, risk: safe, default_enabled: false}
+      - {name: list_searches, risk: safe, default_enabled: false}
+      # Mutating / shell / config writes (high): agent-only, off by default.
+      - {name: write_file, risk: high, default_enabled: false}
+      - {name: edit_block, risk: high, default_enabled: false}
+      - {name: create_directory, risk: high, default_enabled: false}
+      - {name: move_file, risk: high, default_enabled: false}
+      - {name: set_config_value, risk: high, default_enabled: false}
+      - {name: start_process, risk: high, default_enabled: false}
+      - {name: kill_process, risk: high, default_enabled: false}
+
+  # --- Extra candidates (not in the coding-assistant baseline). Add with
+  #     `--mcp-server <name>` or paste the server block into config.yaml. ---
+
+  time:
+    description: Current time and timezone conversion utilities.
+    transport: stdio
+    command: uvx
+    args: [mcp-server-time]
+    requires: uv
+    source: https://pypi.org/project/mcp-server-time/
+    updated: "2026-06-04"
+    tools:
+      - {name: get_current_time, risk: safe, default_enabled: true}
+      - {name: convert_time, risk: safe, default_enabled: true}
+
+  github:
+    description: GitHub platform API (issues / PRs / repos). Remote MCP — needs a token.
+    transport: remote
+    url: https://api.githubcopilot.com/mcp/
+    auth_env: GITHUB_MCP_TOKEN
+    source: https://github.com/github/github-mcp-server
+    updated: "2026-06-04"
+    # Large surface (70+ tools); enable specific tools by name as needed.
+    tools: []