{"id":50104393,"url":"https://github.com/froggychips/mcp-skills-vault","last_synced_at":"2026-06-12T05:00:57.135Z","repository":{"id":356553336,"uuid":"1178846405","full_name":"froggychips/mcp-skills-vault","owner":"froggychips","description":"Deterministic registry + supply-chain integrity scanner for MCP (Model Context Protocol) servers. One-line install via npx, hash-pinned 112-entry DB, 4 advisory feeds, offline-first audit. Make MCP boring.","archived":false,"fork":false,"pushed_at":"2026-06-04T10:18:25.000Z","size":605,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-04T12:10:35.788Z","etag":null,"topics":["agent-tools","agentic-ai","ai-agents","anthropic","claude","claude-code","claude-skill","dependency-scanning","llm-tools","mcp","mcp-client","mcp-server","mcp-servers","mcp-tools","model-context-protocol","npm-security","package-audit","skills","supply-chain-security"],"latest_commit_sha":null,"homepage":"https://mcp.froggychips.xyz","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/froggychips.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T12:33:18.000Z","updated_at":"2026-05-25T06:24:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/froggychips/mcp-skills-vault","commit_stats":null,"previous_names":["froggychips/mcp-skills-vault"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/froggychips/mcp-skills-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/froggychips%2Fmcp-skills-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/froggychips%2Fmcp-skills-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/froggychips%2Fmcp-skills-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/froggychips%2Fmcp-skills-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/froggychips","download_url":"https://codeload.github.com/froggychips/mcp-skills-vault/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/froggychips%2Fmcp-skills-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","agentic-ai","ai-agents","anthropic","claude","claude-code","claude-skill","dependency-scanning","llm-tools","mcp","mcp-client","mcp-server","mcp-servers","mcp-tools","model-context-protocol","npm-security","package-audit","skills","supply-chain-security"],"created_at":"2026-05-23T09:06:04.345Z","updated_at":"2026-06-12T05:00:57.121Z","avatar_url":"https://github.com/froggychips.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-skills-vault\n\n[![npm version](https://img.shields.io/npm/v/@froggychips/mcp-vault.svg)](https://www.npmjs.com/package/@froggychips/mcp-vault)\n[![npm downloads](https://img.shields.io/npm/dm/@froggychips/mcp-vault.svg)](https://www.npmjs.com/package/@froggychips/mcp-vault)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](./PHILOSOPHY.md)\n[![Tests](https://img.shields.io/badge/tests-271%20pass-brightgreen.svg)](./tests)\n\n**Homepage:** [mcp.froggychips.xyz](https://mcp.froggychips.xyz) · **npm:** [`@froggychips/mcp-vault`](https://www.npmjs.com/package/@froggychips/mcp-vault)\n\n\u003e **Make MCP boring.** A deterministic registry + integrity scanner for [Model Context Protocol](https://modelcontextprotocol.io) servers, so installing one stops feeling like `curl | bash`.\n\n![demo](./docs/demo.gif)\n\n```text\n$ npx -y @froggychips/mcp-vault scan\nStack: Langs: Node | DB: postgres | Infra: aws, teamcity, atlassian\nNeeds: database, infra, ci-cd, pm\n\n── Recommended ──────────────────────────────────────────────\n  Core         mcp-server-neon            10 tools  score 105\n  Core         mcp-server-aws             20 tools  score 105\n  Core         mcp-server-filesystem      10 tools  score 105\n  Core         mcp-server-memory           9 tools  score 105\n  Recommended  teamcity-mcp              null tools  score  65\n\n── Heavy — scope before global install ──────────────────────\n  Experimental mcp-atlassian             72 tools ⚠  score  55\n                 --toolsets jira,confluence\n\n$ npx -y @froggychips/mcp-vault verify --offline\n…\n112 entries checked — 0 failure(s)\n```\n\n## Without this vault vs. with it\n\n| | Without | With |\n|---|---|---|\n| **Discoverability** | search GitHub, hope the README isn't lying | curated DB of **112 entries** with health scores, license, category, est-tools-count |\n| **Trust** | unknown publisher, unknown last commit | `trust: verified` per entry, **94/112 (84%)** hand-vetted against a written checklist; the remaining 18 are `trust: \"candidate\"` held by upstream install hooks (see [Install-Hook Policy](./CONTRIBUTING.md#install-hook-policy)) |\n| **Integrity** | `npx -y whatever@latest` runs whatever ships today | sha512/sha256/Docker `@sha256:` pinned + re-verified against the live registry on every check |\n| **Vulnerabilities** | `npm audit` after the fact, if you remember | 4 advisory feeds merged: npm bulk + OSV.dev + GHSA + Snyk† — checked *before* the install command is written |\n| **Stack matching** | manual reading of awesome-lists | detects 40+ env-key patterns + 14 file paths + docker-compose images → suggests what to install |\n| **Offline use** | doesn't | `--offline` makes no network calls and validates stored pins; `--no-audit` still checks live registries but skips advisory APIs |\n| **Telemetry** | varies | none. Ever. |\n\n† Snyk requires `SNYK_TOKEN` (no public anonymous API)\n\n## Quick start\n\n**As a CLI** — one line, no clone, no global install:\n\n```bash\nnpx -y @froggychips/mcp-vault scan --cwd ./my-project\nnpx -y @froggychips/mcp-vault audit --strict\nnpx -y @froggychips/mcp-vault verify --offline\nnpx -y @froggychips/mcp-vault doctor\n```\n\nPrefer it installed? `npm i -g @froggychips/mcp-vault` then drop the `npx -y` prefix.\n\n**As a Claude Code skill** — drop the bundled skill folder into `~/.claude/skills/` and Claude will pick it up:\n\n```bash\ngit clone https://github.com/froggychips/mcp-skills-vault.git\nmkdir -p ~/.claude/skills\ncp -r mcp-skills-vault/mcp-ecosystem-intelligence ~/.claude/skills/\n```\n\n**Direct script invocation** — every command also runs without the CLI wrapper, e.g. `node mcp-ecosystem-intelligence/scripts/orchestrate.cjs --cwd /path/to/project`. Flags are identical; the CLI is a thin pass-through.\n\nZero runtime dependencies. Node built-ins only. One JSON file is the entire database.\n\nAsk Claude something like:\n\n\u003e _\"Is there an MCP server for ClickHouse I should add to this project?\"_\n\u003e _\"Audit my MCP setup.\"_\n\u003e _\"What MCP tools should I install for a Next.js app on Cloudflare?\"_\n\n## Five constraints that shape every decision\n\n- **Offline-first** — the gate the user cares about runs with no network\n- **Minimal** — zero runtime deps; supply-chain attack surface = Node's\n- **Inspectable** — every entry carries an audit trail; every output has `--json`\n- **Deterministic** — same DB, same commit → same recommendation, every time\n- **Boring** — supply-chain tooling should not be exciting\n\nFull rationale and the rules each constraint imposes: [PHILOSOPHY.md](./PHILOSOPHY.md).\n\n## What's in here\n\n| | Purpose | Status |\n|---|---|---|\n| [`mcp-ecosystem-intelligence/`](./mcp-ecosystem-intelligence) | The scanner + DB. Stack detection, integrity verification, advisory feeds, drift detection, candidate discovery, wrapper generator. | Ready |\n| [`concepts/`](./concepts/) | Unfinished sketches kept for reference. Nothing here ships or runs in CI. | Not active |\n\n---\n\n## What works today\n\n### Pipeline orchestrator\n\n[`scripts/orchestrate.cjs`](./mcp-ecosystem-intelligence/scripts/orchestrate.cjs) — the single entry point. Deterministically runs steps 1, 2, 7, 8 of the pipeline so Claude only interprets results.\n\n```bash\n# Scan project, match DB, show what to install\nmcp-vault scan --cwd /path/to/project\n\n# Keyword search on top of stack detection\nmcp-vault scan --query kubernetes\n\n# Install a tool: integrity gate → writes .mcp.json\nmcp-vault install github-mcp-server\nmcp-vault install mcp-server-memory --global\n```\n\nDetects stack from: `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `docker-compose.yml`, `.env*` (key names only — no value leaks).\n\n### Supply-chain security scanner\n\n[`scripts/verify_integrity.cjs`](./mcp-ecosystem-intelligence/scripts/verify_integrity.cjs) — run before any install:\n\n```bash\nmcp-vault verify\n```\n\n| Ecosystem | Integrity | Source URL | Install hooks | CVE / advisory |\n|---|---|---|---|---|\n| npm (`npx -y`) | sha512 SRI from npm | `repository.url` | `pre/post/install` + `prepare` | npm bulk + OSV.dev + GHSA + Snyk† |\n| PyPI (`uvx`) | sha256 of sdist tarball | `project_urls` | n/a | OSV.dev + GHSA + Snyk† |\n| Docker (`docker run`) | image must be pinned by `@sha256:\u003cdigest\u003e` | n/a | n/a | n/a |\n\n† Snyk active only when `SNYK_TOKEN` env var is set (no public anonymous API). GHSA uses `GITHUB_TOKEN`/`GH_TOKEN` when present to raise its rate limit from 60→5000 req/hr; anonymous works at low volume. Advisories from all feeds are deduplicated by ID before flagging.\n\nFlags:\n\n| Flag | Effect |\n|---|---|\n| `--update` | Refresh `version` + `pkg_integrity` from registries |\n| `--strict` | Treat WARNs (hooks, repo mismatch, unpinned docker) as hard failures |\n| `--no-audit` | Skip advisory APIs; still fetch registry metadata for live hash/repo/hook checks |\n| `--offline` | True offline mode; no network calls, validates stored DB pins only |\n\n### Doctor\n\n[`scripts/doctor.cjs`](./mcp-ecosystem-intelligence/scripts/doctor.cjs) — local readiness check:\n\n```bash\nmcp-vault doctor\nmcp-vault doctor --json\n```\n\nChecks Node version, optional `gh` / Docker / `uvx`, project `.mcp.json`, project `.claude/settings.json`, and global `~/.claude.json` MCP server config. It never prints token values.\n\n### What this project is NOT\n\n- **Not a sandbox.** Installing an MCP server still runs that server with your local MCP host's permissions.\n- **Not a runtime monitor.** Vault is an install-time gate; use `mcp-trace` or another monitor for runtime behaviour.\n- **Not proof that a server is benign.** Hashes prove you got the artifact you expected, not that the artifact is safe.\n\n### Docker `@sha256` drift detection\n\n[`scripts/check_docker_drift.cjs`](./mcp-ecosystem-intelligence/scripts/check_docker_drift.cjs) — for every Docker entry, fetches the registry digest for the tracked tag (`tracked_tag` in the entry, default `latest`) via the OCI Distribution Spec and reports drift against the pinned `@sha256:` digest.\n\n```bash\nmcp-vault docker-drift           # human-readable\nmcp-vault docker-drift --json    # machine-readable\nmcp-vault docker-drift --strict  # exit 1 on any drift\n```\n\nDrift = upstream rebuilt the tag under a new digest. The weekly CI job (`docker-drift`) fails on any drift so a maintainer reviews the upstream change *before* refreshing the pin — a routine rebuild and a registry hijack look identical from here.\n\n### Behavioural smoke (mcp-eval)\n\n[`scripts/mcp_eval.cjs`](./mcp-ecosystem-intelligence/scripts/mcp_eval.cjs) — closes the \"did the artifact actually start?\" gap. The integrity gate verifies the *file* you downloaded; this script verifies that spawning the server produces a usable tool surface.\n\nFor each DB entry with a recognized install method (`npx -y`, `uvx`, `docker run`), the script spawns the subprocess and runs the canonical JSON-RPC handshake — `initialize` → `notifications/initialized` → `tools/list` — then lints each returned tool's `inputSchema` with a minimal validator (intentionally narrower than full JSON Schema Draft 2020-12; covers only what Claude Code actually reads: `type`, `properties`, `required`, `enum`, `description`, plus nested objects + array items).\n\n```bash\nmcp-vault eval                       # smoke all (needs network)\nmcp-vault eval --name memory         # one entry, substring match\nmcp-vault eval --json --strict       # CI form\nmcp-vault eval --no-spawn            # offline self-test\n```\n\nOutput: `assets/eval_results.json` — `{name, status, boot_ms, list_latency_ms, tool_count, tool_count_db, tool_count_drift, schema_errors[], error_code, checked_at}` per entry, sorted by name for deterministic diffs. Results never flow back into `tools_database.json` — DB stays the source of truth, eval is a separate evidence stream.\n\nNetwork policy: real smoke needs to fetch packages (`npx` cache miss, `uvx` wheel download, `docker pull`), so it is NOT offline. The CI job (`mcp-eval-smoke`) runs cron-only — never on PRs. The `--no-spawn` flag re-lints existing results without spawning anything; that path IS offline.\n\nWhat it does NOT validate: behavioural correctness (we don't call any tool), business logic, or security of the server's tool implementations. This is a *smoke* check, not a fitness test.\n\n### Discovery pipeline\n\n[`scripts/discover.cjs`](./mcp-ecosystem-intelligence/scripts/discover.cjs) — harvest MCP server candidates from three sources, deduplicate by repo URL, annotate with health metrics from GitHub, score, and emit a candidates JSON ready for manual cherry-pick into `tools_database.json`.\n\n```bash\n# Default: all three sources, top-50 candidates, capped at 200 gh api calls\nmcp-vault discover --out candidates.json\n\n# Single source / smaller limit\nmcp-vault discover --source npm --limit 20 --out candidates.json\n```\n\nSources:\n\n| Source | Endpoint | Notes |\n|---|---|---|\n| `readme` | `modelcontextprotocol/servers` README | Curated. No `gh` calls. |\n| `gh`     | `gh search repos --topic mcp-server / modelcontextprotocol` | Requires `gh auth login`. Topic-tags catch non-MCP projects, filtered out by name/description heuristic. |\n| `npm`    | `npm search mcp-server` | Filters to packages with a GitHub `repository` field. |\n\nAnnotation uses `gh api repos/\u003cowner\u003e/\u003crepo\u003e` for stars, last commit, license, archive/fork status. Reject heuristics: `\u003c10 stars`, `last_commit \u003e 365 days`, archived, fork, doesn't look like an MCP server in `name`/`description`. Surviving candidates are scored with the same formula as `calculate_health.cjs` and emitted with the same shape as `tools_database.json` entries (minus `pkg_integrity`, which `verify_integrity.cjs --update` fills after manual merge).\n\nThe weekly `discover-candidates` CI job runs this script every Thursday and opens a PR refreshing `mcp-ecosystem-intelligence/assets/discovery/candidates.json`. That file is a living *inbox* — never auto-merged into the DB; a human cherry-picks entries with `trust: \"candidate\"`.\n\n### Audit installed setup\n\n[`scripts/audit_setup.cjs`](./mcp-ecosystem-intelligence/scripts/audit_setup.cjs) — diff the user's installed MCP servers against the DB. Reads `\u003ccwd\u003e/.mcp.json`, the `mcpServers` key of `~/.claude.json` (and *only* that key — auth tokens live elsewhere in the file), and `\u003ccwd\u003e/.claude/settings.json` (`enabledMcpjsonServers`, `permissions.allow`):\n\n```bash\nmcp-vault audit            # human-readable\nmcp-vault audit --json     # machine-readable findings\nmcp-vault audit --strict   # exit 1 on drift/untrusted/heavy\n```\n\n| Finding | Trigger |\n|---|---|\n| `drift` | installed version differs from DB-pinned version |\n| `untrusted` | DB `trust: \"candidate\"` but actively installed |\n| `heavy-unbounded` | `est_tools_count \u003e 15` (or unknown) and no `--toolsets`/`--caps`/`allowedTools`/`enabledMcpjsonServers` scoping |\n| `unknown` | installed but not in DB (legitimate custom servers ok — informational) |\n| `scope` | global install of a typically project-scoped category (`vcs`/`ci-cd`/`pm`/`infra`) |\n\nExit codes: `0` clean / info-only · `1` `--strict` triggered · `2` bad invocation. Closes the \"Audit my MCP setup\" use case without an LLM in the critical path.\n\n### Public registry page\n\n[`scripts/generate_registry_page.cjs`](./mcp-ecosystem-intelligence/scripts/generate_registry_page.cjs) renders the DB into `docs/site/registry.html` plus `docs/site/registry.json`:\n\n```bash\nmcp-vault site-registry\n```\n\nThe generated page is static, searchable, and filterable by category, tier, and trust. It is meant to be published with the rest of the GitHub Pages site.\n\n### Health scorer\n\n[`scripts/calculate_health.cjs`](./mcp-ecosystem-intelligence/scripts/calculate_health.cjs) — score any MCP candidate:\n\n```bash\nmcp-vault health \\\n  \u003cstars\u003e \u003clast_commit_days\u003e \u003cin_registry\u003e \u003chas_install_cmd\u003e \u003ccritical_issues\u003e [license]\n```\n\n```\nscore = min(20, 10·log10(stars+1))   # popularity, capped\n      + {40|20|10|0}                  # recency: \u003c30d / \u003c90d / \u003c180d / older\n      + 30 if in_registry\n      + 15 if install_cmd documented\n      + 5  if open_issues/10 \u003c 5\n      − 10 if license is non-OSI / source-available / Unknown\n```\n\n| Score | Tier | Behaviour |\n|---|---|---|\n| 85+ | Core | recommend by default |\n| 65–84 | Recommended | recommend with note |\n| 40–64 | Experimental | mention only on ask |\n| \u003c 40 | Deprecated | hide unless asked |\n\n### Vetted database\n\n`mcp-ecosystem-intelligence/assets/tools_database.json` — **112 entries** across ~25 categories, all with pinned versions, integrity hashes (npm sha512 / PyPI sha256 / Docker @sha256), SPDX license, and `trust` field.\n\n```\nai        browser   ci-cd      cms       communication   crm\ndatabase  demo      docs       filesystem http            infra\nmaps      memory    meta       mobile     observability   payments\npm        reasoning search     testing    utility         vcs       web-scraping\n```\n\nDistribution: **96 Core / 11 Recommended / 5 Experimental**.\n\n**Verified hand-curated core** (the original 30): the seven official `modelcontextprotocol/servers` (filesystem, fetch, git, memory, sequentialthinking, time, everything) plus vendor-maintained servers (`github`, `microsoft/playwright`, `cloudflare`, `notion`, `sentry`, `stripe`, `neon`, `mongodb`, `redis`, `clickhouse`, `awslabs/mcp`, `context7`, …) and high-quality community entries (`mcp-atlassian`, `firecrawl`, `tavily`, `exa`, `brave`, `kubernetes`, `duckduckgo`, …).\n\n**Candidate batch** (75, added 2026-05): vendor servers harvested via `discover.cjs` from npm + the official servers README, all with `trust: \"candidate\"` pending human-vetting on usage patterns. Highlights: `@mapbox/mcp-server`, `@azure-devops/mcp`, `@dynatrace-oss/dynatrace-mcp-server`, `@browserstack/mcp-server`, `@salesforce/mcp`, `@postman/postman-mcp-server`, `@eslint/mcp`, `@circleci/mcp-server-circleci`, `argocd-mcp`, …\n\nEntry schema:\n\n```jsonc\n{\n  \"name\": \"pkg-name\",\n  \"category\": \"database|search|infra|…\",\n  \"install_cmd\": \"npx -y pkg@1.2.3\",   // always pinned\n  \"source_url\": \"https://github.com/owner/repo\",\n  \"version\": \"1.2.3\",                  // pinned npm version\n  \"pkg_integrity\": \"sha512-…\",         // npm dist.integrity\n  \"trust\": \"verified\",                 // \"verified\" | \"candidate\"\n  \"license\": \"MIT\",                    // SPDX; non-OSI triggers -10 penalty\n  \"health_score\": 105.0,\n  \"classification\": \"Core\",\n  \"est_tools_count\": 10,               // tools injected into context (~200-500 tokens each)\n  \"toolsets\": \"--toolsets repos,issues\" // how to reduce tool count; null = no native filtering\n}\n```\n\n### CI\n\n`.github/workflows/security-scan.yml` runs six jobs across PRs, pushes, and two weekly crons:\n\n- **unit-tests** — `node --test tests/*.test.cjs` on every PR / push (fast, no network). Covers parser helpers, advisory dedup, drift parsing, signal mapping, eval schema lint. Smoke depends on this.\n- **smoke** — `verify_integrity.cjs --offline` on every PR / push to master (network-free, fast).\n- **refresh-hashes** — Monday cron, opens a PR refreshing `version` + `pkg_integrity` from live registries. Human-gated before merge.\n- **docker-drift** — Monday cron + manual dispatch. Compares each Docker entry's pinned `@sha256:` against the upstream registry digest; fails the job on any drift so a maintainer reviews before refreshing the pin.\n- **discover-candidates** — Thursday cron + manual dispatch. Runs `discover.cjs` against the three sources and opens a PR with a fresh `assets/discovery/candidates.json`. The file is an *inbox* — never auto-merged into `tools_database.json`.\n- **mcp-eval-smoke** — Monday cron + manual dispatch. Runs `mcp_eval.cjs --json` against the whole DB, uploads `eval_results.json` as an artifact. Cron-only — needs network to fetch packages. Results never auto-commit to the DB.\n\n---\n\n## Roadmap\n\nThe following are described in [`SKILL.md`](./mcp-ecosystem-intelligence/SKILL.md) as intended behaviour but are not yet scripted — Claude performs them interactively using available tools (Bash, WebFetch, Read) on each invocation:\n\n| Feature | Status |\n|---|---|\n| Stack detection from manifests (`package.json`, `pyproject.toml`, …) | [`orchestrate.cjs detectStack()`](./mcp-ecosystem-intelligence/scripts/orchestrate.cjs) — done |\n| Registry / aggregator / `gh search` discovery pipeline | [`scripts/discover.cjs`](./mcp-ecosystem-intelligence/scripts/discover.cjs) — done |\n| Reject heuristics (5-Minute Rule, Bloat, Duplication) | Claude-executed judgment, no dedicated script |\n| Formatted recommendation output (terse / verbose) | Claude-generated, no dedicated formatter |\n| Project-scoped `.mcp.json` install (default path) | [`orchestrate.cjs --install`](./mcp-ecosystem-intelligence/scripts/orchestrate.cjs) — done |\n| `allowedTools` per-project filtering for heavy servers | Pattern documented in SKILL.md §10; [`audit_setup.cjs`](./mcp-ecosystem-intelligence/scripts/audit_setup.cjs) flags unscoped heavy servers |\n| Audit installed setup (drift / untrusted / heavy / scope) | [`scripts/audit_setup.cjs`](./mcp-ecosystem-intelligence/scripts/audit_setup.cjs) — done |\n| Wrapper generator (CLI/API → MCP boilerplate) | [`scripts/generate_wrapper.cjs`](./mcp-ecosystem-intelligence/scripts/generate_wrapper.cjs) — done |\n\n---\n\n## Token cost management\n\nEvery active MCP server injects its full tool list into Claude's system prompt (~200–500 tokens per tool). With 112 servers in the DB the spread is wide: `mcp-server-fetch` = 1 tool vs. `gitlab-mcp` = 153 tools.\n\nThree levers, in order of preference:\n\n**1. Native filtering** (server flag / config key) — use the `toolsets` field in the DB:\n```bash\n# github-mcp: keep only what the project needs\n--toolsets repos,issues,pull_requests\n# playwright-mcp: drop 56 tools, keep 8\n--caps core\n# mongodb-mcp: exclude destructive tools\ndisabledTools: [\"dropCollection\", \"dropDatabase\"] in mcp_settings.json\n```\n\n**2. Project-scoped `.mcp.json`** (default install target) — server is active only in the repo where `.mcp.json` lives, invisible everywhere else:\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"--cap-drop\", \"ALL\",\n               \"--security-opt\", \"no-new-privileges\",\n               \"-e\", \"GITHUB_PERSONAL_ACCESS_TOKEN\",\n               \"--toolsets\", \"repos,issues\",\n               \"ghcr.io/github/github-mcp-server@sha256:…\"],\n      \"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${GITHUB_TOKEN}\" }\n    }\n  }\n}\n```\n\nReserve `~/.claude.json` for truly cross-project servers: `mcp-server-filesystem`, `mcp-server-memory`.\n\n**3. Wrapper (anti-bloat pattern)** — when a vendor server has no native filtering and exposes 50+ tools you don't need, wrap the 3–5 tools you do need in a thin custom MCP server using `assets/mcp-wrapper-template/`. The wrapper replaces the vendor server entirely, keeping context lean.\n\n---\n\n## Wrapping a CLI/API as MCP\n\nWhen the vendor server has no native filtering and exposes 50+ tools you don't need, generate a thin wrapper that exposes only the 3–5 tools you actually use. Saves ~200–500 tokens per dropped tool.\n\n```bash\n# Skeleton wrapper, no tools yet\nmcp-vault wrap \\\n  --name my-cli-mcp --tool \"My CLI\" --out ./my-cli-mcp\n\n# Pre-populated with tool definitions from a JSON spec\nmcp-vault wrap \\\n  --name warehouse-mcp --tool \"Internal Warehouse\" \\\n  --tools-file ./tools.json \\\n  --out ./warehouse-mcp\n```\n\n`tools.json` is an array of MCP tool defs (`name` / `description` / `inputSchema`); the generator emits `ListToolsRequestSchema` entries plus `switch`-cases with `required`-arg validation, runs Node's `--check` on the result, and writes a `.mcp.json`-ready README.\n\nUnderlying template lives in `mcp-ecosystem-intelligence/assets/mcp-wrapper-template/` if you'd rather edit by hand.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the entry schema, reject criteria, the triage checklist for promoting `trust: candidate` to `trust: verified`, and the review process for changes to the integrity gate.\n\nRunning the suite locally:\n\n```bash\nnode --test tests/*.test.cjs        # unit tests (offline)\nmcp-vault verify --offline          # DB smoke, no network\nmcp-vault site-registry             # regenerate docs/site/registry.html\n```\n\n---\n\n## Topics\n\n`claude-code` · `claude-skill` · `mcp` · `model-context-protocol` · `mcp-server` · `mcp-tools` · `anthropic` · `ai-agents`\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffroggychips%2Fmcp-skills-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffroggychips%2Fmcp-skills-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffroggychips%2Fmcp-skills-vault/lists"}