# TokenSaver MCP

[![CI](https://github.com/KaryawanSurga/TokenSaverMcp/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/TokenSaverMcp/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Stop burning context tokens on files that don't matter.**

TokenSaver MCP is an offline [Model Context Protocol](https://modelcontextprotocol.io) server that gives coding agents a compact map of any repository in one call: filtered file tree, language stats, entry points, and key symbols — capped by an explicit token budget. Instead of reading dozens of files to orient itself, an agent asks for the map and reads only what it needs.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## Why

Agents navigate repositories by reading files until they understand the layout. That burns context, costs money, and pushes the actual task out of the window. TokenSaver answers the orientation questions in a single, deterministic, budgeted response:

- Where does this project start executing?
- Which files and directories exist (minus dependencies and build output)?
- What functions, classes, and interfaces live where?

No network, no API keys, no telemetry. Every tool is read-only.

## Tools

| Tool | What it returns |
| --- | --- |
| `repo_map` | Compact map: file tree, language stats, entry points, and key symbols, trimmed to a token budget. |
| `find_symbol` | Every matching function, class, interface, type, enum, constant, or method with file, line, and visibility. |
| `file_outline` | Structure of one JS/TS file — declarations with line ranges, including class methods. |
| `entry_points` | Detected entry points from `package.json` (`bin`, `main`, `exports`), `bin/` scripts, index/cli conventions, and Python modules. |

## Example output

Running `repo_map` against this repository itself:

```text
# TokenSaver map: TokenSaverMcp
Files: 30 | Languages: TypeScript 19 files, JSON 4 files, Markdown 3 files, Python 1 files

## Entry points
- src/index.ts (src/index.ts convention)

## Tree
* = entry point
.gitignore
CHANGELOG.md
LICENSE
package.json
README.md
tsconfig.json
src/
  index.ts *
  server.ts
  core/
    entrypoints.ts
    languages.ts
    scanner.ts
    symbols.ts
    tokens.ts
  tools/
    entry-points.ts
    file-outline.ts
    find-symbol.ts
    repo-map.ts
tests/
  scanner.test.ts
  server.test.ts
  symbols.test.ts
  tokens.test.ts
  fixtures/
    sample-repo/ (6 files)

## Symbols
() function, (C) class, (i) interface, (t) type, (e) enum, (c) const, (m) method, (n) namespace
src/index.ts: HELP(c), main()
src/core/scanner.ts: FileEntry(i), LanguageStat(i), RepoScan(i), scanRepository()
src/core/symbols.ts: SymbolInfo(i), extractSymbols()
src/core/tokens.ts: estimateTokens(), fitToBudget()
src/server.ts: SERVER_NAME(c), SERVER_VERSION(c), buildServer()
```

Roughly 650 estimated tokens for a full project overview — often less than reading a single source file.

## Install

Run it directly with `npx` (no install):

```sh
npx -y tokensaver-mcp
```

Or install from source:

```sh
git clone https://github.com/KaryawanSurga/TokenSaverMcp.git
cd TokenSaverMcp
npm install
npm run build
```

## Client configuration

Add the server to any MCP-compatible client.

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

From a local checkout, point `command` at `node` and `args` at the built entry point:

```json
{
  "mcpServers": {
    "tokensaver": {
      "command": "node",
      "args": ["/absolute/path/to/TokenSaverMcp/dist/index.js"]
    }
  }
}
```

## Token budgeting

Every response states its estimated size. `repo_map` accepts a `budget` (approximate tokens, default 1500, max 20000) and trims the tree or symbol section to fit, telling you when it truncated. Token counts are approximated at four characters per token, which keeps the server dependency-free and offline.

## Design principles

- **Offline and deterministic.** Same repository, same output. No network calls, no model downloads, no environment discovery.
- **Read-only.** Tools never write to the target repository.
- **Ignore-aware.** `.gitignore` is respected, and dependency/build directories (`node_modules/`, `dist/`, `.venv/`, `target/`, …) are always skipped.
- **Safe by default.** `file_outline` refuses to resolve paths outside the repository root.
- **Bounded output.** Token budgets keep responses inside the context window.

## Roadmap

- Python symbol extraction (v0.2).
- Import graph and reverse-dependency lookup.
- `--json` output mode for scripting.
- Repository snapshot diffing between git refs.

## Development

```sh
npm install
npm run typecheck
npm run build
npm test
```

The test suite covers the scanner, symbol extraction, entry point detection, token budgeting, and in-memory MCP client/server round trips for every tool.

## License

MIT — see [LICENSE](LICENSE).