dsh-project-mcp 0.2.0

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.
@@ -0,0 +1,190 @@
1
+ /**
2
+ * The host's own usage counters, read where a surface shows them.
3
+ *
4
+ * Nothing here is measured, sampled or invented: `ProjectSnapshot.usage`
5
+ * (`src/types.ts:425`) is published by the host half from the tool registry's
6
+ * own events, keyed by server name, and these two readings are the whole of it
7
+ * — how often a tool was called, and how long a server has not been used. A
8
+ * surface that has no record draws no text (the plugin's "no data, no label"
9
+ * rule), which is why both functions answer `undefined` rather than `0` when
10
+ * the host said nothing: an invented zero reads as a fact the host never
11
+ * published.
12
+ *
13
+ * Pure and React-free, so the sidebar tab, the settings page and the pin picker
14
+ * share one reading of the same numbers.
15
+ *
16
+ * @module dsh-project-mcp/client/usage-view
17
+ */
18
+
19
+ import type { ServerUsage } from '../types.ts'
20
+
21
+ /**
22
+ * The prefix the registry publishes project MCP tools under.
23
+ *
24
+ * Five characters, underscores included: a name is `mcp__<server>__<tool>`, so
25
+ * the server starts after the prefix, not after `mcp`. The vocabulary lives here
26
+ * rather than in `view.ts` because this module reads the same names and must not
27
+ * import the panel back — a cycle between the panel and its counter reader would
28
+ * make the counter's own module graph depend on the surface that draws it.
29
+ * `view.ts` re-exports both names, so every existing caller keeps its import.
30
+ */
31
+ export const MCP_TOOL_PREFIX = 'mcp__'
32
+
33
+ /** The `__` that closes the server segment of a registry name, and opens the tool's. */
34
+ const SEPARATOR = '__'
35
+
36
+ /**
37
+ * The server part of a registry tool name.
38
+ * @param name - a public registry name, e.g. `mcp__tglider__workspace`.
39
+ * @returns the server name, or undefined when the name is not an MCP one.
40
+ */
41
+ export function serverOfToolName(name: string): string | undefined {
42
+ if (!name.startsWith(MCP_TOOL_PREFIX)) return undefined
43
+ const separator = name.indexOf(SEPARATOR, MCP_TOOL_PREFIX.length)
44
+ return separator === -1 ? undefined : name.slice(MCP_TOOL_PREFIX.length, separator)
45
+ }
46
+
47
+ /** One project's counters, as the host published them; `undefined` — the host said nothing. */
48
+ export type ProjectUsage = Record<string, ServerUsage> | undefined
49
+
50
+ /**
51
+ * How often one tool was called, by its public registry name.
52
+ *
53
+ * The name is `mcp__<server>__<tool>` (see `serverOfToolName`), and the counter
54
+ * is keyed by the tool name as the server declared it — everything after the
55
+ * second separator, which is why the split is not `name.split('__')`.
56
+ * @param name - a public registry name, e.g. `mcp__tglider__workspace`.
57
+ * @param usage - the project's counters, when the host published any.
58
+ * @returns the call count, or undefined when the host recorded nothing for it.
59
+ */
60
+ export function callsOfToolName(name: string, usage: ProjectUsage): number | undefined {
61
+ const split = splitToolName(name)
62
+ if (split === undefined) return undefined
63
+ return usage?.[split.server]?.tools[split.tool]
64
+ }
65
+
66
+ /**
67
+ * Both readings one tool row may print: the project's counter and this session's.
68
+ *
69
+ * A server is mounted for a project and shared by its sessions, so the two
70
+ * numbers answer different questions and differ exactly when another session of
71
+ * the project called the tool (F-34). `recorded` is the host's mere existence of
72
+ * a record for the name's server, which is what separates "never called" from
73
+ * "not counted at all".
74
+ */
75
+ export interface ToolCalls {
76
+ /** `true` when the host published a record for this name's server. */
77
+ recorded: boolean
78
+ /**
79
+ * `true` when the host published this session's own slice of that record.
80
+ *
81
+ * It is the difference between "the host does not split by session yet" and
82
+ * "this session is counted and has never called this tool" — two states whose
83
+ * `session` reading is both `undefined`, and which a row must not print the
84
+ * same way.
85
+ */
86
+ split: boolean
87
+ /** Calls the project counted for this tool, when it counted any. */
88
+ project: number | undefined
89
+ /** Calls this session counted for this tool, when it counted any. */
90
+ session: number | undefined
91
+ }
92
+
93
+ /**
94
+ * Read both counters of one tool, by its public registry name.
95
+ * @param name - a public registry name, e.g. `mcp__tglider__workspace`.
96
+ * @param usage - the project's counters, when the host published any.
97
+ * @param sessionId - the session to read the split for; absent reads the project only.
98
+ * @returns the two readings, and whether the host recorded the server at all.
99
+ */
100
+ export function toolCalls(
101
+ name: string,
102
+ usage: ProjectUsage,
103
+ sessionId: string | undefined,
104
+ ): ToolCalls {
105
+ const split = splitToolName(name)
106
+ const record = split === undefined ? undefined : usage?.[split.server]
107
+ if (split === undefined || record === undefined) {
108
+ return { recorded: false, split: false, project: undefined, session: undefined }
109
+ }
110
+ const own = sessionId === undefined ? undefined : record.sessions?.[sessionId]
111
+ return {
112
+ recorded: true,
113
+ split: own !== undefined,
114
+ project: record.tools[split.tool],
115
+ session: own?.tools[split.tool],
116
+ }
117
+ }
118
+
119
+ /** The server and the declared tool name inside one public registry name. */
120
+ function splitToolName(name: string): { server: string; tool: string } | undefined {
121
+ const server = serverOfToolName(name)
122
+ if (server === undefined) return undefined
123
+ // Past `mcp__<server>__`: the tool name as the server declared it, separator
124
+ // included, because a declared name may hold one of its own.
125
+ return { server, tool: name.slice(MCP_TOOL_PREFIX.length + server.length + SEPARATOR.length) }
126
+ }
127
+
128
+ /** How long a server has been unused, in the one unit its row prints. */
129
+ export interface IdleSpan {
130
+ /** The largest whole unit the span holds. */
131
+ unit: 'day' | 'hour' | 'minute'
132
+ /** How many of that unit, floored. */
133
+ count: number
134
+ }
135
+
136
+ const MINUTE_MS = 60_000
137
+ const HOUR_MS = 60 * MINUTE_MS
138
+ const DAY_MS = 24 * HOUR_MS
139
+
140
+ /**
141
+ * The span since a server was last used, in its largest whole unit.
142
+ *
143
+ * `≥ 24 h → days`, `≥ 1 h → hours`, otherwise whole minutes (`0` is a real
144
+ * answer: the call just landed). A date the parser does not accept, a missing
145
+ * one, and one in the future are all "nothing to print" — the last one because
146
+ * a host clock ahead of this viewer's is not a negative idle span.
147
+ * @param lastUsedAt - ISO timestamp of the server's most recent call.
148
+ * @param now - epoch milliseconds to measure against.
149
+ * @returns the span, or undefined when there is no usable date.
150
+ */
151
+ export function idleOf(lastUsedAt: string | undefined, now: number): IdleSpan | undefined {
152
+ if (lastUsedAt === undefined) return undefined
153
+ const at = Date.parse(lastUsedAt)
154
+ if (!Number.isFinite(at)) return undefined
155
+ const elapsed = now - at
156
+ if (elapsed < 0) return undefined
157
+ if (elapsed >= DAY_MS) return { unit: 'day', count: Math.floor(elapsed / DAY_MS) }
158
+ if (elapsed >= HOUR_MS) return { unit: 'hour', count: Math.floor(elapsed / HOUR_MS) }
159
+ return { unit: 'minute', count: Math.floor(elapsed / MINUTE_MS) }
160
+ }
161
+
162
+ /**
163
+ * The order a list of tool names is drawn in: the most-called first.
164
+ *
165
+ * Sorting follows the figure the row leads with — this session's counter when
166
+ * the host published the split, the project's otherwise — so the list is ordered
167
+ * by the number a reader can see. That cuts both ways: a tool other sessions
168
+ * called 290 times and this one never called leads with `never called`, so it
169
+ * sinks below a tool this session really used, even though the project figure
170
+ * printed beside it is larger. The host's counter is the only frequency there
171
+ * is; a name with no reading of its own is "not measured", not "zero", and it
172
+ * neither outranks a measured name nor loses the order it arrived in (the sort
173
+ * is stable and this comparator returns `0` for a tie), so a list the host
174
+ * already ordered is never reshuffled for no reason.
175
+ * @param usage - the project's counters, as the host published them.
176
+ * @param sessionId - the session whose split leads the ordering; absent reads the project.
177
+ * @returns comparator for `Array.prototype.sort`.
178
+ */
179
+ export function byCalls(
180
+ usage: ProjectUsage,
181
+ sessionId?: string,
182
+ ): (left: string, right: string) => number {
183
+ const count = (name: string): number => {
184
+ const calls = toolCalls(name, usage, sessionId)
185
+ // The lead figure, and only it: a name the session is in the split without
186
+ // is unmeasured, however loud the project total beside it is.
187
+ return (calls.split ? calls.session : calls.project) ?? -1
188
+ }
189
+ return (left, right) => count(right) - count(left)
190
+ }