io.github.mdfifty50-boop/token-lens
Context window token analysis and budget management
Open source Open in the app JSON README (API)
About
Context window token analysis and budget management
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mdfifty50-boop
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-04-24T13:40:53Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-29 04:00:46
- Updated
- 2026-08-29 04:00:46
- Origin id
io.github.mdfifty50-boop/token-lens
README
# token-lens-mcp
MCP server for analyzing and optimizing context window token usage. MCP tool definitions consume 40-72% of context windows before any user work begins — this server helps you measure, compress, and eliminate that waste.
## Install
```bash
npx token-lens-mcp
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"token-lens": {
"command": "npx",
"args": ["token-lens-mcp"]
}
}
}
```
### Claude Code
```bash
claude mcp add token-lens -- npx token-lens-mcp
```
## Tools
### audit_context_budget
Analyze the token cost of your MCP tool definitions. Estimates tokens per tool using chars/4 approximation on the full JSON definition.
**Params:**
- `tools` — Array of `{name, description, schema}` objects
**Returns:** Per-tool token cost (sorted by cost), total tokens, percentage of 128K/200K/1M context windows.
### optimize_tool_loading
Given a task description, recommend the minimal set of tools needed. Uses keyword matching and category relevance scoring.
**Params:**
- `task_description` — What you're trying to accomplish
- `available_tools` — Array of `{name, description, category?}`
**Returns:** Recommended tools sorted by relevance, excluded tools, estimated tokens saved.
### compress_schema
Compress verbose tool schemas to reduce token usage.
**Params:**
- `tool_name` — Name of the tool
- `schema` — JSON Schema object to compress
- `level` — `"light"` | `"medium"` | `"aggressive"`
**Levels:**
- **light** — Remove descriptions under 20 chars
- **medium** — Shorten descriptions to 50 chars, remove examples
- **aggressive** — Strip all descriptions, keep only types and required fields
**Returns:** Compressed schema, original/compressed token counts, savings percentage.
### analyze_session_usage
Track which tools are actually called vs loaded during a session.
**Params:**
- `session_id` — Unique session identifier
- `action` — `"register_tool"` | `"log_call"` | `"report"`
- `tool_name` — Tool name (required for register_tool/log_call)
- `tool_tokens` — Token cost (for register_tool, default 50)
**Report returns:** Loaded vs used counts, waste percentage, unused tools ranked by token cost.
### suggest_removals
Identify tools that can be safely removed based on usage patterns.
**Params:**
- `usage_history` — Array of `{tool_name, call_count, last_used_days_ago}`
**Scoring:** never_used (priority 3) > not_used_30_days (priority 2) > rarely_used (priority 1)
**Returns:** Removal candidates with reasons and estimated token savings.
### get_optimization_report
Full context window health check combining audit, removal suggestions, and compression recommendations.
**Params:**
- `tools` — Array of tool definitions
- `usage_history` — Optional usage history array
**Returns:** Executive summary with health grade (excellent/good/fair/poor), audit results, removal suggestions, compression opportunities, and actionable recommendations.
## Resources
### token-lens://tips
Best practices guide for reducing MCP context window bloat, including schema design tips, token budget guidelines, and dynamic tool loading strategies.
## Development
```bash
npm install
npm test
npm run dev # watch mode
```
## License
MIT