mcpstat 0.1.2__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.2] - 2026-02-16
11
+
12
+ ### Added
13
+
14
+ - **Latency Tracking**: Track execution duration for each tool call
15
+ - `@stat.track` decorator for automatic latency tracking (recommended)
16
+ - `async with stat.tracking(name, type)` context manager alternative
17
+ - `duration_ms` parameter in `record()` for manual timing
18
+ - New latency columns: `total_duration_ms`, `min_duration_ms`, `max_duration_ms`
19
+ - `latency_summary` in `get_stats()` response with total duration
20
+ - Per-tool `avg_latency_ms`, `min_duration_ms`, `max_duration_ms` metrics
21
+
22
+ ### Changed
23
+
24
+ - Database schema bumped to v3 with latency tracking columns
25
+ - `get_stats()` response now includes `latency_summary` object
26
+ - Each stat item now includes latency fields
27
+ - **API Improvement**: `@stat.track` decorator is now the recommended way to track calls
28
+ - Eliminates the "first line" requirement
29
+ - Automatic latency measurement
30
+ - Never fails user code
31
+
32
+ ### Migration
33
+
34
+ - Automatic database migration from v2 to v3
35
+ - Preserves all existing data
36
+ - New latency columns default to 0/NULL for existing records
37
+
38
+ ## [0.2.1] - 2026-02-01
39
+
40
+ ### Added
41
+
42
+ - **Token Tracking**: New feature to track response sizes and estimate token usage
43
+ - `response_chars` parameter in `record()` for automatic token estimation
44
+ - `input_tokens` and `output_tokens` parameters for actual token tracking
45
+ - New `report_tokens()` method for deferred token reporting
46
+ - Token summary in `get_stats()` response with totals and averages
47
+ - **Schema Migration**: Automatic database migration from v1 to v2
48
+ - Adds token tracking columns with backward compatibility
49
+ - Preserves all existing data
50
+ - **Documentation**: Added new and updated guides, API references, and examples
51
+
52
+ ### Changed
53
+
54
+ - Database schema bumped to v2 with new columns:
55
+ - `total_input_tokens`, `total_output_tokens`
56
+ - `total_response_chars`, `estimated_tokens`
57
+ - `get_stats()` response now includes `token_summary` object
58
+ - Each stat item now includes token fields and `avg_tokens_per_call`
59
+
10
60
  ## [0.1.2] - 2026-01-17
11
61
 
12
62
  ### Added
@@ -51,7 +101,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
51
101
  - Full type annotations with strict mypy compliance (`py.typed` marker included)
52
102
  - Comprehensive test suite
53
103
 
54
- [Unreleased]: https://github.com/tekkidev/mcpstat/compare/v0.1.2...HEAD
104
+ [Unreleased]: https://github.com/tekkidev/mcpstat/compare/v0.2.2...HEAD
105
+ [0.2.2]: https://github.com/tekkidev/mcpstat/compare/v0.2.1...v0.2.2
106
+ [0.2.1]: https://github.com/tekkidev/mcpstat/compare/v0.1.2...v0.2.1
55
107
  [0.1.2]: https://github.com/tekkidev/mcpstat/compare/v0.1.1...v0.1.2
56
108
  [0.1.1]: https://github.com/tekkidev/mcpstat/compare/v0.1.0...v0.1.1
57
109
  [0.1.0]: https://github.com/tekkidev/mcpstat/releases/tag/v0.1.0
mcpstat-0.2.2/PKG-INFO ADDED
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcpstat
3
+ Version: 0.2.2
4
+ Summary: Usage tracking, analytics, and file logging for MCP (Model Context Protocol) servers
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Keywords: mcp,model-context-protocol,statistics,analytics,usage-tracking,logging,ai,llm,agent,mcp-server,tool-tracking,observability,token-tracking,latency-tracking
8
+ Author: Vadim Bakhrenkov
9
+ Author-email: hello@vadim.dev
10
+ Requires-Python: >=3.10,<4.0
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Framework :: AsyncIO
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Classifier: Topic :: System :: Logging
24
+ Classifier: Topic :: System :: Monitoring
25
+ Classifier: Typing :: Typed
26
+ Provides-Extra: all
27
+ Provides-Extra: dev
28
+ Provides-Extra: mcp
29
+ Requires-Dist: mcp (>=1.0.0) ; extra == "mcp" or extra == "all"
30
+ Requires-Dist: mypy (>=1.0) ; extra == "dev" or extra == "all"
31
+ Requires-Dist: pytest (>=7.0) ; extra == "dev" or extra == "all"
32
+ Requires-Dist: pytest-asyncio (>=0.21) ; extra == "dev" or extra == "all"
33
+ Requires-Dist: pytest-cov (>=4.0) ; extra == "dev" or extra == "all"
34
+ Requires-Dist: ruff (>=0.1) ; extra == "dev" or extra == "all"
35
+ Project-URL: Author, https://vadim.dev
36
+ Project-URL: Changelog, https://github.com/tekkidev/mcpstat/blob/main/CHANGELOG.md
37
+ Project-URL: Homepage, https://github.com/tekkidev/mcpstat
38
+ Project-URL: Issues, https://github.com/tekkidev/mcpstat/issues
39
+ Project-URL: Repository, https://github.com/tekkidev/mcpstat
40
+ Description-Content-Type: text/markdown
41
+
42
+ # mcpstat
43
+
44
+ [![PyPI - Version](https://img.shields.io/pypi/v/mcpstat)](https://pypi.org/project/mcpstat/)
45
+ [![GitHub License](https://img.shields.io/github/license/tekkidev/mcpstat?color=yellow)](https://github.com/tekkidev/mcpstat/blob/main/LICENSE)
46
+ [![PyPI - Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/mcpstat/)
47
+ [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/tekkidev/mcpstat/tests.yaml)](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
48
+ [![PyPI - Downloads](https://img.shields.io/pypi/dm/mcpstat)](https://pypistats.org/packages/mcpstat)
49
+ [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
50
+ [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
51
+ [![Codecov](https://codecov.io/gh/tekkidev/mcpstat/branch/main/graph/badge.svg)](https://codecov.io/gh/tekkidev/mcpstat)
52
+
53
+ **Usage tracking and analytics for MCP servers.** Pure Python, zero required dependencies.
54
+
55
+ Track which tools get called, how often, and keep an audit trail - all in 3 lines of code.
56
+
57
+ ## Installation
58
+
59
+ ```bash
60
+ pip install mcpstat
61
+ ```
62
+
63
+ With MCP SDK:
64
+ ```bash
65
+ pip install "mcpstat[mcp]"
66
+ ```
67
+
68
+ ## Quick Start
69
+
70
+ ```python
71
+ from mcp.server import Server
72
+ from mcpstat import MCPStat
73
+
74
+ app = Server("my-server")
75
+ stat = MCPStat("my-server")
76
+
77
+ @app.call_tool()
78
+ @stat.track # ← One decorator does everything!
79
+ async def handle_tool(name: str, arguments: dict):
80
+ # Your logic here - latency tracked automatically
81
+ return await my_logic(arguments)
82
+ ```
83
+
84
+ Then ask your AI assistant: *"Give me MCP usage stats"*
85
+
86
+ ## Features
87
+
88
+ - **SQLite-backed** - Stats persist across restarts
89
+ - **Built-in MCP tools** - `get_tool_usage_stats`, `get_tool_catalog`
90
+ - **Tag system** - Categorize and filter tools
91
+ - **Token tracking** - Estimate or record actual token usage
92
+ - **Latency tracking** - Measure execution duration, identify slow tools
93
+ - **File logging** - Optional timestamped audit trail
94
+ - **Async-first** - Thread-safe via `asyncio.Lock`
95
+
96
+ ## Documentation
97
+
98
+ **[Full Documentation](https://github.com/tekkidev/mcpstat/tree/main/docs)** - Quick start, API reference, examples
99
+
100
+ - [Quick Start](https://github.com/tekkidev/mcpstat/blob/main/docs/quickstart.md) - Get running in 5 minutes
101
+ - [Configuration](https://github.com/tekkidev/mcpstat/blob/main/docs/configuration.md) - Customize paths, logging, presets
102
+ - [API Reference](https://github.com/tekkidev/mcpstat/blob/main/docs/api.md) - Complete method reference
103
+ - [Token Tracking](https://github.com/tekkidev/mcpstat/blob/main/docs/token-tracking.md) - Cost analysis features
104
+ - [Latency Tracking](https://github.com/tekkidev/mcpstat/blob/main/docs/latency-tracking.md) - Performance monitoring
105
+
106
+ ## Examples
107
+
108
+ ```bash
109
+ # Clone and run example server
110
+ git clone https://github.com/tekkidev/mcpstat.git
111
+ cd mcpstat
112
+ pip install -e ".[mcp]"
113
+ python examples/example_server.py
114
+ ```
115
+
116
+ See [examples/](https://github.com/tekkidev/mcpstat/tree/main/examples/) for minimal and full integration patterns.
117
+
118
+ ## Contributing
119
+
120
+ See [CONTRIBUTING.md](https://github.com/tekkidev/mcpstat/blob/main/CONTRIBUTING.md). Run tests with:
121
+
122
+ ```bash
123
+ pip install "mcpstat[dev]"
124
+ pytest tests/
125
+ ```
126
+
127
+ ## License
128
+
129
+ MIT - see [LICENSE](https://github.com/tekkidev/mcpstat/blob/main/LICENSE) for details.
130
+
131
+ ---
132
+
133
+ *MCP is a trademark of its respective owners. This project is not affiliated with or endorsed by any trademark holders.*
134
+
@@ -0,0 +1,92 @@
1
+ # mcpstat
2
+
3
+ [![PyPI - Version](https://img.shields.io/pypi/v/mcpstat)](https://pypi.org/project/mcpstat/)
4
+ [![GitHub License](https://img.shields.io/github/license/tekkidev/mcpstat?color=yellow)](https://github.com/tekkidev/mcpstat/blob/main/LICENSE)
5
+ [![PyPI - Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/mcpstat/)
6
+ [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/tekkidev/mcpstat/tests.yaml)](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
7
+ [![PyPI - Downloads](https://img.shields.io/pypi/dm/mcpstat)](https://pypistats.org/packages/mcpstat)
8
+ [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
9
+ [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
10
+ [![Codecov](https://codecov.io/gh/tekkidev/mcpstat/branch/main/graph/badge.svg)](https://codecov.io/gh/tekkidev/mcpstat)
11
+
12
+ **Usage tracking and analytics for MCP servers.** Pure Python, zero required dependencies.
13
+
14
+ Track which tools get called, how often, and keep an audit trail - all in 3 lines of code.
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ pip install mcpstat
20
+ ```
21
+
22
+ With MCP SDK:
23
+ ```bash
24
+ pip install "mcpstat[mcp]"
25
+ ```
26
+
27
+ ## Quick Start
28
+
29
+ ```python
30
+ from mcp.server import Server
31
+ from mcpstat import MCPStat
32
+
33
+ app = Server("my-server")
34
+ stat = MCPStat("my-server")
35
+
36
+ @app.call_tool()
37
+ @stat.track # ← One decorator does everything!
38
+ async def handle_tool(name: str, arguments: dict):
39
+ # Your logic here - latency tracked automatically
40
+ return await my_logic(arguments)
41
+ ```
42
+
43
+ Then ask your AI assistant: *"Give me MCP usage stats"*
44
+
45
+ ## Features
46
+
47
+ - **SQLite-backed** - Stats persist across restarts
48
+ - **Built-in MCP tools** - `get_tool_usage_stats`, `get_tool_catalog`
49
+ - **Tag system** - Categorize and filter tools
50
+ - **Token tracking** - Estimate or record actual token usage
51
+ - **Latency tracking** - Measure execution duration, identify slow tools
52
+ - **File logging** - Optional timestamped audit trail
53
+ - **Async-first** - Thread-safe via `asyncio.Lock`
54
+
55
+ ## Documentation
56
+
57
+ **[Full Documentation](https://github.com/tekkidev/mcpstat/tree/main/docs)** - Quick start, API reference, examples
58
+
59
+ - [Quick Start](https://github.com/tekkidev/mcpstat/blob/main/docs/quickstart.md) - Get running in 5 minutes
60
+ - [Configuration](https://github.com/tekkidev/mcpstat/blob/main/docs/configuration.md) - Customize paths, logging, presets
61
+ - [API Reference](https://github.com/tekkidev/mcpstat/blob/main/docs/api.md) - Complete method reference
62
+ - [Token Tracking](https://github.com/tekkidev/mcpstat/blob/main/docs/token-tracking.md) - Cost analysis features
63
+ - [Latency Tracking](https://github.com/tekkidev/mcpstat/blob/main/docs/latency-tracking.md) - Performance monitoring
64
+
65
+ ## Examples
66
+
67
+ ```bash
68
+ # Clone and run example server
69
+ git clone https://github.com/tekkidev/mcpstat.git
70
+ cd mcpstat
71
+ pip install -e ".[mcp]"
72
+ python examples/example_server.py
73
+ ```
74
+
75
+ See [examples/](https://github.com/tekkidev/mcpstat/tree/main/examples/) for minimal and full integration patterns.
76
+
77
+ ## Contributing
78
+
79
+ See [CONTRIBUTING.md](https://github.com/tekkidev/mcpstat/blob/main/CONTRIBUTING.md). Run tests with:
80
+
81
+ ```bash
82
+ pip install "mcpstat[dev]"
83
+ pytest tests/
84
+ ```
85
+
86
+ ## License
87
+
88
+ MIT - see [LICENSE](https://github.com/tekkidev/mcpstat/blob/main/LICENSE) for details.
89
+
90
+ ---
91
+
92
+ *MCP is a trademark of its respective owners. This project is not affiliated with or endorsed by any trademark holders.*