# Costwise Mcp > Local MCP server that helps coding agents stop re-reading the same code every turn. Repository intelligence, cache-write optimization, and long-term session memory. 100% local. No API keys. - **Type:** MCP server - **Install:** `agentstack add mcp-okyashgajjar-costwise-mcp` - **Verified:** Pending review - **Seller:** [okyashgajjar](https://agentstack.voostack.com/s/okyashgajjar) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [okyashgajjar](https://github.com/okyashgajjar) - **Source:** https://github.com/okyashgajjar/costwise-mcp - **Website:** https://costwise-mcp.vercel.app ## Install ```sh agentstack add mcp-okyashgajjar-costwise-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About **CostWise — MCP** Coding agents that explore less, remember more, and carry less context. [](#installation) [](#supported-platforms) [](#supported-platforms) [](#supported-platforms) [](#supported-clients--config) [](#supported-clients--config) [](#supported-clients--config) [](https://github.com/okyashgajjar/costwise-mcp) ``` curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash ``` One command on Linux, macOS, or Windows (via WSL). Detects your OS, installs Go if needed, builds from source, and connects your AI coding client. **Star this repo** — it helps others find CostWise. Without CostWise▶ watch video With CostWise▶ watch video --- ## Coding agents should behave like experienced engineers An experienced engineer walks into a codebase and does **not**: - Re-read the same files every time they answer a question. - Re-discover symbols they already found ten minutes ago. - Keep a 5,000-line build log in their head because they might need it later. - Carry every detail of every conversation around forever. They remember where things live. They open only what they need. They hold facts, not files. Most AI coding agents do the opposite. They re-explore the same repository over and over. They dump whole files into context. They grow the conversation window until every turn becomes expensive — not because the answer is hard, but because *everything else* in the window has to be re-read and re-cached. CostWise is a local MCP server that makes coding agents behave more like that experienced engineer. It gives them fast, token-budgeted access to your repository — so they stop reading whole files to find small facts. --- ## How CostWise fixes it A tool that connects over MCP cannot control how or when the client caches. Cache breakpoints and TTLs are the client's decision. There is exactly one lever the server controls: > **How many tokens ever enter the resident context window in the first place.** Shrink that, and both costs fall: a smaller window is cheaper to read every turn *and* cheaper to rewrite when the cache is invalidated. CostWise does four things in service of that goal. ### 1. Answer from a local index, not from files CostWise parses your repository once with Tree-sitter and stores symbols, references, and call edges in a local SQLite index. Navigation questions — "where is this defined," "who calls this," "what references this" — are answered from the index in a few tokens instead of by dumping source files. Results are compressed scopes sized to the kind of question asked. The model gets the location, not the file; the implementation body, not the whole module; the caller list, not the grep output. ### 2. Remember facts instead of repeating them The `remember` tool persists a small durable fact — a decision, an entry point, a gotcha — to a per-repository store. The `recall` tool retrieves it later. Facts the model would otherwise re-derive or re-paste each turn are written down once and read back only when relevant. ### 3. Stash large output instead of pasting it inline The `stash_context` tool parks a large blob — a file, a command output, a test log — out of the conversation and returns a short handle. The full content stays on disk, recoverable. The `recall` tool pulls back only the slice that matches a query, within a token budget. A 5,000-line build log pasted inline is re-read and potentially re-written to the cache every turn for the rest of the session. Stashed, it costs about 20 tokens (the handle) and is pulled back only in the slice you need. ### 4. A session-awareness skill that makes the model use all of the above A small piece of guidance (about 275 tokens) is delivered to every connected editor through the MCP protocol's `instructions` field. It teaches the model the lean workflow once per session: route large output through `stash_context`, persist durable facts with `remember`, prefer narrow retrieval over file reads. It is also installable as a native Claude Code skill, AGENTS.md entry, or rules file for any editor that reads them. The same canonical source backs all delivery paths. --- ## Supported Languages CostWise indexes **11 languages** using Tree-sitter AST parsers — symbol definitions, references, and call edges are all precomputed and stored in a local SQLite index. | Language | File Extensions | Parser | |---------------|------------------------------------------------|------------------| | **Go** | `.go` | Native (bespoke) | | **Python** | `.py` | Native (bespoke) | | **JavaScript** | `.js`, `.jsx`, `.mjs` | Native (bespoke) | | **TypeScript** | `.ts`, `.tsx` | Native (bespoke) | | **Rust** | `.rs` | Tree-sitter | | **Java** | `.java` | Tree-sitter | | **C** | `.c`, `.h` | Tree-sitter | | **C++** | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` | Tree-sitter | | **C#** | `.cs` | Tree-sitter | | **Ruby** | `.rb` | Tree-sitter | | **PHP** | `.php` | Tree-sitter | Go, Python, JavaScript, and TypeScript use bespoke extractors with deeper analysis; the other seven use a generic spec-driven extractor built on Tree-sitter's common conventions. All languages get symbols, references, call edges, and full-text search. --- ## Installation Installation > Full installation guide with platform-specific variants: [costwise-mcp.vercel.app/docs/install](https://costwise-mcp.vercel.app/docs/install) ### Quick Install (Linux / macOS / Windows via WSL) The recommended way — one command: ```bash curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash ``` The script does everything: 1. On Windows, detects Git Bash / MSYS and routes through WSL automatically 2. Checks for Go and installs it if missing 3. Checks for a C compiler (a CGO dependency) and installs it if missing 4. Clones the repo and builds from source 5. Installs to `/usr/local/bin/costwise` 6. Detects AI coding clients and asks which to connect 7. Configures MCP for the selected clients (and installs the session skill unless `--no-skill`) ### Windows (Native PowerShell) Not recommended unless you already have Go and gcc. Build manually: ```powershell git clone https://github.com/okyashgajjar/costwise-mcp.git cd costwise-mcp $env:CGO_ENABLED=1 go build -o costwise.exe ./cmd/costwise/ ``` Or use the recommended path — install WSL (Windows 10 2004+ / Windows 11): ```powershell # In PowerShell as Administrator: wsl --install # Then in WSL: curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash ``` ### macOS / Linux (Manual Build) Requires Go 1.25+ and a C compiler (CGO is mandatory — see the build notes below). ```bash git clone https://github.com/okyashgajjar/costwise-mcp.git cd costwise-mcp CGO_ENABLED=1 go build -o costwise ./cmd/costwise/ sudo mv costwise /usr/local/bin/ costwise --version ``` --- ## What you get CostWise provides **10 MCP tools** that fall into three categories. **Retrieval tools** answer questions from a pre-built index instead of by reading files: - `search_code` — semantic search by natural language question. - `find_symbol` — locate where a symbol is defined. - `read_symbol` — return a symbol's full implementation body. - `find_references` — every usage of a symbol, precomputed. - `find_callers` — which functions call a given function. **Maintenance tools** keep the index in sync: - `get_repository_summary` — token-budgeted overview of the repo, drillable by module. - `index_repository` — manual re-index trigger (auto-watcher normally handles this). **Context-control tools** keep large content and durable facts out of the resident window: - `remember` — persist a fact once instead of repeating it inline. - `stash_context` — park a large blob out of context behind a tiny handle. - `recall` — pull back only the slice that matches a query, within a budget. Full tool catalog — why each tool exists and how to use it > Interactive tool catalog with schemas and examples: [costwise-mcp.vercel.app/tools](https://costwise-mcp.vercel.app/tools) ### Retrieval tools #### search_code Semantic repository search powered by Tree-sitter. *Why:* a natural-language question ("where is caching implemented?") should return the relevant scopes directly, not a list of files for the model to open one by one. > Example: `Where is caching implemented?` #### find_symbol Find where a symbol is defined. *Why:* "where is X defined" is the single most common navigation question. It should cost a location, not a file. > Example: `Find UserService` #### read_symbol Return a symbol's full implementation body by name. *Why:* "show me how X works" should cost one indexed line-range read, not a whole-file dump or an agent looping through search to reconstruct the body. > Example: `Show the body of GetOrCreateRepoSession` #### find_references Find every usage of a symbol. *Why:* impact analysis ("what will this change break?") needs every usage, precomputed, without grepping the tree live. > Example: `Where is UserService used?` #### find_callers Find which functions call another function. *Why:* understanding a call chain should read from stored call edges, not from the model reconstructing it by reading callers' files. > Example: `What calls processPayment()?` *Note:* `search_code` already routes an exact-text/full-text strategy internally, so a literal match is covered without a separate tool. For raw regex over files, use the host's native file search. ### Maintenance tools #### get_repository_summary A token-budgeted overview of the repository: languages, the top modules by symbol count, and key symbols. Pass `module` to drill into one directory, and `budget` (`small` / `medium` / `large`) to cap the output. *Why:* this is usually the first call of a session, so it is also the first thing that lands in the cached context and stays there. The earlier version emitted one line per directory plus a full per-directory chain with no limit — on a large monorepo that was tens of thousands of tokens, cached for the entire session. It is now hard-capped: the output stays small no matter how large the repository is, and details are pulled on demand via `module`. #### index_repository Refresh or rebuild repository indexes manually. Usually unnecessary because the watchdog re-indexes automatically. ### Context-control tools (V2) These exist because of the cache cost described above. They let the model keep large content and durable facts *out* of the resident window, losslessly. #### remember Persist a small durable fact — a decision, an entry point, a gotcha — to a per-repository store, so it does not have to be repeated inline in the conversation every time it is relevant. *Why:* facts the model re-derives or re-pastes each turn are pure cache overhead. Write them down once; read them back when needed. #### stash_context Park a large blob (a whole file, a long command or test output, a generated report) **out of the conversation** and get back a short handle. Nothing is lost — the full content is written to disk and remains re-fetchable. *Why:* this is the most direct lever on window size. A 5,000-line log pasted inline is re-read and potentially re-written to the cache every turn for the rest of the session. Stashed, it costs about 20 tokens (the handle) and is pulled back only in the slice you actually need. > Example: stash a 5,000-line log, keep roughly 20 tokens in context. #### recall Take back **only what you need**: the budgeted slice of a stashed blob (by handle), or matching remembered facts — instead of re-reading the whole thing. *Why:* "take output by necessary query" is the read side of the loop. Combined with `stash_context` it becomes: stash the monster, then recall only the lines that match your query, within a token budget. **The loop:** `stash_context` (park it) → `recall` (pull back only the slice) → `remember` (keep the durable conclusion). The content is always recoverable; the window stays small. --- End-to-end workflow: a real CostWise session See what a typical session looks like from first command to final answer — and how many tokens stay *out* of the window. **Step 1 — Install and index** ```bash curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash # Script detects OS, installs Go + C compiler if needed, # builds binary, detects AI coding clients, and writes MCP config. # The server auto-indexes your repo on first connection. ``` **Step 2 — Start a coding session** Your AI agent connects to CostWise via MCP. On connect, the agent receives the ~275-token session skill — it now knows to use stash/recall/remember instead of pasting things inline. **Step 3 — Ask a navigation question** Instead of dumping a file, the agent calls: ``` find_symbol("UserService") → user_service.go:142 read_symbol("UserService") → func (s *UserService) Create(ctx context.Context, req *CreateRequest) (*User, error) { // full body returned, not the whole file } ``` Cost: ~50 tokens. Without CostWise: the agent reads `user_service.go` (potentially 500+ lines) into the window. **Step 4 — Trace an impact** You ask "what calls validateInput?" The agent calls: ``` find_callers("validateInput") → processPayment (payment.go:310) → validateOrder (order.go:88) → validateInput (validator.go:45) ``` Cost: ~30 tokens. Without CostWise: the agent opens each file, reads the callers, reconstructs the chain. Hundreds of tokens entering the window. **Step 5 — Run tests, get a failure** Tests fail with a 2,000-line log. Instead of pasting the whole thing inline: ``` stash_context(label="test-failure-output", content=) → Stashed → abc123 (~28,000 tokens kept out of context) ``` Cost of the handle: ~20 tokens in context. The full log sits on disk. **Step 6 — Investigate the failure** ``` recall(source="abc123", query="FAIL|panic|error") → test_service_test.go:42: TestCreateUser FAILED expected: 201, got: 500 error: database connection refused ``` Cost: ~40 tokens (just the matching lines). Without CostWise: the agent re-reads or re-pastes the whole 2,000-line log. **Step 7 — Remember what you found** ``` remember(key="db-conn-fix", fact="Database connection refused in tests — check DB_HOST env var in .env.test") → Remembered "db-conn-fix" ``` Cost: ~20 tokens, persisted for the rest of the session and future sessions. **Step 8 — Later, recall the fact** ``` recall(query="db fix") → db-conn-fix: Database connection refused in tests — check DB_HOST env var in .env.test ``` No need to re-derive the fix. Cost: ~15 tokens. **Bottom line** | Step | Without CostWise | With CostWise | |------|---------------------|-------------------| | Find `UserService` | 500+ tokens (whole file) | ~15 tokens (location) | | Read implementation | 500+ tokens (whole file) | ~40 tokens (body only) | | Call chain trace | 300+ tokens (multiple files) | ~30 tokens (precomputed edges) | | Test log investigation | 2,000+ tokens (pasted inline) | ~20 tokens (handle) + ~40 tokens (recall) | | Remember the fix | Re-derived next time | ~20 tokens (persisted) | | **Total window cost** | **~3,300+ tokens** | **~165 tokens** | Over a full session, those savings compound to 80%+ fewer tokens in the resident window — and every subsequent turn pays less cache read. How the session skill makes the … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [okyashgajjar](https://github.com/okyashgajjar) - **Source:** [okyashgajjar/costwise-mcp](https://github.com/okyashgajjar/costwise-mcp) - **License:** MIT - **Homepage:** https://costwise-mcp.vercel.app Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-okyashgajjar-costwise-mcp - Seller: https://agentstack.voostack.com/s/okyashgajjar - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.