README ↔ docs/ sync drift — 89 entries missing from docs/, 1255 missing from README, 11 description mismatches

[ivannikolovbg]

Summary

While reviewing PR #488 I noticed pre-existing drift between README.md and the per-category docs/*.md files. After auditing all 34 categories, the gap is significant enough that I want to check with you on the preferred shape of a fix before opening a 100+-line PR cold.

Drift snapshot

Two kinds of drift exist:

A) Entries in README but missing from docs/*.md — 89 entries across 19 sections. These look like clear drift since docs/ is supposed to be the fuller list. Examples:

• finance--crypto.md (18 entries): cnghockey/sats4ai-mcp-server, atxp-dev/atxp, covalenthq/goldrush-mcp-server, …
• marketing-sales--crm.md (9 entries): sharozdawa/ai-visibility, brandu-mos/konquest-meta-ads-mcp, …
• developer-productivity--utilities.md (9 entries): cafeTechne/antigravity-link-extension, OzorOwn/frostbyte-mcp, …

B) Entries in docs/*.md but missing from README — 1255 entries (after taking the recent tail of each docs file). The README header says "we only show the most recent 30 servers in each category", but actual README per-section counts range from 5 to 75, so the rule isn't strict. Some sections clearly have recent docs additions that never made it to README. Example I noticed first (which led to this audit):

• travel--transportation.md: 7 entries in docs, 6 of them at the very bottom (most recent), missing from README. e.g. r-huijts/ns-mcp-server, sunsetcoder/flightradar24-mcp-server, GongRzhe/TRAVEL-PLANNER-MCP-Server.

C) Description mismatches — 11 entries with same slug in both files but different descriptions (e.g. walkojas-boop/regexforge, arcadia-finance/mcp-server, shopsavvy/shopsavvy-mcp-server).

Question

How would you like the cleanup landed?

1. One large sync PR — covers all three categories above. Probably ~1300+ lines changed across README + most docs/ files.
2. Section-by-section PRs — one PR per affected category (~19-27 PRs depending on scope), easier to review but heavier on your queue.
3. README→docs only — just fix the 89 unambiguous "in README, missing from docs" entries first; revisit the docs→README direction later once you've clarified the truncation rule.
4. Close as known debt — you're aware, no action needed.

I can do any of the above. Happy to start with whichever you prefer, or skip if you'd rather handle internally.

For reference, the audit script is just standard re parsing of ^- \[name\](url): description lines per section — happy to share if useful.

— spotted while working on #488 (which is unrelated and self-contained)

[wilsonccccc]

Wow — thank you for taking the time to do this audit. This is genuinely above-and-beyond for someone who landed here just to submit their own project; we really appreciate it.

Yes, please go ahead — and we'd love to have you do it. Of the four options you laid out, option 3 (README → docs only) is the path we'd love to take first: those 89 entries are unambiguous drift and a clean win. The other directions are policy questions we can tackle separately.

A few notes to make the work easier:

• One PR vs many — completely your call. If it's mostly mechanical, one bundled PR is great; if you'd rather split by category for easier review, we're happy with that too. Whichever feels lower-friction for you.
• Description mismatches (11) — go with whichever description reads as more accurate / current. If genuinely unclear, default to the README version since that's typically the one contributors update first.
• Docs → README direction (the 1255) — let's set that aside for now. The "30 most recent per category" line in the README header is a soft rule, and we want to think through the truncation policy properly before bulk-syncing entries upward. That's a separate conversation, not something for you to solve.

And yes please share the audit script — that would be incredibly useful as a maintainer tool to catch drift early. Happy to land it in a scripts/ or tools/ directory in the repo if you're open to that.

Open the PR(s) whenever you're ready — no rush, and again, thanks so much. Contributors like you make this list better for everyone.