# headlesson

> Find and compare headless apps (CLI, MCP, API) for agents, with sources, lessons and changes.

- name: com.headlesson/catalog
- version: 0.1.0
- connection class: R0 (autonomous)
- trust: 81/100 flags: no-repository
- quality: 73/100 (needs work)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/com.headlesson%2Fcatalog
- tools: https://api.protogrid.dev/v1/servers/com.headlesson%2Fcatalog/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "catalog": {
      "type": "http",
      "url": "https://mcp.headlesson.com/mcp"
    }
  }
}
```


## Trust

- hygiene: 80
- liveness: 96
- freshness: 100
- provenance: 55
- drivers: +dns-namespace +website +reachable +uptime-89% +updated-10d-ago -no-repository
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 73/100 (needs work)

### protocol: 88 (weight 25)

- pass `protocol.modern`: supports 2026-07-28 (server/discover)
- pass `protocol.stateless`: answers without a session
- pass `protocol.transport`: streamable HTTP
- warn `protocol.list_ttl`: tools/list declares ttlMs 0, so clients re-fetch it on every use

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 86 (weight 30)

- pass `tools.descriptions`: every tool has a description
- pass `tools.description_length`: descriptions are concise
- pass `tools.schemas`: every tool has an object input schema
- pass `tools.annotations`: 4 of 4 tools declare readOnlyHint or destructiveHint
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: headlesson_feedback (idempotentHint); headlesson_search (idempotentHint); headlesson_whats_new (idempotentHint); …
- pass `tools.token_cost`: about 1,989 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 25 (weight 15)

- warn `stability.changes`: 9 tool changes in 30 days
- fail `stability.rug_pull`: 5 tools kept their name but changed most of their description in 30 days; review before trusting them

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 4, about 1,989 tokens to load them all
- tool set hash: 10aca7b4634e021bcbae472403d3f225
- tools last changed: 2026-10-15T07:53:58.344Z
- badge: [![protogrid quality](https://protogrid.dev/badge/com.headlesson/catalog.svg)](https://protogrid.dev/servers/com.headlesson/catalog)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

- 2026-10-15 `headlesson_feedback` changed (annotations)
- 2026-10-15 `headlesson_whats_new` changed (annotations)
- 2026-10-15 `headlesson_get` changed (annotations)
- 2026-10-15 `headlesson_search` changed (annotations)
- 2026-10-13 `headlesson_whats_new` changed (title, description) **meaning changed**
  - before: List documented changes since a date, optionally by kind or affected record. Public source URLs remain; private sources use non-URL labels and grouped exceptions.
  - after: List dated changes in agent tools and standards (new tools, renames, deprecations, breaking changes, new standards) since a date, optionally by kind or affected record. Useful for checking what changed after your training data. Public source URLs are kept; private sources appear as labels.
- 2026-10-13 `headlesson_get` changed (title, description) **meaning changed**
  - before: Get a curated record or a live Registry listing by ID. Live reversible name IDs re-fetch the fixed official detail endpoint without a stored mapping; old local full-import hash IDs cannot be resolved here. Live lookup may contact the Official Registry; a detail failure does not prove the ID absent. Private source tuples use non-URL source labels and grouped non-public exceptions; docs/homepage labels are not links. operator_own and the whole lesson.test subtree retain their values as operator observations excluded from source-default inheritance; passed/partial/failed include a dated execution report.
  - after: Get one record by an ID from headlesson_search: an app, usecase, feature, concept or change. For an app, sections ["lesson","gotchas"] return the install, check and first-task steps with the recorded test result (a dated observation by the headlesson operator) and known failure conditions; "relations" lists alternatives and what it wraps or depends on; "axes" returns every compared fact. Without sections you get the description, interfaces and six main axes. Each fact carries its source and check date; private sources appear as labels, not links. Official MCP Registry listing IDs are fetched live and are unverified; a failed lookup does not prove the ID absent.
- 2026-10-13 `headlesson_search` changed (title, description) **meaning changed**
  - before: Find and compare CLI, MCP, and API apps by task, name, and confirmed axes. Curated records are preferred. Only when curated_not_found or include:["registry"] is requested, one public name fragment (longest significant ASCII word from free text, or a supplied namespace; max 200 characters) may be sent to the Official MCP Registry. Full free text, IDs, general words and where-only queries are not sent. Recognized credential, URL and PII patterns skip external lookup; this is not a complete secret filter. Official registry_name and declared remote URLs/package kinds and identifiers are returned as unverified data. At most five unverified listings are compared within one returned page; descriptions/task intent are not searched. Search status and completeness distinguish a failed/skipped lookup from no returned candidates. External lookup results are not stored or cached; normal allowlisted tool/result logging remains. Known axis spelling aliases are normalized (licence to license, local_mcp_server to local_mcp, remote_mcp_server to remote_mcp); unrecognized axes are reported as unknown_axes. Private sources use an operator-provided or editorial source label; local paths are not returned as citations. Non-public provenance exceptions are grouped by source/at/cert/by. operator_own is an operational observation excluded from source-default inheritance.
  - after: Find command-line tools, MCP servers and APIs for a task, and compare them. Ask in plain English or Japanese ("extract text from scanned PDFs") or by product name. Each result gives an ID, a one-line reason it matches, and when it was checked. Pass the ID to headlesson_get with sections ["lesson","gotchas"] to get the steps (install, check, first task) with their recorded test result (most were run by an agent; a few are untested) and known failure conditions, such as a tool that exits 0 with empty or wrong output. Filter or compare with axes such as auth, pricing, license and remote_mcp (where, axes, ids). Curated records come first. If none match, or include:["registry"] is set, one public word from the query is looked up in the Official MCP Registry; those listings are unverified (what is sent is described on the query field).
- 2026-10-11 `headlesson_get` changed (description, annotations) **meaning changed**
  - before: Get a recorded app, concept, protocol, usecase, feature, axes or search guide by ID. Private source tuples use non-URL source labels and grouped non-public exceptions; docs/homepage labels are not links. operator_own and lesson.tested retain their values but are operational observations excluded from source-default inheritance.
  - after: Get a curated record or a live Registry listing by ID. Live reversible name IDs re-fetch the fixed official detail endpoint without a stored mapping; old local full-import hash IDs cannot be resolved here. Live lookup may contact the Official Registry; a detail failure does not prove the ID absent. Private source tuples use non-URL source labels and grouped non-public exceptions; docs/homepage labels are not links. operator_own and the whole lesson.test subtree retain their values as operator observations excluded from source-default inheritance; passed/partial/failed include a dated execution report.
- 2026-10-11 `headlesson_search` changed (description, inputSchema, annotations) **meaning changed**
  - before: Find and compare CLI, MCP, and API apps by task, name, and confirmed axes. Known axis spelling aliases are normalized (licence to license, local_mcp_server to local_mcp, remote_mcp_server to remote_mcp); unrecognized axes are reported as unknown_axes. Private sources use an operator-provided or editorial source label; local paths are not returned as citations. Non-public provenance exceptions are grouped by source/at/cert/by. operator_own is an operational observation excluded from source-default inheritance.
  - after: Find and compare CLI, MCP, and API apps by task, name, and confirmed axes. Curated records are preferred. Only when curated_not_found or include:["registry"] is requested, one public name fragment (longest significant ASCII word from free text, or a supplied namespace; max 200 characters) may be sent to the Official MCP Registry. Full free text, IDs, general words and where-only queries are not sent. Recognized credential, URL and PII patterns skip external lookup; this is not a complete secret filter. Official registry_name and declared remote URLs/package kinds and identifiers are returned as unverified data. At most five unverified listings are compared within one returned page; descriptions/task intent are not searched. Search status and completeness distinguish a failed/skipped lookup from no returned candidates. External lookup results are not stored or cached; normal allowlisted tool/result logging remains. Known axis spelling aliases are normalized (licence to license, local_mcp_server to local_mcp, remote_mcp_server to remote_mcp); unrecognized axes are reported as unknown_axes. Private sources use an operator-provided or editorial source label; local paths are not returned as citations. Non-public provenance exceptions are grouped by source/at/cert/by. operator_own is an operational observation excluded from source-default inheritance.

Full history: https://api.protogrid.dev/v1/servers/com.headlesson%2Fcatalog/changes

## Remotes

- https://mcp.headlesson.com/mcp (streamable-http, auth none, reachable true, uptime30d 0.8947368)

## Packages

_none_

## Tools (4)

- `headlesson_feedback`: This content is sent to the headlesson operator. Feedback about headlesson itself is sufficient. Do not include personal information or conversation contents.
- `headlesson_get`: Get one record by an ID from headlesson_search: an app, usecase, feature, concept or change. For an app, sections ["lesson","gotchas"] return the install, check and first-task steps with the recorded test result (a dated observation by the headlesson operator) and known failure conditions; "relations" lists alternatives and what it wraps or depends on; "axes" returns every compared fact. Without sections you get the description, interfaces and six main axes. Each fact carries its source and check date; private sources appear as labels, not links. Official MCP Registry listing IDs are fetched live and are unverified; a failed lookup does not prove the ID absent.
- `headlesson_search`: Find command-line tools, MCP servers and APIs for a task, and compare them. Ask in plain English or Japanese ("extract text from scanned PDFs") or by product name. Each result gives an ID, a one-line reason it matches, and when it was checked. Pass the ID to headlesson_get with sections ["lesson","gotchas"] to get the steps (install, check, first task) with their recorded test result (most were run by an agent; a few are untested) and known failure conditions, such as a tool that exits 0 with empty or wrong output. Filter or compare with axes such as auth, pricing, license and remote_mcp (where, axes, ids). Curated records come first. If none match, or include:["registry"] is set, one public word from the query is looked up in the Official MCP Registry; those listings are unverified (what is sent is described on the query field).
- `headlesson_whats_new`: List dated changes in agent tools and standards (new tools, renames, deprecations, breaking changes, new standards) since a date, optionally by kind or affected record. Useful for checking what changed after your training data. Public source URLs are kept; private sources appear as labels.