Metadata-Version: 2.4
Name: agent-harnesses-mcp
Version: 0.1.1
Summary: MCP server for best-of-Agent-Harnesses: harness recommendations, search, and head-to-head decision guides over a hand-curated, weekly-rescored list of 110 agent harnesses
Project-URL: Repository, https://github.com/RyanAlberts/best-of-Agent-Harnesses
Project-URL: Documentation, https://github.com/RyanAlberts/best-of-Agent-Harnesses/tree/main/mcp
Author: Ryan Alberts
License-Expression: MIT
Keywords: agent-harness,agents,llm,mcp,model-context-protocol
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

# agent-harnesses MCP server

`mcp-name: io.github.RyanAlberts/agent-harnesses`

The [best-of-Agent-Harnesses](https://github.com/RyanAlberts/best-of-Agent-Harnesses) list as an MCP server, so agents can recommend harnesses instead of you reading 101 table rows.

Single file, stdio transport, no clone needed — it fetches [harnesses.json](../harnesses.json) from this repo at startup (or reads it locally from a checkout). Requires [uv](https://docs.astral.sh/uv/).

## Install

Claude Code:

```sh
claude mcp add agent-harnesses -- uv run https://raw.githubusercontent.com/RyanAlberts/best-of-Agent-Harnesses/main/mcp/server.py
```

Any other MCP client (Cursor, Codex, Gemini CLI, ...):

```json
{
  "mcpServers": {
    "agent-harnesses": {
      "command": "uv",
      "args": ["run", "https://raw.githubusercontent.com/RyanAlberts/best-of-Agent-Harnesses/main/mcp/server.py"]
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `pick_harness(use_case, max_complexity?, min_autonomy?, min_recovery?, open_source_only?, limit?)` | Ranked recommendations for a use case, seeded by the list's hand-curated use-case index. `max_complexity` caps adoption surface (`super simple` → `complex`); `min_autonomy` requires a designed autonomy regime (`step-gated` → `headless`); `min_recovery` requires a failure-recovery tier (`none` → `durable`). |
| `search_harnesses(query, limit?)` | Keyword search across names, descriptions, tags, and categories. |
| `get_harness(github_id)` | Full record for one project. |
| `list_comparisons()` | The head-to-head decision guides (OpenClaw vs Hermes, terminal coding agents, …) with summaries. |
| `get_comparison(slug)` | Full markdown of one guide — architecture trade-offs, field reports, billing reality. Always current: served from the repo's `main`. |
| `list_categories()` | The 10 categories, use-case intents, and the complexity/autonomy/recovery scales. |

Example: *"pick_harness('sandboxed code execution for generated code', max_complexity='slightly complex', open_source_only=True)"* → E2B, smolagents, Daytona... each with stars, tier, license signal, and a one-line reason.

Data is regenerated by [`scripts/generate.py`](../scripts/generate.py); star counts carry a `stars_captured` date, and the comparisons index is rebuilt from `comparisons/*.md` on every refresh — the server always serves current `main`.

## Distribution

The server is packaged as **`agent-harnesses-mcp`** (this directory's `pyproject.toml`) and registered in the official MCP registry as **`io.github.RyanAlberts/agent-harnesses`** (`server.json` at the repo root). Once a release is published, package-manager installs work everywhere:

```sh
# any MCP client, via PyPI
uvx agent-harnesses-mcp
# Claude Code
claude mcp add agent-harnesses -- uvx agent-harnesses-mcp
```

Until then (and forever, as the zero-install path), the raw-URL one-liner at the top of this README works from any machine with uv.

## Publishing (maintainer runbook)

Releases are automated by [`.github/workflows/publish-mcp.yml`](../.github/workflows/publish-mcp.yml) on a `mcp-v*` tag: it builds the wheel, publishes to PyPI via trusted publishing, and publishes `server.json` to the official MCP registry via GitHub OIDC.

One-time setup, then never again:
1. On pypi.org: create the project name `agent-harnesses-mcp` → Settings → Publishing → add a **trusted publisher**: owner `RyanAlberts`, repo `best-of-Agent-Harnesses`, workflow `publish-mcp.yml`. No API tokens.
2. Nothing for the MCP registry — GitHub OIDC from this repo authorizes the `io.github.RyanAlberts/*` namespace automatically.

Per release: bump the version in `mcp/pyproject.toml` **and** `server.json` (the workflow fails loudly on mismatch), then `git tag mcp-v<version> && git push origin mcp-v<version>`.

Also indexed via [`smithery.yaml`](../smithery.yaml) (submit the repo once at [smithery.ai](https://smithery.ai)); other directories (Glama, PulseMCP, mcpservers.org) crawl the official registry.
