npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@stipend-mcp/cli

v1.0.0

Published

Stipend CLI — `stipend-mcp dev` boots the full local stack; `stipend-mcp keygen` generates Ed25519 signing keys; `stipend-mcp repair` runs the one-off data repairs for an upgrade from 0.1.0-alpha.2.

Readme

@stipend-mcp/cli

Command-line interface for Stipend. Ships three commands:

  • stipend-mcp dev — boot the full local stack (proxy + API + mock Stripe + dev resolver) in one command.
  • stipend-mcp keygen — generate an Ed25519 receipt-signing keypair.
  • stipend-mcp repair — the two one-off Firestore data repairs for an upgrade from 0.1.0-alpha.2.

The dev command is Stipend's hero "see it work in under 60 seconds" path. Not for production — it uses a mock payment provider and a permissive identity resolver.

Install

pnpm add -g @stipend-mcp/cli
# or run without installing:
pnpm dlx @stipend-mcp/cli dev --upstream npx @upstream/server

The bin is stipend-mcp.

stipend-mcp dev

stipend-mcp dev --upstream <command...>

Boots:

  • An in-memory EntitlementStore + DeliveryStore (or Firestore on the local emulator with --emulator, which needs FIRESTORE_EMULATOR_HOST).
  • A fresh Ed25519 signer keypair per boot (receipts are always signed; the API refuses to boot without a signer).
  • A MockStripeProvider that auto-approves every intent.
  • A DevAgentTokenResolver that accepts any non-empty bearer token and lazily upserts an account for it.
  • An MCP proxy on --proxy-port (default 7071), reachable at http://127.0.0.1:7071/mcp.
  • The Stipend HTTP API on --api-port (default 7070), reachable at http://127.0.0.1:7070/v1/..., with one all-scopes host key, dev-api-key.

The upstream's tools are exposed as upstream.<toolname> (e.g. upstream.get_secret_message); the namespace upstream is also the service its entitlements are scoped to.

Agents connect to the proxy port; hosts (and the test harness in front of you) talk to the API port.

Options

| Flag | Default | Purpose | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --upstream <cmd...> | required | The upstream MCP server. Spawns a child process and pipes stdio. Everything after --upstream is treated as the command + args (verbatim). | | --proxy-port <port> | 7071 | Agent-facing port. | | --api-port <port> | 7070 | Host-facing API port. | | --emulator | unset | Use FirestoreStore + FirestoreDeliveryStore on the local Firestore emulator instead of the in-memory adapters. Needs FIRESTORE_EMULATOR_HOST: without it the command refuses to start (it never reaches a real project). Auto-detected when FIRESTORE_EMULATOR_HOST is set. | | --quiet | unset | Suppress info/warn lines; errors still print. |

Example

# Stand up a sample upstream + the proxy:
stipend-mcp dev --upstream npx -y @modelcontextprotocol/server-everything

# In another shell, talk to it:
curl -sS http://127.0.0.1:7071/healthz
# {"status":"ok"}

# Initialize an MCP session against the proxy. The auto-generated dev
# token is printed in the boot banner.
curl -sS http://127.0.0.1:7071/mcp \
  -H 'Authorization: Bearer dev-token-1' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}
  }'

The first time a token is seen, the dev resolver lazily upserts an account and the logger emits a registration line. Subsequent requests reuse the same identity.

Pretty-printed output

stipend-mcp dev formats key events on stderr:

AGENT  dev-0c4f7aa2e2cc6e49 (account 1952…)
ALLOW  dev-0c4f7aa2e2cc6e49 → upstream/upstream.say_hello
402    dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (payment_required: per_call)
ALLOW  dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (one_time ent-12345678)
DUP    dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (call key already used; not run again)
UNDO   dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (upstream timeout; charge given back)
PAY+   pmt-abc 1.00 USD
PAY$   pmt-abc 1.00 USD
RCPT   pmt-abc (receipt rcp-xyz)
REFND  pmt-abc

Amounts carry their own currency code (10.00 EUR). Use --quiet to suppress everything except error lines (the boot banner included); a boot failure always prints.

What stipend-mcp dev is NOT

  • Not for production. The MockStripeProvider returns synthetic IDs and "succeeds" on every charge; no real money moves. The DevAgentTokenResolver accepts any token. Replace both with StripeProvider (@stipend-mcp/stripe) and HttpAgentTokenResolver (@stipend-mcp/proxy) when you wire your own deployment.
  • Not a deployment / production launcher. Use createApiServer (@stipend-mcp/api) + createProxyServer (@stipend-mcp/proxy) programmatically in your own service. The dev command is single-process glue meant for local iteration.
  • Not a multi-upstream demo. The CLI spawns a single upstream from the --upstream flag and exposes its tools under the namespace upstream. For production catalogs with multiple upstream MCP services, wire createProxyServer({upstreams: {…}}) directly — see @stipend-mcp/proxy.

Production path

// your-server.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { configFromEnv, createApiServer } from '@stipend-mcp/api';
import { createProxyServer, HttpAgentTokenResolver } from '@stipend-mcp/proxy';
import { FirestoreStore, FirestoreDeliveryStore } from '@stipend-mcp/store-firestore';
import { StripeProvider } from '@stipend-mcp/stripe';
import { Ed25519Signer, Stipend } from 'stipend-mcp';

// — store + delivery store
const firestore = /* your Firestore client */;
const store = new FirestoreStore({ firestore });
const deliveryStore = new FirestoreDeliveryStore({ firestore });

// — real Stripe + signer
const provider = new StripeProvider({ apiKey: process.env.STRIPE_SECRET_KEY! });
const signer = new Ed25519Signer({
  keyId: process.env.STIPEND_SIGNING_KEY_ID!,
  privateKey: process.env.STIPEND_SIGNING_PRIVATE_KEY!,
});
const stipend = new Stipend({ store, signer });

// — real resolver
const resolver = new HttpAgentTokenResolver({
  url: process.env.STIPEND_RESOLVER_URL!,
  sharedSecret: process.env.STIPEND_RESOLVER_SECRET,
});

// — API (a signer is required; host keys are named and scoped)
const api = createApiServer({
  store, deliveryStore, provider, signer,
  config: configFromEnv(), // STIPEND_API_KEYS, STRIPE_WEBHOOK_SECRET, … — see @stipend-mcp/api
});
await api.start();

// — proxy (wire to your own HTTP transport)
const upstream = new Client({ name: 'prod-upstream', version: '1.0.0' }, {});
await upstream.connect(/* your upstream transport */);
const { server: proxyServer } = createProxyServer({ stipend, upstreams: { main: upstream }, resolver });
await proxyServer.connect(/* your agent-facing transport */);

stipend-mcp keygen

stipend-mcp keygen [--key-id <id>] [--out <path>]

Prints (or writes to file) an Ed25519 keypair in PEM format. The key id is embedded in every receipt signed with the private key so verification can find the right public key for an older receipt during rotation.

# To stdout (the default):
stipend-mcp keygen --key-id stipend-prod-2026
# # keyId: stipend-prod-2026
# # Set the private key on your deployment, e.g.:
# #   export STIPEND_SIGNING_PRIVATE_KEY="$(cat private.pem)"
# # ...

# To a file (mode 600):
stipend-mcp keygen --key-id stipend-prod-2026 --out ./signing.pem
# wrote keypair to ./signing.pem (mode 600)

--key-id defaults to stipend-<YYYY-MM-DD>. In the monorepo, pnpm generate-key builds and runs this same command (pnpm generate-key --key-id <id>), so there is one output format.

stipend-mcp repair

Two one-off data repairs for an upgrade from 0.1.0-alpha.2 on Firestore. Run each once dry, then once with --apply, straight after the coordinated deploy (see the CHANGELOG migration section). stipend-mcp is this package's bin, so without installing it name the package with -p (the npm package called stipend-mcp is the core library and has no bin):

npx -p @stipend-mcp/[email protected] stipend-mcp repair payment-index   --project <id> [--collection-prefix <p>] [--apply]
npx -p @stipend-mcp/[email protected] stipend-mcp repair periodic-quotas --project <id> [--collection-prefix <p>] [--apply]
  • payment-index rebuilds the per-account payment idempotency index, so a retry made across the deploy with a pre-deploy Idempotency-Key returns the original payment instead of charging twice. A slot already pointing at another payment is reported as a conflict and never overwritten; a key alpha.2 accepted but 1.0.0 refuses (e.g. one containing /) is reported as invalid; an index document whose paymentId is not a string is reported in invalid_index_docs, and its slot is never overwritten (fix or delete it by hand).
  • periodic-quotas revives periodic quotas that alpha.2 left consumed at zero: active, 0 remaining, the next reset in the future. Non-periodic quotas stay consumed, and so does a quota core grantWithdrawal withholds (its granting payment was fully refunded or disputed, or it remembers a host revoke made while it was consumed): it is listed under skipped_withdrawn ({entitlementId, paymentId?, reason}; reason host, without a payment for a direct grant, when the host revoked the quota while it was consumed), a correct skip that does not set needs_attention. Each apply transaction re-reads the payment, so a refund or dispute that lands between the scan and the write still withholds the revive. An entitlement document, or a stranded quota's payment, that does not decode is listed under invalid ({entitlementId, reason}), and a repair whose transaction fails under failed ({entitlementId, error}; nothing written for it, a re-run plans it again); the run goes on and repairs the rest. An active periodic quota stored without a reset boundary (alpha.2 stored none on any quota, so one with calls left at the upgrade has none) is listed under active_without_reset_at ({entitlementId, resetPeriod, grantedAt}), dry run and apply alike, and never written: it needs no repair, as it resets on the schedule from its grant and its first reset stores the boundary; not an error.

Both are dry runs unless --apply, scan the whole set (paged) before the first write, re-check each write in its own transaction (safe next to live traffic), and print one JSON summary that starts with its target: project, collection_prefix, emulator_host. A second run changes nothing (present counts slots another run created first). Exit code 1 means the operator must look: needs_attention (a conflicts, invalid, invalid_index_docs, raced or failed row; a payment missing its account or creation time is invalid, and so is a periodic-quotas row that does not decode), or the target collection is empty (collection_size: 0; pass --allow-empty if the store really is empty). Exit code 2 is a usage error, including a project that does not match the emulator setting: a demo-* project needs FIRESTORE_EMULATOR_HOST, and any other project refuses to run with it set. Credentials: Application Default Credentials, or the emulator when FIRESTORE_EMULATOR_HOST is set.

Programmatic API

The CLI composition is exported for reuse by other dev tooling:

import { startDevStack, MockStripeProvider, DevAgentTokenResolver } from '@stipend-mcp/cli';

// Boot the full stack (without the SIGINT handler the bin installs):
const stack = await startDevStack({
  upstream: ['npx', '-y', '@upstream/server'],
});
console.log('proxy:', stack.proxyUrl);
console.log('api:  ', stack.apiUrl);
await stack.stop();

The dev primitives also have subpath exports so consumers can pull them without the full CLI:

import { MockStripeProvider } from '@stipend-mcp/cli/mock-stripe';
import { DevAgentTokenResolver } from '@stipend-mcp/cli/dev-resolver';

Tests

pnpm test packages/cli   # from the repo root: this package's unit (src/) and integration (test/) tests

Covers:

  • mock-stripe.test.ts — synthetic-id shape, override hooks, refund.
  • dev-resolver.test.ts — deterministic identity, lazy upsert, first-resolve callback.
  • logger.test.ts — formatting per event type, --quiet semantics.
  • keygen.test.ts — round-trip a sign-then-verify with a generated keypair; --out writes mode-600.
  • repair.test.ts — argument parsing, dry-run default, JSON summary and exit codes of stipend-mcp repair.
  • dev.test.ts — end-to-end: boot the dev stack against an in-memory upstream, exercise health / 404 / 405 / unauthorized / tools-list discovery / free tool forwarding / payment_required / stipend/whoami over real HTTP.