Skip to main content
Glama

The problem, in one table

What you see

What you conclude

One factor, on its own

RankIC 0.0105, t 3.03, p 0.0027

Significant. Ship it.

The same factor, 200 draws deep

the same numbers, plus p_family = 0.346

It is luck. Drop it.

Nothing about the factor changed. Only the count did.

That count is the one thing an agent cannot keep. A researcher tests five ideas a day and remembers them. An agent tests two hundred an hour, and every session starts with a blank context.


Related MCP server: Factor Miner MCP

See it in twenty seconds

One command, on a panel of 300 names × 250 dates where every factor is pure noise:

$ python demos/noise_200.py

  best factor     fp=v1:32625af66…
  RankIC          +0.0105
  t (iid / NW)    3.03 / 3.27
  p_single        0.00273   <- looks publishable
  family          200 trials
  bar_q95         3.67      <- what a real factor needed
  p_family        0.346     <- it is luck
  verdict         REJECT

  "Trial #200 of 200 — REJECT. IC=+0.0105, t=3.03, p_single=0.0027, p_family=0.346."

A RankIC of 1% is an ordinary magnitude for a real factor, so the size of the effect cannot tell you whether it is real. The only discriminating information is how many times you drew.


How it works

flowchart LR
    F["factor panel"] --> IC["RankIC series<br/>one value per date"]
    R["forward returns"] --> IC
    IC --> ID["fingerprint<br/>rank pattern, hashed"]
    IC --> ST["t, p_single"]
    ID --> L[("ledger")]
    L --> FAM["family<br/>N trials on this panel"]
    FAM --> NUL["null of max abs(t)<br/>block bootstrap"]
    ST --> G{"p_family ≤ α ?"}
    NUL --> G
    G -->|yes| P["PASS"]
    G -->|no| X["REJECT"]

Four tools sit on top of that loop:

Tool

Question it answers

Cost

fingerprint

Have I tried this factor before?

free — no trial consumed

evaluate

What is its RankIC, and what is its trial number?

one trial

gate

Does it survive the family correction, and how far off was it?

free

ledger_stats

How much have I tried, and where am I going in circles?

free

A PASS requires p_family ≤ α. p_single is reported and is never evidence.


Install

alphaledger is an MCP server, wrapped in a four-file dsh plugin. One implementation, two ways in; nothing leaves the machine and no API key is involved.

DeepSeek Harness — one command:

$ dsh plugin --profile web add dsh-alphaledger

The bundle only writes the config that launches the server. If you would rather see it:

- insert:
    - id: alphaledger
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: alphaledger
        transport: stdio
        command: uvx
        args: ['alphaledger-mcp']
        failOnStartupError: true

Claude Code, Codex, or any other MCP client:

claude mcp add alphaledger -- uvx alphaledger-mcp

Tools appear as mcp__alphaledger__evaluate, mcp__alphaledger__gate, and so on.

Both routes need uv once (curl -LsSf https://astral.sh/uv/install.sh | sh), because dsh deliberately does not manage Python environments. The server is on PyPI; the npm bundle is not published yet, so for now the dsh route installs from the checkout: dsh plugin --profile web add ./dsh/alphaledger. That is the ordinary pnpm add path, not a fallback — it was run against dsh 0.2.0-rc.2 with an isolated DSH_HOME: the command exits 0, dsh-alphaledger is added to dsh.profile.bundles, and its MCP entry appears in dsh --profile <name> --dump-config. Publishing to npm would only buy the shorter spelling dsh plugin add dsh-alphaledger.

Dependencies are numpy and the standard library. scipy would double the install and add seconds to a cold start, and the two things we needed from it — rank correlation and Student-t tails — are a few dozen lines. See docs/METHOD.md.


Three things the ledger refuses to do

It will not count rank(x) as a new factor. Identity is the factor's rank pattern, hashed as integers. x, rank(x), log(x) and 2x+3 rank identically, so they are one trial with four evaluations. Flipping the sign is the same trial too — recorded as a sign_flip, which is the cheapest way a family quietly grows.

It will not merge near-duplicates. Two factors correlating at 0.97 are reported as NEAR_DUPLICATE and left alone. Merging them would let "I only changed one parameter" escape the count, which is the entire problem.

It will not pass a leaked factor. A factor ranked identically to the forward return is LABEL_CONTAMINATION, checked before significance — because that is the one case where the numbers look best.


What it does not do

No data layer — you bring a panel, and an akshare adapter is planned. No backtest engine, no portfolio construction, no UI. It judges one factor's IC series and keeps the books, and that is all.


Documentation

docs/METHOD.md

Every formula, with the function and the test that pins it

docs/TOOLS.md

Schemas, error codes, host wiring

docs/AUDIT.md

Three existing dsh quant tools, read at source level

docs/CALIBRATION.md

Measured false-positive rate and power

ROADMAP.md

What shipped, what is v0.2


Status

0.1.0. On PyPI as alphaledger-mcp. The npm bundle is not published yet. Statistics, identity, ledger and the MCP surface are implemented and tested: 104 tests, ruff and mypy clean, false-positive rate 8.3% (1 in 12 studies), power 4 of 4 on a planted IC of 0.03.

v0.2: akshare adapter, one-shot OOS test lock, full look-ahead perturbation.

Available Tools

4 tools
evaluateB

Measure one factor and record it as a trial. Returns cross-sectional RankIC, Newey-West t, single-test p, the trial's index within its family, and the family-adjusted verdict. This is the only supported way to produce evidence.

Inputs: factor (required), forward (required), expr, alpha, +3 more.

fingerprintA

Identify a factor WITHOUT consuming a trial. Returns the value fingerprint, whether the ledger has seen it, and its position if so. Call this before writing new factor code to avoid re-testing something already counted.

Inputs: factor (required), forward (required), expr, horizon.

gateA

Re-judge an already-recorded trial against its family, optionally at a different alpha. Use after importing more trials or to ask 'how much better would this need to be'.

Inputs: fp (required), alpha.

ledger_statsB

How much has been tried, and where the session is going in circles: repeated evaluations, sign flips, near-duplicate clusters, and the cross-family error rate.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a distinct role: fingerprint checks identity without a trial, evaluate records evidence, ledger_stats summarizes behavior, and gate re-judges existing trials. The only mild overlap is between evaluate and gate, both of which return family-adjusted verdicts, but their preconditions and use cases are clearly separated.

    Naming Consistency3/5

    All names are lowercase snake_case and readable, but they mix noun-style names (fingerprint, gate, ledger_stats) with a verb (evaluate). There is no single predictable verb_noun or noun pattern throughout.

    Tool Count5/5

    Four tools is well-scoped for a focused factor-research ledger. Each tool covers a distinct part of the workflow and none feels redundant or excessive.

    Completeness4/5

    The core lifecycle is covered: identify a factor, evaluate and record it, inspect ledger health, and re-judge recorded trials. Minor gaps exist around listing or retrieving individual trials and explicit import/export operations, though these may be intentionally outside the server's scope.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables A-share quantitative factor workflows from any MCP client, including sandboxed factor execution, qlib backtesting, out-of-sample admission checks, daily factor computation, decay monitoring, ML training/prediction, and portfolio/volatility analytics.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables quant research organizations to log hypotheses and outcomes, count trials for honest statistical verdicts, explore novel methods, run significance gates, and evolve reusable skills from validated trajectories, all backed by SQLite.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to capture and replay intermittent software failures, minimize reproductions, compare trials, search regressions, verify proposed fixes against a saved failing baseline, and retrieve investigation evidence without rerunning commands.
      52 npm
      MIT