{"_id":"@ahmedshaikh/token-estimate-mcp","name":"@ahmedshaikh/token-estimate-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ahmedshaikh/token-estimate-mcp","version":"0.1.0","type":"module","description":"Estimate the token / context-window cost of a file, directory, or string BEFORE reading it — as an MCP server. So an agent can decide what fits in its budget instead of reading blind.","bin":{"agent-tokens":"dist/cli.js"},"engines":{"node":">=18"},"scripts":{"serve":"tsx src/server.ts","tokens":"tsx src/cli.ts","build":"tsc","test":"node --import tsx --test --test-force-exit test/*.test.ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.7.0","typescript":"^5.4.0"},"license":"MIT","author":{"name":"ahmedshaikh"},"keywords":["mcp","model-context-protocol","claude","agent","ai","tokens","context-window","budget","estimate"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/token-estimate-mcp.git"},"homepage":"https://github.com/RaziStuff/token-estimate-mcp#readme","bugs":{"url":"https://github.com/RaziStuff/token-estimate-mcp/issues"},"publishConfig":{"access":"public"},"gitHead":"d169ed54f55c829875a858bc23b88807f1956644","_id":"@ahmedshaikh/token-estimate-mcp@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-vu35s+7Pi7AUWkmDtxoioqO6TOzXVZzlA5JCeXJMwsoNCuPkUQ/uqSYVXukCEcMpYOR+d68hYZFfUxjSVG0AZA==","shasum":"0f30a63b9f27ae65b191bd378fc402733ed6ea0e","tarball":"https://registry.npmjs.org/@ahmedshaikh/token-estimate-mcp/-/token-estimate-mcp-0.1.0.tgz","fileCount":6,"unpackedSize":8715,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCwZ/GIAPjjrMW4WwRp3SMW++Q1aWeLO0BXdTJ9gRWoqgIhAJer6QRK1MXcSQhQE1liD5DhruYLhHp6Zq+UX6P9dlA3"}]},"_npmUser":{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"},"directories":{},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/token-estimate-mcp_0.1.0_1782701040495_0.35398510130197725"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T02:44:00.315Z","0.1.0":"2026-06-29T02:44:00.642Z","modified":"2026-06-29T02:44:00.857Z"},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"description":"Estimate the token / context-window cost of a file, directory, or string BEFORE reading it — as an MCP server. So an agent can decide what fits in its budget instead of reading blind.","homepage":"https://github.com/RaziStuff/token-estimate-mcp#readme","keywords":["mcp","model-context-protocol","claude","agent","ai","tokens","context-window","budget","estimate"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/token-estimate-mcp.git"},"author":{"name":"ahmedshaikh"},"bugs":{"url":"https://github.com/RaziStuff/token-estimate-mcp/issues"},"license":"MIT","readme":"# token-estimate\n\n**\"Will reading this fit in my budget?\"** — estimate the token / context-window\ncost of a file, directory, or string *before* an agent reads it, instead of\nreading blind and blowing the window.\n\n```\nestimate({ path: \"src/\" })\n→ { kind: \"dir\", files: 38, est_tokens: 41200, pct_context: 20.6,\n    top_files: [ { path: \"generated/schema.ts\", est_tokens: 9100 }, … ] }\n```\n\n## Why\n\nAgents read files with no idea of their size, and large files or directories\nsilently eat the context window. This makes size a thing you can *check first* —\nand for a directory it points at the biggest offenders so you can skip or scope them.\n\n## The tool\n\n**`estimate(path? | text?, top?)`** — returns:\n- exact `chars`, `words`, `lines`, `bytes`\n- `est_tokens` — a rough estimate (~chars/4, **±20%**; not an exact tokenizer)\n- `pct_context` — % of the context window (default 200k, set `CONTEXT_WINDOW`)\n- for a directory: `files` count + `top_files` (largest first)\n\nDirectories skip `node_modules`/`.git`/build dirs; files over 2 MB are estimated\nfrom size without reading.\n\n## Setup\n\n```bash\nnpm install\nnpm test\n```\n\n```bash\nclaude mcp add token-estimate -- node /abs/path/token-estimate/dist/server.js\n# CLI: agent-tokens src/    |    agent-tokens bigfile.json\n```\n\n## Honest limits\n\n- **It's an estimate**, not a real tokenizer — `chars/4` is a rule of thumb that's\n  off by ±20% (more for dense code or non-English). Good for \"2k or 50k?\"\n  decisions, not exact billing. `chars`/`words`/`lines` *are* exact.\n- Reads file contents to count (skips the heavy dirs and >2 MB files).\n","readmeFilename":"README.md","_rev":"1-f7d5136e8635fbea931f9f5cefb8c5bd"}