Working with Agents¶

Two ways to put Patcher in front of an AI assistant.

Patcher meets agents on two surfaces. The server exposes the public catalog over the Model Context Protocol (MCP) so that Claude (Code & Desktop), Cursor, or any MCP-aware client can query app coverage through natural language. The Claude Code skill is a bundled slash command that looks up a Mac app across catalog sources, and vendor docs in one shot.

Connect your client

Connecting Claude, Cursor, and other agents to Patcher.

MCP Recipes

Interacting with Patcher via AI Agents

Claude Code Skill

MCP not the right fit? The bundled Patcher skill for Claude Code can act as a middleground.

MCP Server¶

Connect your AI clients to the server at mcp.patcherctl.dev. Once connected, you can ask natural-language questions and the assistant calls Patcher on your behalf, returning structured catalog data inline. No authentication is required as the catalog is public.

Connect Your Client¶

Claude Code

Automatically creates .mcp.json in project directory¶

$ claude mcp add --transport http patcher https://mcp.patcherctl.dev/mcp

Note

If you want Patcher available in every Claude Code session, pass the --scope user flag.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json¶

{
  "mcpServers": {
    "patcher": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.patcherctl.dev/mcp"]
    }
  }
}

Fully quit Claude Desktop (CMD+Q) and reopen. The Patcher tools appear in the menu next to the input box.

Cursor

Add to ~/.cursor/mcp.json¶

{
  "mcpServers": {
    "patcher": {
      "url": "https://mcp.patcherctl.dev/mcp"
    }
  }
}

Restart Cursor or use Refresh in the MCP panel to load the new server.

Verify It Works¶

Smoke-test the connection by asking a Patcher-flavored question. Structured catalog data back means you’re connected; if not, see Troubleshooting.

What You Can Ask¶

You don’t need to call these tools by name, your AI client picks the right one automatically based on your question.

Get a catalog summary

Top-line stats. Total apps and per-source coverage counts.

Search apps

Fuzzy lookup across slug, name, vendor, and bundle ID.

Get a specific app

The full record for one app (versions, sources, download URL, installation method).

Listing drift

Apps where upstream sources disagree on the latest version.

Listing categories

Distinct install methods, sources, and vendors present in the catalog.

See the MCP tools reference for full signatures, and MCP recipes for worked prompt examples.

Troubleshooting¶

If the tools don’t appear after configuring:

Check server health

$ curl -sS https://mcp.patcherctl.dev/health

Should return {"status":"ok"}. If it does not, the catalog itself is unreachable. If it does, the server is up and running and the issue is client-side.

Check your agents

Claude Code: claude mcp list confirms whether the server is registered. Re-run claude mcp add if it’s missing.
Claude Desktop: Fully quit (CMD+Q, not just close the window) and reopen. The MCP config is read once at launch.
Cursor: The MCP panel has a Refresh control. Restart Cursor if it still doesn’t appear.

Check debugging logs

Speak MCP directly and surface any handshake errors verbatim.¶

$ fastmcp list https://mcp.patcherctl.dev/mcp --transport http --auth none

MCP Recipes¶

A handful of tools, lots of useful questions. This section groups example prompts by intent so you can crib whichever match your workflow. The assistant picks the right tool based on phrasing; you don’t have to invoke them by name.

For full tool signatures, see MCP Tools.

Catalog-Wide Questions¶

Top-level reads when you want to know what Patcher knows or which sources cover what.

Summarize the Patcher catalog.

Which install methods are represented in the catalog?

How many apps does Patcher track from Mozilla?

These call get_catalog_summary or list_categories.

Single-App Drilldowns¶

When you know (or roughly know) the app and want the full record.

What's the latest version of Slack?

Show me the full Patcher record for 1Password 8.

What's the download URL for the latest Firefox build?

These call get_app, or search_apps first to disambiguate (e.g. firefox, firefoxesr, firefoxpkg).

Drift and Quality Audits¶

Do upstream sources agree on the latest version?

Are there any apps with version drift across sources?

Show me drift for Mozilla apps specifically.

Which apps have Installomator and Homebrew Cask disagreeing on what's latest?

Backed by list_drift, which can filter by vendor or by which source must have participated in the disagreement. Useful for triaging “did this label fall behind upstream?” without scanning the full catalog by hand. For the underlying mental model, see Resolution.

Search and Exploration¶

When you only have a partial app name, or want to compare a few apps.

Find me apps with "office" in the name.

What apps does Patcher track from Microsoft?

Search the catalog for anything matching "vsc".

Backed by search_apps, which matches case-insensitively against slug, name, vendor, and bundle ID.

Chained Questions¶

The assistant happily calls multiple tools in one turn when a question requires it. A prompt like the one below first calls search_apps to find Mozilla apps, then list_drift filtered to that vendor.

For every Mozilla app in the catalog, tell me whether sources agree on the latest version.

Find Adobe apps and show me which ones have version drift.

This is where MCP earns its keep relative to other methods of Patcher use. Describe the goal and the assistant picks the tools and orchestrates the calls.

Working in Claude Code¶

If you’ve connected the MCP server inside a Claude Code session in this repo, the catalog is one prompt away from any other work. It’s especially useful when adding tests or debugging matching.

Show me everything Patcher knows about Sublime Text

List apps where my Installomator label is silently behind Homebrew Cask

Patcher Skill¶

Patcher ships a Claude Code skill alongside the repository. It’s a read-only lookup utility that takes an app name, checks catalog sources, and pulls vendor and Jamf deployment documentation into one report. No database writes, no Jamf access required.

Install¶

The skill lives in the Patcher repo, so contributors who clone Patcher already have it. To make the skill available across every Claude Code session regardless of working directory, copy it into your user-level skills directory.

$ mkdir -p ~/.claude/skills
$ cp -R /path/to/Patcher/.claude/skills/patcher ~/.claude/skills/

Note

The Installomator matching step calls uv run python with rapidfuzz. Either run user-scoped invocations from inside a project that has rapidfuzz available, or install it on a system Python that uv run falls back to.

Usage¶

Pass the name of the app to the skill. The app name will be normalized (lowercased, whitespace stripped and dots removed) before matching but preserves the original form in the report.

/patcher Google Chrome

/patcher "Cisco AnyConnect Secure Mobility Client"

Sample output for a well-covered app (Slack)¶

App: Slack
─────────────────────────────────────────────────────────────

Installomator
  slack                                    score 100  (direct, exact)

Homebrew Cask
  slack                                    v4.42.117

AutoPkg
  autopkg/recipes/Slack/Slack.download.recipe       (source: local)
  autopkg/recipes/Slack/Slack.pkg.recipe            (source: local)

Jamf App Installer
  skipped (no Jamf access). Browse public catalog at:
  https://learn.jamf.com/r/en-US/jamf-app-catalog/App_Installers_Software_Titles

Deployment docs
  Slack — Manage Slack at your organization
    https://slack.com/help/articles/115004629603

Confidence Flags¶

Skill will output a confidence score so you can determine accuracy of findings.

Score	Flag	Meaning
`100`	exact	Direct or normalized hit on the label name
`85`–`99`	high conf	Above Patcher’s default matching threshold, would auto-match
`75`–`84`	below threshold	Surfaced for visibility, would NOT be picked up automatically

Limitations¶

AutoPkg fallback is org-scoped

When local autopkg search isn’t available, the skill falls back to a GitHub code search across the autopkg/ org only. Community recipes outside that org won’t surface.

Web search filters aggressively

The Deployment docs section prefers vendor admin docs, learn.jamf.com, and community.jamf.com accepted solutions. Blog posts and YouTube tutorials are rejected by design. If nothing high-quality surfaces, the section reports (no official deployment docs surfaced) rather than fabricating links.

Not a version source

For current versions and install commands, use the patcherctl CLI or PatcherAPIClient against api.patcherctl.dev.