mcp-fleet

Four MCP servers I wrote for myself and use daily: a fitness wearable, a hosting platform, a domain registrar, and my editor's own hook configuration. 3,364 lines of server source plus 500 in the auth and smoke scripts, 47 tools, stdio transport.

They share no code and I wrote them in a week without planning a house style. Reading them back afterwards, they had converged on the same three patterns — and that convergence is the only part of this repository I would call a finding, so it is written up first: docs/patterns.md.

Short version:

1. Single-flight credential refresh. Agents are concurrent; refresh tokens usually are not. Six tool calls landing on an expired token must produce one refresh, not six.
2. Dry-run by default on anything irreversible. The gate lives in the tool's own schema, so the model sees it before calling and the default path is the safe one.
3. One composite tool per server that fans out and returns a ranked action list — where each finding names the tool that fixes it, so the model doesn't have to plan.

The servers

Package	Tools	What it's for
whoop	12	Recovery, sleep, strain, workouts, cycles. Full OAuth with rotating refresh tokens.
vercel	16	Deployments, env vars, domains, logs — plus vercel_project_audit.
spaceship	15	Domain registration and DNS, with a confirm gate on anything that costs money.
claude-code-hooks	4	Reads and analyses a Claude Code hook configuration.

The piece I'd point at first

packages/whoop/src/auth/token-manager.ts. The OAuth flow is a real authorization-code flow: an ephemeral callback server on :4567, CSRF state generated and verified on return, a 404 on any other path, tokens written at mode 0600, and the listener closed the moment authorization completes.

The runtime half is twenty lines and every line is load-bearing:

if (!cached) cached = await deps.readTokens();
if (cached.expires_at - REFRESH_SKEW_MS > deps.now()) {
  return cached.access_token;
}
if (!inFlight) {
  inFlight = refresh(cached).finally(() => {
    inFlight = null;
  });
}
cached = await inFlight;

In-memory cache so disk is read once per process. A 60-second skew so a token that would expire mid-flight is refreshed before the request rather than after a 401. The promise itself as the lock. .finally so a failed refresh doesn't poison the next attempt.

Refreshing it for this repository meant making the dependencies injectable, which is why there is now a test that actually pins the concurrency property rather than asserting it in a comment:

it("issues one refresh for six concurrent callers", async () => {
  const pending = Array.from({ length: 6 }, () => manager.getAccessToken());
  release();
  const results = await Promise.all(pending);

  expect(h.refreshCalls()).toBe(1);
  expect(results).toEqual(Array(6).fill("access-2"));
  expect(h.writes()).toHaveLength(1);
});

Sixteen tests over the token manager, covering the skew boundary, rotation, the latch clearing after failure, and the case where a provider omits the rotated token.

Honest state

docs/patterns.md ends with the list of what is still wrong; the headlines are that only the WHOOP token manager has unit tests — everything else has live-API smoke scripts and nothing that runs offline — that annotation coverage is uneven (12/12 on WHOOP, 0 on the other three, including destructive tools), and that the confirm gate is missing on three destructive tools whose siblings have it.

These four were published to npm under an account that no longer exists, so every package's repository field currently points at a 404. Republishing under a working identity is pending.

Running them

pnpm install
pnpm test          # 16 tests
pnpm build

Then point an MCP client at the built entry point. WHOOP needs one-time authorization:

cd packages/whoop
WHOOP_CLIENT_ID=... WHOOP_CLIENT_SECRET=... pnpm auth

Credentials come from the environment. Nothing in this repository reads a credential from a file it also tracks.

License

MIT.