magist-mcp-server

# @magist/mcp-server

Connect [Magist](https://magist.io) to your AI host over the Model Context
Protocol. Magist is an open, deterministic, cited **reference** for product
regulation: which laws apply to a product, the obligations and Controls they
imply, and the primary sources behind each. Open data (CC BY-SA 4.0), a
deterministic engine (same inputs produce the same outputs, no LLM in the path),
permanent citation URLs, and a named-practitioner attribution on every response.

This package is a thin **stdio bridge** to the hosted server at
`https://magist.io/api/mcp`. Remote-capable hosts can skip it and point straight
at that URL.

## Offline receipt integrity

The separate [receipt-v9 content-integrity utility](docs/receipt-integrity.md) checks a saved JSON body hash using only Node built-ins. It makes no network call and does not run the engine or authenticate the sender. Its synthetic tests and source are separate from the published bridge and plugin payloads.

## Research plugin packages (experimental previews)

This repository also contains the separate **magist-research 0.1.1** portable
plugin: root `plugin.json`, the remote connection in `mcp.json`, and a newly
authored workflow in `skills/magist-research/`. It connects directly to the
public HTTPS service and does not run the npm stdio bridge.

The portable connection uses only `type` and `url`, as allowed by the
[Agent Plugins 1.0.0 MCP schema](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json).
The endpoint requires no authentication. The schema does not admit the
server-level authentication extensions shown in some host-specific examples;
those extensions are omitted here. Schema validation alone does not establish
that a host can install and run the complete plugin.

Create its bounded source package with Python 3.9 or newer:

```bash
python3 scripts/package-plugin.py --output /absolute/new/path/magist-research-0.1.1.zip
```

The ZIP includes the two portable manifests, the skill and its MCP
dependency declaration, an existing public Magist icon, and this repository's MIT license. It excludes
the bridge executable, dependencies, private platform source and assets. The
plugin version is independent of `@magist/mcp-server@0.1.1`.

This is a proposed integration package, not an accepted directory listing or a
host validation certificate. Public submission uses OpenAI's
[With MCP route](https://developers.openai.com/plugins/deploy/submission);
publisher verification, actual host/reviewer cases, media, any required visual
assets, connection checks and submission review remain separate requirements.
See the [portable package format](https://developers.openai.com/plugins/build/plugins).

OpenAI listing metadata and five positive/three negative reviewer scenarios
are included in `plugin.json`. Those are proposed host cases, not records of
completed installed-plugin runs. A reviewer video is not yet supplied; the
website demo is not an installed-plugin walkthrough.

### Claude plugin and optional Desktop bundle

The Claude plugin lives at `integrations/claude`. It uses Claude's separate
`.claude-plugin/plugin.json` and `.mcp.json` format, pins its reviewed Claude
skill bytes, and connects to the same hosted endpoint. Version 0.1.2 adds an
explicit audience, bounded research work shape, evidence-confidence bands and
escalation rules, retaining the illustrative lookup and response template.
These design controls do not establish unconditional framework readiness,
installed-host behavior or directory acceptance. The shared OpenAI skill and optional
Desktop bundle remain separate, unchanged artifacts. Its clean
subfolder excludes this repository's top-level `bin/`, which chat and Cowork
do not accept in a plugin. Build both artifacts without installing dependencies:

```bash
python3 scripts/package-claude.py --kind plugin --output /absolute/new/path/magist-claude-plugin-0.1.2.zip
python3 scripts/package-claude.py --kind desktop --output /absolute/new/path/magist-desktop-0.1.1.mcpb
```

The `.mcpb` embeds the exact dependency-free published 0.1.1 bridge and requires
Node.js 18 or newer. It is unsigned and for private Desktop testing. Claude's
current directory no longer accepts Desktop MCPB listings. For public review,
submit the remote MCP connector and the `integrations/claude` plugin folder as
two linked submissions from the same intended publisher organization. See
[Claude's current directory routes](https://claude.com/docs/directory/publish).
No package here implies installation, portal validation, acceptance or a
completed Claude workflow.

> **Beta: content under attorney review.** The server is live and the engine is
> stable; substantive attorney review of the regulation corpus is in progress.
> Entries carry a `contentReviewStatus` field (`reviewed` is human-verified,
> `draft` is AI-prepared and pending review). Magist returns legal **information**
> for research and attorney handoff, **not legal advice**. Consult a licensed
> attorney before relying on any output for a launch decision.

## One-line install

**Claude Code (CLI)** uses the remote transport directly (no npm install):

```bash
claude mcp add --transport http magist https://magist.io/api/mcp
```

**Claude Desktop / Cursor / Windsurf (npx)**: add the bridge to the host's
`mcpServers` config:

```json
{
  "mcpServers": {
    "magist": {
      "command": "npx",
      "args": ["-y", "@magist/mcp-server"]
    }
  }
}
```

- **Claude Desktop:** Settings -> Developer -> Edit Config (`claude_desktop_config.json`). Restart Claude after saving.
- **Cursor:** Settings -> MCP -> Add new server, or edit `~/.cursor/mcp.json`.
- **Windsurf:** edit `~/.codeium/windsurf/mcp_config.json`, then reload.
- **Codex:** add to `~/.codex/config.toml`:

  ```toml
  [mcp_servers.magist]
  command = "npx"
  args = ["-y", "@magist/mcp-server"]
  ```

**ChatGPT (Developer Mode / Connectors), Manus, and other remote-capable hosts:**
add a custom connector pointing at the Streamable-HTTP endpoint
`https://magist.io/api/mcp` (no npm package needed).

## Verify it works

A `200` with `name: "magist"` means the endpoint is live:

```bash
curl -s https://magist.io/api/mcp
```

List the tools (you should see nine):

```bash
curl -s -X POST https://magist.io/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

In your host, once connected, ask Magist to look up COPPA and list its Controls.
A working connection returns a cited regulation record, not a refusal or a
no-such-tool error.

## Tools

| Tool | What it returns |
| --- | --- |
| `lookup_regulation(id)` | One regulation's structured record: citation, jurisdiction, status, review dates, plain-language summary, and the Controls that may satisfy it. |
| `search_regulations(query, filters?)` | Deterministic keyword + filter search over the corpus, with permanent citation URLs. |
| `compute_requirements(features, markets, audiences, businessModel?)` | Runs the deterministic engine: triggered regulations + Controls, complexity tier, blocker count, per-audience breakdown. Creates or refreshes an idempotent public receipt-report link retained for up to 90 days; use only nonconfidential public or synthetic inputs. |
| `find_controls(regulationId)` | Controls that may satisfy a regulation, each with a priority signal and summary. |
| `find_vendors(controlId, jurisdiction?)` | Vendors and in-house approaches that implement a Control, with effort/cost and a source disclosure. Magist does not accept payment from vendors. |
| `get_enforcement(regulationId?, since?, limit?)` | Recent enforcement actions with penalties, authorities, and primary-source links. |
| `find_counsel(jurisdiction, practiceArea?, language?)` | Open counsel directory by jurisdiction and practice area. Inclusion is not endorsement. |
| `list_feature_catalog()` | The closed feature, market, and audience identifiers accepted by `compute_requirements`, so agents can validate inputs before analysis. |
| `verify_ai_answer(token)` | Verifies a signed Magist grounding-proof token from the REST API. It proves what Magist served, not legal correctness or applicability. |

Eight tools read the public corpus or verify a grounding-proof signature.
`compute_requirements` additionally persists the public receipt report described
above. Access is unauthenticated and subject to server rate limits; do not send
personal, confidential or privileged information. Tool-call telemetry may be
recorded. The bridge package license does not license the hosted platform.

## Self-hosting

Set `MAGIST_MCP_URL` to point the bridge at your own deployment of the open
corpus and engine:

```json
{
  "mcpServers": {
    "magist": {
      "command": "npx",
      "args": ["-y", "@magist/mcp-server"],
      "env": { "MAGIST_MCP_URL": "https://your-host.example.com/api/mcp" }
    }
  }
}
```

## For host LLM developers

Every tool response is wrapped in a canonical envelope. When you render a Magist
response to a user: render the `disclaimer.text` field verbatim; do not restate
outputs as directives or conclusions; surface the `practitioner` attribution and
the `verification` field; suggest a licensed attorney when `counsel_recommended`
is `true`; and prefer the `citations` links when you summarize.

## Links

- Docs: https://magist.io/mcp
- Open-data hub: https://magist.io/data
- License (this package): MIT. The corpus is CC BY-SA 4.0.