Metadata-Version: 2.4
Name: mcptokens
Version: 0.1.5
Summary: 172 tokens in your agent's harness. One MCP tool that counts the tool-definition cost of any other MCP server.
Project-URL: Repository, https://github.com/dondai1234/mcptokens
Project-URL: Issues, https://github.com/dondai1234/mcptokens/issues
Project-URL: Changelog, https://github.com/dondai1234/mcptokens/blob/main/CHANGELOG.md
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-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcptokens

**172 tokens in your agent's harness.** One tool, `inspect`, that
counts the tool-definition cost of any other MCP server before you
enable it.

```bash
pip install mcptokens
```

<p>
  <a href="https://pypi.org/project/mcptokens/"><img src="https://img.shields.io/pypi/v/mcptokens.svg" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://github.com/dondai1234/mcptokens"><img src="https://img.shields.io/badge/Repo-dondai1234%2Fmcptokens-1f6feb.svg" alt="Repo"></a>
</p>

---

## Why

When your agent enables a new MCP server, its tools enter the
agent's context on every turn. The cost compounds fast. `mcptokens`
lets the agent ask *is this server cheap enough?* before flipping
the switch.

## How

Add `mcptokens` to your agent's MCP config (Claude Code, Pi,
OpenCode, Codex, ...). The agent gains one tool:

```jsonc
{
  "name": "inspect",
  "description": "Count tool-def tokens of any MCP server. Pass argv [...]",
  "inputSchema": {
    "properties": {
      "command":  {"type": "array",  "items": {"type": "string"}},
      "encoding": {"type": "string", "enum": ["cl100k_base","o200k_base"], "default": "cl100k_base"},
      "timeout":  {"type": "number", "default": 15, "minimum": 1, "maximum": 60}
    },
    "required": ["command"]
  }
}
```

The agent calls:

```python
inspect(command=["python", "-m", "some_mcp_server"])
```

The agent decides whether to enable the candidate server based on
the answer.

## The numbers

| | |
|--|--|
| **Self-cost on wire** | **172 tokens** of `cl100k_base` |
| Tools exposed         | **1**, named `inspect`           |
| Cross-platform        | Linux, macOS, Windows            |
| Python                | 3.11+                            |
| Imports               | `tiktoken`, `mcp`                |

## Install

```bash
pip install mcptokens
```

Add `mcptokens` to your agent's `mcpServers` / `mcp_servers`. Done.

## CLI (debug surface)

```bash
mcptokens python -m some_mcp_server     # human table
mcptokens --json python -m some_mcp_server   # pipeline-friendly JSON
mcptokens --timeout 30 python -m srv    # custom spawn, custom timeout
mcptokens serve                         # run as an MCP server
```

| Flag          | Default        | Purpose                                       |
|---------------|----------------|-----------------------------------------------|
| `--encoding`  | `cl100k_base`  | `cl100k_base` or `o200k_base`                 |
| `--timeout`   | `15`           | Per-server timeout in seconds (1 to 60)       |
| `--json`      | `false`        | Output JSON instead of the table              |

## Why it's cheap

One server, one tool, tight description, minimal schema. The
shipped tool definition tokenizes to **172 tokens**. A small tool
list is the product.

## License

MIT. `pip install mcptokens` from the canonical PyPI index.
