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.
- {mcpstat-0.1.2 → mcpstat-0.2.2}/CHANGELOG.md +53 -1
- mcpstat-0.2.2/PKG-INFO +134 -0
- mcpstat-0.2.2/README.md +92 -0
- mcpstat-0.2.2/docs/api.md +478 -0
- mcpstat-0.2.2/docs/configuration.md +234 -0
- mcpstat-0.2.2/docs/index.md +152 -0
- mcpstat-0.2.2/docs/latency-tracking.md +278 -0
- mcpstat-0.2.2/docs/quickstart.md +209 -0
- mcpstat-0.2.2/docs/token-tracking.md +229 -0
- {mcpstat-0.1.2 → mcpstat-0.2.2}/examples/example_server.py +49 -41
- {mcpstat-0.1.2 → mcpstat-0.2.2}/examples/minimal_server.py +15 -17
- {mcpstat-0.1.2 → mcpstat-0.2.2}/llms.txt +30 -14
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/__init__.py +14 -12
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/core.py +214 -12
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/database.py +238 -28
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/logging.py +2 -2
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/prompts.py +11 -11
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/tools.py +2 -2
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/utils.py +32 -6
- {mcpstat-0.1.2 → mcpstat-0.2.2}/pyproject.toml +35 -4
- mcpstat-0.2.2/tests/conftest.py +52 -0
- mcpstat-0.2.2/tests/test_documentation.py +105 -0
- mcpstat-0.2.2/tests/test_mcpstat.py +1422 -0
- mcpstat-0.1.2/PKG-INFO +0 -654
- mcpstat-0.1.2/README.md +0 -612
- mcpstat-0.1.2/tests/test_mcpstat.py +0 -539
- {mcpstat-0.1.2 → mcpstat-0.2.2}/CODE_OF_CONDUCT.md +0 -0
- {mcpstat-0.1.2 → mcpstat-0.2.2}/LICENSE +0 -0
- {mcpstat-0.1.2 → mcpstat-0.2.2}/mcpstat/py.typed +0 -0
|
@@ -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.
|
|
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
|
+
[](https://pypi.org/project/mcpstat/)
|
|
45
|
+
[](https://github.com/tekkidev/mcpstat/blob/main/LICENSE)
|
|
46
|
+
[](https://pypi.org/project/mcpstat/)
|
|
47
|
+
[](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
|
|
48
|
+
[](https://pypistats.org/packages/mcpstat)
|
|
49
|
+
[](http://mypy-lang.org/)
|
|
50
|
+
[](https://github.com/PyCQA/bandit)
|
|
51
|
+
[](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
|
+
|
mcpstat-0.2.2/README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# mcpstat
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/mcpstat/)
|
|
4
|
+
[](https://github.com/tekkidev/mcpstat/blob/main/LICENSE)
|
|
5
|
+
[](https://pypi.org/project/mcpstat/)
|
|
6
|
+
[](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
|
|
7
|
+
[](https://pypistats.org/packages/mcpstat)
|
|
8
|
+
[](http://mypy-lang.org/)
|
|
9
|
+
[](https://github.com/PyCQA/bandit)
|
|
10
|
+
[](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.*
|