Skip to main content
Glama
TokenSaver MCP

TokenSaver MCP

TokenSaver MCP

CI Node License: MIT

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

TokenSaver MCP is an offline Model Context Protocol 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.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.

Related MCP server: hebros-mcp

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:

# 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):

npx -y tokensaver-mcp

Or install from source:

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.

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

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

{
  "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

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.

Available Tools

4 tools
entry_pointsEntry pointsA
Read-only

Detect where a repository actually starts executing: package.json bin/main/exports targets, bin/ scripts, index and cli conventions, and Python entry modules. Use it to orient before exploring or running a project.

Inputs: path (required).

file_outlineFile outlineA
Read-only

List the structure of one JavaScript/TypeScript file — functions, classes (with methods), interfaces, types, enums, and constants with line ranges. Cheaper than reading the whole file when you only need its shape.

Inputs: file (required), path (required).

find_symbolFind symbolA
Read-only

Find functions, classes, interfaces, types, enums, constants, or methods by name across JavaScript and TypeScript files. Returns file, line, kind, and visibility so you can jump straight to the definition.

Inputs: path (required), query (required), kind, limit.

repo_mapRepository mapA
Read-only

Get a compact map of a repository in one call: filtered file tree, language stats, entry points, and key symbols. Use it before reading files to decide which files matter. Respects .gitignore. Output is capped by a token budget.

Inputs: path (required), depth, budget.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool targets a distinct concern: repo_map gives a whole-repo overview, find_symbol locates a named symbol across files, file_outline shows one file's structure, and entry_points finds execution starts. There is minor overlap between repo_map and entry_points (both orient you in a repo), but the descriptions make the difference clear.

    Naming Consistency4/5

    All tool names use a consistent noun-based pattern (repo_map, find_symbol, file_outline, entry_points) with snake_case. The pattern is predictable, though the verbs are not uniform (find vs. implicit get/list), which is a minor deviation.

    Tool Count5/5

    Four tools is a well-scoped set for a code-navigation/exploration server. Each tool covers a distinct need without redundancy, and the count feels appropriate for the stated purpose.

    Completeness4/5

    The server covers the main exploration workflow: orient (repo_map, entry_points), locate (find_symbol), and inspect (file_outline). A minor gap is the lack of a tool to read file contents or search by text/pattern, but the server's stated purpose is navigation, not full code retrieval.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to pre-compute repository structure and access structured intelligence briefs, including dependency graphs, hotspots, and blast radius, reducing token usage and improving code understanding.
      59 npm
      1
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides coding agents with a compact map of a TypeScript/TSX codebase, enabling direct answers about symbol locations, imports, dependencies, and references while reducing token usage.
      5
      14 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to understand unfamiliar codebases through project summaries, file explanations, feature tracing, change planning, test discovery, guided walkthroughs, and token-efficient repository digests.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to retrieve compact structural codebase context through repository architecture summaries, AST symbol extraction, cyclomatic complexity scoring, and TODO/FIXME hotspot search.
      1
      MIT