Skip to main content
Glama
README.md
# claimscope

claimscope is a thin local bridge to the ECCA hosted
MCP server, a panel-style engine for interrogating
claims and questions. Instead of trusting a single
model's answer, the upstream compares answers from its
configured engines and exposes where they disagree,
runs adversarial pre-mortems and decision tournaments,
verifies candidate answers written by other AIs, and —
for psychology, learning, nutrition, and money
questions — fetches scholarly studies and grades the
evidence behind a verdict before giving one.

The bridge itself holds no answers and grades nothing.
It serves the upstream server's tool list locally —
exactly as captured from the live endpoint — and
forwards each tool call upstream, returning the result
untouched. Some captured tool descriptions speak of
"keyed tier-quota slots"; that is the upstream's own
wording, served verbatim. This client adds no quota or
payment machinery of its own, and it sends a credential
only when you give it one (see Configuration).

## Tools

- `ecca_synthesize` — compare answers from the
  configured engines for one inquiry (`query`,
  required) and inspect the disagreement: lexical
  similarity and final-answer agreement when measurable.
  Optional: `model` (label echoed in the result),
  `depth` (one-engine fast routes through multi-engine
  deep routes), and `antagonist` to force one engine
  into a red-team role.
- `ecca_pre_mortem` — stress-test a plan or premise
  (`premise`, required) by simulating how it fails:
  failure modes and early warning indicators, checked
  with empirical argument verification. Optional:
  `horizonMonths` (default 18).
- `ecca_decision_tournament` — score discrete options
  (`options`, required) inside a decision context
  (`decisionContext`, required) using minimax regret
  and Pareto ranking.
- `ecca_bts_divergence` — measure lexical and semantic
  divergence across candidate `assertions` (required),
  penalising sycophantic near-duplicates.
- `ecca_refine` — sharpen a rough question (`text`,
  required, up to 2000 characters) without adding
  facts; returns detected niches and refinement chips.
- `ecca_research` — fetch and grade studies from
  scholarly indexes for a `question` (required),
  returning the fetched evidence and the explicit gaps.
  Optional: `niche` (`psychology`, `learning`,
  `nutrition`, or `money`).
- `ecca_verify` — independently answer a `question`
  and compare a `candidate_answer` (both required)
  against deterministic panel agreement, showing named
  dissent.
- `ecca_psychology` — a psychology `question`
  (required): refine it, fetch studies, and show named
  claims before the verdict.
- `ecca_learning` — the same evidence-and-claims
  treatment for a learning or study-skills `question`
  (required).
- `ecca_nutrition` — the same treatment for a
  nutrition or supplements `question` (required).
- `ecca_money` — the same treatment for a money or
  business `question` (required).
- `ecca_claim_protocol_validate` — check one
  ecca.claim-protocol 1.0 `document` (required) for
  shape only: versioning, engine slots rather than
  vendor names, causes drawn from the published
  taxonomy, consent for question text, and the seal.
  Returns `ok` with the error list; it validates the
  document's shape, never the record behind it.

## Configuration

- `ECCA_MCP_URL` (optional) — override the upstream
  endpoint. Defaults to `https://eccaai.com/api/mcp`.
  (The override hook is this rebuild's own labelled
  reconstruction.)
- `ECCA_API_KEY` (optional) — when set, every upstream
  request carries `Authorization: Bearer <key>`. When
  unset, no auth header is sent at all; the original
  capture this rebuild is based on was keyless. (This
  auth forwarding is this rebuild's own labelled
  reconstruction.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC `initialize`
request (protocolVersion `2025-03-26`, clientInfo name
`claimscope`), then a `notifications/initialized`
notification, then the `tools/call` request carrying
the caller's arguments unchanged. When the upstream
answers `initialize` with an `Mcp-Session-Id` header,
that value rides on every later request of the
session, which is reused for the life of the process.
Replies may arrive as plain JSON or as server-sent
events; both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `claimscope error:` (this rendering
is this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON
argument string:

```bash
npx @reneturcios/claimscope ecca_verify '{"question":"does spaced repetition work?","candidate_answer":"yes, robustly"}'
npx @reneturcios/claimscope ecca_decision_tournament '{"decisionContext":"hire or contract","options":["hire","contract","defer"]}'
npx @reneturcios/claimscope ecca_refine '{"text":"why do i forget things"}'
npx @reneturcios/claimscope --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/claimscope mcp
```

MCP client config:

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

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/claimscope
docker run --rm ghcr.io/cloudcorprecords/claimscope --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.