mcp-algorithm-finder

# algorithm-finder

**Describe a computational problem and get back the algorithms that fit, why
they fit, the bounds cited to the page, and where to get an implementation.**

Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1743+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

By [Mojibake](https://pipeworx.io), creators of Pipeworx.

Ask it "all-pairs shortest paths" and it does not guess. It looks up the
textbook answer (Floyd-Warshall, Johnson's, the precondition that decides
between them, cited to the exact page of CLRS), checks the last five years of
arXiv and Hugging Face Papers for anything newer, and tells you what it does
not know yet. No model runs in the request path. Every fact is either a
citation or a live source, never a guess.

## Three things it actually returned

These are real calls against the live pack, trimmed for length. Nothing below
is invented.

### 1. "What solves all-pairs shortest paths?"

```
algorithm_find({ problem: "all-pairs shortest paths", want: "both" })
```

Two methods, correctly separated by the constraint that actually decides
between them:

```json
{
  "name": "Floyd-Warshall algorithm",
  "preconditions": ["Negative edge weights are allowed, but there must be no negative-weight cycle."],
  "guarantee": "exact",
  "bounds": [
    { "quantity": "time", "bound": "Theta(V^3)", "kind": "worst_case",
      "cite": "CLRS4 ch. 23.2 p. pdf:851" }
  ],
  "when_to_use": "All-pairs shortest paths on dense graphs, or whenever its simple triple-loop implementation (no priority queue needed) is worth the cubic cost.",
  "when_not": "On sparse graphs, Johnson's algorithm has a better asymptotic bound.",
  "alternatives": ["Johnson's algorithm", "Dijkstra's algorithm", "Bellman-Ford algorithm"]
},
{
  "name": "Johnson's algorithm",
  "preconditions": ["No negative-weight cycle (checked by the initial Bellman-Ford run)."],
  "guarantee": "exact",
  "bounds": [
    { "quantity": "time", "bound": "O(V^2 lg V + VE)", "kind": "worst_case",
      "cite": "CLRS4 ch. 23.3 p. pdf:857" }
  ],
  "when_to_use": "All-pairs shortest paths on sparse graphs with some negative edge weights -- asymptotically faster there than Floyd-Warshall's Theta(V^3)."
}
```

It also names the open questions that would change the answer, before you ask:

```json
"open_questions": [
  "Can any edge weight be negative? (Dijkstra requires non-negative weights; Bellman-Ford does not.)",
  "One source, or every pair of vertices?",
  "Are capacities integral? Is there a cost per unit of flow to minimise as well?"
]
```

...plus five recent, dated papers on the "novel" side, including *Warm-Starting
All-Pairs Shortest Paths with Predictions* (arXiv, 2026) and *Fast 2-Approximate
All-Pairs Shortest Paths* (arXiv, 2023).

### 2. "What's new in approximate nearest neighbor search?"

```
algorithm_find({ problem: "approximate nearest neighbor search", want: "novel" })
```

This is the pure research leg, no textbook entry involved. It does not just
list papers; it clusters method names across them so a recurring name reads as
a real answer rather than a title you have to notice yourself:

```json
"novel_methods": [
  {
    "name": "HNSW",
    "mentions": 8,
    "first_seen": 2022,
    "last_seen": 2026,
    "example_paper": {
      "title": "From HNSW to Information-Theoretic Binarization: Rethinking the Architecture of Scalable Vector Search",
      "date": "2025-12-16T23:24:37.000Z",
      "url": "https://huggingface.co/papers/2601.11557"
    }
  },
  { "name": "NSG", "mentions": 6, "first_seen": 2017, "last_seen": 2025 },
  { "name": "SPANN", "mentions": 2, "first_seen": 2021, "last_seen": 2025 }
]
```

HNSW surfaces on its own, from the research, with the count and date range
that make it a real signal rather than a single paper's opinion.

### 3. "CP-SAT, MIP or a flow formulation for fair shift scheduling?"

```
algorithm_compare({
  problem: "assign people to shifts with availability and skills, minimum staffing per shift, and distribute undesirable shifts fairly",
  names: ["constraint-programming", "mixed-integer-programming", "min-cost-flow"],
  constraints: { objective: "fairness", exact: true }
})
```

Every constraint you state gets a verdict per method, and every restriction
you did not state comes back as an assumption rather than a silent yes:

```json
{
  "verdict": "conditional",
  "winner": "Constraint programming (CP-SAT)",
  "summary": "Constraint programming (CP-SAT), IF continuous_variables is false.",
  "candidates": [
    { "name": "Constraint programming (CP-SAT)",
      "constraints": { "objective": { "status": "satisfied", "given": "fairness" },
                       "exact":     { "status": "satisfied", "given": true } },
      "assumes": [{ "constraint": "continuous_variables", "requires": [false],
        "why": "CP-SAT requires every decision variable to be declared as an integer; it has no native continuous-variable type the way an LP/MIP solver does." }] },
    { "name": "Mixed-integer programming",
      "constraints": { "objective": { "status": "unknown", "given": "fairness" } },
      "assumes": [{ "constraint": "linear", "requires": [true] }] },
    { "name": "Minimum-cost flow (successive shortest paths)",
      "constraints": { "objective": { "status": "unknown", "given": "fairness" } },
      "assumes": [{ "constraint": "integer_capacities", "requires": [true] }],
      "bounds": [{ "bound": "O(F*m*n)", "kind": "worst_case",
                   "cite": "Minimum-cost flow, Complexity <https://cp-algorithms.com/graph/min_cost_flow.html>" }] }
  ],
  "open_questions": [
    "How should fairness be measured: equal counts of undesirable assignments, minimise the worst-off person, or minimise variance? Each is a different objective.",
    "Do you need a provably optimal schedule, or is a good feasible one enough? (CP-SAT/MIP can prove optimality; heuristics only find feasible answers.)",
    "Are any rules hard (must hold) versus soft (preferences with a penalty)?"
  ]
}
```

It does not claim the flow formulation fails on fairness. It says it does not
know, and asks the question that would settle it. A key it has no rule for
(say `gpu_available`) is rejected by name with the list of keys it does
understand, never quietly marked satisfied.

## Install

### Hosted (no setup)

```json
{
  "mcpServers": {
    "algorithm-finder": {
      "url": "https://gateway.pipeworx.io/algorithm-finder/mcp"
    }
  }
}
```

This endpoint also carries the shared Pipeworx meta-tools (`ask_pipeworx`,
`discover_tools`, and friends), so you can ask in plain English instead of
calling a tool directly:

```
ask_pipeworx({ question: "what algorithm solves the assignment problem?" })
```

### Local (no account, no network dependency on us)

```json
{
  "mcpServers": {
    "algorithm-finder": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-algorithm-finder"]
    }
  }
}
```

Available once published. Same source, same four tools, no gateway
round-trip and none of the shared meta-tools.

## Why trust it

- **Every fact is in our own words, cited to a page.** The curated method
  table (`data/methods.json`) states what a method solves, its preconditions,
  its bounds (worst-case, expected, or amortized -- never collapsed into one
  number), when to use it and when not, and names the book and chapter the
  fact was read from: CLRS 4th ed., Erciyes's *Guide to Graph Algorithms*,
  Christian & Griffiths's *Algorithms to Live By*, Bhargava's *Grokking
  Algorithms*. No sentence, figure, or code from any of those books is served
  -- only facts established from them, restated.
- **An uncited bound is refused, not shipped.** The bake script that builds
  this table rejects any non-qualitative complexity bound with no page
  citation attached. A bound you cannot point at a page for comes back
  labelled `qualitative`, never dressed up as a number.
- **Implementations are labelled for what they are.** Every code sample
  carries `grade: "educational"` -- it is Rosetta Code's reference solution,
  not a production-tested package. There is no `application` grade yet;
  nothing has been tested against pinned dependencies.
- **Licenses travel with the data, not just in this README.** NIST's
  Dictionary of Algorithms and Data Structures is a work of the US
  government and is public domain (17 U.S.C. § 105). Rosetta Code and
  cp-algorithms are CC BY-SA 4.0 -- every response from those sources carries
  the attribution line and the share-alike obligation inline, so you see the
  terms at the point you use the data, not buried in a license file.

## Contributing

Two ways in: add a method, or add a test case. A method goes in
`data/methods.json` and needs a real citation (book, chapter and page, or a
paper or official library doc) for every bound you add; the build refuses an
entry that names a complexity with no citation behind it. A test case goes in
`data/harness.json`: a problem, optionally the candidates and constraints, and
the answer it should produce. Cases that fail today are the most useful ones,
because they are what gets fixed next. Either way, point at a source. No
source, no merge.

## Reference

## Tools

- `algorithm_find(problem, want?, since_year?, limit?)` — describe the problem
  in words and get the matching textbook methods (what each solves,
  preconditions, bounds with their kind — worst-case / expected / amortized —
  when to use and when not, alternatives, citations), the open questions whose
  answers decide between them, Skiena Algorithm Repository problem pages, and
  recent papers from Hugging Face Papers and arXiv. `want` is `common`,
  `novel` or `both` (default). Optional `constraints` (same keys as
  `algorithm_compare`) move textbook results that violate one to the end and
  add a per-constraint `fit` to each.
- `algorithm_compare(names? | problem?, constraints