mcpspan-mcp 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kacper Zatoń
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# mcpspan-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ask your AI agent about your MCP servers. Claude Code, Cursor or any other MCP
+client answers from your mcpspan numbers:
+
+- *Which tools failed most this week, and why?*
+- *How does 1.4.1 compare with 1.4.0?*
+- *What do agents ask for that my server does not have?*
+- *Does Cursor fail more often than Claude?*
+- *Which tools are agents shown but never call?*
+
+It reads with a token that sees what you see in the dashboard and changes
+nothing. It sends nothing anywhere but your mcpspan.
+
+## Get a token
+
+In mcpspan, open **Settings → Read tokens** and make one. It is shown once,
+already filled into the lines below, ready to copy.
+
+## Add it to your agent
+
+### mcpspan Cloud
+
+Claude Code:
+
+```sh
+claude mcp add mcpspan -e MCPSPAN_READ_TOKEN=mcpspan_read_... -- npx -y mcpspan-mcp
+```
+
+Cursor, Claude Desktop, Windsurf and others, in their MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mcpspan": {
+      "command": "npx",
+      "args": ["-y", "mcpspan-mcp"],
+      "env": { "MCPSPAN_READ_TOKEN": "mcpspan_read_..." }
+    }
+  }
+}
+```
+
+### Self-hosted
+
+The same, with the address your MCP servers report to:
+
+```sh
+claude mcp add mcpspan \
+  -e MCPSPAN_READ_TOKEN=mcpspan_read_... \
+  -e MCPSPAN_URL=http://localhost:6271 \
+  -- npx -y mcpspan-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "mcpspan": {
+      "command": "npx",
+      "args": ["-y", "mcpspan-mcp"],
+      "env": {
+        "MCPSPAN_READ_TOKEN": "mcpspan_read_...",
+        "MCPSPAN_URL": "http://localhost:6271"
+      }
+    }
+  }
+}
+```
+
+Needs mcpspan 0.9.0 or newer. If the agent reaches your installation over the
+internet, put HTTPS in front of it: the token travels with every question.
+
+## Settings
+
+| Variable | |
+|---|---|
+| `MCPSPAN_READ_TOKEN` | The read token. Required. |
+| `MCPSPAN_URL` | Your installation's API, for self-hosted mcpspan. `https://api.mcpspan.com` when left out. |
+
+Needs Node 20 or newer.
+
+## Tools
+
+Every tool only reads. Each takes the server by name or id (left out when the
+account has one) and a window: `days` back from now (7 when left out), or
+`from` and `to`.
+
+| Tool | Answers |
+|---|---|
+| `list_servers` | The servers the account reports on. |
+| `get_overview` | Calls, failures, error rate, response times and clients. |
+| `list_tools` | Tools ranked by calls, errors, response time or name. |
+| `get_tool` | One tool: why it failed, refused arguments, answer sizes, definition changes, repeats, and the call before each failure. |
+| `list_errors` | The latest failed calls, with the kind of failure and the message. |
+| `list_unknown_tools` | Tools agents asked for that the server lacks, the closest one it has, and what the agent did next. |
+| `list_clients` | Each client's calls, error rate and response times. |
+| `compare_versions` | The server's releases side by side. |
+| `get_tool_listing` | What agents were shown: tools never used, and what their definitions cost. |
+| `list_sessions` | Recent sessions, with failures and repeated calls. |
+| `get_session` | One session's calls, in order. |
+
+A token can be revoked at any time under **Settings → Read tokens**; the agent
+loses access at once.
+
+## Licence
+
+MIT

package/dist/index.mjs

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+/** How long one question may take before the agent is told it did not come back. */
+const TIMEOUT_MS = 3e4;
+/** A failure worded for the agent, and through it the person, to act on. */
+var ApiError = class extends Error {
+	name = "ApiError";
+};
+function createApi({ token, url, fetch: send = fetch }) {
+	const base = url.replace(/\/+$/, "");
+	return { async get(path, query = {}) {
+		if (token === void 0 || token.trim().length === 0) throw new ApiError("MCPSPAN_READ_TOKEN is not set. Make a read token in mcpspan, under Settings → Read tokens, and give it to this MCP server.");
+		const target = new URL(`${base}${path}`);
+		for (const [key, value] of Object.entries(query)) if (value !== void 0) target.searchParams.set(key, String(value));
+		let response;
+		try {
+			response = await send(target, {
+				headers: {
+					authorization: `Bearer ${token.trim()}`,
+					accept: "application/json"
+				},
+				signal: AbortSignal.timeout(TIMEOUT_MS)
+			});
+		} catch {
+			throw new ApiError(`Could not reach mcpspan at ${base}. Check MCPSPAN_URL and that the installation is running.`);
+		}
+		const body = await response.json().catch(() => void 0);
+		const said = typeof body?.["error"] === "string" ? body["error"] : void 0;
+		if (response.ok && body !== void 0) return body;
+		switch (response.status) {
+			case 401: throw new ApiError("mcpspan refused the read token: it was revoked or mistyped. Make a new one under Settings → Read tokens.");
+			case 404: throw new ApiError(said?.startsWith("No route") === true || said === void 0 ? `${base} does not answer read tokens. It needs mcpspan 0.9.0 or newer, and MCPSPAN_URL must be the address your MCP servers report to.` : said);
+			case 429: throw new ApiError(said ?? "Too many questions at once. Wait a minute and ask again.");
+			case 503: throw new ApiError(said ?? "mcpspan cannot reach its database right now. Try again shortly.");
+			default: throw new ApiError(said ?? `mcpspan answered ${response.status}.`);
+		}
+	} };
+}
+//#endregion
+//#region src/tools.ts
+/** Every tool here only reads, and reads only what its owner's dashboard shows. */
+const READ_ONLY = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false
+};
+const server = z.string().optional().describe("The MCP server to ask about, by name or id. Leave out when the account has only one.");
+const days = z.number().int().min(1).max(365).optional().describe("How many days back to look, ending now. 7 when left out. Ignored when from is given.");
+const from = z.string().optional().describe("Start of the window, as an ISO 8601 date or time. Overrides days.");
+const to = z.string().optional().describe("End of the window, as an ISO 8601 date or time. Now when left out.");
+const client = z.string().optional().describe("Only calls from this client type, as list_clients names them, such as claude-code or cursor.");
+const scope = {
+	server,
+	days,
+	from,
+	to
+};
+/** The tools an agent gets, each answering from one or a few of the dashboard's endpoints. */
+function registerTools(mcp, api) {
+	mcp.registerTool("list_servers", {
+		title: "List servers",
+		description: "The MCP servers this mcpspan account reports on, with their names and ids.",
+		annotations: READ_ONLY
+	}, () => answer(async () => {
+		const { servers } = await api.get("/v1/servers");
+		return { servers: servers.map((s) => ({
+			id: s.id,
+			name: s.name,
+			createdAt: s.createdAt,
+			...s.hasActiveKey ? {} : { note: "No API key: it cannot report until one is generated." }
+		})) };
+	}));
+	mcp.registerTool("get_overview", {
+		title: "Overview",
+		description: "Calls, failures, error rate, response times (median and 95th percentile) and the share of each client, for one server over a window.",
+		inputSchema: z.object({
+			...scope,
+			client
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		return at.describe(await api.get("/v1/dashboard/summary", at.query({ clientType: args.client })));
+	}));
+	mcp.registerTool("list_tools", {
+		title: "List tools",
+		description: "A server's tools ranked by calls, errors, response time or name, each with its calls, errors, error rate and response times.",
+		inputSchema: z.object({
+			...scope,
+			client,
+			sort: z.enum([
+				"calls",
+				"errors",
+				"duration",
+				"name"
+			]).optional().describe("How to rank them. calls when left out."),
+			limit: z.number().int().min(1).max(100).optional().describe("How many to return. 20 when left out.")
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/tools", at.query({
+			clientType: args.client,
+			sort: args.sort,
+			limit: args.limit ?? 20
+		}));
+		return at.describe({
+			sort: result.sort,
+			total: result.total,
+			tools: result.tools
+		});
+	}));
+	mcp.registerTool("get_tool", {
+		title: "Tool details",
+		description: "Everything recorded about one tool: why its calls failed and the commonest error messages, which arguments the server refused, its parameters, how large its answers are, when its definition changed, how often agents repeated a call, and which call came right before the ones that repeated or failed.",
+		inputSchema: z.object({
+			...scope,
+			tool: z.string().describe("The tool's name, as list_tools gives it.")
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const details = await api.get("/v1/dashboard/tool-details", at.query({
+			toolName: args.tool,
+			messagesLimit: 10,
+			parametersLimit: 30,
+			beforeLimit: 10
+		}));
+		return at.describe(pick(details, [
+			"toolName",
+			"failures",
+			"messages",
+			"refusedArguments",
+			"parameters",
+			"responseSizes",
+			"definitionChanges",
+			"repeats",
+			"before"
+		]));
+	}));
+	mcp.registerTool("list_errors", {
+		title: "List failed calls",
+		description: "The most recent failed calls, newest first: which tool, which client, when, what kind of failure (a handler that threw, a tool that answered with an error, refused arguments, an unknown tool) and the error message when the server records them.",
+		inputSchema: z.object({
+			...scope,
+			client,
+			tool: z.string().optional().describe("Only failures of this tool."),
+			limit: z.number().int().min(1).max(100).optional().describe("How many to return. 20 when left out.")
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/errors", at.query({
+			clientType: args.client,
+			toolName: args.tool,
+			limit: args.limit ?? 20
+		}));
+		return at.describe({
+			failures: result.failures.map((call) => pick(call, [
+				"occurredAt",
+				"kind",
+				"toolName",
+				"clientType",
+				"clientName",
+				"errorSource",
+				"errorType",
+				"errorMessage",
+				"durationMs",
+				"serverVersion",
+				"sessionId",
+				"repeated"
+			])),
+			more: result.nextCursor !== null
+		});
+	}));
+	mcp.registerTool("list_unknown_tools", {
+		title: "List unknown tools",
+		description: "Tools that agents asked for but the server does not have: how often, which clients, the closest tool the server does have, and what the agent did next.",
+		inputSchema: z.object({ ...scope }),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/unknown-tools", at.query({ limit: 20 }));
+		return at.describe({
+			tools: result.tools,
+			more: result.hasMore
+		});
+	}));
+	mcp.registerTool("list_clients", {
+		title: "List clients",
+		description: "The clients that called the server (Claude, Claude Code, Cursor, VS Code, ChatGPT and others), each with its calls, error rate and response times.",
+		inputSchema: z.object({ ...scope }),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const summary = await api.get("/v1/dashboard/summary", at.query());
+		const clients = await Promise.all(summary.clients.slice(0, 15).map(async ({ clientType }) => {
+			return {
+				clientType,
+				...pick(await api.get("/v1/dashboard/summary", at.query({ clientType })), [
+					"totalCalls",
+					"failedCalls",
+					"errorRate",
+					"durationMs"
+				])
+			};
+		}));
+		return at.describe({ clients });
+	}));
+	mcp.registerTool("compare_versions", {
+		title: "Compare versions",
+		description: "The server's versions in the window, newest first, each with when it was first seen, its calls, error rate and response times: how a release compares with the one before.",
+		inputSchema: z.object({
+			...scope,
+			client
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/versions", at.query({ clientType: args.client }));
+		return at.describe(pick(result, ["versions", "unversionedCalls"]));
+	}));
+	mcp.registerTool("get_tool_listing", {
+		title: "What agents are shown",
+		description: "Every tool as agents were shown it when they listed the tools: in how many sessions, how many of those called it, and how large its definition is. Finds tools agents see but never use, and definitions that cost context.",
+		inputSchema: z.object({
+			...scope,
+			client
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/listing", at.query({
+			clientType: args.client,
+			listingLimit: 100
+		}));
+		return at.describe(omit(result, [
+			"range",
+			"offset",
+			"limit"
+		]));
+	}));
+	mcp.registerTool("list_sessions", {
+		title: "List sessions",
+		description: "Recent sessions (one connection each), newest first, with their calls, failures, tools used and calls an agent repeated with the same arguments.",
+		inputSchema: z.object({
+			...scope,
+			client,
+			tool: z.string().optional().describe("Only sessions that called this tool."),
+			with: z.enum(["failures", "repeats"]).optional().describe("Only sessions with failures, or with repeated calls."),
+			limit: z.number().int().min(1).max(100).optional().describe("How many to return. 20 when left out.")
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, args);
+		const result = await api.get("/v1/dashboard/sessions", at.query({
+			clientType: args.client,
+			toolName: args.tool,
+			with: args.with,
+			limit: args.limit ?? 20
+		}));
+		return at.describe({
+			sessions: result.sessions,
+			more: result.hasMore,
+			sampled: result.sampled
+		});
+	}));
+	mcp.registerTool("get_session", {
+		title: "Session",
+		description: "One session's calls in the order the agent made them, with each call's outcome and error.",
+		inputSchema: z.object({
+			...scope,
+			session: z.string().describe("The session id, as list_sessions or list_errors gives it.")
+		}),
+		annotations: READ_ONLY
+	}, (args) => answer(async () => {
+		const at = await locate(api, {
+			...args,
+			days: args.days ?? 30
+		});
+		const result = await api.get(`/v1/dashboard/sessions/${encodeURIComponent(args.session)}`, at.query());
+		return at.describe({
+			sessionId: args.session,
+			calls: result.calls.map((call) => omit(call, ["id"])),
+			more: result.nextCursor !== null
+		});
+	}));
+}
+/**
+* Which server and which window a question is about, worked out once.
+*
+* The server is looked up by name as well as id, since that is how a person
+* names it; with only one, it can be left out, as in the dashboard.
+*/
+async function locate(api, args) {
+	const { servers } = await api.get("/v1/servers");
+	const chosen = pickServer(servers, args.server);
+	const window = windowOf(args);
+	return {
+		query: (extra = {}) => ({
+			serverId: chosen.id,
+			from: window.from,
+			to: window.to,
+			...extra
+		}),
+		describe: (result) => ({
+			server: chosen.name,
+			window,
+			...omit(result, ["range"])
+		})
+	};
+}
+function pickServer(servers, wanted) {
+	if (servers.length === 0) throw new ApiError("This account has no servers yet. Add one in mcpspan and connect its SDK.");
+	const names = servers.map((s) => s.name).join(", ");
+	if (wanted === void 0 || wanted.trim().length === 0) {
+		if (servers.length === 1) return servers[0];
+		throw new ApiError(`This account has several servers; name one with server: ${names}.`);
+	}
+	const asked = wanted.trim().toLowerCase();
+	const found = servers.find((s) => s.id === wanted.trim()) ?? servers.find((s) => s.name.toLowerCase() === asked) ?? onlyOne(servers.filter((s) => s.name.toLowerCase().includes(asked)));
+	if (found === void 0) throw new ApiError(`No server called "${wanted}". The servers are: ${names}.`);
+	return found;
+}
+function windowOf(args) {
+	const end = args.to === void 0 ? /* @__PURE__ */ new Date() : new Date(args.to);
+	if (Number.isNaN(end.getTime())) throw new ApiError(`to is not a date: ${args.to}`);
+	const start = args.from === void 0 ? /* @__PURE__ */ new Date(end.getTime() - (args.days ?? 7) * 24 * 60 * 60 * 1e3) : new Date(args.from);
+	if (Number.isNaN(start.getTime())) throw new ApiError(`from is not a date: ${args.from}`);
+	if (start >= end) throw new ApiError("from must be earlier than to.");
+	return {
+		from: start.toISOString(),
+		to: end.toISOString()
+	};
+}
+/**
+* Fractions cut to what a person would read: a rate to four places, a time
+* or a size to one. Fifteen digits of an error rate cost the agent context
+* and tell it nothing more.
+*/
+function rounded(_key, value) {
+	if (typeof value !== "number" || Number.isInteger(value)) return value;
+	return Number(value.toFixed(Math.abs(value) < 1 ? 4 : 1));
+}
+function onlyOne(candidates) {
+	return candidates.length === 1 ? candidates[0] : void 0;
+}
+function pick(source, keys) {
+	return Object.fromEntries(keys.filter((key) => key in source).map((key) => [key, source[key]]));
+}
+function omit(source, keys) {
+	return Object.fromEntries(Object.entries(source).filter(([key]) => !keys.includes(key)));
+}
+/**
+* A tool's result as text the agent reads: compact JSON, or what went wrong
+* marked as an error, so it can tell the person rather than guess.
+*/
+async function answer(work) {
+	try {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(await work(), rounded)
+		}] };
+	} catch (error) {
+		if (error instanceof ApiError) return {
+			content: [{
+				type: "text",
+				text: error.message
+			}],
+			isError: true
+		};
+		throw error;
+	}
+}
+//#endregion
+//#region src/version.ts
+/** This package's version, as its server names itself to clients. Kept in step by the release script. */
+const VERSION = "0.9.0";
+//#endregion
+//#region src/server.ts
+/** The MCP server, answering from one mcpspan account through its read token. */
+function buildServer(api) {
+	const server = new McpServer({
+		name: "mcpspan",
+		version: VERSION
+	}, {
+		capabilities: { tools: {} },
+		instructions: "Answers questions about the user's MCP servers from mcpspan: calls, failures, response times, clients, releases and sessions. Every tool reads; none changes anything. Start with list_servers when the account may have several."
+	});
+	registerTools(server, api);
+	return server;
+}
+//#endregion
+//#region src/index.ts
+const token = process.env["MCPSPAN_READ_TOKEN"];
+const url = process.env["MCPSPAN_URL"]?.trim() || "https://api.mcpspan.com";
+if (token === void 0 || token.trim().length === 0) console.error("mcpspan-mcp: MCPSPAN_READ_TOKEN is not set; make one in mcpspan under Settings → Read tokens.");
+const api = createApi({
+	token,
+	url
+});
+serveStdio(() => buildServer(api));
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "mcpspan-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "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.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "analytics",
+    "observability",
+    "mcpspan"
+  ],
+  "mcpName": "io.github.mcpspan/mcpspan",
+  "license": "MIT",
+  "author": "Kacper Zatoń",
+  "homepage": "https://github.com/mcpspan/mcpspan/tree/main/packages/mcpspan-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcpspan/mcpspan.git",
+    "directory": "packages/mcpspan-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/mcpspan/mcpspan/issues"
+  },
+  "type": "module",
+  "bin": {
+    "mcpspan-mcp": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@mcpspan/core-api": "0.9.0",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@types/node": "^20.19.0",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }