# sun-tzu-mcp

An MCP server that finds the Sun Tzu quote for a situation. Built for workplace use: describe what is
happening ("the PM keeps adding scope two days before release") and get back verses from *The Art of
War* with their chapter citation, so the quote you paste is the quote Sun Tzu actually wrote.

## Tools

| Tool | What it does |
|---|---|
| `find_quote(situation, count?, theme?)` | Matches a plain-language situation to verses, best first |
| `list_themes()` | The theme vocabulary, with a gloss and verse count for each |
| `random_quote(theme?)` | One verse at random from the annotated set |
| `quote_card(situation? \| verse?, caption?, scale?)` | Renders a verse as a PNG card, 1200x630, and copies it to the clipboard |

There is also a `sun-tzu://corpus` resource holding all 383 verses.

The card is written to a temp file and put on the clipboard. Clipboard copying is macOS only; on other
platforms the PNG is still written and the tool says so instead of failing.

`caption` sets one italic line above the verse, for framing the quote (`On being told "good job"`). It is
taken verbatim, shrunk to fit, then clipped with an ellipsis. Omit it for a bare card.

## Install

Needs Node 20 or newer. Nothing else: no API key, no network, no database.

```
claude mcp add sun-tzu -- npx -y sun-tzu-mcp
```

Or, for any MCP client that takes a JSON config:

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

The server runs locally as a subprocess of the client and talks stdio. Nothing is hosted, nothing
phones home.

### From a clone

```
pnpm install
pnpm build
claude mcp add sun-tzu -- node /absolute/path/to/sun-tzu-mcp/dist/index.js
```

## How matching works

No embeddings, no network, no API key. The corpus ships with the server and matching is deterministic:

1. The situation is normalized, tokenized and stemmed.
2. A lexicon maps working-life vocabulary onto the theme vocabulary, so `reorg` reaches verses tagged
   `adaptability` and `micromanage` reaches `delegation` without sharing a word with the text.
3. Verses score on three fields: matched themes (weight 3), curated situation hints (2), and verse
   text (1). A theme that several query terms agree on counts for more, which keeps an incidental word
   from steering the result.

The tradeoff: paraphrase far outside the lexicon matches less well than embeddings would. In exchange
it is instant, free, offline and debuggable, and the calling model is already good at rewriting a
situation into words the lexicon knows.

## Data

- `data/source/pg132.txt` — the Giles 1910 translation, Project Gutenberg #132, public domain.
- `data/verses.json` — **generated.** 383 verses parsed out of the source by `pnpm corpus`. Do not
  edit by hand.
- `data/tags.json` — **hand-curated.** Themes and situation hints for the verses that carry over to
  working life. Kept separate from `verses.json` so re-parsing never wipes it.
- `data/themes.json` — the theme vocabulary. `tags.json` is validated against it at server startup,
  so an unknown theme fails loudly instead of silently never matching.

### Parsing notes

The Gutenberg plain text interleaves Giles' commentary with the verses and its brackets are not
reliable: blocks are missing opening brackets, missing closing brackets, and one verse (V.9) is missing
the period after its number. Character-level bracket counting silently swallows whole chapters. The
parser therefore works paragraph by paragraph, uses verse numbers as hard boundaries, and falls back on
markers of Giles' voice (commentator names, dates, "says:") where the brackets fail. `pnpm corpus`
prints verse coverage per chapter and flags any gap in the numbering, so a regression is visible.

## Tests

```
pnpm build && pnpm test
```

Covers the corpus (verse count, citation format, no commentary leakage) and the matcher (a table of
situations that must each reach a specific verse in the top 3). Add a row to `EXPECTED` in
`test/match.test.mjs` when you extend the lexicon.

## Licence

The translation is public domain. The code and the curation are MIT.