Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/babyline00--mcp-server-marketplace/badge.svg)](/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

i

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
  1. # MCP Server Marketplace
  2. 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.
  3. This is Project #33 of the 110-project portfolio — a fresh rebuild after the original was lost to a sandbox recycle.
  4. ---
  5. ## Overview
  6. 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.
  7. The end-to-end flow:
  8. ```
  9. ┌─ Header ───────────────────────────────────────────────────────────────┐
  10. │ Mock user + plan badge + Manage subscription button │
  11. ├──────────────┬───────────────────────────────────────┬──────────────────┤
  12. │ Left │ Center: server cards grid │ Right tabs │
  13. │ ───── │ ───────────────────────────────── │ ───────────── │
  14. │ Search │ ┌────────┐ ┌────────┐ ┌────────┐ │ My Installations│
  15. │ Category │ │ Server │ │ Server │ │ Server │ │ Audit Log │
  16. │ Sort │ └────────┘ └────────┘ └────────┘ │ Admin analytics │
  17. │ Stats │ │ │
  18. └──────────────┴───────────────────────────────────────┴──────────────────┘
  19. │ │ │
  20. ▼ ▼ ▼
  21. GET /api/servers POST /api/servers/[id]/install GET /api/audit
  22. (BM25+RRF) POST /api/installations/[id]/invoke GET /api/admin/stats
  23. POST /api/subscriptions POST /api/subscriptions
  24. │
  25. ▼
  26. ┌──────────────────────┐
  27. │ mock-invoke.ts │ ← deterministic mock result
  28. │ (real Docker = stretch goal)
  29. └──────────────────────┘
  30. │
  31. ▼
  32. ┌──────────────────────┐
  33. │ AuditLog + quota │
  34. └──────────────────────┘
  35. ```
  36. ---
  37. ## MVP scope vs. stretch goals
  38. | Feature | MVP (this repo) | Stretch goal |
  39. |---|---|---|
  40. | 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 |
  41. | Billing | Mock Stripe checkout — no payment taken, just inserts a Subscription row + flips `user.planId` | Real Stripe Checkout + webhooks, customer portal, invoicing |
  42. | 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 |
  43. | Search | BM25 + hashing-embedding (vector) + RRF, all in-memory | Plug OpenAI text-embedding-3-small via `EMBEDDINGS_API_KEY`; persistent pgvector / sqlite-vec |
  44. | Author revenue share | N/A | Stripe Connect, author payouts, onboarding flow |
  45. | Server verification | Hand-curated `verified: boolean` flag on the registry row | Automated verification pipeline: container scanning, tool input-schema validation, sandbox probes, signature |
  46. ---
  47. ## Features
  48. - **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`.
  49. - **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.
  50. - **Category filter + sort.** Sidebar filters by category; sort dropdown toggles most-installs / verified-first / recently-added. Search overrides sort when `q` is present.
  51. - **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.
  52. - **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.
  53. - **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).
  54. - **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.
  55. - **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.
  56. - **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).
  57. - **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.
  58. ---
  59. ## Tech stack
  60. - **Framework**: Next.js 16 with App Router (TypeScript 5)
  61. - **Styling**: Tailwind CSS 4 with shadcn/ui (New York) + Lucide icons
  62. - **Database**: Prisma 6 + SQLite (per-app DB isolation under `db/custom.db`)
  63. - **Search**: in-memory BM25 + hashing-embedding (384-dim, FNV-1a signed-bag) + RRF fusion
  64. - **State**: React hooks + fetch (no Zustand needed for an MVP single page)
  65. - **Tests**: `bun test` with 118 unit tests across 8 modules
  66. - **MCP protocol**: `@modelcontextprotocol/sdk` is declared in `package.json` (mocked — not actually invoked; we mock the protocol intentionally to keep the MVP sandbox-free)
  67. ---
  68. ## Architecture
  69. ```
  70. ┌──────────────────────────────────────────┐
  71. │ Browser (page.tsx) │
  72. │ Header · Left sidebar · Server grid │
  73. │ Right tabs: Installs / Audit / Admin │
  74. └────────────┬─────────────────────────────┘
  75. │ fetch /api/* (x-mock-user-email header)
  76. ▼
  77. ┌────────────────────────────────────────────────────────────────┐
  78. │ Next.js 16 Route Handlers │
  79. │ │
  80. │ /api/servers /api/servers/[id]/install │
  81. │ /api/servers/[id] /api/installations │
  82. │ /api/installations/[id]/invoke /api/installations/[id] │
  83. │ /api/audit /api/admin/stats │
  84. │ /api/subscriptions /api/plans /api/stats │
  85. │ /api/users /api/users/me │
  86. └────────┬───────────────────────┬─────────────────────┬─────────┘
  87. │ │ │
  88. ▼ ▼ ▼
  89. ┌─────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
  90. │ src/lib/ │ │ src/lib/ │ │ Prisma 6 + SQLite │
  91. │ server-search.ts │ │ mock-invoke.ts │ │ Server │
  92. │ bm25.ts │ │ quota.ts │ │ User · Plan │
  93. │ embeddings.ts │ │ subscription.ts │ │ Installation │
  94. │ hybrid-search.ts │ │ audit.ts │ │ AuditLog │
  95. │ category.ts │ │ plan.ts │ │ Subscription │
  96. │ mock-user.ts │ │ install-token.ts │ │ │
  97. └─────────────────────┘ └────────────────────┘ └────────────────────┘
  98. pure logic pure logic single file:
  99. (testable) (testable) db/custom.db
  100. ```
  101. 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`.
  102. ---
  103. ## Setup
  104. ```bash
  105. # 1. Install deps
  106. bun install
  107. # 2. Push the Prisma schema to the isolated SQLite DB
  108. bun run db:push
  109. # 3. Seed 3 plans + demo admin user + demo regular user + 15 hardcoded MCP servers
  110. bun run seed
  111. # 4. Run the dev server
  112. bun run dev
  113. # → open the Preview Panel to view the app (no http://localhost:3000 from outside the sandbox)
  114. # 5. Run the unit tests
  115. bun test
  116. ```
  117. ### Per-app DB isolation (CRITICAL)
  118. 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:
  119. ```json
  120. "db:push": "DATABASE_URL=\"$(pwd)/db/custom.db\" prisma db push --accept-data-loss"
  121. ```
  122. `.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.
  123. ---
  124. ## Tests
  125. ```bash
  126. bun test
  127. ```
  128. 118 unit tests across 8 modules:
  129. | File | Tests | What it covers |
  130. |---|---|---|
  131. | `quota.test.ts` | 14 | `checkQuota` allowed/over-quota, default-to-0 defensive, team vs free vs pro |
  132. | `mock-invoke.test.ts` | 19 | `mockInvoke` happy path + error cases, `stableHash` determinism, `buildMockOutput` typed synthesis |
  133. | `audit.test.ts` | 9 | `formatAuditEntry` happy path, JSON parse, truncation, malformed input |
  134. | `server-search.test.ts` | 17 | BM25, vector, and hybrid (RRF) ranking; "filesystem" ranks filesystem server first |
  135. | `category.test.ts` | 15 | `categorizeServer` per-category hits + default fallback + edge cases |
  136. | `plan.test.ts` | 16 | `planLimits`, `isHigherTier`, `formatPrice`, `PLAN_ORDER` |
  137. | `subscription.test.ts` | 14 | `activeSubscription`, `effectivePlan`, `mockCreateCheckoutSession` |
  138. | `install-token.test.ts` | 14 | `generateInstallToken` uniqueness + `isValidInstallToken` shape validation |
  139. ---
  140. ## Environment variables
  141. | Variable | Default | Notes |
  142. |---|---|---|
  143. | `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. |
  144. | `EMBEDDINGS_API_KEY` | unset | Optional. Set to enable OpenAI-compatible embeddings; falls back to the deterministic hashing-embedding when unset. |
  145. | `EMBEDDINGS_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint. |
  146. | `EMBEDDINGS_MODEL` | `text-embedding-3-small` | Embedding model id. |
  147. | `ZAI_API_KEY` | unset | Optional. Powers LLM enrichment via `z-ai-web-dev-sdk` (not used in the MVP). |
  148. | `STRIPE_SECRET_KEY` | unset | Optional. Real Stripe integration is mocked; this is reserved for the stretch goal. |
  149. | `STRIPE_WEBHOOK_SECRET` | unset | Optional. Same as above. |
  150. ---
  151. ## Project structure
  152. ```
  153. 33-mcp-server-marketplace/
  154. ├── prisma/
  155. │ └── schema.prisma # 6 models (Server, User, Plan, Installation, AuditLog, Subscription)
  156. ├── scripts/
  157. │ └── seed-servers.ts # 3 plans + admin + alice + 15 hardcoded MCP servers
  158. ├── src/
  159. │ ├── app/
  160. │ │ ├── layout.tsx
  161. │ │ ├── page.tsx # 3-column marketplace UI (single client component)
  162. │ │ ├── globals.css
  163. │ │ └── api/
  164. │ │ ├── servers/route.ts # GET (filter + hybrid search + sort)
  165. │ │ ├── servers/[id]/route.ts # GET single
  166. │ │ ├── servers/[id]/install/route.ts # POST (idempotent)
  167. │ │ ├── installations/route.ts # GET (user-scoped)
  168. │ │ ├── installations/[id]/route.ts # DELETE (soft uninstall)
  169. │ │ ├── installations/[id]/invoke/route.ts # POST (quota + mock + audit)
  170. │ │ ├── audit/route.ts # GET last 50
  171. │ │ ├── admin/stats/route.ts # GET admin analytics
  172. │ │ ├── subscriptions/route.ts # POST mock Stripe
  173. │ │ ├── plans/route.ts # GET catalog
  174. │ │ ├── stats/route.ts # GET global counters
  175. │ │ ├── users/route.ts # GET mock users
  176. │ │ └── users/me/route.ts # GET current mock user
  177. │ ├── components/ui/ # shadcn/ui (New York) — 16 components copied from parent
  178. │ ├── hooks/use-toast.ts
  179. │ └── lib/
  180. │ ├── db.ts # Prisma client (singleton)
  181. │ ├── utils.ts # cn() class merge helper
  182. │ ├── tokenizer.ts # lowercase + Unicode-aware + CJK split
  183. │ ├── bm25.ts # Okapi BM25 in-memory index
  184. │ ├── embeddings.ts # 384-dim hashing embedding (+ optional OpenAI provider)
  185. │ ├── hybrid-search.ts # RRF fusion (k=60 default)
  186. │ ├── chunker.ts # markdown-aware chunker (used by search index)
  187. │ ├── server-search.ts # hybridServerSearch(Sync) over ServerDoc
  188. │ ├── mock-invoke.ts # deterministic mock tool execution
  189. │ ├── quota.ts # checkQuota + buildQuotaInput
  190. │ ├── plan.ts # PLANS catalog + planLimits + formatPrice
  191. │ ├── subscription.ts # effectivePlan + mockCreateCheckoutSession
  192. │ ├── audit.ts # formatAuditEntry(s)
  193. │ ├── category.ts # categorizeServer (keyword lexicon)
  194. │ ├── install-token.ts # cuid-like token generator + validator
  195. │ ├── mock-user.ts # getMockUser + listMockUsers (header-based)
  196. │ └── __tests__/ # 8 test files, 118 tests
  197. ├── package.json
  198. ├── tsconfig.json
  199. ├── next.config.ts
  200. ├── postcss.config.mjs
  201. ├── tailwind.config.ts
  202. ├── components.json
  203. ├── eslint.config.mjs
  204. ├── .env / .env.example
  205. ├── .gitignore
  206. ├── LICENSE (MIT)
  207. └── README.md
  208. ```
  209. ---
  210. ## Case study — what's mock and what's real
  211. ### Mock sandbox runtime (`src/lib/mock-invoke.ts`)
  212. The MVP does **not** run Docker containers. `mockInvoke(server, toolName, input)` is a pure function that:
  213. 1. Validates the tool exists on the server (throws `TOOL_NOT_FOUND` otherwise).
  214. 2. Validates required input fields against the tool's `inputSchema.required` (throws `MISSING_REQUIRED` otherwise).
  215. 3. Computes a deterministic FNV-1a hash of `(server.slug, toolName, JSON.stringify(input))` — the same call always yields the same hash.
  216. 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.).
  217. 5. Returns a deterministic `durationMs` in 5-50ms derived from the hash.
  218. 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.
  219. ### Mock Stripe (`src/lib/subscription.ts` + `/api/subscriptions/route.ts`)
  220. 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:
  221. 1. `mockCreateCheckoutSession(userId, planId)` returns a synthetic `cs_test_...` session id + a fake redirect URL (for completeness — the UI doesn't actually redirect).
  222. 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.
  223. 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.
  224. ### Quota model (`src/lib/quota.ts`)
  225. 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`).
  226. ### What I'd do differently
  227. With more time, the obvious stretch goals, in priority order:
  228. 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.
  229. 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.
  230. 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.
  231. 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.
  232. 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.
  233. ### Resume bullet
  234. > 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.
  235. ---
  236. ## License
  237. MIT — see `LICENSE`.
  238. ---
  239. ## Push to GitHub
  240. When ready to publish (do **not** push from inside the sandbox without explicit creds):
  241. ```bash
  242. gh repo create mcp-server-marketplace --public --source=. --remote=origin --push
  243. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.