Token Savior MCP Server: Code Navigation and Memory for AI Coding Agents

• Finds where a function or class is defined

  Returns the file, line, signature and a preview for a name, definitions only, where a text search returns every mention. Looks at functions and classes first, then module constants.

  Try: “Where is parse_config defined?”

  Read · find_symbol

• Reads one function without opening the file

  Returns the source of a function or method by name, with no path needed. Can take a list of names and a detail level.

  Try: “Show me the source of handle_request”

  Read · get_function_source

• Reads one class with its methods

  Returns the body of a class including its methods, by name. Can batch up to ten names.

  Try: “Show me the UserSession class”

  Read · get_class_source

• Reads an exact range of lines

  Returns lines start to end of a file, up to a cap of 400, and names the function or class that holds the first line. Meant for line numbers from stack traces or lint errors.

  Try: “Read lines 105 to 150 of app/server.py”

  Read · read_lines

• Searches code and names the function around each hit

  Regex search over the project (or semantic ranking with semantic=true) where each hit also names the function or class that contains it. The description says to use it instead of Grep or rg.

  Try: “Find every place we call send_email”

  Read · search_codebase

• Regex search that returns the enclosing symbol

  Returns each match with its file and line plus the function or class around it.

  Try: “Search for TODO inside function bodies”

  Read · search_in_symbols

• Bundles a symbol with its callers and callees

  Returns the location, source and, at depth 1, dependencies and dependents. At depth 2 it adds change impact.

  Try: “Give me full context on process_order”

  Read · get_full_context

• Collects what you need before editing a symbol

  Returns the source, direct dependencies, callers, siblings in the same file and impacted tests in one call.

  Try: “What do I need to know before changing validate_token?”

  Read · get_edit_context

• Lists what a symbol calls

  Shows outgoing dependencies of a function or class, to a chosen depth.

  Try: “What does build_report call?”

  Read · get_dependencies

• Lists who calls a symbol

  Shows the direct references to a symbol across the project.

  Try: “Who calls charge_card?”

  Read · get_dependents

• Shows what a change could break

  Returns direct and transitive dependents of a symbol.

  Try: “What could break if I change User.email?”

  Read · get_change_impact

• Finds the path between two functions

  Returns the shortest dependency path between two symbols using a breadth-first search of the graph.

  Try: “How does the router reach save_order?”

  Read · get_call_chain

• Lists files a file imports

  Shows the outgoing file-level import edges for one file.

  Try: “What does api/routes.py import?”

  Read · get_file_dependencies

• Lists files that import a file

  Shows the incoming file-level import edges for one file.

  Try: “Which files import utils/dates.py?”

  Read · get_file_dependents

• Lists functions in a file or project

  Returns functions with names, lines and files, from one file or the whole project. Output is compact by default.

  Try: “List the functions in billing.py”

  Read · get_functions

• Lists classes

  Returns class names, line ranges, methods, bases and files.

  Try: “List all classes in the models folder”

  Read · get_classes

• Lists a file's imports

  Returns each import with its module, names and line.

  Try: “Show the imports in main.py”

  Read · get_imports

• Summarises a file's structure

  Returns functions, classes, imports and line counts for one file, or for the whole project if you omit the file.

  Try: “Give me an outline of server.py”

  Read · get_structure_summary

• Gives a project overview

  Returns the file count, packages, top classes and functions, and infrastructure folders.

  Try: “Summarise this project”

  Read · get_project_summary

• Lists indexed files

  Lists the files the index knows about, optionally filtered by a glob.

  Try: “List all test files”

  Read · list_files

• Finds the files behind a feature

  Returns files matching a keyword plus the files they import, labelled as core, test or config.

  Try: “Which files make up the checkout feature?”

  Read · get_feature_files

• Lists registered projects

  Shows each registered workspace project and whether its index is ready.

  Try: “Which projects are registered?”

  Read · list_projects

• Switches the active project

  Makes another registered project the active one by name or path.

  Try: “Switch to the api project”

  Write · switch_project

• Registers a new project folder

  Adds a path as a project root and switches to it. A path that is already registered becomes a quick switch, with no reindex unless force is set.

  Try: “Add /Users/me/code/shop as a project”

  Write · set_project_root

• Rebuilds the code index

  Rebuilds the project index. The index is also saved as a cache file inside the project.

  Try: “Reindex the project”

  Write · reindex

• Shows structured git status

  Returns the branch, ahead and behind counts, and staged, unstaged and untracked files.

  Try: “What is my git status?”

  Read · get_git_status

• Lists changed functions and classes

  Summarises worktree changes at the symbol level, or HEAD compared with a ref.

  Try: “Which functions changed since main?”

  Read · get_changed_symbols

• Drafts a commit narrative

  Returns a compact summary with stats, hotspots and a suggested commit type.

  Try: “Write a commit summary for my changes”

  Read · build_commit_summary

• Finds API breaking changes

  Compares against a git ref and lists removed functions or parameters, new required parameters and signature changes.

  Try: “Any breaking changes since v1.2?”

  Read · detect_breaking_changes

• Runs the type checker and groups errors by symbol

  Runs the checker the project already declares (tsc, mypy or pyright) and maps each error to its enclosing function. Output is bounded and says what it cut.

  Try: “Run the type checker and show errors by function”

  Runs code · get_diagnostics

• Guesses which tests a change affects

  Infers the pytest files likely impacted by changed files or symbols.

  Try: “Which tests cover my changes?”

  Read · find_impacted_test_files

• Runs the tests a change affects

  Runs pytest on the files impacted by the current changes, with a timeout and an output cap.

  Try: “Run the tests affected by my edit”

  Runs code · run_impacted_tests

• Lists the project's build, test and lint commands

  Reads build files such as package.json and pyproject.toml and lists conventional actions without running them.

  Try: “What commands can this project run?”

  Read · discover_project_actions

• Runs a project command by id

  Runs one of the discovered actions, for example an npm script, with a timeout and an output cap. Scripts named start or dev count as actions too.

  Try: “Run the lint action”

  Runs code · run_project_action

• Rewrites a whole function or class

  Replaces a function or class by name with new source, with no need to read the file first.

  Try: “Replace parse_date with this new version”

  Write · replace_symbol_source

• Edits text inside one function or class

  Swaps an exact old string for a new one, matched only inside the named symbol. replace_all changes every match inside that symbol.

  Try: “In handle_login, change the timeout from 30 to 60”

  Write · edit_lines_in_symbol

• Inserts code before or after a symbol

  Adds content directly before or after an indexed function or class.

  Try: “Add a helper function after build_report”

  Write · insert_near_symbol

• Moves a function to another file

  Moves a symbol to a different file and updates imports at the call sites. It can create the target file.

  Try: “Move format_price into utils/money.py”

  Write · move_symbol

• Adds a field to a model

  Adds a field to a model, class or interface. Works with .prisma files, Python dataclasses and SQLAlchemy models, and .ts or .tsx.

  Try: “Add a nullable phone field to the User model”

  Write · add_field_to_model

• Saves, restores or deletes file snapshots

  One tool with operations create, list, restore, delete, prune and compare. Creating copies the listed files, restoring copies them back over your files, and delete and prune remove saved snapshots.

  Try: “Create a checkpoint of app/models.py”

  Delete · checkpoint

• Traces where an env var is used

  Cross-references a variable across code, .env files and workflow configs, showing where it is defined, read and written.

  Try: “Where is DATABASE_URL used?”

  Read · get_env_usage

• Audits config files

  Checks .env, yaml, toml and json files for duplicates, secrets and orphans.

  Try: “Check my config files for leaked secrets”

  Read · analyze_config

• Audits Dockerfiles

  Lists base images, stages, exposed ports and ENV or ARG values, and cross-references them with config files.

  Try: “Review my Dockerfiles”

  Read · analyze_docker

• Summarises your SQL migrations

  Builds a snapshot of tables, columns, types, keys, indexes and row-level security policies from migration files.

  Try: “What tables exist according to my migrations?”

  Read · get_db_schema

• Lists API routes in a Next.js app

  Detects pages and API routes in a Next.js App Router project with path, file, HTTP methods and type.

  Try: “List my Next.js routes”

  Read · get_routes

• Ranks likely entry points

  Scores functions by how likely they are routes, handlers, main functions or exported APIs.

  Try: “What are the entry points of this codebase?”

  Read · get_entry_points

• Finds unused functions and classes

  Audits for functions and classes with zero callers, skipping entry points, tests and route handlers.

  Try: “Find dead code in src”

  Read · find_dead_code

• Ranks risky functions

  Ranks functions by complexity for all languages, or allocation and performance for Java.

  Try: “Which functions are the most complex?”

  Read · find_hotspots

• Finds duplicate functions

  Finds copy-pasted code by AST hash, or similar-meaning code with embeddings.

  Try: “Find duplicated functions”

  Read · find_semantic_duplicates

• Finds circular imports

  Detects cycles in the file-level import graph.

  Try: “Do I have any circular imports?”

  Read · find_import_cycles

• Saves a note to memory across sessions

  Stores a fact, guardrail or note, optionally tied to a symbol or file, with importance and an expiry. Notes persist between sessions in a local database.

  Try: “Remember that we never use raw SQL in this repo”

  Write · memory_save

• Shows an index of recent memories

  Layer 1 of the memory lookup. Returns a compact list of recent notes with id, type, title, importance and age.

  Try: “What have you remembered recently?”

  Read · memory_index

• Searches your saved memories

  Layer 2. Full-text search over memory notes that returns short snippets.

  Try: “Search memory for notes on auth”

  Read · memory_search

• Reads full memory notes by id

  Layer 3. Returns the full content of the notes whose ids you give.

  Try: “Show memory notes 12 and 15”

  Read · memory_get

• Archives a memory note

  Soft-deletes a note by id by marking it archived. The row stays in the database.

  Try: “Delete memory note 12”

  Delete · memory_delete

• Runs memory maintenance

  One tool for status, doctor, dedup_sweep, distill, consistency, vector reindex and other maintenance operations on the memory store.

  Try: “Run a memory status check”

  Write · memory_admin

• Builds a themed set of memories

  Collects memory notes filtered by type, tags or symbol into a named corpus.

  Try: “Build a corpus of all auth-related notes”

  Write · corpus_build

• Asks a question over a corpus

  Formats all notes in a named corpus as markdown with your question, ready for the assistant to answer.

  Try: “Using the auth corpus, what rules did we set?”

  Read · corpus_query

• Saves a reasoning trace

  Stores a goal, steps and conclusion with a confidence level so they can be reused later.

  Try: “Save how we debugged the cache bug”

  Write · reasoning_save

• Finds past reasoning traces

  Searches stored reasoning chains by goal similarity.

  Try: “Have we solved a cache problem before?”

  Read · reasoning_search

• Lists saved reasoning traces

  Lists stored chains ordered by how often they were used, then recency.

  Try: “List my saved reasoning chains”

  Read · reasoning_list

• Stores a long tool output for later search

  Saves verbose tool output in a local full-text store and returns an id and preview. Hooks normally call this, not the assistant.

  Try: “Store this build log for later”

  Write · capture_put

• Searches stored tool outputs

  BM25 search across the sandboxed outputs, returning ids, snippets and sizes.

  Try: “Search captured outputs for "timeout"”

  Read · capture_search

• Reads a stored tool output

  Reads a capture by id, as head, tail, all, a preview or a line range.

  Try: “Show the tail of capture 42”

  Read · capture_get

• Summarises a stored output

  Runs stats, line counts, unique lines or a regex extract or count over one capture.

  Try: “Count error lines in capture 42”

  Read · capture_aggregate

• Lists stored tool outputs

  Lists recent captures, newest first, filtered by session, project or tool.

  Try: “List my recent captures”

  Read · capture_list

• Deletes stored tool outputs

  Deletes captures by age, session or project. At least one filter is required.

  Try: “Purge captures older than a week”

  Delete · capture_purge

• Shows usage and savings stats

  One tool for several report categories such as usage, session budget and other internal statistics.

  Try: “Show my Token Savior usage stats”

  Read · get_stats

• Finds where Token Savior would have saved tokens

  Scans your Claude Code session transcripts for chains of native calls that one Token Savior call could replace, or reports adoption ratios. The description calls it read-only and free of personal data.

  Try: “How often did I use Token Savior tools last week?”

  Files · ts_discover

• Lists outdated results in the session

  Scans recent transcripts for tool results made obsolete later in the same session, such as a file read and then edited.

  Try: “What in this session is stale?”

  Files · ts_stale_context

• Finds the right Token Savior tool

  Ranks Token Savior's own tools against a plain-language question using embeddings and returns each candidate with its schema.

  Try: “Which tool finds who calls a function?”

  Read · ts_search

• Runs a JavaScript script that chains tools

  Runs a JavaScript body in a Node vm context that can call only a fixed list of 41 Token Savior tools, including the editing ones, checkpoint (restore, delete), reindex and switch_project. It has no require or process. Node does not treat vm as a security boundary, so this is not a hard sandbox.

  Try: “Find dependents of save_order and read each in one script”

  Delete · ts_execute

Watch out for

• It runs project commands on your machine

  run_project_action runs a discovered action such as an npm script, and get_diagnostics and run_impacted_tests run tsc, mypy, pyright or pytest. A project script runs with your permissions, so check the project first. github.com

• ts_execute runs scripts with limited, not hard, isolation

  The script runs in a Node vm context with a short list of globals (no require or process) and can call 41 listed tools, among them replace_symbol_source, move_symbol, checkpoint (restore and delete), reindex and switch_project. run_project_action, get_diagnostics and run_impacted_tests are not on that list. The worker is a normal Node process with no OS sandbox, and Node says vm is not a security mechanism. github.com

• It rewrites your source files

  replace_symbol_source, edit_lines_in_symbol, insert_near_symbol, move_symbol and add_field_to_model change files in place. Use git, and approve edits before they run. github.com

• It can overwrite or delete saved data

  checkpoint with restore copies saved files back over your current ones, and with delete or prune removes snapshots. memory_delete archives notes and capture_purge deletes stored outputs. github.com

• The optional installer adds always-on hooks to Claude Code settings

  `ts init --agent claude` merges four hook bundles into ~/.claude/settings.json, after printing a diff and saving a backup. Memory hooks (session start, every prompt, pre/post tool use, compaction, stop) and the tool-capture hook are active as soon as they are installed. The Bash rewriter is off until TS_BASH_REWRITE=1; once on, it answers permissionDecision allow for the commands it rewrites, so those skip the permission prompt. The discipline guard stays inert unless TS_DISCIPLINE_GUARD=1. github.com

• Hidden tools can still be called

  The optimized profile only changes what is advertised. The code states that a filtered-out tool still runs if called by name. github.com

• Tool descriptions push the assistant to use them

  search_codebase says to use it instead of Grep or rg on code. This steers the assistant away from its built-in tools, which is the product's purpose but worth knowing. The README adds that `alwaysLoad` is needed so the model does not reach for Read and Grep. Server-level instructions that push the same way exist but are off unless TS_DISCIPLINE=1. github.com

• It writes files next to your code

  The index is cached in a .token-savior-cache.json file inside each project, so add it to your ignore file. github.com

Security advisories