Momentum

An MCP server that answers "what should I work on right now?" across a portfolio of workstreams — clients, projects, initiatives — with a score you can audit, not a guess.

Point Claude (or any MCP client) at it and ask "what now?". It returns a ranked board where every position is explained: stale 11 days past a weekly cadence; deadline in 2 days; revenue-bearing. The ranking is computed in deterministic Python. No language model is in the scoring path.

Why this exists

Most "AI productivity" tooling asks a model to rank your priorities. That's the wrong job for a model. Ranking needs to be consistent (the same inputs produce the same order every time) and explainable (you can see exactly why something is #1). Language models are neither by construction — they're non-deterministic and their reasoning isn't inspectable.

So Momentum splits the labor the way it should be split:

• Code decides the ranking. Four weighted factors, computed from your data, fully reproducible.

• The model handles language and judgment. It decides when to call a tool, interprets your shorthand ("just wrapped the ACME spec"), and presents the result conversationally.

This is the same principle behind well-designed agent systems generally: keep the deterministic hot path in code, and reserve the model for the parts that genuinely need judgment. It's easier to trust, easier to debug, and it doesn't drift.

How the score works

Each active workstream is scored 0–100 from four factors, combined by weights you set in config:

A daily capacity check-in (energy 1–5, available focus hours) applies a state modifier on top. On low-energy days the engine biases toward workstreams you've flagged as low-effort-compatible, so a depleted afternoon surfaces the proposal-follow-up instead of the hardest build on the board.

Everything — the weights, the tier thresholds, the cadence definitions, the per-workstream revenue and low-capacity values — lives in a JSON config and is hot-reloadable. Re-tuning the ranking never requires touching code.

The tools

The cross-MCP brokering pattern

An MCP server can't call another MCP server directly. Momentum needs live task data from a task tool (TickTick, ClickUp) but stays dependency-free by making Claude the broker:

1. sync_tasks takes rows Claude has already read from the task-tool MCP and caches them locally, so deadlines factor into the score.

2. mark_task_disposition updates the local cache and returns a routing block naming the exact downstream MCP tool and params to call. Claude then executes that call.

The server never reaches across the boundary; it hands Claude a precise instruction and lets the model bridge the two servers. This keeps Momentum self-contained and portable across whatever task tool a given workstream uses.

Quick start

python -m venv .venv && source .venv/bin/activate
pip install fastmcp

# create and seed a demo database (a small consulting portfolio)
MOMENTUM_DB_PATH=./momentum.db python init_db.py

# create your config from the example
cp config.example.json config.json

# run the server
MOMENTUM_DB_PATH=./momentum.db MOMENTUM_CONFIG_PATH=./config.json python server.py

Then register it with your MCP client. Example Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "momentum": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/momentum-mcp/server.py"],
      "env": {
        "MOMENTUM_DB_PATH": "/path/to/momentum.db",
        "MOMENTUM_CONFIG_PATH": "/path/to/config.json"
      }
    }
  }
}

Replace every /path/to/ with the real absolute path on your machine — the interpreter, server.py, the database, and your config. Use full paths starting with /Users/...; ~ is not reliably expanded here. A leftover placeholder is the most common cause of a "Failed to spawn process" error in the logs.

Restart your MCP client, then ask Claude: "What should I focus on right now?" → it calls get_now and walks you through the ranked board.

Tuning the ranking

config.json is where you customize weights, tier thresholds, revenue rules, and low-capacity fit — edit it to match your own workstreams. Every key is optional; anything you omit falls back to the engine defaults, so a minimal config file works fine. config.json is gitignored so your real tuning never lands in the repo. Use the reload_config tool to apply edits without restarting.

Design notes

• Config over code. No user- or business-specific value is hardcoded. Weights, thresholds, cadences, and per-workstream rules are all external and hot-reloadable. The default config runs sensibly with no file at all.

• Fail fast on config. Required paths come from environment variables set by the MCP client. A missing MOMENTUM_DB_PATH is a hard error at import rather than a silent fallback that breaks subtly on another machine.

• Tools never raise. Every tool returns {"status": "ok" | "error", ...}. A bad input surfaces as a structured error the model can read and relay, not a stack trace that kills the session.

• SQLite in WAL mode, foreign keys on. Durable, concurrent-read-friendly, zero-infrastructure.

• Tool descriptions are written for the model. Each docstring states plainly when to call the tool and disambiguates likely confusions (e.g. "workstreams" are your tracked areas of effort, not DNS domains) — because a tool the model can't reliably select is a tool that doesn't work.

Provenance

Momentum is the open, generalized core of a private personal-operating-system MCP server the author built to run several businesses and a research project in parallel. The scoring engine, the cross-MCP brokering pattern, and the config-driven architecture are lifted directly from that system and reframed for a professional workstream portfolio. The same engine could be configured to rank any set of things, personal or professional, competing for finite attention and resources.

License

MIT.