mcpspan 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,264 @@
+//#region src/config.d.ts
+interface McpspanConfig {
+  /**
+   * Key identifying the server these events belong to.
+   *
+   * Falls back to `MCPSPAN_API_KEY`. Without either, the SDK collects nothing.
+   */
+  apiKey?: string;
+  /**
+   * Base URL of the ingest API.
+   *
+   * Falls back to `MCPSPAN_ENDPOINT`. There is no default: without either,
+   * the SDK collects nothing and says so once.
+   */
+  endpoint?: string;
+  /**
+   * The version to record calls under: a release, a tag, a commit.
+   *
+   * Falls back to `MCPSPAN_SERVER_VERSION`, then to the version the MCP server
+   * gives itself (`new McpServer({ name, version })`), which is usually all
+   * that is needed. The dashboard marks where each version began.
+   */
+  serverVersion?: string;
+  /** Writes delivery diagnostics to stderr. Off by default. */
+  debug?: boolean;
+  /**
+   * Receives diagnostics instead of stderr.
+   *
+   * For servers with their own logger, so our messages arrive in the same
+   * stream and the same format as everything else. Implies `debug`.
+   *
+   * A callback that throws is ignored: a problem with reporting a problem
+   * cannot be allowed to become one.
+   */
+  onDiagnostic?: (message: string) => void;
+  /**
+   * Sends whatever is queued when the process is about to exit.
+   *
+   * On by default. Without it the last partly filled batch dies with the
+   * process, and on a stdio server that lives as long as one conversation
+   * that can be most of a session.
+   *
+   * The hook runs when Node's event loop empties. It does not keep the
+   * process alive, does not intercept signals, and does not interfere with a
+   * server's own shutdown handling.
+   */
+  flushOnExit?: boolean;
+  /** How long a partly filled batch waits before being sent anyway. */
+  flushIntervalMs?: number;
+  /** Largest number of events in a single request. */
+  maxBatchSize?: number;
+  /** Largest number of events held while delivery is failing. */
+  maxQueueSize?: number;
+  /**
+   * Records which parameters a tool was called with, by name and type only.
+   *
+   * Off by default. Values are never read, in this mode or any other: the name
+   * of this option is the whole promise. Turning it on tells you that
+   * `search_flights` is always called with `destination` and never with
+   * `departureDate`, which usually means a tool description is not landing.
+   */
+  captureParameterNames?: boolean;
+}
+/**
+ * Starts collecting, or stops if there is nothing to collect with.
+ *
+ * Calling this again with a different configuration replaces the previous
+ * one, sending whatever the old one still held. Calling it again with the same
+ * configuration changes nothing. That is the common case, not an edge: an HTTP
+ * server that builds a fresh MCP server for every request - the stateless
+ * pattern, and how v2 of the official SDK serves the 2026-07-28 protocol -
+ * calls instrument() on each of them, and starting over each time would
+ * announce the server once per request and throw away the batching.
+ *
+ * **Never throws.** This runs inside a developer's server during startup, so a
+ * mistyped option must not be the reason their server fails to boot. Bad
+ * values are reported on stderr and replaced with defaults.
+ */
+export declare function configure(config?: McpspanConfig): void;
+/**
+ * Stops collecting and makes a final attempt to deliver what is queued.
+ *
+ * Worth calling from a server's own shutdown path. Without it the last partly
+ * filled batch dies with the process, which on a short-lived stdio server can
+ * be most of a session.
+ */
+export declare function shutdown(): Promise<void>;
+//#endregion
+//#region src/instrument.d.ts
+/**
+ * Records every tool a server registers from this point on.
+ *
+ * This is the whole integration:
+ *
+ * ```ts
+ * const server = new McpServer({ name: 'flights', version: '1.0.0' });
+ * instrument(server, { apiKey: process.env.MCPSPAN_API_KEY });
+ * ```
+ *
+ * Tools registered afterwards are wrapped as they are registered, and tools
+ * registered before it are wrapped where they already are, so nothing about
+ * how they are declared, or where this line sits, has to change.
+ *
+ * **Never throws.** An unfamiliar server object, or one with no registration
+ * method at all, leaves the server exactly as it was and collects nothing. A
+ * telemetry library that can stop somebody's server from starting has failed
+ * at the only thing it truly must not do.
+ */
+export declare function instrument<TServer extends object>(server: TServer, config?: McpspanConfig): TServer;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Client application a tool call originated from, as far as the transport
+ * allows us to tell.
+ *
+ * Over stdio the client is usually invisible to the server, which yields
+ * `unknown`. `other` is different: a client did identify itself, we just do
+ * not recognise it.
+ */
+type ClientType = 'claude' | 'claude-code' | 'cursor' | 'chatgpt' | 'mcp-inspector' | 'other' | 'unknown';
+/**
+ * How a failed tool call announced itself.
+ *
+ * MCP asks tools to report their own failures inside the result, with
+ * `isError` set, so that the model can see what went wrong. A thrown exception
+ * is the deviation from that, and usually means the handler crashed rather
+ * than failing on purpose. Keeping the two apart lets a developer tell a
+ * handled business error from a bug.
+ *
+ * The other two never reach a handler. The server refuses them itself, and
+ * the model sees that refusal like any other error result.
+ */
+type ErrorSource = 'result' | 'exception' |
+/** Refused by the server's schema validation before the handler ran. */
+'arguments' |
+/** A tool name the server does not have, or has disabled. */
+'unknown_tool' |
+/** A resource address the server has nothing registered for. */
+'unknown_resource' |
+/** A prompt name the server does not have, or has disabled. */
+'unknown_prompt';
+/** What an event is about: a tool call, a resource read, or a prompt got. */
+type CallKind = 'tool' | 'resource' | 'prompt';
+/**
+ * A single tool invocation recorded by the SDK.
+ *
+ * The event carries no server identity on purpose. The ingest API derives that
+ * from the API key the batch was sent with, so a caller cannot attribute tool
+ * calls to a server it does not own.
+ *
+ * Parameter values are never part of an event, in any mode.
+ */
+interface ToolCallEvent {
+  /**
+   * Identifies this call for as long as it takes to reach storage.
+   *
+   * A batch that times out after the server has already written it gets resent,
+   * so ingest needs a way to recognise a replay and drop it. Without this, a
+   * flaky network inflates the very numbers the product exists to report.
+   */
+  id: string;
+  /** Absent for a tool call; `resource` or `prompt` for the others (contract, 3.5). */
+  kind?: Exclude<CallKind, 'tool'>;
+  /**
+   * Name the tool was registered under; for a resource, its registered URI or
+   * URI template; for a prompt, its name.
+   */
+  toolName: string;
+  /** How long the call took, in milliseconds. May be fractional. */
+  durationMs: number;
+  /** False when the call was refused, the handler threw, or it returned `isError`. */
+  success: boolean;
+  /** Which failure path this call took. Absent on success. */
+  errorSource?: ErrorSource;
+  /** Constructor name of a thrown error, for example `TypeError`. Absent otherwise. */
+  errorType?: string;
+  /** Error message, truncated to a bounded length. Absent on success. */
+  errorMessage?: string;
+  /** Where the call came from, or `unknown` when nothing identified itself. */
+  clientType: ClientType;
+  /**
+   * The name the client reported, as it reported it.
+   *
+   * Turns an unrecognised client into a lead rather than a dead end: a
+   * dashboard showing forty percent `other` is useless if nobody can find out
+   * what `other` was. This is an application's self-description, the MCP
+   * equivalent of a User-Agent, and says nothing about whoever is using it.
+   */
+  clientName?: string;
+  /** The version the client gives itself, as it gives it. */
+  clientVersion?: string;
+  /**
+   * The version of the server that answered: the `serverVersion` setting, or
+   * the version the MCP server gives itself.
+   */
+  serverVersion?: string;
+  /** When the call started, as an ISO 8601 timestamp. */
+  timestamp: string;
+  /** Version of the mcpspan package that produced the event. */
+  sdkVersion: string;
+  /**
+   * The connection this call arrived on, as a random identifier made by the
+   * SDK. Absent for calls recorded through `track` alone, which has no way to
+   * see the connection.
+   */
+  sessionId?: string;
+  /**
+   * Parameter names mapped to their types, when a developer opted in.
+   *
+   * Absent by default, and never contains a value. Seeing that
+   * `search_flights` is always called with `destination` and never with
+   * `departureDate` tells a developer their tool description is not landing;
+   * seeing which destination tells them nothing they needed and puts their
+   * users' data somewhere it does not belong.
+   */
+  parameters?: Record<string, string>;
+}
+//#endregion
+//#region src/track.d.ts
+/**
+ * Wraps a tool handler so its calls are recorded.
+ *
+ * The returned function keeps the handler's exact signature, including its
+ * `this`, and passes the result back untouched. Whatever the handler is to the
+ * code around it, the wrapper has to be indistinguishable - the moment using
+ * this changes how a tool behaves, it stops being an observability library and
+ * becomes a liability.
+ *
+ * Synchronous handlers are measured as they return. Asynchronous ones are
+ * measured when their promise settles, since the time a tool takes is the time
+ * the agent waits for it, not the time spent building the promise.
+ *
+ * Failure is recognised in both of its MCP forms: a result the tool marked
+ * with `isError`, which the specification treats as the ordinary way to report
+ * a problem, and a thrown exception, which usually means the handler broke.
+ *
+ * Arguments are never read. Nothing a caller passes to a tool reaches an
+ * event.
+ */
+export declare function track<TArgs extends unknown[], TResult>(toolName: string, handler: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+/**
+ * Keeps a tool out of the numbers entirely.
+ *
+ * The counterpart to {@link track}: where that one records a handler, this one
+ * marks it so that wrapping the server never touches it.
+ *
+ * ```ts
+ * server.registerTool('health_check', schema, exclude(handler));
+ * ```
+ *
+ * Meant for tools that are called by machinery rather than by an agent - a
+ * health check polled every few seconds would outnumber everything a person
+ * actually did, and would drag the error rate and response time of the whole
+ * server towards its own.
+ *
+ * Takes no tool name on purpose. A name repeated here could drift from the
+ * real one during a rename, and the exclusion would quietly stop applying.
+ *
+ * Does nothing on its own: without instrumentation there was nothing about to
+ * record this handler anyway. The handler is returned exactly as given.
+ */
+export declare function exclude<THandler extends (...args: never[]) => unknown>(handler: THandler): THandler;
+//#endregion
+export type { ClientType, ErrorSource, McpspanConfig, ToolCallEvent };

package/dist/index.d.mts

@@ -0,0 +1,264 @@
+//#region src/config.d.ts
+interface McpspanConfig {
+  /**
+   * Key identifying the server these events belong to.
+   *
+   * Falls back to `MCPSPAN_API_KEY`. Without either, the SDK collects nothing.
+   */
+  apiKey?: string;
+  /**
+   * Base URL of the ingest API.
+   *
+   * Falls back to `MCPSPAN_ENDPOINT`. There is no default: without either,
+   * the SDK collects nothing and says so once.
+   */
+  endpoint?: string;
+  /**
+   * The version to record calls under: a release, a tag, a commit.
+   *
+   * Falls back to `MCPSPAN_SERVER_VERSION`, then to the version the MCP server
+   * gives itself (`new McpServer({ name, version })`), which is usually all
+   * that is needed. The dashboard marks where each version began.
+   */
+  serverVersion?: string;
+  /** Writes delivery diagnostics to stderr. Off by default. */
+  debug?: boolean;
+  /**
+   * Receives diagnostics instead of stderr.
+   *
+   * For servers with their own logger, so our messages arrive in the same
+   * stream and the same format as everything else. Implies `debug`.
+   *
+   * A callback that throws is ignored: a problem with reporting a problem
+   * cannot be allowed to become one.
+   */
+  onDiagnostic?: (message: string) => void;
+  /**
+   * Sends whatever is queued when the process is about to exit.
+   *
+   * On by default. Without it the last partly filled batch dies with the
+   * process, and on a stdio server that lives as long as one conversation
+   * that can be most of a session.
+   *
+   * The hook runs when Node's event loop empties. It does not keep the
+   * process alive, does not intercept signals, and does not interfere with a
+   * server's own shutdown handling.
+   */
+  flushOnExit?: boolean;
+  /** How long a partly filled batch waits before being sent anyway. */
+  flushIntervalMs?: number;
+  /** Largest number of events in a single request. */
+  maxBatchSize?: number;
+  /** Largest number of events held while delivery is failing. */
+  maxQueueSize?: number;
+  /**
+   * Records which parameters a tool was called with, by name and type only.
+   *
+   * Off by default. Values are never read, in this mode or any other: the name
+   * of this option is the whole promise. Turning it on tells you that
+   * `search_flights` is always called with `destination` and never with
+   * `departureDate`, which usually means a tool description is not landing.
+   */
+  captureParameterNames?: boolean;
+}
+/**
+ * Starts collecting, or stops if there is nothing to collect with.
+ *
+ * Calling this again with a different configuration replaces the previous
+ * one, sending whatever the old one still held. Calling it again with the same
+ * configuration changes nothing. That is the common case, not an edge: an HTTP
+ * server that builds a fresh MCP server for every request - the stateless
+ * pattern, and how v2 of the official SDK serves the 2026-07-28 protocol -
+ * calls instrument() on each of them, and starting over each time would
+ * announce the server once per request and throw away the batching.
+ *
+ * **Never throws.** This runs inside a developer's server during startup, so a
+ * mistyped option must not be the reason their server fails to boot. Bad
+ * values are reported on stderr and replaced with defaults.
+ */
+export declare function configure(config?: McpspanConfig): void;
+/**
+ * Stops collecting and makes a final attempt to deliver what is queued.
+ *
+ * Worth calling from a server's own shutdown path. Without it the last partly
+ * filled batch dies with the process, which on a short-lived stdio server can
+ * be most of a session.
+ */
+export declare function shutdown(): Promise<void>;
+//#endregion
+//#region src/instrument.d.ts
+/**
+ * Records every tool a server registers from this point on.
+ *
+ * This is the whole integration:
+ *
+ * ```ts
+ * const server = new McpServer({ name: 'flights', version: '1.0.0' });
+ * instrument(server, { apiKey: process.env.MCPSPAN_API_KEY });
+ * ```
+ *
+ * Tools registered afterwards are wrapped as they are registered, and tools
+ * registered before it are wrapped where they already are, so nothing about
+ * how they are declared, or where this line sits, has to change.
+ *
+ * **Never throws.** An unfamiliar server object, or one with no registration
+ * method at all, leaves the server exactly as it was and collects nothing. A
+ * telemetry library that can stop somebody's server from starting has failed
+ * at the only thing it truly must not do.
+ */
+export declare function instrument<TServer extends object>(server: TServer, config?: McpspanConfig): TServer;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Client application a tool call originated from, as far as the transport
+ * allows us to tell.
+ *
+ * Over stdio the client is usually invisible to the server, which yields
+ * `unknown`. `other` is different: a client did identify itself, we just do
+ * not recognise it.
+ */
+type ClientType = 'claude' | 'claude-code' | 'cursor' | 'chatgpt' | 'mcp-inspector' | 'other' | 'unknown';
+/**
+ * How a failed tool call announced itself.
+ *
+ * MCP asks tools to report their own failures inside the result, with
+ * `isError` set, so that the model can see what went wrong. A thrown exception
+ * is the deviation from that, and usually means the handler crashed rather
+ * than failing on purpose. Keeping the two apart lets a developer tell a
+ * handled business error from a bug.
+ *
+ * The other two never reach a handler. The server refuses them itself, and
+ * the model sees that refusal like any other error result.
+ */
+type ErrorSource = 'result' | 'exception' |
+/** Refused by the server's schema validation before the handler ran. */
+'arguments' |
+/** A tool name the server does not have, or has disabled. */
+'unknown_tool' |
+/** A resource address the server has nothing registered for. */
+'unknown_resource' |
+/** A prompt name the server does not have, or has disabled. */
+'unknown_prompt';
+/** What an event is about: a tool call, a resource read, or a prompt got. */
+type CallKind = 'tool' | 'resource' | 'prompt';
+/**
+ * A single tool invocation recorded by the SDK.
+ *
+ * The event carries no server identity on purpose. The ingest API derives that
+ * from the API key the batch was sent with, so a caller cannot attribute tool
+ * calls to a server it does not own.
+ *
+ * Parameter values are never part of an event, in any mode.
+ */
+interface ToolCallEvent {
+  /**
+   * Identifies this call for as long as it takes to reach storage.
+   *
+   * A batch that times out after the server has already written it gets resent,
+   * so ingest needs a way to recognise a replay and drop it. Without this, a
+   * flaky network inflates the very numbers the product exists to report.
+   */
+  id: string;
+  /** Absent for a tool call; `resource` or `prompt` for the others (contract, 3.5). */
+  kind?: Exclude<CallKind, 'tool'>;
+  /**
+   * Name the tool was registered under; for a resource, its registered URI or
+   * URI template; for a prompt, its name.
+   */
+  toolName: string;
+  /** How long the call took, in milliseconds. May be fractional. */
+  durationMs: number;
+  /** False when the call was refused, the handler threw, or it returned `isError`. */
+  success: boolean;
+  /** Which failure path this call took. Absent on success. */
+  errorSource?: ErrorSource;
+  /** Constructor name of a thrown error, for example `TypeError`. Absent otherwise. */
+  errorType?: string;
+  /** Error message, truncated to a bounded length. Absent on success. */
+  errorMessage?: string;
+  /** Where the call came from, or `unknown` when nothing identified itself. */
+  clientType: ClientType;
+  /**
+   * The name the client reported, as it reported it.
+   *
+   * Turns an unrecognised client into a lead rather than a dead end: a
+   * dashboard showing forty percent `other` is useless if nobody can find out
+   * what `other` was. This is an application's self-description, the MCP
+   * equivalent of a User-Agent, and says nothing about whoever is using it.
+   */
+  clientName?: string;
+  /** The version the client gives itself, as it gives it. */
+  clientVersion?: string;
+  /**
+   * The version of the server that answered: the `serverVersion` setting, or
+   * the version the MCP server gives itself.
+   */
+  serverVersion?: string;
+  /** When the call started, as an ISO 8601 timestamp. */
+  timestamp: string;
+  /** Version of the mcpspan package that produced the event. */
+  sdkVersion: string;
+  /**
+   * The connection this call arrived on, as a random identifier made by the
+   * SDK. Absent for calls recorded through `track` alone, which has no way to
+   * see the connection.
+   */
+  sessionId?: string;
+  /**
+   * Parameter names mapped to their types, when a developer opted in.
+   *
+   * Absent by default, and never contains a value. Seeing that
+   * `search_flights` is always called with `destination` and never with
+   * `departureDate` tells a developer their tool description is not landing;
+   * seeing which destination tells them nothing they needed and puts their
+   * users' data somewhere it does not belong.
+   */
+  parameters?: Record<string, string>;
+}
+//#endregion
+//#region src/track.d.ts
+/**
+ * Wraps a tool handler so its calls are recorded.
+ *
+ * The returned function keeps the handler's exact signature, including its
+ * `this`, and passes the result back untouched. Whatever the handler is to the
+ * code around it, the wrapper has to be indistinguishable - the moment using
+ * this changes how a tool behaves, it stops being an observability library and
+ * becomes a liability.
+ *
+ * Synchronous handlers are measured as they return. Asynchronous ones are
+ * measured when their promise settles, since the time a tool takes is the time
+ * the agent waits for it, not the time spent building the promise.
+ *
+ * Failure is recognised in both of its MCP forms: a result the tool marked
+ * with `isError`, which the specification treats as the ordinary way to report
+ * a problem, and a thrown exception, which usually means the handler broke.
+ *
+ * Arguments are never read. Nothing a caller passes to a tool reaches an
+ * event.
+ */
+export declare function track<TArgs extends unknown[], TResult>(toolName: string, handler: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+/**
+ * Keeps a tool out of the numbers entirely.
+ *
+ * The counterpart to {@link track}: where that one records a handler, this one
+ * marks it so that wrapping the server never touches it.
+ *
+ * ```ts
+ * server.registerTool('health_check', schema, exclude(handler));
+ * ```
+ *
+ * Meant for tools that are called by machinery rather than by an agent - a
+ * health check polled every few seconds would outnumber everything a person
+ * actually did, and would drag the error rate and response time of the whole
+ * server towards its own.
+ *
+ * Takes no tool name on purpose. A name repeated here could drift from the
+ * real one during a rename, and the exclusion would quietly stop applying.
+ *
+ * Does nothing on its own: without instrumentation there was nothing about to
+ * record this handler anyway. The handler is returned exactly as given.
+ */
+export declare function exclude<THandler extends (...args: never[]) => unknown>(handler: THandler): THandler;
+//#endregion
+export type { ClientType, ErrorSource, McpspanConfig, ToolCallEvent };