TokenSaver MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TokenSaver MCP map the current repository with a 1000-token budget"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TokenSaver MCP
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.
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 |
| Compact map: file tree, language stats, entry points, and key symbols, trimmed to a token budget. |
| Every matching function, class, interface, type, enum, constant, or method with file, line, and visibility. |
| Structure of one JS/TS file — declarations with line ranges, including class methods. |
| Detected entry points from |
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-mcpOr install from source:
git clone https://github.com/KaryawanSurga/TokenSaverMcp.git
cd TokenSaverMcp
npm install
npm run buildClient 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.
.gitignoreis respected, and dependency/build directories (node_modules/,dist/,.venv/,target/, …) are always skipped.Safe by default.
file_outlinerefuses 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.
--jsonoutput mode for scripting.Repository snapshot diffing between git refs.
Development
npm install
npm run typecheck
npm run build
npm testThe 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 toolsentry_pointsEntry pointsARead-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 outlineARead-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 symbolARead-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 mapARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables 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 npm1-
- AlicenseAqualityBmaintenanceProvides 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.514 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to retrieve compact structural codebase context through repository architecture summaries, AST symbol extraction, cyclomatic complexity scoring, and TODO/FIXME hotspot search.1MIT