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.
Files changed (26) hide show
  1. {mcpstat-0.2.1 → mcpstat-0.2.2}/CHANGELOG.md +30 -1
  2. {mcpstat-0.2.1 → mcpstat-0.2.2}/PKG-INFO +9 -4
  3. {mcpstat-0.2.1 → mcpstat-0.2.2}/README.md +7 -2
  4. {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/api.md +154 -25
  5. {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/configuration.md +23 -6
  6. {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/index.md +49 -11
  7. mcpstat-0.2.2/docs/latency-tracking.md +278 -0
  8. {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/quickstart.md +56 -14
  9. {mcpstat-0.2.1 → mcpstat-0.2.2}/docs/token-tracking.md +2 -1
  10. {mcpstat-0.2.1 → mcpstat-0.2.2}/examples/example_server.py +45 -39
  11. {mcpstat-0.2.1 → mcpstat-0.2.2}/examples/minimal_server.py +4 -6
  12. {mcpstat-0.2.1 → mcpstat-0.2.2}/llms.txt +29 -13
  13. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/__init__.py +6 -4
  14. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/core.py +143 -4
  15. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/database.py +72 -6
  16. {mcpstat-0.2.1 → mcpstat-0.2.2}/pyproject.toml +2 -1
  17. {mcpstat-0.2.1 → mcpstat-0.2.2}/tests/test_documentation.py +5 -1
  18. {mcpstat-0.2.1 → mcpstat-0.2.2}/tests/test_mcpstat.py +526 -4
  19. {mcpstat-0.2.1 → mcpstat-0.2.2}/CODE_OF_CONDUCT.md +0 -0
  20. {mcpstat-0.2.1 → mcpstat-0.2.2}/LICENSE +0 -0
  21. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/logging.py +0 -0
  22. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/prompts.py +0 -0
  23. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/py.typed +0 -0
  24. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/tools.py +0 -0
  25. {mcpstat-0.2.1 → mcpstat-0.2.2}/mcpstat/utils.py +0 -0
  26. {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.1...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
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.1
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
  [![PyPI - Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/mcpstat/)
47
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
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)
49
51
  [![Codecov](https://codecov.io/gh/tekkidev/mcpstat/branch/main/graph/badge.svg)](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
- await stat.record(name, "tool") # ← Add as FIRST line
78
- # ... your tool logic
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
  [![PyPI - Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/mcpstat/)
6
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
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)
8
10
  [![Codecov](https://codecov.io/gh/tekkidev/mcpstat/branch/main/graph/badge.svg)](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
- await stat.record(name, "tool") # ← Add as FIRST line
37
- # ... your tool logic
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 = False,
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
- Record a tool, prompt, or resource invocation.
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
- > **Critical**: Always call `record()` as the **FIRST line** in your handlers to guarantee 100% tracking coverage.
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
- > **AND Logic**: Tag filtering uses AND logic - tools must have **all** specified tags.
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
- "call_count": int,
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 tool.
285
+ Manually register metadata for a primitive.
231
286
 
232
287
  ```python
233
288
  await stat.register_metadata(
234
289
  name: str,
235
- tags: list[str] | None = None,
236
- short_description: str | None = None,
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 call counts grouped by type.
336
+ Get usage statistics grouped by MCP primitive type.
246
337
 
247
338
  ```python
248
- counts = await stat.get_by_type()
249
- # {"tool": 15, "prompt": 3, "resource": 2}
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
- Explicit cleanup (usually automatic).
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 | None = None,
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(server_name="my-server")
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(stat, server_name="my-server")
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` | `{}` | Pre-defined metadata for tools |
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. Record First
195
+ ### 2. Use @stat.track Decorator (Recommended)
189
196
 
190
- Always place `stat.record()` as the FIRST line:
197
+ The `@stat.track` decorator is the simplest and most reliable tracking method:
191
198
 
192
199
  ```python
193
- # ✅ Correct - always tracked
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 about three lines of code. Then ask your AI assistant: *"Give me MCP usage stats."*
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") # Initialize
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 stat.record(name, "tool") # Track as FIRST line
65
- # ... your tool logic
66
+ return await my_logic(arguments) # Latency tracked automatically
66
67
  ```
67
68
 
68
- One line - `await stat.record(name, "tool")` - and you're tracking.
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
- | Guide | Description |
96
- |-------|-------------|
97
- | [Quick Start](quickstart.md) | Install mcpstat and add tracking to your first MCP server in minutes. |
98
- | [Configuration](configuration.md) | Configure paths, logging, metadata presets, and environment variables. |
99
- | [API Reference](api.md) | Complete reference for `MCPStat`, built-in tools, and handlers. |
100
- | [Token Tracking](token-tracking.md) | Track response sizes and estimate token usage for cost analysis. |
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