# motivate-mcp

An MCP server that returns a motivational quote matched to the task you are actually
working on.

essentially you getting cool motivational quotes with their authors which are semantically chosen to your task that your agent is currently working on ! 
Have fun , learn and use it for good things. Also i suggest go outside more , laugh and give love to others as much as you can. Go and see your parents as much as possible.
They won't always be here -- but they would love you to be here for long , and live the life you deserve. Love you.

``
> "When you have eliminated the impossible, whatever remains, however improbable,
>  must be the truth."
>     — Arthur Conan Doyle
```

72 quotes across 57 topics. No API key, no network calls, no telemetry.

## Install

```bash
git clone https://github.com/lazyturtle22/motivate-mcp.git
cd motivate-mcp
npm install
```

## Use it as an MCP server

Add it to your MCP client config. For Claude Code, `~/.claude.json`:

```json
{
  "mcpServers": {
    "motivate": {
      "command": "node",
      "args": ["/absolute/path/to/motivate-mcp/src/index.js"]
    }
  }
}
```

Restart the client and three tools appear.

### Tools

| Tool | What it does |
|---|---|
| `motivate` | Returns a quote matched to a task description. Takes `task` (string) and optional `avoid_repeats` (boolean, default true) |
| `list_topics` | Lists every topic and how many quotes sit under it |
| `explain_match` | Shows which topics a description matches, without returning a quote. Useful when tuning the keyword map |

Repeats are tracked per session, so a long session will not serve you the same line twice
until it runs out of relevant ones.

## Getting a quote on *every* message

An MCP tool only fires when the model decides to call it, so it will not reliably hit
every message. If you want one every time, use the included hook instead. It runs on every
prompt you submit, reads what you typed, and prints a matched quote into the context.

Add to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/motivate-mcp/hook/motivate-hook.js"
          }
        ]
      }
    ]
  }
}
```

Set `MOTIVATE_QUIET=1` to silence it without unwiring it. The hook fails silently by
design: a broken quote generator should never be able to break your prompt.

The two can run together. The hook gives you the every-message drip, the MCP tool lets the
model ask for one deliberately when it thinks you need it.

## How the matching works

`src/match.js` holds a map of topic to signal words. A task description is scanned for
those words, topics are scored (multi-word phrases count double, since they are stronger
evidence), and quotes are ranked by how well their topics overlap the top matches.

**Signals match at a word start, not anywhere in the string.** This matters if you add
your own. A plain substring check looks fine until you notice `ui` fires on "b**ui**lt"
and "g**ui**de", `try` fires on "coun**try**", and `lead` fires on "mis**lead**ing" — so
you ask about building something and get a quote about design.

There is deliberately no boundary on the *end* of a signal, so stems still work:
`optimis` matches "optimising", `frustrat` matches "frustrated". When adding a short
signal (three characters or fewer), check it against a few real sentences first.

The final pick is randomised across everything within 70% of the best score, so the same
input does not always produce the same line.

If nothing matches, it falls back to the whole database rather than returning nothing.

Check what a description matches before adding new signal words:

```bash
node -e "import('./src/match.js').then(m => console.log(m.scoreTopics('your text here')))"
```

## Adding quotes

Edit `src/quotes.js`. Each entry is:

```js
{
  text: "The quote itself.",
  by: "Who said it",
  topics: ["debugging", "persistence"],
}
```

Attribution rules, please keep to them:

- Where a line is widely repeated but the original wording or source is disputed, `by`
  starts with `attributed to`. Do not strip that prefix to make it look tidier.
- Proverbs and genuinely anonymous lines are credited as `Proverb` or `Anonymous`.

Use topics that already exist where you can, so quotes cluster rather than scatter. Run
`npm test` afterwards, which checks for duplicates, missing authors and orphan topics.

## Tests

```bash
npm test
```

Nine tests using the built-in `node:test` runner. No framework, no build step.

## Licence

MIT. See [LICENSE](LICENSE).