mcpspan-mcp 0.12.0 → 0.14.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.
- package/README.md +60 -12
- package/dist/index.mjs +35 -1
- package/package.json +2 -3
package/README.md
CHANGED
|
@@ -9,8 +9,11 @@ client answers from your mcpspan numbers:
|
|
|
9
9
|
- *Does Cursor fail more often than Claude?*
|
|
10
10
|
- *Which tools are agents shown but never call?*
|
|
11
11
|
|
|
12
|
-
It
|
|
13
|
-
|
|
12
|
+
It sees what you see in the dashboard and changes nothing. It sends nothing
|
|
13
|
+
anywhere but your mcpspan.
|
|
14
|
+
|
|
15
|
+
There are two ways to add it: by address, which needs nothing installed, or
|
|
16
|
+
as a command your agent starts.
|
|
14
17
|
|
|
15
18
|
## Try it on the demo
|
|
16
19
|
|
|
@@ -18,21 +21,65 @@ No account needed: the [live demo](https://demo.mcpspan.com) answers any
|
|
|
18
21
|
token. In Claude Code:
|
|
19
22
|
|
|
20
23
|
```sh
|
|
21
|
-
claude mcp add mcpspan-demo \
|
|
22
|
-
|
|
23
|
-
-e MCPSPAN_URL=https://demo-api.mcpspan.com \
|
|
24
|
-
-- npx -y mcpspan-mcp
|
|
24
|
+
claude mcp add --transport http mcpspan-demo https://demo-api.mcpspan.com/mcp \
|
|
25
|
+
--header "Authorization: Bearer demo"
|
|
25
26
|
```
|
|
26
27
|
|
|
27
28
|
Then ask about the demo's server, Flights: *what went wrong in the last day?*
|
|
28
29
|
|
|
29
|
-
##
|
|
30
|
+
## By address
|
|
31
|
+
|
|
32
|
+
The MCP server runs inside mcpspan itself, at `/mcp` on its API. Add that
|
|
33
|
+
address to your agent, and the first time it connects it opens mcpspan in your
|
|
34
|
+
browser: sign in, check which app is asking, and allow it. Nothing to copy.
|
|
35
|
+
|
|
36
|
+
### mcpspan Cloud
|
|
37
|
+
|
|
38
|
+
The address is `https://api.mcpspan.com/mcp`.
|
|
39
|
+
|
|
40
|
+
| Agent | How |
|
|
41
|
+
|---|---|
|
|
42
|
+
| claude.ai, Claude Desktop, the Claude apps | Settings → Connectors → Browse connectors, find mcpspan, and Connect. Or Add custom connector, with the address. |
|
|
43
|
+
| ChatGPT | In its connector settings (developer mode), a new connector with the address, signing in with OAuth. |
|
|
44
|
+
| Claude Code | `claude mcp add --transport http mcpspan https://api.mcpspan.com/mcp`, then `/mcp` in Claude Code to sign in. |
|
|
45
|
+
| Cursor | In `mcp.json`: `{"mcpServers": {"mcpspan": {"url": "https://api.mcpspan.com/mcp"}}}` |
|
|
46
|
+
| VS Code | In `.vscode/mcp.json`: `{"servers": {"mcpspan": {"type": "http", "url": "https://api.mcpspan.com/mcp"}}}` |
|
|
47
|
+
| Others | Whatever they call a remote, HTTP or Streamable HTTP server, with the address. |
|
|
48
|
+
|
|
49
|
+
The apps you allowed are listed in **Settings → Connected apps**, where one
|
|
50
|
+
click disconnects an app and ends its access at once.
|
|
51
|
+
|
|
52
|
+
An agent that cannot sign in with OAuth can send a read token instead (see
|
|
53
|
+
[Get a token](#get-a-token)), as a header:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
claude mcp add --transport http mcpspan https://api.mcpspan.com/mcp \
|
|
57
|
+
--header "Authorization: Bearer mcpspan_read_..."
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Self-hosted
|
|
61
|
+
|
|
62
|
+
The address is your API's, the one your MCP servers report to, with `/mcp`:
|
|
63
|
+
`http://localhost:6271/mcp` on the machine itself. Agents on that machine, such
|
|
64
|
+
as Claude Code or Cursor, connect as above.
|
|
65
|
+
|
|
66
|
+
An app that connects from elsewhere, such as claude.ai or ChatGPT, needs that
|
|
67
|
+
address on HTTPS and reachable from the internet, and the API told where people
|
|
68
|
+
open your dashboard, since that is where it sends them to allow it: set
|
|
69
|
+
`MCPSPAN_DASHBOARD_URL` in `.env`, for instance `https://mcpspan.example.com`.
|
|
70
|
+
|
|
71
|
+
Needs mcpspan 0.13.0 or newer.
|
|
72
|
+
|
|
73
|
+
## As a command
|
|
74
|
+
|
|
75
|
+
The same tools, started by your agent with `npx`, reading with a read token.
|
|
76
|
+
For agents that only start commands, or to keep it on your machine.
|
|
77
|
+
|
|
78
|
+
### Get a token
|
|
30
79
|
|
|
31
80
|
In mcpspan, open **Settings → Read tokens** and make one. It is shown once,
|
|
32
81
|
already filled into the lines below, ready to copy.
|
|
33
82
|
|
|
34
|
-
## Add it to your agent
|
|
35
|
-
|
|
36
83
|
### mcpspan Cloud
|
|
37
84
|
|
|
38
85
|
Claude Code:
|
|
@@ -84,7 +131,7 @@ claude mcp add mcpspan \
|
|
|
84
131
|
Needs mcpspan 0.9.0 or newer. If the agent reaches your installation over the
|
|
85
132
|
internet, put HTTPS in front of it: the token travels with every question.
|
|
86
133
|
|
|
87
|
-
|
|
134
|
+
### Settings
|
|
88
135
|
|
|
89
136
|
| Variable | |
|
|
90
137
|
|---|---|
|
|
@@ -112,9 +159,10 @@ account has one) and a window: `days` back from now (7 when left out), or
|
|
|
112
159
|
| `get_tool_listing` | What agents were shown: tools never used, and what their definitions cost. |
|
|
113
160
|
| `list_sessions` | Recent sessions, with failures and repeated calls. |
|
|
114
161
|
| `get_session` | One session's calls, in order. |
|
|
162
|
+
| `get_where_agents_get_lost` | What came of each session, the tools agents got stuck at and what they did next; for one tool, by client. |
|
|
115
163
|
|
|
116
|
-
A token can be revoked at any time under **Settings → Read tokens
|
|
117
|
-
loses access at once.
|
|
164
|
+
A token can be revoked at any time under **Settings → Read tokens**, and an app
|
|
165
|
+
disconnected under **Settings → Connected apps**; either loses access at once.
|
|
118
166
|
|
|
119
167
|
## Licence
|
|
120
168
|
|
package/dist/index.mjs
CHANGED
|
@@ -268,6 +268,40 @@ function registerTools(mcp, api) {
|
|
|
268
268
|
sampled: result.sampled
|
|
269
269
|
});
|
|
270
270
|
}));
|
|
271
|
+
mcp.registerTool("get_where_agents_get_lost", {
|
|
272
|
+
title: "Where agents get lost",
|
|
273
|
+
description: "Where agents got stuck and what they did about it. A time stuck is a failed tool call and the retries of the same tool straight after it; each ends recovered (the tool then worked, with meanRetries retries on average), wentElsewhere (the agent called something else, insteadMostOften), endedOnIt (the session stopped there, nothing for 30 minutes) or undecided (too recent to tell); looped counts those where a retry repeated the same arguments. Without a tool: every session by the worst that happened in it (clean, recovered, wentElsewhere, looped, endedOnFailure, undecided) and the tools agents got stuck at, worst first. With a tool: that tool's times stuck, as a whole and by client.",
|
|
274
|
+
inputSchema: z.object({
|
|
275
|
+
...scope,
|
|
276
|
+
client,
|
|
277
|
+
tool: z.string().optional().describe("Only this tool, split by client. The tool's name, as list_tools gives it.")
|
|
278
|
+
}),
|
|
279
|
+
annotations: READ_ONLY
|
|
280
|
+
}, (args) => answer(async () => {
|
|
281
|
+
const at = await locate(api, args);
|
|
282
|
+
if (args.tool !== void 0) {
|
|
283
|
+
const result = await api.get("/v1/dashboard/lost/tool", at.query({ toolName: args.tool }));
|
|
284
|
+
return at.describe(result.tool === null ? {
|
|
285
|
+
toolName: args.tool,
|
|
286
|
+
note: "Agents never got stuck at this tool in this window."
|
|
287
|
+
} : {
|
|
288
|
+
toolName: args.tool,
|
|
289
|
+
...result.tool,
|
|
290
|
+
clients: result.clients,
|
|
291
|
+
sampled: result.sampled
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
const result = await api.get("/v1/dashboard/lost", at.query({
|
|
295
|
+
clientType: args.client,
|
|
296
|
+
limit: 20
|
|
297
|
+
}));
|
|
298
|
+
return at.describe({
|
|
299
|
+
sessions: result.sessions,
|
|
300
|
+
tools: result.tools,
|
|
301
|
+
more: result.hasMore,
|
|
302
|
+
sampled: result.sampled
|
|
303
|
+
});
|
|
304
|
+
}));
|
|
271
305
|
mcp.registerTool("get_session", {
|
|
272
306
|
title: "Session",
|
|
273
307
|
description: "One session's calls in the order the agent made them, with each call's outcome and error.",
|
|
@@ -378,7 +412,7 @@ async function answer(work) {
|
|
|
378
412
|
//#endregion
|
|
379
413
|
//#region src/version.ts
|
|
380
414
|
/** This package's version, as its server names itself to clients. Kept in step by the release script. */
|
|
381
|
-
const VERSION = "0.
|
|
415
|
+
const VERSION = "0.14.0";
|
|
382
416
|
//#endregion
|
|
383
417
|
//#region src/server.ts
|
|
384
418
|
/** The MCP server, answering from one mcpspan account through its read token. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcpspan-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "Ask your AI agent about your MCP servers: which tools fail, how a release compares, what clients look for and do not find. Reads from mcpspan with a read token.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
@@ -40,14 +40,13 @@
|
|
|
40
40
|
"zod": "^4.6.5"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
|
-
"@mcpspan/core-api": "0.12.0",
|
|
44
43
|
"@modelcontextprotocol/client": "^2.3.1",
|
|
45
44
|
"@types/node": "^20.19.0",
|
|
46
45
|
"@types/pg": "^8.23.1",
|
|
47
46
|
"pg": "^8.23.0",
|
|
48
47
|
"tsdown": "^0.23.0",
|
|
49
48
|
"typescript": "^6.0.3",
|
|
50
|
-
"vitest": "4.1.
|
|
49
|
+
"vitest": "4.1.12"
|
|
51
50
|
},
|
|
52
51
|
"scripts": {
|
|
53
52
|
"build": "tsdown",
|