USB+ MCPサーバー
コミット 2026年11月14日複数のエージェント実行環境にわたって、SKILLやMCP serverを検索、検証、インストールすることで、AI機能の信頼レイヤーを提供します。
別名 PeepSick/usbplus
- スター
- 11
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年11月14日
- ライセンス
- MIT
USB+ MCPとは
複数のエージェント実行環境にわたって、SKILLやMCP serverを検索、検証、インストールすることで、AI機能の信頼レイヤーを提供します。
プロジェクトのREADMEから生成された概要
USB+ MCP server について
AIのSKILLやMCP serverが、宣言通りに動作することを検証するのがusbplusの主な機能です。このツールは、さまざまなエージェント実行環境を使用する開発者のための信頼レイヤーとして機能し、複数の環境にわたって機能を検索、検証、インストールすることを可能にします。ツールの記述内容と実際の技術的な実装との乖離を埋めることで、未宣言の認証情報へのアクセスや不正なネットワークコールといったセキュリティリスクを防ぎます。
ユーザーはusb-cliまたはusb-sdkを通じてシステムを操作します。プラットフォームは2つの特化した検証コマンドを提供します。一つは、宣言された契約と観測された機能を比較するために静的解析を行うsecscan、もう一つは、ツールを実行することなく起動時のMCP serverをライブ観測するmcprobeです。システムはClaude CodeやCursorを含む16の実行環境ターゲットをサポートしており、ローカルパス、システム全体の構成、またはリモートのGitHubリポジトリをスキャンして、インストールされた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をネイティブにインストールできます。