Add metadata tokens CLI and token_count tool

Introduce a new "instrmcp metadata tokens" subcommand and a standalone tools/token_count.py utility to count tokens used by MCP metadata (tools and resource templates). The CLI wiring and handler are added in instrmcp/cli.py; the token counter supports tiktoken offline estimation and Anthropic's messages.count_tokens API (auto-fallback, with --offline to force tiktoken). Documentation and README/installation notes updated to document the command and the new "analysis" extra (tiktoken) in pyproject.toml. This helps measure and optimize metadata token usage for context budgeting.

Author: caidish

CLAUDE.md

@@ -125,7 +125,7 @@ tools:
           param1: Description of param1
 ```
 
-**CLI commands**: `instrmcp metadata init|edit|list|show|path|validate`
+**CLI commands**: `instrmcp metadata init|edit|list|show|path|validate|tokens`
 
 **Validation** (`instrmcp metadata validate`) tests the full STDIO proxy path:
 ```

README.md

@@ -112,9 +112,10 @@ In a Jupyter notebook cell:
 #### CLI Utilities
 
 ```bash
-instrmcp config    # Show configuration paths
-instrmcp version   # Show version
-instrmcp --help    # Show all commands
+instrmcp config            # Show configuration paths
+instrmcp version           # Show version
+instrmcp metadata tokens   # Count tokens in metadata descriptions
+instrmcp --help            # Show all commands
 ```
 
 ## Documentation

docs/ARCHITECTURE.md

@@ -318,6 +318,7 @@ Manage metadata configuration via the CLI:
 | `instrmcp metadata show <name>` | Show specific tool/resource override |
 | `instrmcp metadata path` | Show config file path |
 | `instrmcp metadata validate` | Validate config against running server (via STDIO proxy) |
+| `instrmcp metadata tokens` | Count tokens in tool/resource descriptions (requires `tiktoken`) |
 
 #### Validation via STDIO Proxy
 
@@ -345,6 +346,28 @@ instrmcp metadata validate --timeout 30
 instrmcp metadata validate --launcher-path /path/to/claude_launcher.py
 ```
 
+#### Token Counting
+
+The `tokens` command counts tokens used by metadata descriptions to help optimize context budget.
+By default it uses the Anthropic API (`messages.count_tokens`) for exact counts and falls back
+to tiktoken offline estimation if the API is unavailable.
+
+```bash
+# Count tokens (API by default, auto-fallback to tiktoken)
+instrmcp metadata tokens
+
+# Force offline estimation (no API calls)
+instrmcp metadata tokens --offline
+
+# Count tokens in merged config (baseline + user overrides)
+instrmcp metadata tokens --source merged
+
+# Output as JSON for programmatic use
+instrmcp metadata tokens --format json
+```
+
+The standalone script is also available: `python tools/token_count.py`
+
 ### Validation Modes
 
 - **Strict mode** (`strict: true`): Errors on unknown tools/resources - catches typos

docs/source/api/cli.rst

@@ -166,6 +166,21 @@ Then in notebook:
 
    python agentsetting/claudedesktopsetting/claude_launcher.py
 
+metadata tokens
+~~~~~~~~~~~~~~~
+
+Count tokens used by tool/resource metadata descriptions. Useful for optimizing context budget.
+By default uses the Anthropic API for exact counts, with automatic fallback to tiktoken.
+
+.. code-block:: bash
+
+   instrmcp metadata tokens                    # API (auto-fallback to tiktoken)
+   instrmcp metadata tokens --offline          # Force tiktoken offline estimation
+   instrmcp metadata tokens --source merged    # Include user overrides
+   instrmcp metadata tokens --format json      # JSON output
+
+The standalone script is also available: ``python tools/token_count.py``
+
 Development Workflow
 ~~~~~~~~~~~~~~~~~~~~
 

docs/source/installation.rst

@@ -57,6 +57,12 @@ InstrMCP provides several optional dependency groups:
 
    pip install -e .[docs]
 
+**Analysis Tools** (token counting for metadata optimization):
+
+.. code-block:: bash
+
+   pip install -e .[analysis]
+
 **All Features**:
 
 .. code-block:: bash

instrmcp/cli.py

@@ -77,6 +77,30 @@ def _setup_metadata_subcommands(subparsers):
         help="Timeout for proxy communication in seconds (default: 15)",
     )
 
+    # tokens - Count tokens in metadata descriptions
+    tokens_parser = metadata_subparsers.add_parser(
+        "tokens",
+        help="Count tokens in tool/resource metadata descriptions",
+    )
+    tokens_parser.add_argument(
+        "--source",
+        choices=["baseline", "user", "merged"],
+        default="baseline",
+        help="Config source to analyze (default: baseline)",
+    )
+    tokens_parser.add_argument(
+        "--format",
+        choices=["table", "csv", "json"],
+        default="table",
+        dest="output_format",
+        help="Output format (default: table)",
+    )
+    tokens_parser.add_argument(
+        "--offline",
+        action="store_true",
+        help="Force tiktoken offline estimation (skip API)",
+    )
+
     return metadata_parser
 
 
@@ -240,12 +264,44 @@ def _handle_metadata_command(args):
     elif args.metadata_command == "validate":
         return _handle_metadata_validate(args)
 
+    elif args.metadata_command == "tokens":
+        return _handle_metadata_tokens(args)
+
     else:
         print("Usage: instrmcp metadata <command>")
-        print("Commands: init, edit, list, show, path, validate")
+        print("Commands: init, edit, list, show, path, validate, tokens")
         return 1
 
 
+def _handle_metadata_tokens(args):
+    """Handle metadata tokens subcommand."""
+    # Load token_count module from tools/ directory (not part of installed package)
+    import importlib.util
+
+    tools_dir = Path(__file__).resolve().parent.parent / "tools"
+    token_count_path = tools_dir / "token_count.py"
+
+    if not token_count_path.exists():
+        print(f"Error: token_count.py not found at {token_count_path}")
+        print("This command requires a source checkout of instrMCP.")
+        return 1
+
+    spec = importlib.util.spec_from_file_location("token_count", token_count_path)
+    token_count = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(token_count)
+
+    # Default: API with auto-fallback. --offline forces tiktoken only.
+    use_api = False if getattr(args, "offline", False) else None
+
+    output = token_count.run_token_count(
+        source=args.source,
+        output_format=args.output_format,
+        use_api=use_api,
+    )
+    print(output)
+    return 0
+
+
 def _handle_metadata_validate(args):
     """Handle metadata validate subcommand.
 

pyproject.toml

@@ -70,6 +70,9 @@ redpitaya = [
     "scipy>=1.10.0",
     "numpy>=1.24.0"
 ]
+analysis = [
+    "tiktoken>=0.5.0"
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",