{
  "markdown": "# Mukoko News\n\n**Pan-African news, in one place.**\n\n\"Mukoko\" means \"Beehive\" in Shona — where community gathers and stores knowledge. Mukoko News aggregates news from 100+ sources across all 54 African Union member states, surfacing the stories that matter to the continent.\n\n[![Live site](https://img.shields.io/badge/live-news.mukoko.com-brightgreen)](https://news.mukoko.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n---\n\n## What is this?\n\nThis repository is the **Next.js 15 frontend** for Mukoko News, deployed on Vercel. It is one part of a three-repo platform:\n\n| Repo | Role |\n|---|---|\n| **`nyuchi/mukoko-news`** (this repo) | Web frontend — Next.js 15, Vercel |\n| `nyuchi/mukoko-news-gateway` | Public API + MCP server — Cloudflare Workers |\n| `nyuchi/mukoko-news-pipeline` | Data pipeline — Fly.io + Cloudflare |\n\nThe frontend reads news data directly from MongoDB Atlas via Next.js Server Actions.\n\n---\n\n## Features\n\n- **Pan-African coverage** — 54 countries, 100+ sources, updated continuously\n- **Discover** — browse by country, category, or source\n- **NewsBytes** — TikTok-style vertical swipe feed for quick headlines\n- **Search** — full-text search across all articles\n- **Dark mode** — respects system preference\n- **Embed widgets** — drop a news feed into any site with one `<script>` tag\n- **MCP server** — AI assistants can query Pan-African news at `news.mukoko.dev/mcp`\n- **Accessible** — Radix UI primitives, WCAG AAA contrast, Schema.org structured data\n\n---\n\n## Contributing\n\nWe 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**: all 448 tests run against mocked data, and most UI work can be done with the dev server pointed at the live API.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\n### Quick start for contributors\n\n```bash\n# Prerequisites: Node.js 20+, pnpm 10+\ngit clone https://github.com/nyuchi/mukoko-news.git\ncd mukoko-news\npnpm install\n\n# Run the test suite — no credentials needed\npnpm test\n\n# Start the dev server (reads from the live API by default)\ncp .env.example .env.local\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000).\n\n### What you can work on without credentials\n\n- All React components in `src/components/`\n- Page layouts and routing in `src/app/`\n- The embed widget script in `public/embed/`\n- Any of the 448 unit and integration tests — they all mock the data layer\n- Documentation and accessibility improvements\n\n### Running tests\n\n```bash\npnpm test             # full suite\npnpm test:watch       # watch mode\npnpm test:coverage    # with coverage report\n```\n\n---\n\n## Tech stack\n\n| Layer | Technology |\n|---|---|\n| Framework | Next.js 15, App Router, React 19 |\n| Styling | Tailwind CSS 4, CSS variables |\n| Components | Radix UI (accessible primitives) |\n| Icons | Lucide React |\n| Theme | next-themes |\n| Auth | WorkOS AuthKit |\n| Data | MongoDB Atlas via Server Actions |\n| Tests | Vitest, React Testing Library |\n| Deploy | Vercel |\n\n### Design system\n\nNyuchi Brand v6 — African Minerals palette:\n\n| Token | Colour | Name |\n|---|---|---|\n| Primary | `#4B0082` | Tanzanite |\n| Secondary | `#0047AB` | Cobalt |\n| Accent | `#5D4037` | Gold |\n| Surface | `#FAF9F5` | Warm Cream |\n\nFonts: Noto Serif (headings) + Plus Jakarta Sans (body).\n\n---\n\n## Embed widget\n\nAdd a Mukoko News feed to any website:\n\n```html\n<script src=\"https://news.mukoko.com/embed/widget.js\"\n        data-layout=\"cards\"\n        data-feed=\"latest\"\n        data-country=\"ZW\">\n</script>\n```\n\n**Layouts**: `cards` · `compact` · `hero` · `ticker` · `list`  \n**Feeds**: `top` · `featured` · `latest` · `location`  \n**Country**: any ISO 3166-1 alpha-2 code (e.g. `ZW`, `KE`, `ZA`, `NG`)\n\n---\n\n## MCP server\n\nAI assistants and agents can query Pan-African news via the [Model Context Protocol](https://modelcontextprotocol.io):\n\n```json\n{\n  \"mcpServers\": {\n    \"mukoko-news\": {\n      \"type\": \"http\",\n      \"url\": \"https://news.mukoko.dev/mcp\"\n    }\n  }\n}\n```\n\nNo authentication required. The MCP server lives in [`nyuchi/mukoko-news-gateway`](https://github.com/nyuchi/mukoko-news-gateway).\n\n---\n\n## Project structure\n\n```\nsrc/\n├── app/              # Pages (Next.js App Router)\n├── components/\n│   ├── ui/           # Shared components (ArticleCard, Skeleton, ErrorBoundary, …)\n│   └── layout/       # Header, footer, mobile nav\n├── contexts/         # PreferencesContext, ThemeContext\n└── lib/\n    ├── actions/      # Server Actions — all database reads go through here\n    ├── mongodb/      # MongoDB query helpers\n    ├── constants.ts  # Countries, categories, URL utilities\n    └── utils.ts      # Formatting + security helpers\npublic/\n└── embed/            # Self-contained widget script\n```\n\n---\n\n## Security\n\nWe take security seriously. Report vulnerabilities by email to **security@nyuchi.com** — please do not open a public GitHub issue. See [SECURITY.md](SECURITY.md) for details.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\"Ndiri nekuti tiri\" — I am because we are\n\nBuilt by [Nyuchi Technologies](https://nyuchi.com) and open-source contributors.\n",
  "bytes": 5299,
  "sha": "39a7fe282414584c2f1dce5eb3d11990ffb6c80a40c3224841da7af7cef1770a",
  "repo_slug": "nyuchi/mukoko-news",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nyuchi_mukoko_news_7273e455/readme"
}