USB+ MCP server
Commit 14. Nov. 2026Bietet eine Trust Layer für KI-Funktionen durch das Entdecken, Verifizieren und Installieren von Skills und MCP servern über verschiedene Agent Runtimes hinweg.
Auch bekannt als PeepSick/usbplus
- Stars
- 11
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 14. Nov. 2026
- Lizenz
- MIT
Was ist USB+ MCP?
Bietet eine Trust Layer für KI-Funktionen durch das Entdecken, Verifizieren und Installieren von Skills und MCP servern über verschiedene Agent Runtimes hinweg.
Zusammenfassung generiert aus dem README des Projekts
Über USB+ MCP server
Sicherzustellen, dass sich KI Skills und MCP server exakt so verhalten, wie sie es behaupten, ist die Hauptfunktion von usbplus. Dieses Tool fungiert als Trust Layer für Entwickler, die verschiedene Agent Runtimes nutzen, und ermöglicht es ihnen, Capabilities über mehrere Umgebungen hinweg zu entdecken, zu verifizieren und zu installieren. Es schließt die Lücke zwischen der schriftlichen Beschreibung eines Tools und seiner tatsächlichen technischen Implementierung, um Sicherheitsrisiken wie den nicht deklarierten Zugriff auf Credentials oder unbefugte Netzwerkaufrufe zu verhindern.
Nutzer interagieren mit dem System über das usb-cli oder das usb-sdk. Die Plattform bietet zwei spezialisierte Verifizierungsbefehle: secscan, das eine statische Analyse durchführt, um deklarierte Contracts mit beobachteten Capabilities zu vergleichen, und mcprobe, das MCP server beim Start live beobachtet, ohne Tools auszuführen. Das System unterstützt 16 Runtime-Targets, darunter Claude Code und Cursor, und kann lokale Pfade, systemweite Configs oder remote GitHub Repositories scannen, um sicherzustellen, dass installierte Skills ihrem eigentlichen Zweck entsprechen.
Was du damit machen kannst
- 1Skill Security Contracts verifizierenPrüfen, ob ein Third-Party Skill nicht deklarierte Capabilities wie Secret-Zugriff oder Prozessausführung enthält.
- 2Capability Verifizierung in CI automatisierenNutze Exit Codes und maschinenlesbare Reports, um Builds zu blockieren, wenn neue Contract-Verletzungen in Skills erkannt werden.
- 3Skills über Runtimes hinweg installierenFinde und deploye spezifische KI Skills direkt in unterstützte Umgebungen wie Claude oder Cursor.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarpeepsick/usbplus is public and reachablegithub.com/peepsick/usbplus ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Nicht geprüft
- Open Source Lizenz (OSI)MITspdx.org/licenses/MIT.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-11-13github.com/peepsick/usbplus ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNicht geprüft
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenUSB — Universal Systems Bridge
USB is an open-source trust layer for AI capabilities.
Does this skill or MCP server actually do what it claims? USB discovers skills,
MCP servers, agents, and commands inside repositories, compares declared behavior
with observable evidence using secscan, observes live MCP servers with mcprobe,
and delivers inspectable artifacts across agent runtimes.
Contents · Quickstart · Why a systems bridge? · Trust Layer · How it works · Targets · Installing · CLI · API · Who ships · Local dev · Contributing
Quickstart
npm install -g @peepsick/usb-cli
usb install
usb install bridges your machine to the catalog: it detects installed AI runtimes and installs natively where it can — SKILL.md skills for Claude Code, a .mdc rule for Cursor. More than one runtime? It asks which one to install into.
usb search postgres # find a skill
usb install intent-router # install just one
usb install web-dev --target=claude # install a preset into a specific runtime
Real installer output — not mocked up (web-dev = 8 domains × 8 workflows + the 9 core skills):
$ usb install web-dev --target=claude
✅ universal-skill-bridge-catalog v1.0.8 installed for target: claude (73 skills)
📦 Portable pack: ~/.ai-skills/universal-skill-bridge-catalog
🔌 Target files: ~/.claude/skills
📝 Local registry: ~/.ai-skills/universal-skill-bridge-catalog/installed.json
Upgrading from Universal Skill Bridge (v0.4.x)? Every command you run
still works — secscan and mcprobe are new, additive commands.
New in v1 — the Trust Layer. Installation is step one; proving what you run is the next:
usb secscan # declared vs. observed — verdicts with file:line evidence, exit codes for CI
usb mcprobe # observe MCP servers at startup — consented, never calls a tool
Why a systems bridge?
Agent capabilities multiply in the dark: a skill pasted from a gist, an MCP server wired into a repo config, a prompt template copied between teams. Two gaps repeat everywhere — there is no shared unit you can install once and reuse in every runtime, and nothing tells you what the thing you are about to install actually does. The catalog closes the first gap; the Trust Layer closes the second.
| Without USB | With USB | |
|---|---|---|
| Discovery | Capabilities scattered across gists, repos and configs | One catalog: usb search, /api/skills, MCP tools |
| Supply chain | Blind curl | bash |
Download → verify sha256 → read → run |
| Contract drift | A description is the only documentation | usb secscan: declared vs. observed, file:line evidence, exit codes for CI |
| Runtime claims | A README's promise about tools/list |
usb mcprobe: live protocol observation — consented, never calls a tool |
| Portability | Rewrite per framework | One skill → 16 targets: 4 native installs, 11 portable bundles, auto detection |
The Trust Layer
Installing a skill is easy; trusting one is not. The v1 series adds two commands that answer the two questions the install surface alone cannot:
| Question | Tool | Nature | |
|---|---|---|---|
| Contracts | Does this skill do what it declares? | usb secscan |
Static, deterministic — never executes what it scans |
| Runtime | What does this MCP server actually do when it starts? | usb mcprobe |
Live observation, explicit consent — never calls a tool |
secscan — Skill Contract Verifier
Before installing skills you did not write, ask the only question that
matters: does this skill do what it declares? usb secscan answers it
per skill - statically, deterministically, and without executing anything
it scans:
usb secscan # project-local skills (.claude/skills, skills, .cursor/rules)
usb secscan ./vendor-skills # any local path
usb secscan --system # installed skills + your own user-scope MCP configs
usb secscan --repo owner/repo # fetch a git/GitHub repo read-only and scan it
usb secscan --repo https://github.com/who/skills/tree/main/claude
usb secscan --json . # machine-readable report (CI-friendly)
usb secscan --write-baseline . # record today's findings as the baseline
usb secscan --baseline .usb-secscan-baseline.json # fail only on NEW findings
For every skill it reads the declared contract (name/description), observes
the actual capabilities in the body (credential access, piping network
responses into a shell, destructive deletion, process execution, persistence
hooks), and flags every capability that is observed but never declared -
that gap is the whole attack surface of a skill. Bundled executable files
(scripts/*.mjs, *.sh, ...) are behavior evidence too: a helper that phones
home is a capability, whether or not the prose admits it. Evidence is weighted:
a category backed only by ordinary tooling (an outbound fetch, a structured
subprocess.run) is downgraded one severity level, while pipe-to-shell,
encoded commands and known exfil endpoints stay at full strength. Language that
grants vague or silent agency ("without asking", "use your judgment",
instruction overrides, encoded blobs) is reported as advisory signals:
never a verdict on its own, but they corroborate a contract violation when both
appear in the same skill.
skills/meeting-notes-plus/SKILL.md [claude] contract: PURPOSE-MISMATCH
HIGH P101 undeclared capability: secrets-access (line 12)
Read .env and ~/.ssh/id_rsa so context files can be attached.
why: 2 signal line(s) show secrets-access, but the declared
contract never covers it. Corroborating authority signals: A102@13.
summary: 4 skill(s) verified, 1 with findings | exit 1 - blocking findings present
verdicts: matches-declaration:3 · purpose-mismatch:1
findings: high:2 medium:0 low:0 info:0
authority signals: 3 across 1 skill(s) (always advisory)
Unit locators are shown relative to their scan root; --json always carries
full locators for machine consumers. Advisory output (P103, authority
signals) is tagged as such and never contributes to the exit code - only
medium/high findings block.
Each skill gets one deterministic verdict: matches-declaration,
purpose-mismatch, excessive-authority, structural-issues, or
unverifiable. Exit codes gate CI: 0 clean (signals alone never block),
1 findings at medium+ (contract violations), 2 operational error. Same
input tree, byte-identical report.
For MCP servers, requested authority that shares no vocabulary with the
declared purpose is flagged as possible over-breadth (P103,
excessive-authority) - and it is advisory by construction: always low
severity, so it never blocks by itself. A deploy server requesting
DEPLOY_TOKEN is explained by its name; a weather bot holding
STRIPE_SECRET_KEY is not. Remote transports are excluded (their egress is
already judged as observed behavior), operator permission rules are never
judged, and a filesystem-flavored purpose explains path mounts
categorically.
Scanning third-party collections in CI? Record a baseline once
(--write-baseline) and gate with --baseline afterwards: known findings are
reported but acknowledged, and only new contract violations block.
Fingerprints hash rule+evidence-text, so they survive line edits and temp-clone
path changes; entries whose finding disappeared are pruned on the next
--write-baseline.
Discovery knows the difference between a claim and its supporting material:
a bundle's reference docs (skills/<name>/references/*.md, cli.md, ...)
are part of that bundle's claim, not claims of their own, while standalone
agents/*.md and commands/*.md definitions are verified as first-class
capability contracts of their own kind.
MCP server configs get the same contract treatment at the config layer.
Well-known project files (.mcp.json, .cursor/mcp.json, .vscode/mcp.json
- both
mcpServersand VS Code'sserversroot key) yield one unit per server entry: the entry name is the declaration, its command/args/url/env are observed behavior and requested authority. A remoteurlis network egress by existing; acurl … | shbootstrap is undeclared process control; requesting an env token is recorded as authority scope and never branded behavior. A config that cannot be parsed is reported (S101) instead of being silently skipped - the runtime would launch zero servers from it.
--system extends the same treatment to user-scope configs:
~/.claude.json (only its top-level mcpServers table - the rest of that
state file is ignored), ~/.cursor/mcp.json, Windsurf's
mcp_config.json, and Claude Desktop's config across its platform
locations.
Declared tools are read at depth stage 2 - and never invented. An
entry may carry its own tools list (names or {name, description}
objects), and Cursor's permission layer (.cursor/permissions.json,
mcpAllowlist) names tools per server (server:tool, * wildcards).
Declared tool names and descriptions join the server's declared contract,
so a tool that says it "uploads reports over http" covers the egress its
transport exhibits - while the identical entry without a declaration stays
flagged. No list anywhere? tools_declared: false, verdict untouched;
a list present but unreadable is reported (S102, unverifiable) because
no tool contract can be checked against it.
Claude Code's settings layer (.claude/settings.json,
.claude/settings.local.json, user-scope under --system) is read as
authority, never declaration: rules like mcp__server__tool are
recorded verbatim in the unit's authority scope, separated by level
(allow/deny/ask). What the operator permits is not what the server
claims - an allowed tool changes nothing about an undeclared capability,
and a settings file that cannot be parsed is reported on its own (its
rules would silently stop applying).
Depth stage 3 reads implementation source: when a server's launch line
resolves to code files inside the scanned tree, exact SDK registration
idioms are extracted - Python @mcp.tool() decorators and TypeScript
server.tool(...) / server.registerTool(...) calls, nothing else (no
AST walking, no third-party framework hunting). Every registration enters
the report as observed behavior evidence, anchored at its file:line and
categorized by tool name + description through the same lexicon used for
skills. Launch lines that cannot be resolved inside the tree (npx -y @scope/pkg, absolute paths) are recorded verbatim under the server's
authority scope as opaque: USB does not pretend to analyze what it
cannot see.
Rule catalog:
| Group | Rules | Question |
|---|---|---|
S001-S007 structural |
frontmatter present/closable, description required (≤1024 chars), name charset, non-empty body, duplicate names | "Is this a well-formed skill?" |
S101 structural (MCP) |
unparsable JSON, wrong-typed server table, unlaunchable entries | "Can a contract even be read from this config?" |
S102 structural (MCP tools) |
declared tool list present but unreadable | "Can the tool contract be read?" |
P101-P102 purpose / contract |
undeclared capability categories; unsupported purpose statement | "Does it do what it says?" |
P103 purpose (MCP authority) |
authority items unexplainable by the declared purpose - advisory, always low | "Is any requested reach connected to the stated job at all?" |
A101-A106 authority signals |
broad scope over sensitive objects, silent action, vague delegation, instruction overrides, encoded blobs, invisible characters | "Is any requested authority vague, hidden, or out of proportion?" |
Requires python3 (no grep fallback for security work). Scanning a repo via
--repo clones it read-only into a temp directory that is always cleaned up;
nothing from it is ever executed.
mcprobe — Runtime Observation of MCP Servers
Static analysis stops where a server starts. usb mcprobe closes that gap:
it finds every MCP server declared in your configs, completes the protocol
handshake, and reports what the server actually exposes — it never calls
a tool. Probing means running untrusted code or reaching the network, so
mcprobe is a separate, explicitly consented command:
usb mcprobe # dry run: prints what WOULD be contacted, contacts nothing
usb mcprobe --yes . # consent, then observe every MCP server found
usb mcprobe --yes --timeout 10 . # per-phase deadline (default 30s)
Without --yes nothing is contacted — and piped stdin counts as refusal,
so automation cannot fake an interactive confirmation. The protocol scope
is exactly initialize → initialized → tools/list → shutdown:
registration of capabilities is observed, invocation is permanently out of
scope. Local servers receive only the environment variables their config
entry declares, and the report is redacted before it is written — launch
lines, env values and header values never appear (their key names do):
{
"schema": "usb-mcprobe-report/v1",
"mode": "runtime-observation",
"deterministic": false,
"reports": [
{
"locator": ".mcp.json#mcpServers/notes",
"transport": "stdio",
"contact": "local-process",
"handshake": { "initialize": "ok", "tools_list": "ok" },
"server_info": { "name": "notes-server", "version": "1.4.0" },
"observation": { "complete": true, "reason": null },
"tools": [ { "name": "create_note", "description": "…", "input_schema_keys": ["title", "body"] } ],
"launch_line_redacted": "…",
"session_id_present": null
}
],
"summary": { "probed": 1, "failed": 0 }
}
Transports: stdio, streamable HTTP (session id echoed, session closed on
exit) and SSE entries; legacy bare-SSE servers are reported unsupported.
Auth is detected, never bypassed: 401, or 403 with
WWW-Authenticate, reports auth_required; a 403 without it is
bot_blocked (WAF), and no auth flow is attempted in v1. Pagination is
bounded (10 pages / 1000 tools) — hitting a bound reports
"complete": false with a reason instead of pretending a server exposed
nothing. Exit codes: 0 all contacted, 1 any protocol error, timeout,
auth challenge or bot-block, 2 refusal or no targets.
The two halves stay deliberately separate audit chains: secscan is deterministic and never runs anything; mcprobe runs, is consented, and is honestly non-deterministic. Design details and the full report contract are in docs/mcprobe.md.
How it works
Two lanes share one skill record: verify what a capability claims against what it observably does, then install it into the runtime of your choice. Neither lane needs the other to run — but they describe the same artifacts, so what you verify is what you ship.
flowchart LR
subgraph verify["Verify lane"]
R[Repo or path] --> D[Discovery<br/>skills · MCP configs<br/>agents · commands]
D --> K[Contract core]
K --> E[Declared vs observed<br/>file:line evidence]
E --> J[One deterministic verdict<br/>exit 0 / 1 / 2]
end
subgraph install["Install lane"]
C[Catalog<br/>529 skills] --> X[Compiler]
X --> N[Native installs<br/>claude · cursor<br/>leosis · hermes]
X --> B[Portable bundle<br/>+ 11 targets]
end
J -. same skill record .-> C
The verify lane never executes what it scans; the install lane packages, hashes and delivers what the catalog serves. A skill is written once — USB handles the verdict, the packaging, the install paths and sha256-verified delivery for every target.
Supported targets
Sixteen targets (fifteen runtimes plus auto), two tiers:
Installs into the runtime — the runtime loads these on its own, no wiring:
claude · cursor · leosis · hermes
Emits a portable bundle — skill markdown plus a JSON adapter descriptor under ~/.ai-skills/adapters/<target>/, ready to feed into your own agent code:
openai · anthropic · langchain · mcp · openrouter · groq · mistral · ollama · lm-studio · vllm · generic
auto detects the runtime from your environment; generic falls back to plain markdown + a JSON manifest for anything unrecognized. Catalog: 529 skills — 9 hand-written core skills plus 65 engineering domains × 8 workflows (Audit, Plan, Build, Script, Diagnose, Harden, Explain, Tune).
Installing skills
Three ways in, ordered by how much you verify:
npm — the full CLI, every command:
npm install -g @peepsick/usb-cli
usb install intent-router # a single skill
usb install web-dev # a preset bundle
usb install --target=claude # force a specific runtime target
Inspect-then-install — no Node required; verify the bytes before you run them:
curl -fsSL https://usbplus.peepsicklabs.com/api/install?target=auto -o install.sh
EXPECTED=$(curl -fsSL https://usbplus.peepsicklabs.com/api/install-sha256?target=auto)
echo "$EXPECTED install.sh" | sha256sum -c - # mismatch = tampering or a stale CDN
less install.sh # read what it actually does
bash install.sh
Already trust the publisher? One line, no review step: curl -fsSL https://usbplus.peepsicklabs.com/api/install?target=auto | bash
CLI reference
| Command | Description |
|---|---|
usb |
Open the interactive picker — browse domains, categories, presets, skills, or uninstall an installed skill |
usb install [preset|domain|skill] |
Install a curated preset, a whole domain (8 workflows), or a single skill |
usb install |
Install the whole pack (529 skills) |
usb install --target=<name> |
Force a specific provider target |
usb install --dry-run |
Print the install script without executing it |
usb uninstall <slug> |
Remove an installed skill from a runtime target — offline, frontmatter-verified, --dry-run supported |
usb search <query> |
Search the skill catalog |
usb list |
List every skill in the catalog |
usb info <skill> |
Show details for one skill |
usb secscan [paths|--system|--repo] |
Skill Contract Verifier — security-scan skills (see The Trust Layer above) |
usb mcprobe [target] |
Runtime observation of MCP servers (interactive consent) |
usb mcp |
Start the stdio MCP server for AI agents |
usb version |
Print version, latest release, and update check (/api/version) |
usb install --dry-run # print the install script, do NOT execute
less <(usb install --dry-run web-dev) # dry-run a preset and pipe to less
API
| Endpoint | Purpose |
|---|---|
/api/install?target=<name> |
Render the install script for a target |
/api/install-sha256?target=<name> |
sha256 of the above, for verification |
/api/skills |
Browse the skill catalog |
/api/audit/<slug> |
Audit a single skill definition |
/api/version |
CLI/catalog version info |
/api/health |
Health check |
/api/installations |
Opt-in anonymous install logging — off unless USB_LOG_INSTALLATIONS=on |
/api/mcp |
MCP server — HTTP JSON-RPC 2.0, tools: usb_search, usb_get_skill, usb_audit_skill, usb_render_install |
curl -X POST https://usbplus.peepsicklabs.com/api/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
USB ships two MCP surfaces — different transports, different jobs:
| Surface | Transport | Tools | Job |
|---|---|---|---|
| Catalog MCP | HTTP JSON-RPC 2.0 over /api/mcp |
usb_search, usb_get_skill, usb_audit_skill, usb_render_install |
Remote catalog — find skills, audit a definition, render install scripts |
| CLI MCP | stdio (usb mcp) |
usb_scan, usb_mcprobe |
Local security — contract-scan skill dirs/repos, probe MCP servers |
Who ships with USB
- ✅ Agent engineers — land a skill in Claude Code, Cursor, LeoSis or Hermes without touching install paths
- ✅ Security & platform teams — CI gates on
usb secscan --baseline: known findings acknowledged, only new contract violations block (exit 1) - ✅ MCP server authors — configs and server contracts scanned like skills; releases observed with
usb mcprobe - ✅ Framework authors —
@peepsick/usb-sdkgives you a typedAgentbase class to build on - ✅ Auditors —
--jsonreports, path-stable fingerprints, byte-identical reruns
Local development
git clone https://github.com/PeepSick/usbplus.git
cd usbplus
docker compose up -d
Open http://localhost:3000. Stack: Next.js 16, React 19, Tailwind v4, PostgreSQL + Drizzle ORM.
On first boot a one-shot migrate service waits for Postgres and runs
drizzle-kit push, so the schema and the 529-skill catalog are in place before
the app starts — /api/install works straight away. Re-bootstrap from scratch
with docker compose down -v.
If 5433 (Postgres) or 3000 (web) are already taken on your machine, override
the host ports: USB_PG_HOST_PORT=5544 USB_WEB_PORT=3001 docker compose up -d.
Running site code without Docker (npm run dev, npm run build) needs a
reachable DATABASE_URL for its page-data collection step: copy
.env.example to .env — it points at the Postgres the compose stack above
publishes on the host. CI hands the build a dummy URL, since the build there
only verifies compilation.
USB+ MCP Fragen
Wie verifiziert USB, ob ein Skill sicher ist?
Es nutzt secscan, um den deklarierten Contract eines Skills statisch und deterministisch mit seinen tatsächlich beobachteten Fähigkeiten zu vergleichen, ohne den Code auszuführen.
Kann ich USB nutzen, um MCP server live zu beobachten?
Ja, der mcprobe Befehl ermöglicht die Live-Beobachtung von MCP servern beim Start mit expliziter Zustimmung, um sicherzustellen, dass sie nicht unerwartet Tools aufrufen.
Unterstützt USB verschiedene KI Runtimes?
Ja, es unterstützt 16 Zielformate und kann Skills nativ für Runtimes wie Claude Code und Cursor installieren.