# yagna-mcp

The [yAGna](https://annoyinggoods.com/products/yagna/) catalog as an MCP
server, one `npx` away: your whole GitHub stars library — every README,
license, topic, note, health and fit score — as fifteen read and write
tools for your coding agent, served straight from the local SQLite
catalog on your own machine.

## Use it

Point your MCP host at it:

```json
{
  "mcpServers": {
    "yagna": {
      "command": "npx",
      "args": ["-y", "yagna-mcp"]
    }
  }
}
```

The launcher finds the yAGna binary in this order: the `YAGNA_BIN`
environment variable, a `yagna` already on your PATH, or the release
archive for your platform downloaded once from the
[yAGna releases](https://github.com/annoyinggoods/yagna/releases) into a
per-user cache. The server speaks MCP over stdio.

The agent reads the catalog for free — search, repositories, READMEs,
tags, notes, the fit spec. Live GitHub calls (search, refresh, a sweep)
pass a spend ledger with per-hour and per-minute ceilings, and past the
policy's threshold the server asks the host before spending. Every call
lands in an activity trace the app shows you.

The first sweep of your stars takes about five minutes per thousand
repositories — once; after that it is updates, and everything reads
from disk.

GitLab support is on the roadmap; today the catalog speaks GitHub.

## The tools

Reads: `search_library`, `get_repository`, `read_readme`,
`list_vocabulary`, `list_local_repositories`, `read_local_file`,
`get_fit_spec`, `search_github`, `get_github_repository`.
Writes: `set_tag`, `set_note`, `write_fit_spec`, `rescore`,
`refresh_repository`, `sync_catalog`.

yAGna never acts on GitHub for you — no issues, no comments, no pushes.
It is the memory, not a second client.