@xmcp-dev/upstash 0.0.0-stage → 0.1.1

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 CHANGED
@@ -1,3 +1,39 @@
1
- # Temporary Holding Version
1
+ # @xmcp-dev/upstash
2
2
 
3
- 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.
3
+ Apply shared Upstash rate limits to xmcp tool calls with one MCP middleware. Requires xmcp 1.6+ and `@upstash/ratelimit` 2.2+.
4
+
5
+ ```sh
6
+ pnpm add @xmcp-dev/upstash @upstash/ratelimit @upstash/redis
7
+ ```
8
+
9
+ ```ts
10
+ // src/middleware.ts
11
+ import { Ratelimit } from "@upstash/ratelimit";
12
+ import { Redis } from "@upstash/redis";
13
+ import { upstashRateLimit } from "@xmcp-dev/upstash";
14
+
15
+ export const mcp = upstashRateLimit({
16
+ limiter: new Ratelimit({
17
+ redis: Redis.fromEnv(),
18
+ limiter: Ratelimit.fixedWindow(100, "1 m"),
19
+ prefix: "my-app:tools",
20
+ }),
21
+ // An earlier authenticated MCP middleware must set this request-local value.
22
+ identifier: (context) => context.get<string>("customerId"),
23
+ });
24
+ ```
25
+
26
+ Set `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`. All replicas must use the same Redis database and prefix to share a budget. Supply an identifier from verified authentication on every request; missing identifiers deny execution. Do not use an unverified customer header or an API key as the Redis identifier.
27
+
28
+ Options:
29
+
30
+ - `limiter`: an application-owned Upstash `Ratelimit` instance (or an object with its `limit` method).
31
+ - `identifier(context)`: required, possibly asynchronous, verified customer ID.
32
+ - `rate`: positive safe integer or asynchronous callback; defaults to one unit per attempt.
33
+ - `failureMode`: `"closed"` (default) denies on Redis failures, SDK timeouts, or failed background work. `"open"` explicitly allows execution when a quota decision is unavailable. Missing identity and known quota denials always deny.
34
+
35
+ The middleware only checks `tools/call`. Quota denial returns an MCP tool error (`isError: true`) with `_meta["xmcp.dev/rateLimit"]` containing `reason`, `limit`, `remaining`, `reset` (Unix milliseconds), and `retryAfterSeconds`. It does not produce HTTP 429. The middleware awaits the SDK's `pending` work so serverless runtimes do not discard it. This adds that work's latency to the call.
36
+
37
+ Each admitted attempt consumes units, including a tool that subsequently fails, is cancelled, or requires another execution round for input. No refunds or billing ledger are provided. Quota algorithms and their consistency guarantees remain those of the supplied Upstash limiter. STDIO works with a server-side identity callback; it has no HTTP headers.
38
+
39
+ See the [integration guide](https://xmcp.dev/docs/integrations/upstash) and [runnable HTTP example](https://github.com/basementstudio/xmcp/tree/main/examples/upstash-http) for authenticated identities and weighted tool costs.
@@ -0,0 +1,20 @@
1
+ import type { Ratelimit } from "@upstash/ratelimit";
2
+ import type { McpMiddleware, McpMiddlewareContext } from "xmcp";
3
+ type Awaitable<T> = T | Promise<T>;
4
+ export type RateLimitContext = Extract<McpMiddlewareContext, {
5
+ method: "tools/call";
6
+ }>;
7
+ export interface UpstashRateLimitOptions {
8
+ /** The application owns the Redis connection, algorithm, window and prefix. */
9
+ limiter: Pick<Ratelimit, "limit">;
10
+ /** Return a verified user/customer ID. Missing IDs always deny execution. */
11
+ identifier: (context: RateLimitContext) => Awaitable<string | null | undefined>;
12
+ /** Units consumed by each attempt; must be a positive safe integer. Defaults to 1. */
13
+ rate?: number | ((context: RateLimitContext) => Awaitable<number>);
14
+ /** Backend errors and SDK timeouts deny calls unless explicitly set to "open". */
15
+ failureMode?: "closed" | "open";
16
+ }
17
+ /** Apply a shared Upstash budget to tool calls without wrapping tool handlers. */
18
+ export declare function upstashRateLimit(options: UpstashRateLimitOptions): McpMiddleware;
19
+ export {};
20
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,MAAM,CAAC;AAEd,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,MAAM,gBAAgB,GAAG,OAAO,CACpC,oBAAoB,EACpB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,CACzB,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAClC,6EAA6E;IAC7E,UAAU,EAAE,CACV,OAAO,EAAE,gBAAgB,KACtB,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC1C,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,kFAAkF;IAClF,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CACjC;AAaD,kFAAkF;AAClF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,aAAa,CAsEf"}
package/dist/index.js ADDED
@@ -0,0 +1,66 @@
1
+ function errorResult(text, metadata) {
2
+ return {
3
+ isError: true,
4
+ content: [{ type: "text", text }],
5
+ ...(metadata ? { _meta: { "xmcp.dev/rateLimit": metadata } } : {}),
6
+ };
7
+ }
8
+ /** Apply a shared Upstash budget to tool calls without wrapping tool handlers. */
9
+ export function upstashRateLimit(options) {
10
+ const { limiter, identifier, rate = 1, failureMode = "closed" } = options;
11
+ if (failureMode !== "closed" && failureMode !== "open") {
12
+ throw new Error('Upstash failureMode must be "closed" or "open".');
13
+ }
14
+ return async (context, next) => {
15
+ // Discovery, prompts and resources do not consume tool-call quotas.
16
+ if (context.method !== "tools/call")
17
+ return next();
18
+ context.signal.throwIfAborted();
19
+ const key = await identifier(context);
20
+ context.signal.throwIfAborted();
21
+ if (typeof key !== "string" || key.trim().length === 0) {
22
+ return errorResult("A verified customer identifier is required to call this tool.");
23
+ }
24
+ const cost = typeof rate === "function" ? await rate(context) : rate;
25
+ context.signal.throwIfAborted();
26
+ if (!Number.isSafeInteger(cost) || cost < 1) {
27
+ throw new Error("Upstash rate must be a positive safe integer.");
28
+ }
29
+ let result;
30
+ let pendingFailed = false;
31
+ try {
32
+ result = await limiter.limit(key, { rate: cost });
33
+ // Complete SDK analytics/synchronization before returning, including on
34
+ // Workers where work detached from the request may otherwise be dropped.
35
+ pendingFailed = await result.pending.then(() => false, () => true);
36
+ }
37
+ catch {
38
+ context.signal.throwIfAborted();
39
+ return failureMode === "open"
40
+ ? next()
41
+ : errorResult("Rate limit service unavailable. Please try again later.");
42
+ }
43
+ context.signal.throwIfAborted();
44
+ // Never let a background failure override a known denial.
45
+ if (!result.success) {
46
+ const retryAfterSeconds = Math.max(0, Math.ceil((result.reset - Date.now()) / 1000));
47
+ return errorResult(result.reason === "denyList"
48
+ ? "This request is blocked by the rate limit policy."
49
+ : `Rate limit exceeded. Try again in ${retryAfterSeconds} seconds.`, {
50
+ reason: result.reason === "denyList" ? "blocked" : "limit",
51
+ limit: result.limit,
52
+ remaining: result.remaining,
53
+ reset: result.reset,
54
+ retryAfterSeconds,
55
+ });
56
+ }
57
+ // Upstash's timeout response can have success=true without a quota decision.
58
+ if (result.reason === "timeout" || pendingFailed) {
59
+ return failureMode === "open"
60
+ ? next()
61
+ : errorResult("Rate limit service unavailable. Please try again later.");
62
+ }
63
+ return next();
64
+ };
65
+ }
66
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "@xmcp-dev/upstash",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "Upstash rate limiting middleware for xmcp tools",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/basementstudio/xmcp",
9
+ "directory": "packages/plugins/upstash"
10
+ },
11
+ "homepage": "https://xmcp.dev",
12
+ "type": "module",
13
+ "main": "./dist/index.js",
14
+ "types": "./dist/index.d.ts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.ts",
18
+ "import": "./dist/index.js",
19
+ "default": "./dist/index.js"
20
+ }
21
+ },
22
+ "files": [
23
+ "dist"
24
+ ],
25
+ "peerDependencies": {
26
+ "@upstash/ratelimit": "^2.2.0",
27
+ "xmcp": "^1.6.0"
28
+ },
29
+ "devDependencies": {
30
+ "@types/node": "^22.20.5",
31
+ "@upstash/ratelimit": "^2.2.1",
32
+ "tsx": "^4.23.15",
33
+ "typescript": "^5.9.3",
34
+ "xmcp": "1.13.0"
35
+ },
36
+ "scripts": {
37
+ "build": "rm -rf dist && tsc",
38
+ "test": "node --import tsx --test test/*.test.ts"
39
+ }
6
40
  }