Qevyra

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 · Copyright © 2026 Anas Alrezej · github.com/anasrz/qevyra

Contents

• Overview

• Why

• How it works

• What QEVYRA is not

• Quickstart

• Agent scoping

• Policy

• Snapshots

• MCP

• Execution traces

• Architecture

• Benchmark

• Documentation

• Examples

• Development

• Security

• Contributing

• License

• Status

Related MCP server: mcp-nexus

Overview

        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.

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

What QEVYRA is not

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

Quickstart

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

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

• API health: http://127.0.0.1:3847/health

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:

{
  "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:

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

In qevyra.config.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:

CAPABILITY_SNAPSHOT_INVALID

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

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):

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

Or from the repo root with pnpm:

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

See docs/mcp/tools and docs/mcp/client-config 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):

Details: docs/architecture.md · System architecture (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:

pnpm benchmark

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

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

Context size (bytes, JSON):

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.

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

Examples

Development

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.

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 before connecting untrusted capabilities.

Contributing

Contributions welcome under the project license. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

QEVYRA is source-available: inspect, modify, fork, and self-host under LICENSE (Apache License 2.0 with the Commons Clause 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

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