mcpstat 0.2.1__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.2.1 → mcpstat-0.2.2}/CHANGELOG.md +30 -1
- {mcpstat-0.2.1 → mcpstat-0.2.2}/PKG-INFO +9 -4
- {mcpstat-0.2.1 → mcpstat-0.2.2}/README.md +7 -2
- {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/api.md +154 -25
- {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/configuration.md +23 -6
- {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/index.md +49 -11
- mcpstat-0.2.2/docs/latency-tracking.md +278 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/quickstart.md +56 -14
- {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/token-tracking.md +2 -1
- {mcpstat-0.2.1 → mcpstat-0.2.2}/examples/example_server.py +45 -39
- {mcpstat-0.2.1 → mcpstat-0.2.2}/examples/minimal_server.py +4 -6
- {mcpstat-0.2.1 → mcpstat-0.2.2}/llms.txt +29 -13
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/__init__.py +6 -4
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/core.py +143 -4
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/database.py +72 -6
- {mcpstat-0.2.1 → mcpstat-0.2.2}/pyproject.toml +2 -1
- {mcpstat-0.2.1 → mcpstat-0.2.2}/tests/test_documentation.py +5 -1
- {mcpstat-0.2.1 → mcpstat-0.2.2}/tests/test_mcpstat.py +526 -4
- {mcpstat-0.2.1 → mcpstat-0.2.2}/CODE_OF_CONDUCT.md +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/LICENSE +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/logging.py +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/prompts.py +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/py.typed +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/tools.py +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/utils.py +0 -0
- {mcpstat-0.2.1 → mcpstat-0.2.2}/tests/conftest.py +0 -0
|
@@ -7,6 +7,34 @@ 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
|
+
|
|
10
38
|
## [0.2.1] - 2026-02-01
|
|
11
39
|
|
|
12
40
|
### Added
|
|
@@ -73,7 +101,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
73
101
|
- Full type annotations with strict mypy compliance (`py.typed` marker included)
|
|
74
102
|
- Comprehensive test suite
|
|
75
103
|
|
|
76
|
-
[Unreleased]: https://github.com/tekkidev/mcpstat/compare/v0.2.
|
|
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
|
|
77
106
|
[0.2.1]: https://github.com/tekkidev/mcpstat/compare/v0.1.2...v0.2.1
|
|
78
107
|
[0.1.2]: https://github.com/tekkidev/mcpstat/compare/v0.1.1...v0.1.2
|
|
79
108
|
[0.1.1]: https://github.com/tekkidev/mcpstat/compare/v0.1.0...v0.1.1
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mcpstat
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: Usage tracking, analytics, and file logging for MCP (Model Context Protocol) servers
|
|
5
5
|
License: MIT
|
|
6
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
|
|
7
|
+
Keywords: mcp,model-context-protocol,statistics,analytics,usage-tracking,logging,ai,llm,agent,mcp-server,tool-tracking,observability,token-tracking,latency-tracking
|
|
8
8
|
Author: Vadim Bakhrenkov
|
|
9
9
|
Author-email: hello@vadim.dev
|
|
10
10
|
Requires-Python: >=3.10,<4.0
|
|
@@ -46,6 +46,8 @@ Description-Content-Type: text/markdown
|
|
|
46
46
|
[](https://pypi.org/project/mcpstat/)
|
|
47
47
|
[](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
|
|
48
48
|
[](https://pypistats.org/packages/mcpstat)
|
|
49
|
+
[](http://mypy-lang.org/)
|
|
50
|
+
[](https://github.com/PyCQA/bandit)
|
|
49
51
|
[](https://codecov.io/gh/tekkidev/mcpstat)
|
|
50
52
|
|
|
51
53
|
**Usage tracking and analytics for MCP servers.** Pure Python, zero required dependencies.
|
|
@@ -73,9 +75,10 @@ app = Server("my-server")
|
|
|
73
75
|
stat = MCPStat("my-server")
|
|
74
76
|
|
|
75
77
|
@app.call_tool()
|
|
78
|
+
@stat.track # ← One decorator does everything!
|
|
76
79
|
async def handle_tool(name: str, arguments: dict):
|
|
77
|
-
|
|
78
|
-
|
|
80
|
+
# Your logic here - latency tracked automatically
|
|
81
|
+
return await my_logic(arguments)
|
|
79
82
|
```
|
|
80
83
|
|
|
81
84
|
Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
@@ -86,6 +89,7 @@ Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
|
86
89
|
- **Built-in MCP tools** - `get_tool_usage_stats`, `get_tool_catalog`
|
|
87
90
|
- **Tag system** - Categorize and filter tools
|
|
88
91
|
- **Token tracking** - Estimate or record actual token usage
|
|
92
|
+
- **Latency tracking** - Measure execution duration, identify slow tools
|
|
89
93
|
- **File logging** - Optional timestamped audit trail
|
|
90
94
|
- **Async-first** - Thread-safe via `asyncio.Lock`
|
|
91
95
|
|
|
@@ -97,6 +101,7 @@ Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
|
97
101
|
- [Configuration](https://github.com/tekkidev/mcpstat/blob/main/docs/configuration.md) - Customize paths, logging, presets
|
|
98
102
|
- [API Reference](https://github.com/tekkidev/mcpstat/blob/main/docs/api.md) - Complete method reference
|
|
99
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
|
|
100
105
|
|
|
101
106
|
## Examples
|
|
102
107
|
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
[](https://pypi.org/project/mcpstat/)
|
|
6
6
|
[](https://github.com/tekkidev/mcpstat/actions/workflows/tests.yaml)
|
|
7
7
|
[](https://pypistats.org/packages/mcpstat)
|
|
8
|
+
[](http://mypy-lang.org/)
|
|
9
|
+
[](https://github.com/PyCQA/bandit)
|
|
8
10
|
[](https://codecov.io/gh/tekkidev/mcpstat)
|
|
9
11
|
|
|
10
12
|
**Usage tracking and analytics for MCP servers.** Pure Python, zero required dependencies.
|
|
@@ -32,9 +34,10 @@ app = Server("my-server")
|
|
|
32
34
|
stat = MCPStat("my-server")
|
|
33
35
|
|
|
34
36
|
@app.call_tool()
|
|
37
|
+
@stat.track # ← One decorator does everything!
|
|
35
38
|
async def handle_tool(name: str, arguments: dict):
|
|
36
|
-
|
|
37
|
-
|
|
39
|
+
# Your logic here - latency tracked automatically
|
|
40
|
+
return await my_logic(arguments)
|
|
38
41
|
```
|
|
39
42
|
|
|
40
43
|
Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
@@ -45,6 +48,7 @@ Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
|
45
48
|
- **Built-in MCP tools** - `get_tool_usage_stats`, `get_tool_catalog`
|
|
46
49
|
- **Tag system** - Categorize and filter tools
|
|
47
50
|
- **Token tracking** - Estimate or record actual token usage
|
|
51
|
+
- **Latency tracking** - Measure execution duration, identify slow tools
|
|
48
52
|
- **File logging** - Optional timestamped audit trail
|
|
49
53
|
- **Async-first** - Thread-safe via `asyncio.Lock`
|
|
50
54
|
|
|
@@ -56,6 +60,7 @@ Then ask your AI assistant: *"Give me MCP usage stats"*
|
|
|
56
60
|
- [Configuration](https://github.com/tekkidev/mcpstat/blob/main/docs/configuration.md) - Customize paths, logging, presets
|
|
57
61
|
- [API Reference](https://github.com/tekkidev/mcpstat/blob/main/docs/api.md) - Complete method reference
|
|
58
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
|
|
59
64
|
|
|
60
65
|
## Examples
|
|
61
66
|
|
|
@@ -15,10 +15,12 @@ from mcpstat import MCPStat
|
|
|
15
15
|
|
|
16
16
|
stat = MCPStat(
|
|
17
17
|
server_name: str,
|
|
18
|
+
*,
|
|
18
19
|
db_path: str | None = None,
|
|
19
20
|
log_path: str | None = None,
|
|
20
|
-
log_enabled: bool =
|
|
21
|
+
log_enabled: bool | None = None,
|
|
21
22
|
metadata_presets: dict[str, dict] | None = None,
|
|
23
|
+
cleanup_orphans: bool = True,
|
|
22
24
|
)
|
|
23
25
|
```
|
|
24
26
|
|
|
@@ -29,14 +31,57 @@ stat = MCPStat(
|
|
|
29
31
|
| `log_path` | `str` | `./mcp_stat.log` | File log path |
|
|
30
32
|
| `log_enabled` | `bool` | `False` | Enable file logging |
|
|
31
33
|
| `metadata_presets` | `dict` | `None` | Pre-defined metadata |
|
|
34
|
+
| `cleanup_orphans` | `bool` | `True` | Remove metadata for unregistered tools on sync |
|
|
32
35
|
|
|
33
36
|
---
|
|
34
37
|
|
|
35
38
|
## Core Methods
|
|
36
39
|
|
|
40
|
+
### @stat.track (Recommended)
|
|
41
|
+
|
|
42
|
+
Decorator that automatically tracks tool calls with latency measurement.
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
@app.call_tool()
|
|
46
|
+
@stat.track # ← One decorator does everything!
|
|
47
|
+
async def handle_tool(name: str, arguments: dict):
|
|
48
|
+
return await my_logic(arguments)
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Features:**
|
|
52
|
+
|
|
53
|
+
- Automatically measures execution time
|
|
54
|
+
- Records call count
|
|
55
|
+
- Tracks success/failure
|
|
56
|
+
- Never fails user code (errors suppressed)
|
|
57
|
+
- Works with exceptions (still records the call)
|
|
58
|
+
|
|
59
|
+
**With explicit type:**
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
@stat.track(primitive_type="prompt")
|
|
63
|
+
async def handle_prompt(name: str, arguments: dict):
|
|
64
|
+
return await generate_prompt(arguments)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
### stat.tracking() Context Manager
|
|
70
|
+
|
|
71
|
+
For cases where you need more control than a decorator:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
async def handle_tool(name: str, arguments: dict):
|
|
75
|
+
async with stat.tracking(name, "tool"):
|
|
76
|
+
result = await my_logic(arguments)
|
|
77
|
+
return result
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
37
82
|
### record()
|
|
38
83
|
|
|
39
|
-
|
|
84
|
+
Low-level method for manual recording. Use `@stat.track` instead when possible.
|
|
40
85
|
|
|
41
86
|
```python
|
|
42
87
|
await stat.record(
|
|
@@ -48,6 +93,7 @@ await stat.record(
|
|
|
48
93
|
response_chars: int | None = None,
|
|
49
94
|
input_tokens: int | None = None,
|
|
50
95
|
output_tokens: int | None = None,
|
|
96
|
+
duration_ms: int | None = None,
|
|
51
97
|
)
|
|
52
98
|
```
|
|
53
99
|
|
|
@@ -60,18 +106,10 @@ await stat.record(
|
|
|
60
106
|
| `response_chars` | `int` | Response size for token estimation |
|
|
61
107
|
| `input_tokens` | `int` | Actual input token count |
|
|
62
108
|
| `output_tokens` | `int` | Actual output token count |
|
|
109
|
+
| `duration_ms` | `int` | Execution duration in milliseconds |
|
|
63
110
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
**Example:**
|
|
67
|
-
|
|
68
|
-
```python
|
|
69
|
-
@app.call_tool()
|
|
70
|
-
async def handle_tool(name: str, arguments: dict):
|
|
71
|
-
await stat.record(name, "tool") # FIRST LINE
|
|
72
|
-
result = await my_logic(arguments)
|
|
73
|
-
return result
|
|
74
|
-
```
|
|
111
|
+
!!! note "When to use record()"
|
|
112
|
+
Use `record()` directly only when you need to pass additional data like `response_chars` or `input_tokens`. For basic tracking with automatic latency, use `@stat.track` (decorator) or `stat.tracking()` (context manager) instead.
|
|
75
113
|
|
|
76
114
|
---
|
|
77
115
|
|
|
@@ -108,6 +146,10 @@ stats = await stat.get_stats(
|
|
|
108
146
|
"total_estimated_tokens": int,
|
|
109
147
|
"has_actual_tokens": bool,
|
|
110
148
|
},
|
|
149
|
+
"latency_summary": {
|
|
150
|
+
"total_duration_ms": int,
|
|
151
|
+
"has_latency_data": bool,
|
|
152
|
+
},
|
|
111
153
|
"stats": [
|
|
112
154
|
{
|
|
113
155
|
"name": str,
|
|
@@ -116,10 +158,16 @@ stats = await stat.get_stats(
|
|
|
116
158
|
"last_accessed": str | None,
|
|
117
159
|
"tags": list[str],
|
|
118
160
|
"short_description": str | None,
|
|
161
|
+
"full_description": str | None,
|
|
119
162
|
"total_input_tokens": int,
|
|
120
163
|
"total_output_tokens": int,
|
|
164
|
+
"total_response_chars": int,
|
|
121
165
|
"estimated_tokens": int,
|
|
122
166
|
"avg_tokens_per_call": int,
|
|
167
|
+
"total_duration_ms": int,
|
|
168
|
+
"min_duration_ms": int | None,
|
|
169
|
+
"max_duration_ms": int | None,
|
|
170
|
+
"avg_latency_ms": int,
|
|
123
171
|
}
|
|
124
172
|
]
|
|
125
173
|
}
|
|
@@ -148,7 +196,8 @@ catalog = await stat.get_catalog(
|
|
|
148
196
|
| `include_usage` | `bool` | Include call counts |
|
|
149
197
|
| `limit` | `int` | Maximum results |
|
|
150
198
|
|
|
151
|
-
|
|
199
|
+
!!! info "AND Logic"
|
|
200
|
+
Tag filtering uses AND logic - tools must have **all** specified tags.
|
|
152
201
|
|
|
153
202
|
**Returns:**
|
|
154
203
|
|
|
@@ -161,12 +210,18 @@ catalog = await stat.get_catalog(
|
|
|
161
210
|
"tags": list[str],
|
|
162
211
|
"query": str | None,
|
|
163
212
|
},
|
|
213
|
+
"include_usage": bool,
|
|
214
|
+
"limit": int | None,
|
|
215
|
+
"total_calls": int | None, # None when include_usage=False
|
|
164
216
|
"results": [
|
|
165
217
|
{
|
|
166
218
|
"name": str,
|
|
167
219
|
"tags": list[str],
|
|
168
220
|
"short_description": str | None,
|
|
169
|
-
"
|
|
221
|
+
"full_description": str | None,
|
|
222
|
+
"schema_version": int,
|
|
223
|
+
"updated_at": str,
|
|
224
|
+
"call_count": int | None, # None when include_usage=False
|
|
170
225
|
"last_accessed": str | None,
|
|
171
226
|
}
|
|
172
227
|
]
|
|
@@ -227,33 +282,86 @@ await stat.sync_tools(tools)
|
|
|
227
282
|
|
|
228
283
|
### register_metadata()
|
|
229
284
|
|
|
230
|
-
Manually register metadata for a
|
|
285
|
+
Manually register metadata for a primitive.
|
|
231
286
|
|
|
232
287
|
```python
|
|
233
288
|
await stat.register_metadata(
|
|
234
289
|
name: str,
|
|
235
|
-
|
|
236
|
-
|
|
290
|
+
*,
|
|
291
|
+
tags: list[str],
|
|
292
|
+
short_description: str,
|
|
237
293
|
full_description: str | None = None,
|
|
238
294
|
)
|
|
239
295
|
```
|
|
240
296
|
|
|
241
297
|
---
|
|
242
298
|
|
|
299
|
+
### sync_prompts()
|
|
300
|
+
|
|
301
|
+
Sync metadata from MCP Prompt objects.
|
|
302
|
+
|
|
303
|
+
```python
|
|
304
|
+
await stat.sync_prompts(prompts: list[Prompt])
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
### sync_resources()
|
|
310
|
+
|
|
311
|
+
Sync metadata from MCP Resource objects.
|
|
312
|
+
|
|
313
|
+
```python
|
|
314
|
+
await stat.sync_resources(resources: list[Resource])
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
### add_preset()
|
|
320
|
+
|
|
321
|
+
Add a metadata preset for future sync operations.
|
|
322
|
+
|
|
323
|
+
```python
|
|
324
|
+
stat.add_preset(
|
|
325
|
+
name: str,
|
|
326
|
+
*,
|
|
327
|
+
tags: list[str],
|
|
328
|
+
short: str,
|
|
329
|
+
)
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
243
334
|
### get_by_type()
|
|
244
335
|
|
|
245
|
-
Get
|
|
336
|
+
Get usage statistics grouped by MCP primitive type.
|
|
246
337
|
|
|
247
338
|
```python
|
|
248
|
-
|
|
249
|
-
|
|
339
|
+
data = await stat.get_by_type()
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
**Returns:**
|
|
343
|
+
|
|
344
|
+
```python
|
|
345
|
+
{
|
|
346
|
+
"by_type": {
|
|
347
|
+
"tool": [{"name": str, "type": str, "call_count": int, "last_accessed": str}],
|
|
348
|
+
"prompt": [...],
|
|
349
|
+
"resource": [...],
|
|
350
|
+
},
|
|
351
|
+
"summary": {
|
|
352
|
+
"tool": {"count": int, "total_calls": int},
|
|
353
|
+
...
|
|
354
|
+
},
|
|
355
|
+
"total_calls": int,
|
|
356
|
+
"total_items": int,
|
|
357
|
+
}
|
|
250
358
|
```
|
|
251
359
|
|
|
252
360
|
---
|
|
253
361
|
|
|
254
362
|
### close()
|
|
255
363
|
|
|
256
|
-
|
|
364
|
+
Release resources. Call during server shutdown for clean resource release.
|
|
257
365
|
|
|
258
366
|
```python
|
|
259
367
|
stat.close()
|
|
@@ -272,7 +380,7 @@ from mcpstat import build_tool_definitions
|
|
|
272
380
|
|
|
273
381
|
tools = build_tool_definitions(
|
|
274
382
|
prefix: str = "get",
|
|
275
|
-
server_name: str
|
|
383
|
+
server_name: str = "MCP server",
|
|
276
384
|
)
|
|
277
385
|
```
|
|
278
386
|
|
|
@@ -315,7 +423,10 @@ Generate MCP prompt schema for stats prompt.
|
|
|
315
423
|
```python
|
|
316
424
|
from mcpstat import build_prompt_definition
|
|
317
425
|
|
|
318
|
-
prompt = build_prompt_definition(
|
|
426
|
+
prompt = build_prompt_definition(
|
|
427
|
+
prompt_name: str,
|
|
428
|
+
server_name: str = "MCP server",
|
|
429
|
+
)
|
|
319
430
|
```
|
|
320
431
|
|
|
321
432
|
---
|
|
@@ -327,7 +438,25 @@ Generate prompt content with current stats.
|
|
|
327
438
|
```python
|
|
328
439
|
from mcpstat import generate_stats_prompt
|
|
329
440
|
|
|
330
|
-
content = await generate_stats_prompt(
|
|
441
|
+
content = await generate_stats_prompt(
|
|
442
|
+
stat,
|
|
443
|
+
*,
|
|
444
|
+
period: str = "all time",
|
|
445
|
+
type_filter: str = "all",
|
|
446
|
+
include_recommendations: bool = True,
|
|
447
|
+
)
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
452
|
+
### handle_stats_prompt()
|
|
453
|
+
|
|
454
|
+
Handle stats prompt request from MCP client.
|
|
455
|
+
|
|
456
|
+
```python
|
|
457
|
+
from mcpstat.prompts import handle_stats_prompt
|
|
458
|
+
|
|
459
|
+
result = await handle_stats_prompt(stat, arguments={"period": "past week"})
|
|
331
460
|
```
|
|
332
461
|
|
|
333
462
|
---
|
|
@@ -33,7 +33,8 @@ stat = MCPStat(
|
|
|
33
33
|
| `db_path` | `str` | `./mcp_stat_data.sqlite` | Path to SQLite database |
|
|
34
34
|
| `log_path` | `str` | `./mcp_stat.log` | Path to file log |
|
|
35
35
|
| `log_enabled` | `bool` | `False` | Enable timestamped file logging |
|
|
36
|
-
| `metadata_presets` | `dict` | `
|
|
36
|
+
| `metadata_presets` | `dict` | `None` | Pre-defined metadata for tools |
|
|
37
|
+
| `cleanup_orphans` | `bool` | `True` | Remove metadata for unregistered tools on sync |
|
|
37
38
|
|
|
38
39
|
---
|
|
39
40
|
|
|
@@ -81,7 +82,6 @@ stat = MCPStat(
|
|
|
81
82
|
|-------|------|-------------|
|
|
82
83
|
| `tags` | `list[str]` | Categories for filtering |
|
|
83
84
|
| `short` | `str` | Brief description (one line) |
|
|
84
|
-
| `full` | `str` | Extended description (optional) |
|
|
85
85
|
|
|
86
86
|
---
|
|
87
87
|
|
|
@@ -101,7 +101,7 @@ Auto-extraction rules:
|
|
|
101
101
|
- Normalized to lowercase
|
|
102
102
|
- Stopwords filtered (`the`, `to`, `from`, `and`, etc.)
|
|
103
103
|
|
|
104
|
-
Example: `fetch_weather_data` → `["fetch", "weather", "data"]`
|
|
104
|
+
Example: `fetch_weather_data` → `["fetch_weather_data", "fetch", "weather", "data"]`
|
|
105
105
|
|
|
106
106
|
---
|
|
107
107
|
|
|
@@ -149,9 +149,14 @@ mcpstat uses SQLite with two tables:
|
|
|
149
149
|
| `type` | TEXT | `tool`, `prompt`, or `resource` |
|
|
150
150
|
| `call_count` | INTEGER | Total invocations |
|
|
151
151
|
| `last_accessed` | TEXT | ISO 8601 timestamp |
|
|
152
|
+
| `created_at` | TEXT | ISO 8601 creation timestamp |
|
|
152
153
|
| `total_input_tokens` | INTEGER | Cumulative input tokens |
|
|
153
154
|
| `total_output_tokens` | INTEGER | Cumulative output tokens |
|
|
155
|
+
| `total_response_chars` | INTEGER | Cumulative response characters |
|
|
154
156
|
| `estimated_tokens` | INTEGER | Estimated from response size |
|
|
157
|
+
| `total_duration_ms` | INTEGER | Cumulative execution time |
|
|
158
|
+
| `min_duration_ms` | INTEGER | Minimum recorded duration (nullable) |
|
|
159
|
+
| `max_duration_ms` | INTEGER | Maximum recorded duration (nullable) |
|
|
155
160
|
|
|
156
161
|
### `mcpstat_metadata`
|
|
157
162
|
|
|
@@ -161,6 +166,8 @@ mcpstat uses SQLite with two tables:
|
|
|
161
166
|
| `tags` | TEXT | Comma-separated tags |
|
|
162
167
|
| `short_description` | TEXT | Brief description |
|
|
163
168
|
| `full_description` | TEXT | Extended description |
|
|
169
|
+
| `schema_version` | INTEGER | Schema version number |
|
|
170
|
+
| `updated_at` | TEXT | ISO 8601 last update timestamp |
|
|
164
171
|
|
|
165
172
|
---
|
|
166
173
|
|
|
@@ -185,12 +192,22 @@ async def handle_tool(name, args):
|
|
|
185
192
|
await stat.record(name, "tool")
|
|
186
193
|
```
|
|
187
194
|
|
|
188
|
-
### 2.
|
|
195
|
+
### 2. Use @stat.track Decorator (Recommended)
|
|
189
196
|
|
|
190
|
-
|
|
197
|
+
The `@stat.track` decorator is the simplest and most reliable tracking method:
|
|
191
198
|
|
|
192
199
|
```python
|
|
193
|
-
# ✅
|
|
200
|
+
# ✅ Recommended - automatic latency tracking, never misses a call
|
|
201
|
+
@app.call_tool()
|
|
202
|
+
@stat.track
|
|
203
|
+
async def handle_tool(name: str, arguments: dict):
|
|
204
|
+
return await my_logic(arguments)
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
For manual tracking with `record()`, place it as the FIRST line:
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
# ✅ Correct for manual tracking
|
|
194
211
|
async def handle_tool(name, args):
|
|
195
212
|
await stat.record(name, "tool")
|
|
196
213
|
result = do_something(args)
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
**mcpstat** adds usage tracking and analytics to your [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers. Pure Python stdlib, no required dependencies.
|
|
8
8
|
|
|
9
|
-
Track which tools get called, how often, and keep an audit trail - all in
|
|
9
|
+
Track which tools get called, how often, and keep an audit trail - all in 3 lines of code. Then ask your AI assistant: *"Give me MCP usage stats."*
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
@@ -32,6 +32,7 @@ Without tracking, agents may pull irrelevant resources into context - leading to
|
|
|
32
32
|
- **Built-in tools & prompts** - Expose stats directly to LLM clients
|
|
33
33
|
- **Metadata enrichment** - Tag and describe tools for discoverability
|
|
34
34
|
- **Token tracking** - Estimate or record actual token usage
|
|
35
|
+
- **Latency tracking** - Measure execution time, identify slow tools
|
|
35
36
|
- **Async-first** - Thread-safe via `asyncio.Lock`
|
|
36
37
|
|
|
37
38
|
---
|
|
@@ -57,15 +58,15 @@ from mcp.server import Server
|
|
|
57
58
|
from mcpstat import MCPStat
|
|
58
59
|
|
|
59
60
|
app = Server("my-server")
|
|
60
|
-
stat = MCPStat("my-server")
|
|
61
|
+
stat = MCPStat("my-server")
|
|
61
62
|
|
|
62
63
|
@app.call_tool()
|
|
64
|
+
@stat.track # ← One decorator does everything!
|
|
63
65
|
async def handle_tool(name: str, arguments: dict):
|
|
64
|
-
await
|
|
65
|
-
# ... your tool logic
|
|
66
|
+
return await my_logic(arguments) # Latency tracked automatically
|
|
66
67
|
```
|
|
67
68
|
|
|
68
|
-
One
|
|
69
|
+
One decorator - `@stat.track` - and you get full tracking with automatic latency measurement.
|
|
69
70
|
|
|
70
71
|
---
|
|
71
72
|
|
|
@@ -92,12 +93,49 @@ The AI invokes `get_tool_usage_stats` or `get_tool_catalog` as needed.
|
|
|
92
93
|
|
|
93
94
|
## Documentation
|
|
94
95
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
96
|
+
<div class="grid cards" markdown>
|
|
97
|
+
|
|
98
|
+
- :material-rocket-launch:{ .lg .middle } **Getting Started**
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
Install mcpstat and add tracking to your first MCP server in minutes.
|
|
103
|
+
|
|
104
|
+
[:octicons-arrow-right-24: Quick Start](quickstart.md)
|
|
105
|
+
|
|
106
|
+
- :material-cog:{ .lg .middle } **Configuration**
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
Configure paths, logging, metadata presets, and environment variables.
|
|
111
|
+
|
|
112
|
+
[:octicons-arrow-right-24: Configuration](configuration.md)
|
|
113
|
+
|
|
114
|
+
- :material-api:{ .lg .middle } **Core API**
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
Complete reference for `MCPStat`, built-in tools, and handlers.
|
|
119
|
+
|
|
120
|
+
[:octicons-arrow-right-24: API Reference](api.md)
|
|
121
|
+
|
|
122
|
+
- :material-chart-line:{ .lg .middle } **Token Tracking**
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
Track response sizes and estimate token usage for cost analysis.
|
|
127
|
+
|
|
128
|
+
[:octicons-arrow-right-24: Token Tracking](token-tracking.md)
|
|
129
|
+
|
|
130
|
+
- :material-timer-outline:{ .lg .middle } **Latency Tracking**
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
Measure tool execution time to identify slow tools and monitor performance.
|
|
135
|
+
|
|
136
|
+
[:octicons-arrow-right-24: Latency Tracking](latency-tracking.md)
|
|
137
|
+
|
|
138
|
+
</div>
|
|
101
139
|
|
|
102
140
|
---
|
|
103
141
|
|