# Clearon Legislation Monitor MCP

MCP server for review-gated U.S. legislation discovery and watchlist monitoring.

It separates discovery leads from verified watchlist entries, records append-only observations and exceptions, and keeps official-source review in the loop before a measure becomes authoritative.

## What it does

- Records discovery candidates without silently promoting them into the watchlist
- Requires explicit human review before watchlist acceptance
- Tracks official-source observations, due reviews, and retrieval exceptions
- Replays an append-only event log into a rebuildable snapshot
- Optionally uses Open States and NYC Legistar as discovery helpers, never as final proof

## What it does not do

- It does not publish content or modify WordPress
- It does not treat a keyword hit as legal verification
- It does not treat third-party discovery results as source-of-record status
- It does not convert retrieval failures into legal-status changes

## Requirements

- Node.js `20` or newer
- A local MCP client that can launch a stdio server

## Installation

```sh
cd tools/clearon-legislation-monitor-mcp
npm install
npm test
npm run smoke
```

## MCP client setup

Example stdio configuration:

```json
{
  "mcpServers": {
    "clearon-legislation-monitor": {
      "command": "node",
      "args": ["/absolute/path/to/clearon-legislation-monitor-mcp/server.mjs"],
      "env": {
        "CLEARON_LEGISLATION_WORKSPACE": "/absolute/path/to/workspace"
      }
    }
  }
}
```

If your normalized tracker inputs are not in the default workspace locations, also set:

- `CLEARON_LEGISLATION_REGISTRY_PATH`
- `CLEARON_LEGISLATION_WATCHLIST_PATH`

## Storage

By default, monitor state is stored outside the repository in a user data directory:

- macOS: `~/Library/Application Support/clearon-legislation-monitor-mcp/legislation-monitor`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/clearon-legislation-monitor-mcp/legislation-monitor`
- Windows: `%APPDATA%\\clearon-legislation-monitor-mcp\\legislation-monitor`

Override that location with `CLEARON_LEGISLATION_MONITOR_ROOT`.

The canonical tracker inputs are still expected to come from your chosen workspace:

- `trackers/state-legislation/jurisdictions.json`
- `trackers/state-legislation/watchlist.csv`

unless you override them explicitly with environment variables.

## Credentials

Optional provider keys can be supplied directly in the environment:

- `OPENSTATES_API_KEY`
- `NYC_LEGISTAR_TOKEN`

The server also supports an optional local secrets file. By default it looks for:

- macOS: `~/Library/Application Support/openclaw/local-secrets.json`
- Linux: `${XDG_CONFIG_HOME:-~/.config}/openclaw/local-secrets.json`
- Windows: `%APPDATA%\\openclaw\\local-secrets.json`

Override that path with `OPENCLAW_LOCAL_SECRETS`.

Install or rotate stored credentials through protected stdin so values stay out of shell history:

```sh
node bin/install-credentials.mjs < /path/to/private-credentials.json
npm run credentials
```

Supported JSON keys:

```json
{
  "openstatesApiKey": "provider-issued value",
  "nycLegistarToken": "provider-issued value"
}
```

## Recommended workflow

1. Call `list_jurisdictions` to choose the official route.
2. Use `scan_official_source`, `search_openstates_bills`, or `search_nyc_legistar_matters` to gather leads.
3. Record plausible official-source measures with `record_discovery_candidate`.
4. Review each candidate and call `review_candidate` with `accept` or `reject`.
5. Record official observations with `record_measure_observation`.
6. Use `get_due_reviews` and `get_exceptions` for scheduled follow-up.

## Tools

- `get_server_health`
- `list_jurisdictions`
- `scan_official_source`
- `search_openstates_bills`
- `search_nyc_legistar_matters`
- `record_discovery_candidate`
- `list_discovery_candidates`
- `review_candidate`
- `import_normalized_watchlist`
- `list_watchlist`
- `record_measure_observation`
- `dedupe_watchlist_measures`
- `record_exception`
- `resolve_exception`
- `get_due_reviews`
- `get_exceptions`
- `verify_event_log`

## Development

```sh
npm test
npm run smoke
npm run syntax
```