wellworn

Wellworn tells your agent which stack, library, skill, or design system to use, what breaks at the version in your lockfile, and who verified it, in under 800 tokens. It works without an account or key.

Without Wellworn

Your agent picks from training data. It reaches for the library it saw most in 2024, a version that no longer exists, or a package that was deprecated last spring. Sonatype measured 27.76% of AI dependency upgrade suggestions pointing to non-existent, deprecated, or unsafe versions.

Related MCP server: voyager

With Wellworn

Before it adds a dependency or lays out a screen, the agent calls recommend, compare, alternatives, traps, design, or docs and gets a verdict:

VERDICT auth for a Next.js app, solo dev, free tier
PICK Better Auth 1.7: own your users table; org and api-key plugins; no per-MAU bill
ALT Clerk: hosted UI and SSO in a week; wins when you accept per-MAU pricing
AVOID NextAuth: v5 migration stalled since 2025; session callback traps
TRAPS (2)
  [a1f4c0d2] major: role changes wait for the 5 min cookie cache
  [c9e3b7a1] minor: Drizzle adapter needs the schema passed explicitly
SKILL npx skills add WellWorn-dev/wellworn/skills/better-auth-nextjs
VERIFIED 2026-09-05 by youcef · recheck 2026-12-04 · sources 3
remaining: 59

Every verdict names a reviewer, a date, the version tested, and an expiry. A nightly job re-reads the registries; when a major version moves, the verdict is served with a [RECHECK] flag instead of going stale.

Works with

Any client that speaks Streamable HTTP takes the same URL: https://mcp.wellworn.dev/mcp. No key: 60 calls a day per IP. Free key: 2,000 a month per organization, sent as Authorization: Bearer ww_.... Clients that only speak stdio bridge with npx mcp-remote https://mcp.wellworn.dev/mcp.

Claude Code plugin

The plugin adds the server, a skill that tells Claude when to ask it, and a hook that prints known traps whenever a dependency manifest is about to change. The hook is advisory; it never blocks an edit and never sends file contents.

claude plugin marketplace add WellWorn-dev/wellworn
claude plugin install wellworn

Cursor

{ "mcpServers": { "wellworn": { "url": "https://mcp.wellworn.dev/mcp" } } }

Gemini CLI

{ "mcpServers": { "wellworn": { "httpUrl": "https://mcp.wellworn.dev/mcp" } } }

Tools

Plain text without MCP: curl "https://mcp.wellworn.dev/api/traps?library=better-auth&version=1.7.3".

What is in this repository

The web platform, the review tooling, and the signal pipeline that keeps verdicts fresh run at https://wellworn.dev and are not part of this repository.

Running the server yourself

pnpm install
cp packages/mcp/.env.example packages/mcp/.env   # DATABASE_URL, REDIS_URL
DATABASE_URL=... pnpm --filter @wellworn/db migrate
pnpm --filter @wellworn/mcp dev

Tests: pnpm test (Postgres and Redis required).

Contributing

Contributions are welcome: verdicts, traps, skills, client setup pages, and server fixes. Start with an issue template (verdict, trap, bug) or a pull request; see CONTRIBUTING.md and CODE_OF_CONDUCT.md. Traps are fastest through submit_trap; verdicts and corrections arrive as pull requests against verdicts/ and go through a human reviewer.

License

MIT for the code. Corpus CC BY-SA 4.0. Spec CC0.