Mukoko News

The sibling repos. This one is the reader-facing web app. The gateway is the public API and MCP server; the pipeline does the ingestion and enrichment. Issues land in whichever repo owns the code.

What is this?

This repository is the Next.js 15 frontend for Mukoko News, deployed on Vercel. It is one part of a three-repo platform:

The frontend reads news data directly from MongoDB Atlas via Next.js Server Actions.

Features

• Pan-African coverage — see Coverage for what that claim means
• Discover — browse by country, category, or source
• NewsBytes — TikTok-style vertical swipe feed for quick headlines
• Search — full-text search across all articles
• Dark mode — respects system preference
• Embed widgets — drop a news feed into any site with one <script> tag
• MCP server — AI assistants can query Pan-African news at news.mukoko.dev/mcp
• Accessible — Radix UI primitives, WCAG AAA contrast, Schema.org structured data

Coverage

All 54 African Union member states are in scope. The number that is live is a query, not a constant.

getLiveCoverageAction() counts the countries that actually cleared the publishing bar in the last 30 days, and coverageFragment(n) / coverageClaim(n) in src/lib/constants.ts are the only sanctioned wording — every page, meta tag and JSON-LD blurb interpolates one of them. So a country that starts producing appears on its own, and one that goes quiet drops off on its own, with no code change and nobody editing a number in a file.

This README deliberately does not print the current figure. A hard-coded count in a document nothing tests is exactly how the app came to claim "16 African countries" on nine surfaces that had each drifted apart. src/lib/__tests__/coverage-claim.test.ts enforces the rule for src/; here it is enforced by not writing one down.

Contributing

We welcome contributions to the frontend — UI improvements, new features, bug fixes, accessibility, tests, and documentation are all fair game. You do not need a database connection to contribute: the whole suite runs against mocked data, and most UI work can be done with the dev server pointed at the live API.

See CONTRIBUTING.md for the full guide, and come say hello in the Discord — it is the fastest way to get a question answered or to find out whether someone is already on the issue you picked.

Quick start for contributors

# Prerequisites: Node.js 20+, pnpm 10+git clone https://github.com/mukoko-dev/mukoko-news.gitcd mukoko-newspnpm install
# Run the test suite — no credentials neededpnpm test
# Start the dev server (reads from the live API by default)cp .env.example .env.localpnpm dev

Open http://localhost:3000.

What you can work on without credentials

• All React components in src/components/
• Page layouts and routing in src/app/
• The embed widget script in public/embed/
• Any of the unit and integration tests — they all mock the data layer
• Documentation and accessibility improvements

Running tests

pnpm test             # full suitepnpm test:watch       # watch modepnpm test:coverage    # with coverage report

Tech stack

Design system

Mzizi is the upstream source for the palette, the background scale and the type ramp. Be precise about how that binding works, because it is looser than "read from Mzizi" suggests:

• src/app/globals.css holds this app's copy of the values. Nothing is fetched at build time or at runtime — there is no Mzizi package dependency and no network call.
• src/app/__tests__/design-tokens.test.ts parses that stylesheet and asserts every value against a SNAPSHOT object literal inside the test file itself. There is no separate snapshot artefact.
• That snapshot is a copy of what mzizi_get_tokens returned on a dated, recorded refresh. It is updated deliberately, by a human re-querying the MCP in a reviewed change — never by relaxing an assertion.

So CI catches globals.css drifting away from the frozen copy. It does not catch Mzizi itself moving; that is what the deliberate refresh is for.

Mzizi's full palette is 21 colour families — seven minerals, seven heritage, seven experimental. This app uses the seven minerals; these four are the ones you meet first:

Fonts: Noto Serif (display/headings), Noto Sans (UI/body), JetBrains Mono (data and labels) — self-hosted via next/font.

Embed widget

Add a Mukoko News feed to any website:

<script src="https://news.mukoko.com/embed/widget.js"        data-layout="cards"        data-feed="latest"        data-country="ZW"></script>

Layouts: cards · compact · hero · ticker · list
Feeds: top · featured · latest · location
Country: any ISO 3166-1 alpha-2 code (e.g. ZW, KE, ZA, NG)

MCP server

AI assistants and agents can query Pan-African news via the Model Context Protocol:

{  "mcpServers": {    "mukoko-news": {      "type": "http",      "url": "https://news.mukoko.dev/mcp"    }  }}

The read tools answer anonymously. The server itself lives in mukoko-dev/mukoko-news-gateway and is deployed to news.mukoko.dev, not to this app — news.mukoko.com serves no /mcp route.

Project structure

src/├── app/              # Pages (Next.js App Router)├── components/│   ├── ui/           # Primitives (Button, Card, Skeleton, ErrorBoundary, …)│   ├── layout/       # Header, footer, mobile nav│   └── *.tsx         # Feature components (ArticleCard, HeroCard, ShareModal, …)├── contexts/         # PreferencesContext, CoverageContext (theme via next-themes)└── lib/    ├── actions/      # Server Actions — all database reads go through here    ├── mongodb/      # MongoDB query helpers    ├── constants.ts  # Countries, categories, URL utilities    └── utils.ts      # Formatting + security helperspublic/└── embed/            # Self-contained widget script

Security

We take security seriously. Report vulnerabilities by email to [email protected] — please do not open a public GitHub issue. See SECURITY.md for details.

Licence

This repository ships no LICENSE file, and package.json declares no license field. Despite the wording below, no licence is currently granted — a LICENSE file needs adding before the "open-source contributors" framing is accurate.

© Nyuchi Africa (PVT) Ltd.

"Ndiri nekuti tiri" — I am because we are

Built by Nyuchi Web Services and contributors.