factreason

<div align="center">
  <img src="./logo.svg" width="96" height="96" alt="FactReason Logo" />
  <h1>FactReason</h1>
  <p><strong>Reference data agents need before they write code.</strong></p>
  <p>Dependency upgrade advisories for npm and PyPI, developer API schemas across 1,097 services, and electronic component specifications — over MCP, Ed25519-signed, with optional tokenizer-measured compact responses and evidence attached.</p>
  <p><code>https://factreason.com/mcp</code> · <a href="https://factreason.com/docs">Documentation</a> · <a href="https://factreason.com/openapi.json">OpenAPI</a> · <a href="https://factreason.com/skill.md">Agent skill</a> · <a href="https://factreason.com">factreason.com</a></p>
</div>

---

## Stop an agent shipping a broken dependency upgrade

Your agent wants to bump `chalk` from 4.1.2 to 5.0.0. Before it edits `package.json`, it asks what breaks:

```
GET /api/v1/packages/npm/chalk/advisory?from=4.1.2&to=5.0.0
Authorization: Bearer <key>
```

```json
{
  "found": true,
  "packageName": "chalk",
  "fromVersion": "4.1.2",
  "toVersion": "5.0.0",
  "breakingCount": 2,
  "advisories": [
    {
      "severity": "breaking",
      "changeType": "MODULE_FORMAT_CHANGED",
      "description": "chalk 5.0.0 changed module format from \"commonjs (undeclared)\" to \"module\". CommonJS require() of this package will now fail.",
      "evidenceField": "type",
      "evidenceBefore": null,
      "evidenceAfter": "module",
      "migrationHint": "Convert the call site to import(), or pin to the last CommonJS release."
    },
    {
      "severity": "breaking",
      "changeType": "RUNTIME_REQUIREMENT_RAISED",
      "description": "chalk 5.0.0 raised its runtime requirement from \">=10\" to \"^12.17.0 || ^14.13 || >=16.0.0\". Older runtimes are no longer supported.",
      "evidenceField": "engines.node",
      "evidenceBefore": ">=10",
      "evidenceAfter": "^12.17.0 || ^14.13 || >=16.0.0",
      "migrationHint": "Confirm the deployment runtime satisfies the new floor before upgrading."
    }
  ]
}
```

Via MCP, the same question is one tool call:

```json
{
  "name": "factreason_package_upgrade_advisory",
  "arguments": { "registry": "npm", "name": "chalk", "from": "4.1.2", "to": "5.0.0" }
}
```

Set `responseFormat: "compact"` on supported heavy MCP tools to remove repeated fields and prose while retaining the facts an agent needs. Package advisories preserve `evidenceField`, `evidenceBefore`, `evidenceAfter`, and `migrationHint`. Each compact response includes `tokenMetrics` counted with `o200k_base`. The default remains `full` for compatibility, and compact output never bypasses authorization or changes the query price.

Token savings vary with the response. Metrics count one exact JSON `structuredContent` payload and include the `tokenMetrics` object itself; the matching text block remains for MCP clients that do not consume structured content yet. The private application repository also carries a repeatable `npm run benchmark:tokens` fixture so published claims can be checked before release.

**Every finding carries `evidenceField`, `evidenceBefore` and `evidenceAfter`** — the exact registry metadata field and its values either side of the change. An agent can verify the claim against npm or PyPI directly rather than taking our word for it.

An agent can call `factreason_create_key` to get its own key instantly — no human, no card, no signup. The agent can use the returned key straight away, in the same session, by passing it as the `apiKey` argument of any paid tool; no reconnect needed. A client that can set headers can put it on the MCP connection as an `Authorization: Bearer` header instead. Eligible new users may receive **up to $0.05 of one-off trial credit**, subject to grant budgets and spent at the published per-tier prices — up to about two advisory lookups, or fifty component lookups. Successful advisory lookups after that cost **$0.02 per query**. Misses are never billed and never consume trial credit. Wallet-equipped agents can pay the 402 challenge directly with x402 on Base.

---

## Connect

Streamable HTTP. No install, no package to pull.

```json
{
  "mcpServers": {
    "factreason": {
      "type": "http",
      "url": "https://factreason.com/mcp"
    }
  }
}
```

Manifest: [`/.well-known/mcp.json`](https://factreason.com/.well-known/mcp.json)

Human quickstart and workflow guidance: [`/docs`](https://factreason.com/docs). Agents can fetch the same material as Markdown from [`/docs.md`](https://factreason.com/docs.md) or use the complete index at [`/llms-full.txt`](https://factreason.com/llms-full.txt).

The container/stdio bridge accepts an optional `FACTREASON_API_KEY` environment variable and forwards it as a Bearer
credential to the same live endpoint. Tool discovery works without a key; metered lookups return HTTP 402 when neither
a key nor a valid x402 payment is supplied.

Get a key — no signup, no card:

```bash
curl -X POST https://factreason.com/api/v1/keys/create \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'
```

---

## Tools

| Tool | What it answers |
|---|---|
| `factreason_package_upgrade_advisory` | What breaks between two published npm/PyPI versions |
| `factreason_create_key` | Create a key; pass it as the `apiKey` argument of paid tools (or as a Bearer header) |
| `factreason_api_schema` | Exact request/response shape of an API endpoint at a version |
| `factreason_api_breaking_changes` | What breaks between two versions of a third-party HTTP API |
| `factreason_integration_brief` | Everything needed to write one working call to an API |
| `factreason_discover_api` | Which of 1,097 services can do X |
| `factreason_deprecation_scan` | Which endpoints are deprecated, sunset dates, replacements |
| `factreason_auth_playbook` | Auth schemes, scopes, rate-limit headers, error-code table |
| `factreason_component_spec` | Electronics component pinouts, voltages, packages |
| `factreason_subscribe_spec_changes` | Webhook or polling callback when a spec changes |
| `factreason_create_topup_link` | Stripe checkout link when credit runs out |

---

## Proof-of-Fact Signatures

Successful REST data responses and MCP tool-call responses are signed by our Ed25519 private key:

- `X-Warehouse-Proof-Signature`: Ed25519 signature of the response payload
- `X-Fact-Public-Key-Id`: Stable signing key identifier
- `X-Fact-Signature-Alg`: `EdDSA`

Public keys are published and rotated via JWKS at `https://factreason.com/.well-known/jwks.json`.

---

## Licence & Contact

MIT. Attribution requirement for APIs.guru source data: CC-BY 4.0.
Questions, support, or data reports: `hello@factreason.com`.