# LegalQuants MCP

A working local MCP pilot for finding LegalQuants community builds and retrieving
specific source excerpts to help adapt them. Unofficial prototype; not affiliated
with or endorsed by LegalQuants. No community application code is executed.

## Quick start

Requires Node.js 22+ and npm. No AI provider key is required.

```sh
npm ci
npm run build
npm test
```

The checked-in catalog has **310 of 310 public builds**, synced on September 12,
2026; **140 have GitHub repository links**. Search works immediately. Source retrieval
requires indexing; source snapshots are local and excluded from Git.

Index a real example (Manus Clause Bank):

```sh
npm run index -- 43eff50f-cbd8-4e38-80cf-f1f67feab8da
```

Then start with `npm start`, or connect through an MCP client below. A stdio server
waits for protocol messages; it is not an interactive terminal prompt.

## Connect your AI client

Merge this into a client that supports `mcpServers` and stdio. Replace the path
with your absolute checkout path. Use an absolute Node executable if your desktop
client does not inherit your shell's PATH.

```json
{
  "mcpServers": {
    "legalquants": {
      "command": "node",
      "args": ["/absolute/path/to/lq/dist/src/server.js"]
    }
  }
}
```

This server locates its data relative to its installation, independent of the
client's working directory. Set `LQ_DATA_DIR` to an absolute directory to override.

Try:

> I want to build a clause bank. Search LegalQuants for relevant projects, inspect
> Manus Clause Bank, and retrieve its clause schema and extraction code. Cite the
> exact source files and tell me what is unavailable or only claimed in the listing.

## Tools

| Tool | Inputs | Returns |
| --- | --- | --- |
| `search_builds` | `query`, optional `area`, `source_only`, `limit` | Ranked builds, matching keywords, catalog coverage |
| `get_build` | `build_id` | Listing, builder, source links, indexing status, indexed file inventory |
| `search_build_content` | `build_ids` (1–5), `query`, optional `limit` | Ranked source windows with revision, line numbers and GitHub citations |
| `fetch_content` | `build_id`, `path`, `revision`, `start_line`, `end_line` | Exact excerpt at the requested indexed revision |

All tools are local and read-only. Network access occurs only in the explicit index
command. Unknown IDs/files are errors; missing indexes are disclosed rather than
invented. Source text is untrusted reference data, not agent instructions.

The server guides the AI to start with three keyword matches, inspect promising
builds, and search their source only when needed. It requests additional lines only
when existing excerpts are insufficient, then stops with concise cited evidence.
This guidance does not require calling all four tools for every question.

## Refresh data

```sh
# Import the bundled snapshot, or pass a compatible Markdown export path.
# This replaces the full catalog with the partial 30-entry export.
npm run import
npm run import -- /absolute/path/to/new-export.md

# Sync the complete public directory, validating every ID against its search index.
npm run sync

# Index selected catalog build IDs, or all entries with GitHub links.
npm run index -- 43eff50f-cbd8-4e38-80cf-f1f67feab8da
npm run index -- --all
```

An optional `GITHUB_TOKEN` environment variable increases API availability. It is
sent only to api.github.com. The current raw-file downloader supports public source;
private repository support is not implemented. Never put tokens in committed files.
Run one import/index writer at a time, with the server stopped during catalog import.
Content indexing atomically replaces the snapshot after each project; restart is
unnecessary. API failures retain any previous snapshot and record failure status.

Catalog sync reads the public page and discovers its current `loadMoreWorks` action
from the published browser bundle. It retrieves the same pages as “Older entries,”
decodes data without executing JavaScript, and checks exact unique-ID coverage before
atomic replacement. This is an undocumented website integration: site changes can
break it. An owner-provided feed remains preferable for long-term maintenance.

The index follows each repository's default branch and pins its commit SHA. Links
to subdirectories are currently normalized to the repository; branch/subdirectory
restrictions are not preserved. Text/source allowlisting excludes common generated,
upload and secret paths. Per repository: at most 100 files, 100 KB per file and
2 MB total. Truncated trees, budgets and file failures produce partial status.
These filters are not a secret scanner; only index sources suitable for your users.

## Retrieval behavior and limits

- Weighted keyword matching; no embeddings, semantic reranker or LLM calls.
- Source search returns overlapping 40-line windows, not AST-resolved functions.
- Search returns at most five excerpts; exact fetch returns at most 120 lines and
  16,000 characters. Returned line boundaries describe the actual excerpt.
- Catalog descriptions remain publisher claims. Repository licenses and README
  maturity statements can be retrieved, but are not automatically adjudicated.
- Relative dates from the export are not converted into invented publication dates.
- No remote HTTP hosting, accounts, billing, automatic sync or app execution yet.

## Development

```sh
npm run check
npm run build
npm test
```

Tests cover import completeness, six representative top-three retrieval cases,
source scoping, line bounds, URL normalization, and all four tools through a real
stdio SDK client using an isolated source fixture. These are smoke evaluations,
not evidence of broad semantic search quality. GitHub Actions runs build and tests.

`src/catalog.ts` handles normalization and discovery, `src/content.ts` handles
source excerpts, `scripts/index.ts` builds GitHub snapshots, and `src/server.ts`
exposes the MCP interface. The approved scope is recorded in [docs/design.md](docs/design.md).

Before a hosted owner pilot, replace the public-page sync with an owner-provided
feed, obtain contributor source/reuse metadata, add authenticated remote transport,
and evaluate retrieval with real lawyer tasks.

Catalog attribution: [LegalQuants Community Builds](https://www.legalquants.com/builds).
Original project authors and source links are preserved in every catalog record.