Metadata-Version: 2.4
Name: agent-harnesses-mcp
Version: 0.3.0
Summary: MCP server for best-of-Agent-Harnesses: opinionated harness recommendations (recommend/pick_harness), search, and head-to-head decision guides over a hand-curated, weekly-rescored list of 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 100+ 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

Published on [PyPI](https://pypi.org/project/agent-harnesses-mcp/) and the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.RyanAlberts/agent-harnesses`. Claude Code:

```sh
claude mcp add agent-harnesses -- uvx agent-harnesses-mcp
```

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

```json
{
  "mcpServers": {
    "agent-harnesses": {
      "command": "uvx",
      "args": ["agent-harnesses-mcp"]
    }
  }
}
```

No-install alternative — run the single source file straight from this repo:

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

## Tools

| Tool | What it does |
|---|---|
| `recommend(need, language?, must_run_unattended?, open_source_only?)` | **Opinionated single recommendation** — a decision, not a list. Returns one top pick with the reason, up to two alternatives, any harnesses to **avoid** for this need (archived, or flagged for star manipulation — with why), and the most relevant decision guide to read next. |
| `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`). |
| `compare(github_ids)` | **Side-by-side of 2–4 harnesses** — "should I use X or Y?". Records aligned on the list's axes, an edge summary naming who leads on stars / adoption simplicity / autonomy / failure recovery, a warning when a requested repo is in the graveyard (archived or integrity-flagged), and the decision guide covering the matchup when one exists. |
| `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: *"recommend('an always-on personal assistant that lives in my chat apps', open_source_only=True)"* → one top pick with the reason, two alternatives, anything to avoid for this need, and the guide to read next.

Example: *"compare(['openclaw/openclaw', 'NousResearch/hermes-agent'])"* → both records side by side, who leads on which axis, and a pointer to the *OpenClaw vs Hermes* guide.

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 live in the official MCP registry as **`io.github.RyanAlberts/agent-harnesses`** (`server.json` at the repo root), which directories like Glama and PulseMCP crawl. The registry validates PyPI ownership via the `mcp-name:` marker at the top of this README — keep it.

## 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>`.

Directories like Glama, PulseMCP, and mcpservers.org crawl the official registry — no per-directory submissions needed. (Smithery's current publish flow takes hosted-HTTP servers or `.mcpb` bundles, not stdio-from-GitHub, so this server isn't listed there by design.)
