mcp-server-marketplace
Portfolio project from the 110-Advanced-Portfolio-Projects-2025-2026 plan.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/babyline00--mcp-server-marketplace)HTML
<a href="/listings/babyline00--mcp-server-marketplace"><img src="/api/listings/babyline00--mcp-server-marketplace/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 1. Install deps bun install # 2. Push the Prisma schema to the isolated SQLite DB bun run db:push # 3. Seed 3 plans + demo admin user + demo regular user + 15 hardcoded MCP servers bun run seed # 4. Run the dev server bun run dev # → open the Preview Panel to view the app (no http://localhost:3000 from outside the sandbox) # 5. Run the unit tests bun test
Per-app DB isolation (CRITICAL)
The DATABASE_URL is inlined as an absolute path in `package.json`'s `db:*` scripts so each app under `/home/z/my-project/apps/` gets its own SQLite file:
"db:push": "DATABASE_URL=\"$(pwd)/db/custom.db\" prisma db push --accept-data-loss"
`.env` and `.env.example` both use `file:/home/z/my-project/apps/33-mcp-server-marketplace/db/custom.db` (absolute path). Don't move the app directory without updating these.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 309 lines
- # MCP Server Marketplace
- Discovery, install, and sandboxed (mock) runtime for Model Context Protocol (MCP) servers. Browse the registry by category, one-click install, invoke tools in a mock sandbox, enforce per-user daily quotas, mock Stripe billing, and watch every invocation flow through the audit log into an admin analytics dashboard.
- This is Project #33 of the 110-project portfolio — a fresh rebuild after the original was lost to a sandbox recycle.
- ---
- ## Overview
- The Model Context Protocol is an emerging standard for exposing tools to LLM agents over a uniform JSON-RPC surface. A marketplace for MCP servers is the obvious next step: think npm + Docker Hub, but for agent-facing tools. This MVP makes a strong, opinionated call: it ships **the entire product experience without spinning up a single Docker container and without making a single real Stripe call**. The mock runtime and mock checkout are first-class, contract-faithful surfaces that can be swapped for the real things later with no API changes.
- The end-to-end flow:
- ```
- ┌─ Header ───────────────────────────────────────────────────────────────┐
- │ Mock user + plan badge + Manage subscription button │
- ├──────────────┬───────────────────────────────────────┬──────────────────┤
- │ Left │ Center: server cards grid │ Right tabs │
- │ ───── │ ───────────────────────────────── │ ───────────── │
- │ Search │ ┌────────┐ ┌────────┐ ┌────────┐ │ My Installations│
- │ Category │ │ Server │ │ Server │ │ Server │ │ Audit Log │
- │ Sort │ └────────┘ └────────┘ └────────┘ │ Admin analytics │
- │ Stats │ │ │
- └──────────────┴───────────────────────────────────────┴──────────────────┘
- │ │ │
- ▼ ▼ ▼
- GET /api/servers POST /api/servers/[id]/install GET /api/audit
- (BM25+RRF) POST /api/installations/[id]/invoke GET /api/admin/stats
- POST /api/subscriptions POST /api/subscriptions
- │
- ▼
- ┌──────────────────────┐
- │ mock-invoke.ts │ ← deterministic mock result
- │ (real Docker = stretch goal)
- └──────────────────────┘
- │
- ▼
- ┌──────────────────────┐
- │ AuditLog + quota │
- └──────────────────────┘
- ```
- ---
- ## MVP scope vs. stretch goals
- | Feature | MVP (this repo) | Stretch goal |
- |---|---|---|
- | Sandbox runtime | Deterministic mock — echoes input + synthesize a typed fake output | Real Docker container per server, MCP `tools/call` over stdin/stdout, kill after TTL |
- | Billing | Mock Stripe checkout — no payment taken, just inserts a Subscription row + flips `user.planId` | Real Stripe Checkout + webhooks, customer portal, invoicing |
- | Auth | Mock user — single demo admin + a regular user, switchable via header + localStorage | NextAuth.js with GitHub/email magic link, per-user quotas enforced server-side |
- | Search | BM25 + hashing-embedding (vector) + RRF, all in-memory | Plug OpenAI text-embedding-3-small via `EMBEDDINGS_API_KEY`; persistent pgvector / sqlite-vec |
- | Author revenue share | N/A | Stripe Connect, author payouts, onboarding flow |
- | Server verification | Hand-curated `verified: boolean` flag on the registry row | Automated verification pipeline: container scanning, tool input-schema validation, sandbox probes, signature |
- ---
- ## Features
- - **Server registry.** 15 hardcoded MCP servers seeded by `scripts/seed-servers.ts` covering all 6 categories (filesystem, dev-tools, productivity, data, communications, monitoring). Each row carries a JSON list of MCP tool definitions with `inputSchema`.
- - **Hybrid search.** Browse with `?q=…` runs BM25 (Okapi, k1=1.5, b=0.75) over server name + description + tool names + author, fused with a vector cosine rank (deterministic hashing-embedding, 384-dim, FNV-1a signed-bag) via Reciprocal Rank Fusion. Searching `filesystem` ranks the filesystem server first.
- - **Category filter + sort.** Sidebar filters by category; sort dropdown toggles most-installs / verified-first / recently-added. Search overrides sort when `q` is present.
- - **One-click install.** `POST /api/servers/[id]/install` creates an Installation row + atomically increments the server's `installsCount`. Idempotent — installing twice returns the existing Installation.
- - **Mock invoke.** `POST /api/installations/[id]/invoke` runs `mockInvoke(server, toolName, input)` — a pure function that returns a deterministic result echoing the user's input through, plus a synthesized typed mock output derived from the tool's `inputSchema.properties`. Duration is a deterministic 5-50ms derived from the input hash. Real Docker sandboxing is documented in `mock-invoke.ts` as the stretch-goal swap path.
- - **Per-user daily quotas.** Free=100, Pro=1000, Team=10000 invocations per day. The invoke route rejects over-quota requests with 429 and `{ error: 'quota_exceeded', dailyQuota, used }`. Quota is reset daily by the cron layer (out of scope).
- - **Mock Stripe billing.** `POST /api/subscriptions { planId }` cancels any existing active subscription, inserts a new Subscription row, and flips the user's `planId` atomically. The UI exposes a plan picker that calls this endpoint.
- - **Audit log.** Every invocation is persisted as an AuditLog row with `toolName, input (JSON), output (JSON), success, error, durationMs, createdAt`. The audit panel renders the last 50 entries with parsed inputs + outputs, truncated previews, and OK/ERR badges.
- - **Admin analytics.** Admin-only (`user.isAdmin`) panel: total servers / installations / invocations / users / errors, top 10 servers by installs, and a 7-day invocation bar chart computed from AuditLog (SQLite has no `date_trunc`, so we bucket in JS).
- - **Mock auth + user switcher.** No real login. The `x-mock-user-email` header selects which seeded user the API acts as. The header menu in the UI switches the localStorage value and re-fetches, so you can demonstrate plan switching and the admin view in seconds.
- ---
- ## Tech stack
- - **Framework**: Next.js 16 with App Router (TypeScript 5)
- - **Styling**: Tailwind CSS 4 with shadcn/ui (New York) + Lucide icons
- - **Database**: Prisma 6 + SQLite (per-app DB isolation under `db/custom.db`)
- - **Search**: in-memory BM25 + hashing-embedding (384-dim, FNV-1a signed-bag) + RRF fusion
- - **State**: React hooks + fetch (no Zustand needed for an MVP single page)
- - **Tests**: `bun test` with 118 unit tests across 8 modules
- - **MCP protocol**: `@modelcontextprotocol/sdk` is declared in `package.json` (mocked — not actually invoked; we mock the protocol intentionally to keep the MVP sandbox-free)
- ---
- ## Architecture
- ```
- ┌──────────────────────────────────────────┐
- │ Browser (page.tsx) │
- │ Header · Left sidebar · Server grid │
- │ Right tabs: Installs / Audit / Admin │
- └────────────┬─────────────────────────────┘
- │ fetch /api/* (x-mock-user-email header)
- ▼
- ┌────────────────────────────────────────────────────────────────┐
- │ Next.js 16 Route Handlers │
- │ │
- │ /api/servers /api/servers/[id]/install │
- │ /api/servers/[id] /api/installations │
- │ /api/installations/[id]/invoke /api/installations/[id] │
- │ /api/audit /api/admin/stats │
- │ /api/subscriptions /api/plans /api/stats │
- │ /api/users /api/users/me │
- └────────┬───────────────────────┬─────────────────────┬─────────┘
- │ │ │
- ▼ ▼ ▼
- ┌─────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
- │ src/lib/ │ │ src/lib/ │ │ Prisma 6 + SQLite │
- │ server-search.ts │ │ mock-invoke.ts │ │ Server │
- │ bm25.ts │ │ quota.ts │ │ User · Plan │
- │ embeddings.ts │ │ subscription.ts │ │ Installation │
- │ hybrid-search.ts │ │ audit.ts │ │ AuditLog │
- │ category.ts │ │ plan.ts │ │ Subscription │
- │ mock-user.ts │ │ install-token.ts │ │ │
- └─────────────────────┘ └────────────────────┘ └────────────────────┘
- pure logic pure logic single file:
- (testable) (testable) db/custom.db
- ```
- All `src/lib/*.ts` modules except `db.ts` and `mock-user.ts` are pure — no IO, no globals — which is why they're trivially unit-testable with `bun test`.
- ---
- ## Setup
- ```bash
- # 1. Install deps
- bun install
- # 2. Push the Prisma schema to the isolated SQLite DB
- bun run db:push
- # 3. Seed 3 plans + demo admin user + demo regular user + 15 hardcoded MCP servers
- bun run seed
- # 4. Run the dev server
- bun run dev
- # → open the Preview Panel to view the app (no http://localhost:3000 from outside the sandbox)
- # 5. Run the unit tests
- bun test
- ```
- ### Per-app DB isolation (CRITICAL)
- The DATABASE_URL is inlined as an absolute path in `package.json`'s `db:*` scripts so each app under `/home/z/my-project/apps/` gets its own SQLite file:
- ```json
- "db:push": "DATABASE_URL=\"$(pwd)/db/custom.db\" prisma db push --accept-data-loss"
- ```
- `.env` and `.env.example` both use `file:/home/z/my-project/apps/33-mcp-server-marketplace/db/custom.db` (absolute path). Don't move the app directory without updating these.
- ---
- ## Tests
- ```bash
- bun test
- ```
- 118 unit tests across 8 modules:
- | File | Tests | What it covers |
- |---|---|---|
- | `quota.test.ts` | 14 | `checkQuota` allowed/over-quota, default-to-0 defensive, team vs free vs pro |
- | `mock-invoke.test.ts` | 19 | `mockInvoke` happy path + error cases, `stableHash` determinism, `buildMockOutput` typed synthesis |
- | `audit.test.ts` | 9 | `formatAuditEntry` happy path, JSON parse, truncation, malformed input |
- | `server-search.test.ts` | 17 | BM25, vector, and hybrid (RRF) ranking; "filesystem" ranks filesystem server first |
- | `category.test.ts` | 15 | `categorizeServer` per-category hits + default fallback + edge cases |
- | `plan.test.ts` | 16 | `planLimits`, `isHigherTier`, `formatPrice`, `PLAN_ORDER` |
- | `subscription.test.ts` | 14 | `activeSubscription`, `effectivePlan`, `mockCreateCheckoutSession` |
- | `install-token.test.ts` | 14 | `generateInstallToken` uniqueness + `isValidInstallToken` shape validation |
- ---
- ## Environment variables
- | Variable | Default | Notes |
- |---|---|---|
- | `DATABASE_URL` | `file:/home/z/my-project/apps/33-mcp-server-marketplace/db/custom.db` | Absolute path REQUIRED for per-app isolation. Already set in `.env` + inlined in `package.json` scripts. |
- | `EMBEDDINGS_API_KEY` | unset | Optional. Set to enable OpenAI-compatible embeddings; falls back to the deterministic hashing-embedding when unset. |
- | `EMBEDDINGS_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint. |
- | `EMBEDDINGS_MODEL` | `text-embedding-3-small` | Embedding model id. |
- | `ZAI_API_KEY` | unset | Optional. Powers LLM enrichment via `z-ai-web-dev-sdk` (not used in the MVP). |
- | `STRIPE_SECRET_KEY` | unset | Optional. Real Stripe integration is mocked; this is reserved for the stretch goal. |
- | `STRIPE_WEBHOOK_SECRET` | unset | Optional. Same as above. |
- ---
- ## Project structure
- ```
- 33-mcp-server-marketplace/
- ├── prisma/
- │ └── schema.prisma # 6 models (Server, User, Plan, Installation, AuditLog, Subscription)
- ├── scripts/
- │ └── seed-servers.ts # 3 plans + admin + alice + 15 hardcoded MCP servers
- ├── src/
- │ ├── app/
- │ │ ├── layout.tsx
- │ │ ├── page.tsx # 3-column marketplace UI (single client component)
- │ │ ├── globals.css
- │ │ └── api/
- │ │ ├── servers/route.ts # GET (filter + hybrid search + sort)
- │ │ ├── servers/[id]/route.ts # GET single
- │ │ ├── servers/[id]/install/route.ts # POST (idempotent)
- │ │ ├── installations/route.ts # GET (user-scoped)
- │ │ ├── installations/[id]/route.ts # DELETE (soft uninstall)
- │ │ ├── installations/[id]/invoke/route.ts # POST (quota + mock + audit)
- │ │ ├── audit/route.ts # GET last 50
- │ │ ├── admin/stats/route.ts # GET admin analytics
- │ │ ├── subscriptions/route.ts # POST mock Stripe
- │ │ ├── plans/route.ts # GET catalog
- │ │ ├── stats/route.ts # GET global counters
- │ │ ├── users/route.ts # GET mock users
- │ │ └── users/me/route.ts # GET current mock user
- │ ├── components/ui/ # shadcn/ui (New York) — 16 components copied from parent
- │ ├── hooks/use-toast.ts
- │ └── lib/
- │ ├── db.ts # Prisma client (singleton)
- │ ├── utils.ts # cn() class merge helper
- │ ├── tokenizer.ts # lowercase + Unicode-aware + CJK split
- │ ├── bm25.ts # Okapi BM25 in-memory index
- │ ├── embeddings.ts # 384-dim hashing embedding (+ optional OpenAI provider)
- │ ├── hybrid-search.ts # RRF fusion (k=60 default)
- │ ├── chunker.ts # markdown-aware chunker (used by search index)
- │ ├── server-search.ts # hybridServerSearch(Sync) over ServerDoc
- │ ├── mock-invoke.ts # deterministic mock tool execution
- │ ├── quota.ts # checkQuota + buildQuotaInput
- │ ├── plan.ts # PLANS catalog + planLimits + formatPrice
- │ ├── subscription.ts # effectivePlan + mockCreateCheckoutSession
- │ ├── audit.ts # formatAuditEntry(s)
- │ ├── category.ts # categorizeServer (keyword lexicon)
- │ ├── install-token.ts # cuid-like token generator + validator
- │ ├── mock-user.ts # getMockUser + listMockUsers (header-based)
- │ └── __tests__/ # 8 test files, 118 tests
- ├── package.json
- ├── tsconfig.json
- ├── next.config.ts
- ├── postcss.config.mjs
- ├── tailwind.config.ts
- ├── components.json
- ├── eslint.config.mjs
- ├── .env / .env.example
- ├── .gitignore
- ├── LICENSE (MIT)
- └── README.md
- ```
- ---
- ## Case study — what's mock and what's real
- ### Mock sandbox runtime (`src/lib/mock-invoke.ts`)
- The MVP does **not** run Docker containers. `mockInvoke(server, toolName, input)` is a pure function that:
- 1. Validates the tool exists on the server (throws `TOOL_NOT_FOUND` otherwise).
- 2. Validates required input fields against the tool's `inputSchema.required` (throws `MISSING_REQUIRED` otherwise).
- 3. Computes a deterministic FNV-1a hash of `(server.slug, toolName, JSON.stringify(input))` — the same call always yields the same hash.
- 4. Synthesizes a typed mock output by iterating the tool's `inputSchema.properties`. For each property the user passed, the output includes `<key>_received` (echoed value) + `<key>_type` (declared type). For each property they didn't pass, the output includes `<key>_default` with a typed placeholder (string → `mock-<key>`, number → 0, etc.).
- 5. Returns a deterministic `durationMs` in 5-50ms derived from the hash.
- This is **contract-faithful**: the API route response shape, the AuditLog row shape, and the quota check are all identical to what a real Docker runtime would produce. Swapping in the real runtime is a single-file change — `mock-invoke.ts` gets replaced with a function that spawns a Docker container per server image, sends an MCP `tools/call` request over stdin/stdout, parses the response, and returns it. The route, the AuditLog, the quota — none of them change.
- ### Mock Stripe (`src/lib/subscription.ts` + `/api/subscriptions/route.ts`)
- Real Stripe checkout is a redirect dance — your backend creates a Checkout Session, the user goes to Stripe-hosted payment, then a webhook flips the user's plan on success. The MVP mocks this entire flow in two steps:
- 1. `mockCreateCheckoutSession(userId, planId)` returns a synthetic `cs_test_...` session id + a fake redirect URL (for completeness — the UI doesn't actually redirect).
- 2. `POST /api/subscriptions { planId }` cancels any existing active subscription, inserts a new Subscription row, and flips `user.planId` in a single transaction. No payment is taken.
- The `Subscription` table is identical to what a real Stripe integration would produce (id, userId, planId, status, startedAt, canceledAt) so the audit log and the analytics dashboard work unchanged. The stretch goal is to swap the mock for `stripe.checkout.sessions.create()` + a webhook handler that calls the same DB updates.
- ### Quota model (`src/lib/quota.ts`)
- Quotas are enforced as a pure function — `checkQuota({ invocationCount, dailyQuota })` returns `{ allowed, remaining, usedFraction, reason? }`. The invoke route calls it before `mockInvoke`, returning 429 when `allowed === false`. This makes the quota a single point of truth: any future runtime (real Docker, on-prem, etc.) plugs in by replacing only `mock-invoke.ts` — the quota check is unchanged. Tests assert the exact boundary: `invocationCount === dailyQuota` is **not** allowed (the count includes the would-be current call only after success, so the boundary is `count >= quota → reject`).
- ### What I'd do differently
- With more time, the obvious stretch goals, in priority order:
- 1. **Real Docker sandbox per server.** The mock is contract-faithful but obviously doesn't actually do the work the tool advertises. A real implementation would spawn one container per server image, mount a sandboxed scratch volume, send MCP `tools/call` over stdin/stdout, enforce a TTL, and kill on uninstall. Container startup cost is the hard problem — you'd want a warm pool per popular image.
- 2. **Real Stripe OAuth + Connect for author revenue share.** The marketplace's actual product-market fit is letting authors charge for their servers. That requires Stripe Connect (so authors have their own Stripe accounts), a checkout flow that splits the payment between us and the author, and a payout dashboard. The mock Subscription row today is the exact shape you'd extend.
- 3. **Real MCP server protocol.** `@modelcontextprotocol/sdk` is declared in `package.json` but intentionally mocked — the MVP doesn't speak the real JSON-RPC framing. For a real install, the route would negotiate capabilities, list tools via `tools/list`, and call via `tools/call` over the container's stdin/stdout. The tool definitions we seed today are already in the right schema, so this is mostly an I/O-layer change.
- 4. **On-prem runtime.** Some enterprises will never send their data to a hosted marketplace. An on-prem version of the runtime that pulls images from a private registry + writes AuditLog to a local SQLite (or Postgres) is straightforward given the architecture — the only piece that needs to be re-pointed is the `dockerImage` resolver.
- 5. **Server verification pipeline.** Today `verified: boolean` is hand-curated. A real pipeline would: (a) scan the container for known-bad patterns, (b) run the declared `tools/list` and assert each tool's `inputSchema` matches what the server actually accepts, (c) sandbox-probe each tool with a synthetic input to check it doesn't touch the network when it claims it doesn't, (d) require a code-signing certificate from the author. The output of that pipeline would replace the hand-curated flag.
- ### Resume bullet
- > Built an MCP (Model Context Protocol) server marketplace in Next.js 16 + Prisma/SQLite with a 3-column registry UI, hybrid BM25 + hashing-embedding + RRF search over the catalog, a contract-faithful mock Docker runtime (deterministic mock invoke, real Stripe-swappable), per-user daily quota enforcement (429 with `dailyQuota/used`), a persisted audit log of every tool invocation, and an admin analytics dashboard. 118 unit tests across 8 pure-logic modules. Architecture is mock-everything-but-the-contracts so the real Docker + real Stripe stretch goals are single-file swaps.
- ---
- ## License
- MIT — see `LICENSE`.
- ---
- ## Push to GitHub
- When ready to publish (do **not** push from inside the sandbox without explicit creds):
- ```bash
- gh repo create mcp-server-marketplace --public --source=. --remote=origin --push
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.