mcptokens 0.1.0__tar.gz

mcptokens-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Config / secrets
+.env
+.envrc

mcptokens-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to mcptokens are documented in this file.
+
+## [Unreleased]
+
+First release in progress. See
+`~/.pi/agent/workspace/Chatgpt pro subscription/contextlens/project.md`
+for the goal and design constraints.

mcptokens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bishesh Bhandari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcptokens-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: mcptokens
+Version: 0.1.0
+Summary: Ultra-light MCP server for inspecting tool-definition token cost. Plug it into your agent harness.
+Project-URL: Repository, https://github.com/dondai1234/contextlens
+Project-URL: Issues, https://github.com/dondai1234/contextlens/issues
+Project-URL: Changelog, https://github.com/dondai1234/contextlens/blob/master/CHANGELOG.md
+Author-email: Bishesh Bhandari <bishesh@master-fetch.dev>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,context,inspect,mcp,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcptokens
+
+Ultra-light MCP server for inspecting tool-definition token cost.
+Plug it into your agent harness.
+
+```bash
+pip install mcptokens
+```
+
+## What this is
+
+`mcptokens` is an MCP server. Add a one-line entry to your agent's
+MCP config (Claude Code, Pi, OpenCode, ...) and the agent gains
+one tool: `inspect`. Call it with any MCP server's argv; receive
+its token cost back. Use BEFORE enabling an MCP server so the
+agent can decide whether the cost is worth it.
+
+The product is the MCP tool definition. Nothing else ships.
+
+## Constraint
+
+The whole point of `mcptokens` is that it doesn't eat many tokens
+of its own. The shipped tool definition, tokenized under
+`cl100k_base`, MUST stay under 1000 tokens. If a future refactor
+blows the budget, an import-time `RuntimeError` fires. This
+constraint is non-negotiable; tests pin it.
+
+## Status
+
+0.1.0 is the first version. See `CHANGELOG.md` once we ship.
+For the goal articulation and the design constraints that drive
+this package, see
+`~/.pi/agent/workspace/Chatgpt pro subscription/contextlens/project.md`
+(in this operator's workspace, not the published repo).

mcptokens-0.1.0/README.md

@@ -0,0 +1,34 @@
+# mcptokens
+
+Ultra-light MCP server for inspecting tool-definition token cost.
+Plug it into your agent harness.
+
+```bash
+pip install mcptokens
+```
+
+## What this is
+
+`mcptokens` is an MCP server. Add a one-line entry to your agent's
+MCP config (Claude Code, Pi, OpenCode, ...) and the agent gains
+one tool: `inspect`. Call it with any MCP server's argv; receive
+its token cost back. Use BEFORE enabling an MCP server so the
+agent can decide whether the cost is worth it.
+
+The product is the MCP tool definition. Nothing else ships.
+
+## Constraint
+
+The whole point of `mcptokens` is that it doesn't eat many tokens
+of its own. The shipped tool definition, tokenized under
+`cl100k_base`, MUST stay under 1000 tokens. If a future refactor
+blows the budget, an import-time `RuntimeError` fires. This
+constraint is non-negotiable; tests pin it.
+
+## Status
+
+0.1.0 is the first version. See `CHANGELOG.md` once we ship.
+For the goal articulation and the design constraints that drive
+this package, see
+`~/.pi/agent/workspace/Chatgpt pro subscription/contextlens/project.md`
+(in this operator's workspace, not the published repo).

mcptokens-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "mcptokens"
+version = "0.1.0"
+description = "Ultra-light MCP server for inspecting tool-definition token cost. Plug it into your agent harness."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Bishesh Bhandari", email = "bishesh@master-fetch.dev"}]
+keywords = ["mcp", "tokens", "context", "ai-agent", "inspect"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "tiktoken>=0.7",
+    "mcp[cli]>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-mock>=3.14",
+]
+
+[project.urls]
+Repository = "https://github.com/dondai1234/contextlens"
+Issues = "https://github.com/dondai1234/contextlens/issues"
+Changelog = "https://github.com/dondai1234/contextlens/blob/master/CHANGELOG.md"
+
+[project.scripts]
+mcptokens = "mcptokens.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcptokens"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers"]
+markers = [
+    "e2e: end-to-end tests that spawn real MCP servers. Skip by default; run manually with `pytest -m e2e`.",
+]

mcptokens-0.1.0/src/mcptokens/__init__.py

@@ -0,0 +1,11 @@
+"""mcptokens: ultra-light MCP server for inspecting tool-def token cost.
+
+Use case: an AI agent (Claude Code, Pi, OpenCode, ...) connects to
+mcptokens as one of its MCP servers, then calls the single exposed
+tool `inspect` with a candidate server's argv. The agent gets back
+per-tool tokens plus a realistic wire total. Use BEFORE enabling
+an MCP server so the agent can decide whether the cost is worth it.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

mcptokens-0.1.0/src/mcptokens/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m mcptokens ...` entry."""
+from mcptokens.cli import main
+
+raise SystemExit(main())

mcptokens-0.1.0/src/mcptokens/_engine.py

@@ -0,0 +1,413 @@
+"""mcptokens engine.
+
+Spawn a stdio MCP server, speak JSON-RPC `initialize` + `tools/list`,
+count the wire tokens that an LLM agent would receive. Cross-platform
+safe (Windows in particular: stdlib has no `os.set_blocking`, and
+`selectors.DefaultSelector` raises WinError 10093 unless WSAStartup
+has run; we use a daemon reader thread + `queue.Queue` instead).
+
+Public surface:
+    inspect_server(cmd, *, encoding="cl100k_base", timeout_seconds=15.0)
+        -> InspectReport
+    InspectError  (raised on spawn / protocol failures)
+    InspectReport, ToolStats   (dataclasses; serialize via .as_dict())
+"""
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import tiktoken
+
+__all__ = [
+    "inspect_server",
+    "InspectError",
+    "InspectReport",
+    "ToolStats",
+    "DEFAULT_ENCODING",
+    "DEFAULT_TIMEOUT_SECONDS",
+]
+
+DEFAULT_ENCODING = "cl100k_base"
+DEFAULT_TIMEOUT_SECONDS = 15.0
+SUPPORTED_ENCODINGS = ("cl100k_base", "o200k_base")
+_INIT_ID = 1
+_TOOLS_LIST_ID = 2
+_LSP_PROTOCOL_VERSION = "2024-11-05"
+
+
+class InspectError(Exception):
+    """Raised for spawn / protocol / shape failures that the agent
+    needs to know about so it can retry or fall back."""
+
+
+# --- output dataclasses ---------------------------------------------------
+
+
+@dataclass
+class ToolStats:
+    name: str
+    name_tokens: int = 0
+    description_tokens: int = 0
+    schema_tokens: int = 0
+    annotations_tokens: int = 0
+    total_tokens: int = 0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "tokens": {
+                "name": self.name_tokens,
+                "description": self.description_tokens,
+                "schema": self.schema_tokens,
+                "annotations": self.annotations_tokens,
+                "total": self.total_tokens,
+            },
+        }
+
+
+@dataclass
+class InspectReport:
+    ok: bool
+    server: str
+    tools: list[ToolStats] = field(default_factory=list)
+    wire_total_tokens: int = 0
+    encoding: str = DEFAULT_ENCODING
+    elapsed_ms: int = 0
+    error: str = ""
+    version: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "server": self.server,
+            "tool_count": len(self.tools),
+            "tools": [t.as_dict() for t in self.tools],
+            "wire_total_tokens": self.wire_total_tokens,
+            "encoding": self.encoding,
+            "elapsed_ms": self.elapsed_ms,
+            "version": self.version,
+        }
+
+
+# --- json-rpc helpers -----------------------------------------------------
+
+
+def _encode(msg: dict[str, Any]) -> bytes:
+    return (json.dumps(msg, separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def _decode(b: bytes) -> dict[str, Any] | None:
+    try:
+        obj = json.loads(b.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(obj, dict):
+        return None
+    return obj
+
+
+# --- defensive shape coercion --------------------------------------------
+
+
+def _coerce_tools(result: Any) -> list[dict[str, Any]]:
+    """The server's `tools/list` result shape can drift. We accept:
+        {"tools": [...]}, [...], None, "anything else" -> [].
+    Each tool entry that isn't a dict is dropped.
+    """
+    if isinstance(result, list):
+        candidates = result
+    elif isinstance(result, dict):
+        inner = result.get("tools")
+        candidates = inner if isinstance(inner, list) else []
+    else:
+        candidates = []
+    return [t for t in candidates if isinstance(t, dict)]
+
+
+def _count_tool(tool: dict[str, Any], enc) -> ToolStats:
+    """Recipe A+ — split the wire bytes into 4 buckets so the agent
+    sees where its tokens are, then return a ToolStats."""
+    name = str(tool.get("name") or "").strip() or "<unnamed>"
+    description = tool.get("description") or ""
+    schema = tool.get("inputSchema") or {}
+    annotations = tool.get("annotations") or {}
+    name_tokens = len(enc.encode(name))
+    description_tokens = len(enc.encode(description)) if isinstance(description, str) else 0
+    schema_tokens = len(enc.encode(json.dumps(schema, separators=(",", ":")))) if schema else 0
+    annotations_tokens = (
+        len(enc.encode(json.dumps(annotations, separators=(",", ":"))))
+        if annotations
+        else 0
+    )
+    total = name_tokens + description_tokens + schema_tokens + annotations_tokens
+    return ToolStats(
+        name=name,
+        name_tokens=name_tokens,
+        description_tokens=description_tokens,
+        schema_tokens=schema_tokens,
+        annotations_tokens=annotations_tokens,
+        total_tokens=total,
+    )
+
+
+# --- subprocess plumbing -------------------------------------------------
+
+
+class _Killed(Exception):
+    """Internal: process didn't exit cleanly on shutdown."""
+
+
+def _spawn(cmd: list[str]) -> subprocess.Popen:
+    """Spawn the server. Never raise FileNotFoundError — re-raise as
+    `InspectError` so the agent gets one predictable failure type."""
+    if not cmd:
+        raise InspectError("spawn cmd is empty")
+    try:
+        return subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            bufsize=0,
+        )
+    except FileNotFoundError as exc:
+        raise InspectError(f"spawn failed: command not found: {cmd[0]!r}") from exc
+    except (PermissionError, OSError) as exc:
+        raise InspectError(f"spawn failed: {exc}") from exc
+
+
+class _StdioReader:
+    """Daemon reader thread: stdout -> `queue.Queue`. We use a thread
+    instead of `selectors.DefaultSelector` because the latter raises
+    `[WinError 10093]` (WSAStartup not called) on Windows when the
+    current Python process hasn't yet opened a socket.
+
+    Sentinel values for stream-lifecycle:
+        None -> EOF (process closed stdout)
+        ("ERR", exc) -> reader died with an exception
+    """
+
+    def __init__(self, proc: subprocess.Popen) -> None:
+        self._proc = proc
+        self._q: queue.Queue = queue.Queue()
+        self._t = threading.Thread(target=self._run, daemon=True)
+        self._t.start()
+
+    def _run(self) -> None:
+        try:
+            while True:
+                line = self._proc.stdout.readline()
+                if not line:
+                    self._q.put(None)
+                    return
+                self._q.put(line)
+        except Exception as exc:  # pragma: no cover (defensive)
+            self._q.put(("ERR", exc))
+
+    def recv_until_id(
+        self,
+        expected_id: Any,
+        deadline_monotonic: float,
+    ) -> dict[str, Any] | None:
+        """Read JSON-RPC frames until we see one whose `id` matches.
+        Skip notifications and out-of-order replies."""
+        while True:
+            remaining = max(0.0, deadline_monotonic - time.monotonic())
+            if remaining <= 0:
+                return None
+            try:
+                line = self._q.get(timeout=remaining)
+            except queue.Empty:
+                return None
+            if line is None:
+                return None  # EOF
+            if isinstance(line, tuple) and line[0] == "ERR":
+                raise InspectError(f"reader died: {line[1]!r}")
+            msg = _decode(line)
+            if msg is None:
+                continue
+            if "id" not in msg:
+                continue  # notification: skip
+            if msg.get("id") != expected_id:
+                continue
+            return msg
+
+
+# --- top-level entry -----------------------------------------------------
+
+
+def inspect_server(
+    cmd: list[str],
+    *,
+    encoding: str = DEFAULT_ENCODING,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+    version: str = "0.1.0",
+) -> InspectReport:
+    """Spawn `cmd`, run initialize + tools/list, count tokens. The
+    output is the same for the CLI and the MCP server path."""
+    if not isinstance(cmd, list) or not cmd or not all(isinstance(a, str) for a in cmd):
+        raise InspectError("cmd must be a non-empty list[str] of strings")
+    if encoding not in SUPPORTED_ENCODINGS:
+        raise InspectError(
+            f"encoding {encoding!r} is not supported. "
+            f"Pick one of {list(SUPPORTED_ENCODINGS)}."
+        )
+    if timeout_seconds <= 0 or timeout_seconds > 60:
+        raise InspectError(
+            f"timeout_seconds {timeout_seconds!r} is outside (0, 60]"
+        )
+
+    enc = tiktoken.get_encoding(encoding)
+    server_label = " ".join(cmd)
+    started = time.monotonic()
+    proc = _spawn(cmd)
+
+    try:
+        deadline = started + timeout_seconds
+        reader = _StdioReader(proc)
+
+        try:
+            proc.stdin.write(
+                _encode(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": _INIT_ID,
+                        "method": "initialize",
+                        "params": {
+                            "protocolVersion": _LSP_PROTOCOL_VERSION,
+                            "capabilities": {},
+                            "clientInfo": {
+                                "name": "mcptokens",
+                                "version": version,
+                            },
+                        },
+                    }
+                )
+            )
+            proc.stdin.flush()
+            init = reader.recv_until_id(_INIT_ID, deadline)
+            if init is None:
+                raise InspectError(
+                    f"`initialize` exceeded {timeout_seconds:g}s without response"
+                )
+            if "error" in init:
+                raise InspectError(
+                    f"server error on `initialize`: {init['error']}"
+                )
+
+            # notifications/initialized (no id; agent doesn't reply)
+            try:
+                proc.stdin.write(
+                    _encode({"jsonrpc": "2.0", "method": "notifications/initialized"})
+                )
+                proc.stdin.flush()
+            except (BrokenPipeError, OSError):
+                pass
+
+            proc.stdin.write(
+                _encode(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": _TOOLS_LIST_ID,
+                        "method": "tools/list",
+                        "params": {},
+                    }
+                )
+            )
+            proc.stdin.flush()
+            tools_msg = reader.recv_until_id(_TOOLS_LIST_ID, deadline)
+            if tools_msg is None:
+                raise InspectError(
+                    f"`tools/list` exceeded {timeout_seconds:g}s without response"
+                )
+            if "error" in tools_msg:
+                raise InspectError(
+                    f"server error on `tools/list`: {tools_msg['error']}"
+                )
+
+        finally:
+            try:
+                if proc.stdin and not proc.stdin.closed:
+                    proc.stdin.close()
+            except OSError:
+                pass
+
+        # Close stdin so the server's loop reads EOF. Give it 1s to
+        # exit cleanly; if it doesn't, kill it.
+        try:
+            proc.wait(timeout=1.0)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            try:
+                proc.wait(timeout=1.0)
+            except subprocess.TimeoutExpired:  # pragma: no cover
+                pass
+
+    except InspectError:
+        # On error: close stdin to break server's reader, kill if not
+        # exiting, then drain stderr to give the user a one-liner
+        # into the failure.
+        try:
+            if proc.stdin and not proc.stdin.closed:
+                proc.stdin.close()
+        except OSError:
+            pass
+        if proc.poll() is None:
+            proc.kill()
+            try:
+                proc.wait(timeout=1.0)
+            except subprocess.TimeoutExpired:  # pragma: no cover
+                pass
+        stderr_tail = _drain_stderr(proc, max_chars=400)
+        if stderr_tail:
+            # Re-raise with the tail appended so the agent sees one
+            # tidy line, not a stack trace.
+            try:
+                raise
+            except InspectError as exc:
+                if stderr_tail not in str(exc):
+                    raise InspectError(f"{exc} | server stderr: {stderr_tail!r}") from None
+        raise
+    finally:
+        # On happy path, still drain stderr in case there were warnings
+        # worth recording. Don't blow up if the proc is gone.
+        _ = proc.poll()
+
+    result = tools_msg.get("result")
+    tools = _coerce_tools(result)
+    stats = [_count_tool(t, enc) for t in tools]
+    wire_total = len(enc.encode(json.dumps(result if result is not None else {}, separators=(",", ":"))))
+
+    elapsed_ms = int((time.monotonic() - started) * 1000)
+    return InspectReport(
+        ok=True,
+        server=server_label,
+        tools=stats,
+        wire_total_tokens=wire_total,
+        encoding=encoding,
+        elapsed_ms=elapsed_ms,
+        version=version,
+    )
+
+
+def _drain_stderr(proc: subprocess.Popen, *, max_chars: int) -> str:
+    """Read whatever is left on stderr (after the process is dead).
+    Don't block forever — fd is closed; the OS says EOF fast."""
+    try:
+        raw = proc.stderr.read()
+    except (OSError, ValueError):
+        return ""
+    if not raw:
+        return ""
+    text = raw.decode("utf-8", errors="replace").strip()
+    if len(text) <= max_chars:
+        return text
+    return "..." + text[-max_chars:]