sigrank-mcp

SigRank CLI & MCP

Read your local AI usage, inspect the token cascade, and optionally publish a signed snapshot to the SigRank leaderboard on SignalAF.

npx sigrank

Website · Quickstart · MCP setup · Tool and adapter reference · Privacy

What it does

• Reads usage metadata from supported local AI session logs.
• Shows input, output, cache-write, and cache-read counts across available time windows.
• Calculates Yield, Leverage, Velocity, SNR, and 10xDEV locally.
• Provides a terminal dashboard and MCP tools for AI clients.
• Submits signed telemetry only when you choose to publish.

This evaluates observable token-processing patterns, not model quality, work quality, productivity, or business outcomes. An adapter may estimate a pillar when its source does not expose it separately; those limitations are documented in the adapter reference.

Get started

Requires Node.js 20 or later. No global install is required.

Explore locally

npx sigrank                       # interactive dashboard in a terminal
npx sigrank board --once          # public leaderboard, one-shot
npx sigrank board --window 7d --once

The dashboard includes Dashboard, Trends, Compare, Board, Watch, and Connect tabs. Use 1–6 or the arrow keys to switch, R to refresh, and Q to quit.

Publish your own snapshot

1. Sign in at signalaf.com and create a connect code in Settings.
2. Enroll this device, then inspect the dry-run payload.
3. Submit when you are ready to publish.

npx sigrank enroll
npx sigrank submit --dry-run
npx sigrank submit

Enrollment binds a device signing key to your operator account. The private key stays on your device. The server verifies and re-scores submitted telemetry; a local preview is not a guaranteed public rank.

For repeated use, an optional global installation provides the same commands:

npm install -g sigrank
sigrank

Connect an MCP client

Add this server to your client's MCP configuration:

{
  "mcpServers": {
    "sigrank": {
      "command": "npx",
      "args": ["-y", "sigrank"]
    }
  }
}

The entry point automatically runs an MCP stdio server when launched without a terminal. MCP tool names are called by the client; they are not shell commands.

Task	Tools
Inspect local usage	tokenpull, rank_windows, tokenpull_compare
Calculate from supplied counts	rank_paste, get_sigrank_standard_record
Read public results	get_leaderboard, get_operator, discover_peers
Explore possible changes	diagnose_cascade, simulate_change, suggest_improvements
Enroll and submit	enroll, submit_verified

For the full list, arguments, and adapter paths, see the CLI and MCP reference. Publishing through submit_verified requires confirm: true; dry_run: true inspects the payload without publishing.

Command guide

Command	Purpose
sigrank	Open the terminal dashboard
sigrank board --once	Print the public leaderboard
sigrank compare --platform codex	Audit token counts across available local sources
sigrank watch --window 7d	Watch local usage updates
sigrank enroll	Bind a device using a connect code
sigrank submit --dry-run	Inspect a signed submission without sending it
sigrank submit	Publish a verified submission
sigrank proxy	Start the optional loopback usage proxy
sigrank --help	Show the current command reference

Optional usage proxy

Some clients do not persist all provider-reported usage in their session files. sigrank proxy can capture usage from compatible Anthropic or OpenAI API traffic when a client supports a custom API base URL.

The proxy is off by default and binds only to loopback. It forwards provider-bound request/response content and credentials in memory, but does not persist their content. Its local usage log contains token counts and metadata. See the privacy contract before using it.

How measurement works

Four token pillars feed the calculation:

Yield (Υ) = (cache_read × output) / input²
Leverage  = cache_read / input
Velocity  = output / input
SNR       = output / (input + output)
10xDEV    = log₁₀(Leverage)

This package distributes the Upsilon measurement engine through the sigrank CLI/MCP compatibility command. SigRank is the public leaderboard and proof surface on SignalAF. TTEOP defines the protocol semantics; MO§ES™ is the governance framework.

The implementation delegates canonical calculations through token-cascade to tteop-spec. See the TTEOP implementation profile and protocol compatibility notes.

Privacy

Local inspection does not publish your usage. Signed submissions include the four pillars plus account/device identifiers, signature, platform/version information, counts, and report metadata. Enrollment also sends a device label.

Prompt text, response text, source code, repository contents, and local file paths are not part of the ranked submission payload. The optional proxy's transient handling of content is separate from what is persisted or submitted.

Read the full payload and privacy details, and use submit --dry-run to inspect what would be sent.

Development

git clone https://github.com/SunrisesIllNeverSee/sigrank-mcp.git
cd sigrank-mcp
npm install
npm test
npm run test:packaged

Run node index.mjs in a terminal for the dashboard, or configure the checked-out entry point in an MCP client. Release versions are managed by the repository's explicit publishing workflow; a documentation commit does not publish an npm release.

Related projects

• sigrank-app — SignalAF website, profiles, public API, and leaderboard.
• token-cascade — measurement implementation consumed by this package.
• TTEOP — protocol specification and semantics.

Contributing and security

See the contributing guide. Open bugs in GitHub Issues; report vulnerabilities privately through the security policy.

License

MIT.