USB+ MCP server
2026년 11월 14일 커밋여러 에이전트 런타임에서 SKILL 및 MCP server를 검색, 검증 및 설치하여 AI 기능에 대한 신뢰 계층을 제공합니다.
다른 이름 PeepSick/usbplus
- 스타
- 11
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- MIT
USB+ MCP란?
여러 에이전트 런타임에서 SKILL 및 MCP server를 검색, 검증 및 설치하여 AI 기능에 대한 신뢰 계층을 제공합니다.
프로젝트 README에서 생성된 요약
USB+ MCP server 정보
AI SKILL 및 MCP server가 선언된 대로 정확하게 동작하는지 검증하는 것이 usbplus의 핵심 기능입니다. 이 도구는 다양한 에이전트 런타임을 사용하는 개발자를 위한 신뢰 계층 역할을 하며, 여러 환경에서 기능을 검색, 검증 및 설치할 수 있도록 지원합니다. 도구의 설명과 실제 기술 구현 사이의 간극을 메워 선언되지 않은 자격 증명 접근이나 승인되지 않은 네트워크 호출과 같은 보안 리스크를 방지합니다.
사용자는 usb-cli 또는 usb-sdk를 통해 시스템과 상호작용합니다. 플랫폼은 두 가지 특화된 검증 명령어를 제공합니다. 선언된 계약과 관찰된 기능을 비교하기 위해 정적 분석을 수행하는 secscan과, 도구를 실행하지 않고 시작 시 실시간 MCP server를 관찰하는 mcprobe가 있습니다. 시스템은 Claude Code 및 Cursor를 포함한 16가지 런타임 타겟을 지원하며, 로컬 경로, 시스템 전체 설정 또는 원격 GitHub repository를 스캔하여 설치된 SKILL이 의도된 목적과 일치하는지 확인할 수 있습니다.
활용 사례
- 1SKILL 보안 계약 검증서드파티 SKILL에 비밀 정보 접근이나 프로세스 실행과 같이 선언되지 않은 기능이 포함되어 있는지 확인합니다.
- 2CI 환경에서 기능 검증 자동화종료 코드와 기계 판독 가능한 보고서를 사용하여 SKILL에서 새로운 계약 위반이 감지될 경우 빌드를 차단합니다.
- 3런타임 간 SKILL 설치특정 AI SKILL을 찾아 Claude 또는 Cursor와 같이 지원되는 환경에 직접 배포합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능peepsick/usbplus is public and reachablegithub.com/peepsick/usbplus ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/peepsick/usbplus ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기USB — 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 질문
USB는 SKILL의 안전성을 어떻게 검증하나요?
코드를 실행하지 않고 secscan을 사용하여 SKILL에 선언된 계약과 실제 관찰된 기능이 일치하는지 정적이고 결정론적으로 비교합니다.
USB로 실시간 MCP server를 관찰할 수 있나요?
네, mcprobe 명령어를 사용하면 명시적인 동의 하에 시작 시 MCP server를 실시간으로 관찰할 수 있으며, 이를 통해 예상치 못한 도구 호출이 발생하는지 확인할 수 있습니다.
USB는 다양한 AI 런타임을 지원하나요?
네, 16가지 타겟 형식을 지원하며 Claude Code 및 Cursor와 같은 런타임에 SKILL을 네이티브로 설치할 수 있습니다.