Skip to main content
Glama
README.md
# fps-tweaks-mcp

An MCP server that lets an agent answer "which Windows tweaks actually raise
my frame rate" with measurements instead of folklore — and, more often than
you would expect, with "the data cannot tell".

```
Claude Code  ──stdio/JSON-RPC──▶  fps-tweaks-mcp  ──▶  measured pool
                                  5 tools                per hardware class
```

## The idea

Every "best settings" guide assumes one answer fits all hardware. It does
not. The desktop product this data comes from treats each tweak as an arm of
a multi-armed bandit, measures the change in frames per second, and pools
results **by hardware class** so a new machine starts from what similar
machines already learned.

This server puts that pool behind an agent. The interesting part is not the
lookup — it is what the tools refuse to say.

## Honest uncertainty is the whole design

No tool here returns a bare number. Every average arrives with the number of
measurements, the number of distinct machines, a 95% confidence interval and
a verdict:

```json
{
  "tweak": "nagle_off",
  "hardware_class": "nvidia-gtx-1660",
  "avg_reward": 0.0014,
  "measurements": 184,
  "machines": 92,
  "confidence_interval_95": [-0.1988, 0.2016],
  "verdict": "no effect measured",
  "note": "the measured effect (0.0014) is so close to zero that confirming it would take on the order of millions of measurements. Treat this tweak as doing nothing measurable, not as unexplored."
}
```

`recommend` ranks by the **lower bound** of the interval rather than the
average, which prefers a smaller gain that was measured properly over a
larger one seen on two machines. Tweaks whose interval covers zero are left
out entirely, and the tool says so rather than returning a shorter list
quietly.

On one hardware class in the sample — the RTX 4080, where the GPU is rarely
the bottleneck — **nothing clears the bar at all**, and `recommend` returns
an empty list with an explanation. That is the correct answer, and it is the
answer a model is most tempted to improve upon.

### Why Hoeffding and not a t-interval

The pool stores only a count and a running mean: the product computes the
mean incrementally and keeps no history, so there is no variance to work
with. But reward is bounded in `[-1, 1]` by construction, and for a bounded
variable Hoeffding's inequality gives an interval that needs no variance:

```
t = (b − a) · sqrt( ln(2/α) / 2n )
```

It is conservative — wider than the truth when the spread is actually small.
That is a deliberate trade: saying "not yet known" about a real effect is
cheaper for the user than promising a gain that is not there.

## Tools

| Tool | What it answers |
|---|---|
| `list_hardware_classes` | What hardware there are measurements for, and how much |
| `list_tweaks` | The catalogue, filterable by category, with admin-rights flags |
| `tweak_stats` | One tweak on one class: average, interval, machines, verdict |
| `recommend` | What is worth trying here, ranked by lower bound, zero-crossing excluded |
| `simulate_session` | The order UCB1 would try tweaks, with or without the shared pool |

`simulate_session` states its own assumption in the response: real per-run
rewards are not stored, so each measurement is assumed to return the pool
average. The *order* is realistic; the rewards are not samples.

## Running it

```bash
npm install
npm run build
npm run generate   # writes data/pool.sample.json
npm test
```

Then point an MCP client at it. For Claude Code, in `.mcp.json`:

```json
{
  "mcpServers": {
    "fps-tweaks": {
      "command": "node",
      "args": ["/absolute/path/to/fps-tweaks-mcp/dist/src/index.js"]
    }
  }
}
```

Diagnostics go to stderr, never stdout — a single stray `console.log` on
stdout corrupts the JSON-RPC stream and the client disconnects with no
useful error.

## About the data

**The real pool is not in this repository, and that is deliberate.** The
tweak catalogue — which registry keys, which power-scheme GUIDs, which
process settings — is the product I sell. Publishing it here would give it
away.

So `scripts/generate-sample.ts` produces a dataset with the *same schema* as
the production pool, from a fixed seed. The schema, the algorithm, the
intervals and the tools are real; the numbers are synthetic. The generator
models hardware honestly rather than sprinkling uniform noise: a CPU-bound
class gets a real gain from process priority and core parking, a GPU that is
never the bottleneck gets nothing, and rare classes end up with wide
intervals because there are fewer machines behind them.

To run against a real pool, point the server at it:

```bash
FPS_POOL_DATA=/path/to/pool.json npm start
```

The expected shape is in `src/pool.ts`, validated with zod on load.

## The bandit

`src/bandit.ts` is a port of the product's UCB1 implementation, constants
included, so the server's answers match what the user's machine computes.

Two details that are easy to get wrong:

**Pool data is kept separate from local measurements.** If the two were
merged, a machine would send other machines' numbers back to the pool as its
own: a hundred machines would echo one average at each other and the ranking
would become a reflection of itself rather than a sum of measurements.

**Pool entries weigh exactly one pull.** Your first own measurement ties with
the pool's opinion; your second outweighs it. The same GPU does not mean the
same computer, so a borrowed average is a hint about where to start, nothing
more.

`simulate_session` with `use_pool: false` shows what that is worth: cold,
UCB1 must try every tweak once before it can prefer any of them — the
guarantee that made the product abandon ε-greedy, which had left five arms of
eleven untouched over twenty rounds.

## Evals

Two layers, because they answer different questions.

**`npm test` — the server.** 20 cases, no API key, no network. Covers the
bandit's exploration guarantees, the prior-weighting arithmetic, interval
behaviour at small *n*, and a full MCP round-trip through an in-memory
transport: a real client, real tool schemas, real validation.

**`npm run eval` — the model plus the server.** Runs a set of questions
through a live model with these tools attached, and scores three things
separately: did it pick the right tool, did it pass the right arguments, and
**did the answer carry through the uncertainty the tool reported**.

The third is the one worth having. Several cases are traps:

- On the RTX 4080 nothing is demonstrated; an answer listing the largest
  averages anyway has invented a finding.
- On the GTX 1050 Ti the tweak with the *higher* average (`startup_trim`,
  0.214) is not significant, while a *lower* one (`core_parking_off`, 0.208)
  is. Reading the averages alone gives the wrong answer.
- `nagle_off` is a tweak the internet is certain about. It measures at 0.001.

Without `ANTHROPIC_API_KEY` the harness prints that it did not run and exits
zero — a CI run should not look green because the check was skipped.

```bash
ANTHROPIC_API_KEY=... npm run eval
EVAL_MODEL=claude-sonnet-5-5 npm run eval   # to compare models
```

Per-case reports land in `evals/results/`.

## Layout

```
src/bandit.ts     UCB1, ported from the product
src/stats.ts      Hoeffding intervals, verdicts, "how much more data"
src/pool.ts       data model, zod validation, loading
src/server.ts     the five tools
src/index.ts      stdio entry point
scripts/          deterministic sample-data generator
test/             server tests + bandit tests
evals/            cases and the live-model harness
```

TypeScript, Node 20+, `@modelcontextprotocol/sdk`. MIT.

Comments are in Ukrainian. They explain *why* a decision was made rather than
restating the code — that is deliberate.

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation5/5

Each tool occupies a clearly distinct slot: discovery (list_hardware_classes), catalogue (list_tweaks), per-item measurement (tweak_stats), ranked advice (recommend), and policy replay (simulate_session). The descriptions explicitly police the boundaries — list_tweaks says it carries no measurements, tweak_stats says it is one tweak on one class — so an agent cannot sensibly pick the wrong one.

Naming Consistency4/5

All snake_case and consistently noun-oriented (hardware_classes, tweaks, tweak_stats, session), with verbs list_/recommend/simulate_. The only wrinkle is that three names lead with a verb while tweak_stats is a bare noun phrase, but the pattern is still readable and predictable.

Tool Count5/5

Five tools is well-scoped for a read-only dataset exploration surface, and each one earns its place in the discovery → inspect → advise → simulate workflow. Nothing feels like filler or like a redundant wrapper.

Completeness4/5

The core lifecycle is covered end to end: enumerate classes, enumerate tweaks, get stats for a tweak/class pair, get a ranked recommendation, and replay the policy. The main gap is the reverse lookup — there is no way to ask which hardware classes a given tweak helps on, which an agent would have to assemble by looping tweak_stats.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues