tool-tax 0.2.0__tar.gz

tool_tax-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sihyeon Jeon
+
+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.
+

tool_tax-0.2.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: tool-tax
+Version: 0.2.0
+Summary: Measure the hidden token bill of MCP and agent tool catalogs.
+Author: Sihyeon Jeon
+License-Expression: MIT
+Keywords: mcp,agents,tool-calling,context-engineering,token-budget
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# tool-tax
+
+**See how many tokens your agent tools burn before the user even asks a question.**
+
+`tool-tax` scans MCP-style tool catalogs, JSON/YAML tool manifests, and OpenAPI
+files. It shows the full schema cost, ranks the heaviest tools, diffs catalog
+changes in pull requests, and writes a slim tool index for progressive loading.
+
+```bash
+pipx install git+https://github.com/SihyeonJeon/tool-tax.git@v0.2.0
+
+tool-tax scan examples
+tool-tax diff old-tools.json new-tools.json
+tool-tax pack examples --out .tool-tax
+```
+
+Example result:
+
+```text
+Tools: 7
+Full tool tax: 1,144 est. tokens
+Slim index: 309 est. tokens
+Potential savings: 835 est. tokens (73.0%)
+```
+
+## Why
+
+Agents keep getting more tools. MCP servers, browser tools, GitHub tools,
+database tools, and internal APIs all ship long schemas. If every schema is
+loaded up front, your agent pays a context tax before it starts working.
+
+`tool-tax` gives that tax a number.
+
+## What It Does
+
+- Finds tool definitions in JSON, YAML, and OpenAPI files.
+- Estimates token cost for each tool schema.
+- Ranks the most expensive tools.
+- Diffs base/head catalogs for PR budget checks.
+- Generates a slim `tool-index.json` plus separate schema files.
+- Fails CI when the tool catalog grows past a budget.
+- Posts or updates a GitHub PR report comment when configured.
+
+## Install
+
+From GitHub:
+
+```bash
+pipx install git+https://github.com/SihyeonJeon/tool-tax.git@v0.2.0
+```
+
+From a clone:
+
+```bash
+git clone https://github.com/SihyeonJeon/tool-tax.git
+cd tool-tax
+python3 -m pip install -e .
+```
+
+Installs one runtime dependency: `PyYAML`.
+
+## Use
+
+Scan a repo:
+
+```bash
+tool-tax scan .
+```
+
+Write Markdown and JSON reports:
+
+```bash
+tool-tax scan examples --format md --out tool-tax-report.md
+tool-tax scan examples --format json --out tool-tax-report.json
+```
+
+Create a progressive-loading pack:
+
+```bash
+tool-tax pack examples --out .tool-tax
+```
+
+That writes:
+
+```text
+.tool-tax/
+  tool-index.json       # small always-load index
+  schemas/*.json        # full schemas loaded only when needed
+```
+
+Fail CI on tool bloat:
+
+```bash
+tool-tax scan mcp-tools.json --max-tokens 12000 --max-tool-tokens 750
+```
+
+Compare a pull request:
+
+```bash
+tool-tax diff base-tools.json head-tools.json --max-delta-tokens 500
+```
+
+Use it as a GitHub Action:
+
+```yaml
+- uses: SihyeonJeon/tool-tax@v0.2.0
+  with:
+    path: .
+    max-tokens: "12000"
+    max-tool-tokens: "750"
+```
+
+## Output
+
+```md
+# Tool Tax Report
+
+Grade: **lean**
+
+| Metric | Value |
+| --- | ---: |
+| Tools | 7 |
+| Full tool tax | 1,144 est. tokens |
+| Slim index | 309 est. tokens |
+| Potential savings | 835 est. tokens (73.0%) |
+| Worst tool | 255 est. tokens |
+```
+
+## Supports
+
+- MCP-style JSON/YAML tool arrays
+- Agent tool manifests with `name`, `description`, and `inputSchema`
+- OpenAPI `paths` operations
+- Nested JSON catalogs
+- GitHub Step Summary and PR comment reports
+
+## Repo Shape
+
+```text
+src/tool_tax/   # library + CLI
+tests/          # unittest smoke coverage
+examples/       # sample MCP/OpenAPI catalogs and reports
+docs/           # trend scan and repo structure notes
+```
+
+## Claim
+
+This tool does not compress prompts by itself. It measures the up-front schema
+tax and creates a smaller index so your agent can load full schemas later.
+
+It is the measuring tape and CI gate, not a runtime MCP proxy. Use it before or
+alongside proxy/search tools such as MCP compressors, CLI adapters, and
+progressive-disclosure gateways.
+
+## More
+
+- [Roadmap](ROADMAP.md)
+- [Public scan gallery](docs/scans/README.md)
+- [PyPI publish notes](docs/pypi-publish.md)
+- [Star forecast and comparison set](docs/star-forecast-2026-05-17.md)
+- [Launch kit](docs/launch-kit.md)
+- [Trend scan](docs/trend-scan-2026-05-17.md)
+- [Repo shape scan](docs/repo-shape-scan.md)
+
+## License
+
+MIT

tool_tax-0.2.0/README.md

@@ -0,0 +1,167 @@
+# tool-tax
+
+**See how many tokens your agent tools burn before the user even asks a question.**
+
+`tool-tax` scans MCP-style tool catalogs, JSON/YAML tool manifests, and OpenAPI
+files. It shows the full schema cost, ranks the heaviest tools, diffs catalog
+changes in pull requests, and writes a slim tool index for progressive loading.
+
+```bash
+pipx install git+https://github.com/SihyeonJeon/tool-tax.git@v0.2.0
+
+tool-tax scan examples
+tool-tax diff old-tools.json new-tools.json
+tool-tax pack examples --out .tool-tax
+```
+
+Example result:
+
+```text
+Tools: 7
+Full tool tax: 1,144 est. tokens
+Slim index: 309 est. tokens
+Potential savings: 835 est. tokens (73.0%)
+```
+
+## Why
+
+Agents keep getting more tools. MCP servers, browser tools, GitHub tools,
+database tools, and internal APIs all ship long schemas. If every schema is
+loaded up front, your agent pays a context tax before it starts working.
+
+`tool-tax` gives that tax a number.
+
+## What It Does
+
+- Finds tool definitions in JSON, YAML, and OpenAPI files.
+- Estimates token cost for each tool schema.
+- Ranks the most expensive tools.
+- Diffs base/head catalogs for PR budget checks.
+- Generates a slim `tool-index.json` plus separate schema files.
+- Fails CI when the tool catalog grows past a budget.
+- Posts or updates a GitHub PR report comment when configured.
+
+## Install
+
+From GitHub:
+
+```bash
+pipx install git+https://github.com/SihyeonJeon/tool-tax.git@v0.2.0
+```
+
+From a clone:
+
+```bash
+git clone https://github.com/SihyeonJeon/tool-tax.git
+cd tool-tax
+python3 -m pip install -e .
+```
+
+Installs one runtime dependency: `PyYAML`.
+
+## Use
+
+Scan a repo:
+
+```bash
+tool-tax scan .
+```
+
+Write Markdown and JSON reports:
+
+```bash
+tool-tax scan examples --format md --out tool-tax-report.md
+tool-tax scan examples --format json --out tool-tax-report.json
+```
+
+Create a progressive-loading pack:
+
+```bash
+tool-tax pack examples --out .tool-tax
+```
+
+That writes:
+
+```text
+.tool-tax/
+  tool-index.json       # small always-load index
+  schemas/*.json        # full schemas loaded only when needed
+```
+
+Fail CI on tool bloat:
+
+```bash
+tool-tax scan mcp-tools.json --max-tokens 12000 --max-tool-tokens 750
+```
+
+Compare a pull request:
+
+```bash
+tool-tax diff base-tools.json head-tools.json --max-delta-tokens 500
+```
+
+Use it as a GitHub Action:
+
+```yaml
+- uses: SihyeonJeon/tool-tax@v0.2.0
+  with:
+    path: .
+    max-tokens: "12000"
+    max-tool-tokens: "750"
+```
+
+## Output
+
+```md
+# Tool Tax Report
+
+Grade: **lean**
+
+| Metric | Value |
+| --- | ---: |
+| Tools | 7 |
+| Full tool tax | 1,144 est. tokens |
+| Slim index | 309 est. tokens |
+| Potential savings | 835 est. tokens (73.0%) |
+| Worst tool | 255 est. tokens |
+```
+
+## Supports
+
+- MCP-style JSON/YAML tool arrays
+- Agent tool manifests with `name`, `description`, and `inputSchema`
+- OpenAPI `paths` operations
+- Nested JSON catalogs
+- GitHub Step Summary and PR comment reports
+
+## Repo Shape
+
+```text
+src/tool_tax/   # library + CLI
+tests/          # unittest smoke coverage
+examples/       # sample MCP/OpenAPI catalogs and reports
+docs/           # trend scan and repo structure notes
+```
+
+## Claim
+
+This tool does not compress prompts by itself. It measures the up-front schema
+tax and creates a smaller index so your agent can load full schemas later.
+
+It is the measuring tape and CI gate, not a runtime MCP proxy. Use it before or
+alongside proxy/search tools such as MCP compressors, CLI adapters, and
+progressive-disclosure gateways.
+
+## More
+
+- [Roadmap](ROADMAP.md)
+- [Public scan gallery](docs/scans/README.md)
+- [PyPI publish notes](docs/pypi-publish.md)
+- [Star forecast and comparison set](docs/star-forecast-2026-05-17.md)
+- [Launch kit](docs/launch-kit.md)
+- [Trend scan](docs/trend-scan-2026-05-17.md)
+- [Repo shape scan](docs/repo-shape-scan.md)
+
+## License
+
+MIT

tool_tax-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tool-tax"
+version = "0.2.0"
+description = "Measure the hidden token bill of MCP and agent tool catalogs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Sihyeon Jeon"}]
+keywords = ["mcp", "agents", "tool-calling", "context-engineering", "token-budget"]
+dependencies = ["PyYAML>=6.0"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Environment :: Console",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+tool-tax = "tool_tax.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tool_tax-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tool_tax-0.2.0/src/tool_tax/__init__.py

@@ -0,0 +1,3 @@
+"""Tool Tax: measure hidden token cost in agent tool catalogs."""
+
+__version__ = "0.2.0"

tool_tax-0.2.0/src/tool_tax/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .diff import dump_diff_json, to_diff_json, to_diff_markdown
+from .extract import extract_tools
+from .github_comment import DEFAULT_MARKER, resolve_pr_number, upsert_pr_comment
+from .report import summarize, to_json, to_markdown, write_pack, write_report
+
+
+def parse_paths(values: list[str]) -> list[Path]:
+    return [Path(value) for value in values]
+
+
+def append_step_summary(markdown: str) -> None:
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not summary_path:
+        print("WARNING: GITHUB_STEP_SUMMARY is not set", file=sys.stderr)
+        return
+    with Path(summary_path).open("a", encoding="utf-8") as fh:
+        fh.write(markdown.rstrip() + "\n")
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    records, errors = extract_tools(parse_paths(args.paths))
+    payload = to_json(records, errors) if args.format == "json" else to_markdown(records, errors)
+    write_report(payload, Path(args.out).resolve() if args.out else None)
+    if args.github_step_summary:
+        append_step_summary(to_markdown(records, errors))
+    summary = summarize(records)
+    failed = False
+    if args.max_tokens is not None and summary.total_tax_tokens > args.max_tokens:
+        failed = True
+    if args.max_tool_tokens is not None and summary.worst_tool_tokens > args.max_tool_tokens:
+        failed = True
+    if args.fail_on_grade:
+        ranks = {"lean": 0, "warm": 1, "expensive": 2, "brutal": 3}
+        failed = ranks[summary.grade] >= ranks[args.fail_on_grade]
+    return 2 if failed else 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    base_records, base_errors = extract_tools([Path(args.base)])
+    head_records, head_errors = extract_tools([Path(args.head)])
+    errors = [f"base: {error}" for error in base_errors] + [f"head: {error}" for error in head_errors]
+    if args.format == "json":
+        payload = to_diff_json(base_records, head_records, errors)
+        write_report(dump_diff_json(payload), Path(args.out).resolve() if args.out else None)
+    else:
+        payload = to_diff_markdown(base_records, head_records, errors)
+        write_report(payload, Path(args.out).resolve() if args.out else None)
+    if args.github_step_summary:
+        append_step_summary(to_diff_markdown(base_records, head_records, errors))
+    summary = to_diff_json(base_records, head_records, errors)["summary"]
+    failed = False
+    if args.fail_on_increase and summary["delta_tax_tokens"] > 0:
+        failed = True
+    if args.max_delta_tokens is not None and summary["delta_tax_tokens"] > args.max_delta_tokens:
+        failed = True
+    if args.max_tool_delta_tokens is not None and summary["worst_tool_delta_tokens"] > args.max_tool_delta_tokens:
+        failed = True
+    return 2 if failed else 0
+
+
+def cmd_pack(args: argparse.Namespace) -> int:
+    records, errors = extract_tools(parse_paths(args.paths))
+    if errors and not args.ignore_errors:
+        for error in errors:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    write_pack(records, Path(args.out).resolve())
+    summary = summarize(records)
+    print(
+        f"packed {summary.tool_count} tools: "
+        f"{summary.total_tax_tokens:,} -> {summary.total_index_tokens:,} est. tokens "
+        f"({summary.estimated_savings_percent:.1f}% smaller)"
+    )
+    return 0
+
+
+def cmd_comment_pr(args: argparse.Namespace) -> int:
+    repo = args.repo or os.environ.get("GITHUB_REPOSITORY")
+    token = args.token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    pr_number = args.pr or resolve_pr_number()
+    report = Path(args.body_file).read_text(encoding="utf-8")
+    if args.dry_run:
+        print(json.dumps({"repo": repo, "pr": pr_number, "body": report}, ensure_ascii=False, indent=2))
+        return 0
+    missing = []
+    if not repo:
+        missing.append("--repo or GITHUB_REPOSITORY")
+    if not pr_number:
+        missing.append("--pr or pull_request event payload")
+    if not token:
+        missing.append("--token, GITHUB_TOKEN, or GH_TOKEN")
+    if missing:
+        print("ERROR: missing " + ", ".join(missing), file=sys.stderr)
+        return 1
+    result = upsert_pr_comment(repo, pr_number, report, token, args.marker)
+    print(f"{result['action']} PR comment: {result['url']}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tool-tax",
+        description="Measure the hidden token bill of MCP and agent tool catalogs.",
+    )
+    parser.add_argument("--version", action="version", version=f"tool-tax {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="scan JSON/OpenAPI/tool catalogs")
+    scan.add_argument("paths", nargs="+", help="files or directories to scan")
+    scan.add_argument("--format", choices=["md", "json"], default="md")
+    scan.add_argument("--out", help="write report to file")
+    scan.add_argument("--max-tokens", type=int, help="fail if total tool tax is above this")
+    scan.add_argument("--max-tool-tokens", type=int, help="fail if any one tool is above this")
+    scan.add_argument("--fail-on-grade", choices=["lean", "warm", "expensive", "brutal"])
+    scan.add_argument("--github-step-summary", action="store_true", help="append Markdown report to GitHub step summary")
+    scan.set_defaults(func=cmd_scan)
+
+    diff = sub.add_parser("diff", help="compare base and head tool catalogs")
+    diff.add_argument("base", help="base file or directory")
+    diff.add_argument("head", help="head file or directory")
+    diff.add_argument("--format", choices=["md", "json"], default="md")
+    diff.add_argument("--out", help="write diff report to file")
+    diff.add_argument("--fail-on-increase", action="store_true", help="fail if total tool tax increases")
+    diff.add_argument("--max-delta-tokens", type=int, help="fail if total token delta exceeds this")
+    diff.add_argument("--max-tool-delta-tokens", type=int, help="fail if one tool grows more than this")
+    diff.add_argument("--github-step-summary", action="store_true", help="append Markdown diff to GitHub step summary")
+    diff.set_defaults(func=cmd_diff)
+
+    pack = sub.add_parser("pack", help="write slim tool index and schema files")
+    pack.add_argument("paths", nargs="+", help="files or directories to scan")
+    pack.add_argument("--out", required=True, help="output directory")
+    pack.add_argument("--ignore-errors", action="store_true")
+    pack.set_defaults(func=cmd_pack)
+
+    comment = sub.add_parser("comment-pr", help="create or update a GitHub PR comment from a report")
+    comment.add_argument("--body-file", required=True, help="Markdown report file")
+    comment.add_argument("--repo", help="owner/repo, defaults to GITHUB_REPOSITORY")
+    comment.add_argument("--pr", type=int, help="pull request number")
+    comment.add_argument("--token", help="GitHub token, defaults to GITHUB_TOKEN or GH_TOKEN")
+    comment.add_argument("--marker", default=DEFAULT_MARKER, help="hidden marker for updating an existing comment")
+    comment.add_argument("--dry-run", action="store_true", help="print resolved comment payload without calling GitHub")
+    comment.set_defaults(func=cmd_comment_pr)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())