# Research Connector Hub

Research Connector Hub turns operator-authorized local or synthetic source records into a brief that another person can audit. Every finding links to an exact excerpt, character offset, source hash, and excerpt hash.

It is not a web scraper, an LLM summarizer, or an Apify wrapper. The default workflow performs no network requests, needs no token, emits no telemetry, and has no runtime package dependencies.

## Five-minute demo

Requirements: Node.js 22 or newer.

```bash
npm test
npm run demo
```

The demo writes four files to `demo-output/`:

- `brief.md`: human-readable findings and citations.
- `brief.json`: structured brief and source catalog.
- `evidence.json`: exact excerpts, offsets, and hashes.
- `run.json`: deterministic run ID, config hash, connector receipts, counts, and warnings.

Use the included local-data example:

```bash
node ./bin/research-hub.js run \
  --config ./examples/market-signals/research.json \
  --output ./research-output
```

## Research specification

```json
{
  "title": "Synthetic market signals",
  "question": "Which qualities appear in the supplied notes?",
  "queries": ["workflow automation", "evidence traceability"],
  "maxEvidencePerQuery": 2,
  "connectors": [
    { "type": "local-json", "path": "sources.json" }
  ]
}
```

Local paths are relative to the config file. Absolute paths, directory traversal, symlinked inputs, directories owned by another non-root user, invalid UTF-8 or malformed Unicode strings, configs above 1 MB, source files above 5 MB, aggregate local input above 10 MB, more than 1,000 raw local records, more than 10 connectors, more than 200 documents, aggregate document content above 10 MB, token-dense queries or sources, and documents above 500 KB fail closed. URL query parameters are rejected so signed or credential-bearing locators cannot enter artifacts. Local file connectors and output generation require POSIX ownership/mode checks. Output directories and artifacts are private to the current user (`0700`/`0600`).

Source records use this shape:

```json
{
  "title": "Authorized source",
  "url": "https://example.test/source",
  "content": "Exact source text.",
  "publishedAt": "2026-08-01T00:00:00.000Z",
  "sourcePolicy": {
    "license": "License or internal-use basis",
    "termsUrl": "https://example.test/terms",
    "authorizedBy": "source owner or operator"
  }
}
```

If both `sourcePolicy.license` and `sourcePolicy.termsUrl` are missing, the run records a warning. Policy metadata is never treated as proof of authorization.

## Connectors

- `mock`: deterministic synthetic records for evaluation and demos.
- `local-json`: operator-supplied JSON records, filtered locally by query terms.

Future connectors implement one bounded `collect({ query, limits, signal })` contract and return both documents and a provider receipt. See [ARCHITECTURE.md](ARCHITECTURE.md) and [COMMERCIAL_BOUNDARIES.md](COMMERCIAL_BOUNDARIES.md).

## MCP stdio adapter

```bash
node ./bin/research-hub.js mcp
```

The adapter exposes one tool, `build_research_brief`, over newline-delimited JSON-RPC stdio. It accepts inline documents only and calls the same deterministic pipeline. Input frames are capped while streaming and decoded as strict UTF-8, request IDs are bounded scalars, notifications receive no response, output is capped and backpressured, and Markdown is returned once as text rather than duplicated in structured content. It implements a tested subset of the MCP 2025-11-25 surface (`initialize`, `tools/list`, `tools/call`); it does not claim full MCP conformance.

MCP is an adapter, not the product core. The specification describes tools and structured output, while the evidence and research semantics remain application responsibilities. See the [MCP 2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25).

## Apify boundary

The project was designed after auditing Apify MCP Server, but contains no copied upstream source, credentials, telemetry keys, images, cache, or Git history. Apify can be added later as an optional connector only with explicit Actor selection, spend limits, source-policy acknowledgement, terminal run evidence, and provider cost receipts.

Apify pricing varies by Actor and can include compute, storage, proxies, transfer, per-event charges, or rental fees. Review the current [Apify pricing](https://apify.com/pricing), [Store Actor pricing models](https://docs.apify.com/actors/running/actors-in-store), and applicable terms before enabling an external connector.

## Verification

```bash
npm test
npm run lint
npm run build
npm run check:package
```

`npm run build` performs an npm package dry run because the product ships native Node.js ESM and has no compile step.

## Status

This is an MVP for product validation. It produces candidate findings from exact source sentences; it does not verify truth, resolve contradictory evidence, or replace human review.

License: MIT. See [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).