<p align="center">
  <img src="docs/assets/qevyra-mark.svg" alt="QEVYRA" width="320" />
</p>

<p align="center">
  <strong>The capability layer for AI agents.</strong><br />
  One connection. Every capability.
</p>

<p align="center">
  <a href="https://github.com/anasrz/qevyra/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/anasrz/qevyra/ci.yml?branch=main&label=CI" alt="CI" /></a>
  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
  <img src="https://img.shields.io/badge/Node-24%2B-339933?logo=node.js&logoColor=white" alt="Node.js 24+" />
  <img src="https://img.shields.io/badge/MCP-control%20plane-111111" alt="MCP" />
  <img src="https://img.shields.io/badge/tests-Vitest%20%2B%20Playwright-646CFF" alt="Tests" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Source%20Available-555555" alt="Source available" /></a>
  <a href="https://github.com/anasrz/qevyra/releases/tag/v0.1.0"><img src="https://img.shields.io/badge/release-v0.1.0-111111" alt="Release v0.1.0" /></a>
</p>

---

**QEVYRA** gives an agent one stable interface for discovering, scoping, inspecting, governing, and executing external capabilities. Downstream MCP servers, HTTP endpoints, and local tools stay behind a local runtime instead of filling the agent context with full catalogs.

Maintained by **[Anas Alrezej](https://github.com/anasrz)** · Copyright © 2026 Anas Alrezej · [github.com/anasrz/qevyra](https://github.com/anasrz/qevyra)

## Contents

- [Overview](#overview)
- [Why](#why)
- [How it works](#how-it-works)
- [What QEVYRA is not](#what-qevyra-is-not)
- [Quickstart](#quickstart)
- [Agent scoping](#agent-scoping)
- [Policy](#policy)
- [Snapshots](#snapshots)
- [MCP](#mcp)
- [Execution traces](#execution-traces)
- [Architecture](#architecture)
- [Benchmark](#benchmark)
- [Documentation](#documentation)
- [Examples](#examples)
- [Development](#development)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)
- [Status](#status)

## Overview

```text
        AI Agent
            |
            |  intent / tool call
            v
       +-----------+
       |  QEVYRA   |
       +-----------+
            |
    +-------+-------+-------+
    |       |       |       |
   MCP     HTTP    LOCAL   registries
 servers   APIs    tools   (npm, PyPI, official MCP)
```

Large tool catalogs create unnecessary context, difficult configuration, stale metadata, unclear permissions, and fragile execution. QEVYRA **resolves capabilities when they are needed** instead of forcing the agent to manage every downstream tool directly.

<p align="center">
  <img src="docs/assets/architecture.svg" alt="QEVYRA architecture" width="640" />
</p>

## Why

Agent hosts that attach many MCP servers at once pay a steady cost: schemas and descriptions accumulate even when the current task needs only a few capabilities. That leads to:

- **Context overhead** — full tool lists in every turn
- **Selection noise** — ranking over hundreds of similar tools
- **Capability sprawl** — duplicate or overlapping registrations
- **Per-agent exposure** — research and coding agents seeing the same catalog
- **Permission ambiguity** — unclear which tool may run without review
- **Stale schemas** — catalogs changing between selection and invocation
- **Unreliable execution** — health and policy checked too late
- **Hard debugging** — scattered logs across servers

QEVYRA keeps a **local index** (SQLite + FTS5), exposes a **small MCP surface** to the agent, and enforces **scope, policy, health, and snapshots** at execution boundaries.

## How it works

<p align="center">
  <img src="docs/assets/resolve-flow.svg" alt="Intent to trace" width="620" />
</p>

| Stage | Role |
| --- | --- |
| **Intent** | Natural-language or structured request from the agent |
| **Discover** | FTS5 + BM25 search over the local capability index |
| **Resolve** | Hybrid ranking with explainable reasons (`qevyra resolve`, `POST /api/resolve`) |
| **Scope** | Optional per-agent allow-lists (`agents[]` in config) |
| **Policy** | `allow` / `ask` / `deny` before execution |
| **Health** | Lifecycle gates (connected, authorized, circuit state) |
| **Snapshot** | Schema hash from `inspect_capability` bound to execute |
| **Execute** | Downstream MCP or configured handler |
| **Trace** | Persisted run row (duration, decision, redacted errors) |

## What QEVYRA is not

| | QEVYRA | Typical alternative |
| --- | --- | --- |
| Role | Capability **runtime** between agent and tools | Single MCP server, marketplace, or agent framework |
| Agent interface | Four MCP tools | Entire downstream tool surface |
| Discovery | On-demand from local index | Preloaded global catalog |
| Governance | Policy + scope + snapshots at execute | Ad hoc host settings |

QEVYRA complements MCP servers and agent frameworks; it does not replace them.

## Quickstart

**Requirements:** Node.js **24+**, pnpm **9+**.

```bash
git clone https://github.com/anasrz/qevyra.git
cd qevyra
pnpm install
pnpm build
pnpm exec qevyra init --demo
pnpm dev
```

- Web UI: [http://127.0.0.1:3848](http://127.0.0.1:3848)
- API health: [http://127.0.0.1:3847/health](http://127.0.0.1:3847/health)

```bash
pnpm exec qevyra search "github issue"
pnpm exec qevyra resolve "create github issue"
pnpm exec qevyra connect qevyra-demo
pnpm exec qevyra execute demo.calculator.add --args '{"a":2,"b":3}' --yes
pnpm exec qevyra doctor
pnpm exec qevyra runs --json
```

Copy `qevyra.config.example.json` to `qevyra.config.json` for a starting config (local file; not committed).

## Agent scoping

Optional **agent scopes** restrict which capability patterns appear in search, resolve, inspect, execute, API, and MCP when `agentId` is set:

```json
{
  "agents": [
    {
      "id": "researcher",
      "allowed": ["web.search", "browser.*", "github.search"]
    },
    {
      "id": "developer",
      "allowed": ["filesystem.*", "git.*", "github.pull_request"]
    }
  ]
}
```

Unknown agent IDs are denied when any agents are configured. Omit `agentId` for the full indexed catalog (subject to policy).

## Policy

Policies map glob patterns to decisions enforced at execution boundaries:

```yaml
capabilities:
  github.create_issue:
    permission: allow
  filesystem.write:
    permission: ask
  github.delete_repository:
    permission: deny
```

In `qevyra.config.json`:

```json
{
  "policies": {
    "demo.github.create_issue": { "permission": "allow" },
    "filesystem.write": { "permission": "ask" },
    "github.delete_repository": { "permission": "deny" }
  }
}
```

Destructive capability IDs default toward **deny** unless explicitly allowed.

## Snapshots

After **resolve**, call **inspect** to obtain a snapshot (capability id, version, **schema hash**). Pass that snapshot into **execute**. If the live schema changed:

```text
CAPABILITY_SNAPSHOT_INVALID
```

Re-inspect, then execute. This is **local consistency** for your runtime—not distributed locking across every MCP server.

```text
resolve → inspect (snapshot) → execute → schema changed → CAPABILITY_SNAPSHOT_INVALID
```

## MCP

QEVYRA runs an MCP **server** toward your agent (stdio in this release) and MCP **clients** toward registered downstream servers.

**Tools exposed to the agent:** `discover_capability`, `inspect_capability`, `execute_capability`, `capability_status`.

From a built clone (portable paths):

```json
{
  "mcpServers": {
    "qevyra": {
      "command": "node",
      "args": ["packages/cli/dist/bin.js", "serve"]
    }
  }
}
```

Or from the repo root with pnpm:

```json
{
  "mcpServers": {
    "qevyra": {
      "command": "pnpm",
      "args": ["exec", "qevyra", "serve"],
      "cwd": "/path/to/qevyra"
    }
  }
}
```

See [docs/mcp/tools](apps/web/content/docs/mcp/tools.mdx) and [docs/mcp/client-config](apps/web/content/docs/mcp/client-config.mdx) in the web docs.

## Execution traces

Runs are stored locally with correlation IDs, policy decisions, durations, and redacted errors. Use `qevyra runs --json` or `GET /api/runs` for inspection—without echoing secrets from downstream tools.

## Architecture

Monorepo layout (high level):

| Package / app | Role |
| --- | --- |
| `@qevyra/shared` | Types, errors, snapshots |
| `@qevyra/config` | `qevyra.config.json` schema |
| `@qevyra/storage` | SQLite + FTS5 |
| `@qevyra/registry` | Registry providers |
| `@qevyra/search` | Ranking + hybrid resolver |
| `@qevyra/policy` | Policy + agent scope |
| `@qevyra/runtime` | Execute, circuit breaker, demo seed |
| `@qevyra/mcp` | Four-tool MCP server |
| `@qevyra/cli` | CLI and shared service context |
| `apps/api` | Hono HTTP API |
| `apps/web` | Landing, dashboard, MDX docs |

Details: [docs/architecture.md](docs/architecture.md) · [System architecture](apps/web/content/docs/architecture/system.mdx) (on-site docs after `pnpm dev`).

## Benchmark

**Synthetic local benchmark** — seeded catalog (1000 capabilities) and aligned queries. Measures the local resolver, not third-party agent hosts.

Run:

```bash
pnpm benchmark
```

Output: `benchmarks/results/latest.json` (gitignored; regenerate locally).

Example results from a recent local run (58 tasks, catalog size 1005):

| Metric | Value |
| --- | --- |
| Recall@1 | 98.3% |
| Recall@3 | 98.3% |
| Recall@5 | 98.3% |
| MRR | 98.3% |
| Resolve top-1 | 98.3% |
| Search latency p50 / p95 | 9.4 ms / 11.6 ms |
| Resolve latency p50 / p95 | 10.6 ms / 11.8 ms |

**Context size (bytes, JSON):**

| Mode | Size |
| --- | --- |
| Naive full catalog | 83,035 |
| QEVYRA top-5 discover cards | 381 |

Do not treat these figures as production agent performance; they characterize this repository’s benchmark harness only.

## Documentation

After `pnpm dev`, browse [http://127.0.0.1:3848/docs](http://127.0.0.1:3848/docs).

| Topic | Path |
| --- | --- |
| Quickstart | `/docs/getting-started/quickstart` |
| Architecture | `/docs/architecture/system` |
| MCP | `/docs/mcp/overview` |
| Configuration | `qevyra.config.example.json` |
| Security | `/docs/security/threat-model` |
| API | `/docs/reference/api` |
| CLI | `/docs/reference/cli` |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |

**Social preview:** upload [docs/assets/social-preview.svg](docs/assets/social-preview.svg) (1280×640) in GitHub repository settings if desired.

## Examples

| Path | Purpose |
| --- | --- |
| [examples/basic-agent](examples/basic-agent) | Minimal agent integration |
| [examples/mcp-server](examples/mcp-server) | Demo downstream MCP server |
| [examples/custom-capability](examples/custom-capability) | Manual capability registration |

## Development

```bash
pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e    # requires production web on :3848; see Playwright config
pnpm benchmark
```

Package structure and expectations: [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

QEVYRA runs on your machine with your privileges. It provides **policy boundaries**, **risk signals** (`qevyra audit`), **secret redaction** in traces, and **user approval** for sensitive flows—it does **not** sandbox arbitrary third-party code or certify MCP packages as safe.

Read [SECURITY.md](SECURITY.md) before connecting untrusted capabilities.

## Contributing

Contributions welcome under the project license. See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## License

QEVYRA is **source-available**: inspect, modify, fork, and self-host under [LICENSE](LICENSE) (Apache License 2.0 with the [Commons Clause](LICENSE) restriction). This is **not** an OSI-approved open source license. Commercial resale of QEVYRA itself or a substantially similar product derived from it is not permitted under the default terms.

## Status

| | |
| --- | --- |
| **Current release** | v0.1.0 |
| **Stability** | Early public release (pre-1.0) |
| **Upstream MCP serve** | stdio in this release; downstream streamable HTTP client supported |

Known limitations: no cryptographic sandbox for third-party tools; benchmark is synthetic; some registry providers depend on network and local configuration.