# token-discipline-mcp

[![test](https://github.com/Suhaib5333/token-discipline-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Suhaib5333/token-discipline-mcp/actions/workflows/test.yml)
![deps](https://img.shields.io/badge/dependencies-0-brightgreen)
![license](https://img.shields.io/badge/license-MIT-blue)

**Stop your AI coding agent from burning through your usage limits.**

A tiny MCP server (one file, zero dependencies) that loads a set of token-saving rules into every session of Claude Code, Claude Desktop, Cursor, or any MCP client.

## What it makes your agent do

| Rule | Effect |
|------|--------|
| 🧭 Main chat is a dispatcher | Plans and delegates; heavy work runs in subagents |
| ⛔ Agents checkpoint at ~125k tokens | Commit, write `HANDOFF.md`, hand off to a fresh agent |
| 🔍 Grep before reading | Only the needed lines, never re-read files |
| 👥 1 or 2 agents by default, max 5 | Parallel fan-out is what kills a session |
| 📏 Pace huge tasks | Split across sessions instead of hitting the rate limit |

Full list: [RULES.md](RULES.md).

## Setup (1 minute)

Needs **Node 18+**. Nothing to install: `npx` runs it straight from GitHub.

### Claude Code

```bash
claude mcp add token-discipline --scope user -- npx -y github:Suhaib5333/token-discipline-mcp
```

### Claude Desktop, Cursor, Windsurf, others

Add this to your MCP config (`claude_desktop_config.json`, `~/.cursor/mcp.json`, ...):

```json
{
  "mcpServers": {
    "token-discipline": {
      "command": "npx",
      "args": ["-y", "github:Suhaib5333/token-discipline-mcp"]
    }
  }
}
```

Restart the client. Done ✅

## How it works

The rules reach the model 3 ways, so it works whatever your client supports:

| Channel | What |
|---------|------|
| Server instructions | Sent automatically on connect |
| Tool `token_rules` | The agent can fetch the rules any time |
| Prompt `token-discipline` | Load them manually (`/mcp__token-discipline__token-discipline` in Claude Code) |

## Use your own rules

Point it at any Markdown file:

```bash
claude mcp add token-discipline --scope user -e TOKEN_RULES_FILE=/path/to/my-rules.md -- npx -y github:Suhaib5333/token-discipline-mcp
```

(JSON config: add `"env": { "TOKEN_RULES_FILE": "/path/to/my-rules.md" }`.)

Or **fork** this repo, edit `RULES.md`, and swap `Suhaib5333` for your username in the install command.

## Run locally

```bash
git clone https://github.com/Suhaib5333/token-discipline-mcp
cd token-discipline-mcp
npm test
```

## Contributing

Ideas for better rules are welcome. Open an issue or a PR (keep it zero-dependency and short). See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE): use it, fork it, ship it.