Mukoko News

---

関連リポジトリ。 このリポジトリは、読者向けのウェブアプリです。 ゲートウェイは公開APIとMCP サーバーを提供し、 パイプラインはデータの取り込みと拡充を担います。課題は、そのコードを所有するリポジトリに報告してください。

---

これは何ですか？

このリポジトリはMukoko NewsのNext.js 15フロントエンドで、Vercelにデプロイされています。3つのリポジトリで構成されるプラットフォームの一部です。

リポジトリ	役割
mukoko-dev/mukoko-news（このリポジトリ）	ウェブフロントエンド — Next.js 15、Vercel
mukoko-dev/mukoko-news-gateway	公開API + MCP サーバー — Cloudflare Workers
mukoko-dev/mukoko-ingestion-pipeline	データパイプライン — Fly.io + Cloudflare

フロントエンドは、Next.js Server Actionsを介してMongoDB Atlasからニュースデータを直接読み込みます。

---

特長

• 汎アフリカをカバー — この説明の意味についてはカバレッジをご覧ください
• 見つける — 国、カテゴリ、ソースごとに閲覧できます
• NewsBytes — 見出しをすばやくチェックできる、TikTok風の縦スワイプフィードです
• 検索 — すべての記事を対象とする全文検索です
• ダークモード — システム設定に従います
• 埋め込みウィジェット — <script>タグひとつで、あらゆるサイトにニュースフィードを設置できます
• MCP サーバー — AI アシスタントはnews.mukoko.dev/mcpで汎アフリカのニュースを検索できます
• アクセシブル — Radix UIプリミティブ、WCAG AAAコントラスト、Schema.org構造化データに対応しています

---

対象範囲

アフリカ連合の全54加盟国が対象です。現在 稼働中 の国の数は定数ではなく、クエリで取得します。

getLiveCoverageAction() は、過去30日間に実際に公開基準を満たした国の数をカウントします。src/lib/constants.ts の coverageFragment(n) と coverageClaim(n) だけが正式な表現であり、すべてのページ、メタタグ、JSON-LD の説明文はそのいずれかを差し込みます。そのため、ある国でデータの生成が始まると自動的に表示され、生成が止まると自動的に表示対象から外れます。コードを変更したり、ファイル内の数値を誰かが編集したりする必要はありません。

この README には、現在の数値をあえて記載していません。テストのないドキュメントに固定の数値を記載することこそ、このアプリの9か所でそれぞれ別の数値にずれた「アフリカの16か国」という主張が生じた原因です。src/lib/__tests__/coverage-claim.test.ts が src/ でこのルールを徹底しており、ここでは数値を記載しないことで徹底しています。

貢献

フロントエンドへの貢献を歓迎します。UI の改善、新機能、バグ修正、アクセシビリティ、テスト、ドキュメントなど、どのような内容でも歓迎です。貢献にデータベース接続は必要ありません。テストスイート全体はモックデータで実行でき、ほとんどの UI 作業は開発サーバーからライブ API に接続して進められます。

詳しい手順は CONTRIBUTING.md をご覧ください。また、Discord で気軽に声をかけてください。質問への回答を得たり、取り組もうとしている Issue にすでに誰かが着手しているか確認したりするには、Discord が最も手早い方法です。

コントリビューター向けクイックスタート

# Prerequisites: Node.js 20+, pnpm 10+
git clone https://github.com/mukoko-dev/mukoko-news.git
cd mukoko-news
pnpm install

# Run the test suite — no credentials needed
pnpm test

# Start the dev server (reads from the live API by default)
cp .env.example .env.local
pnpm dev

http://localhost:3000 を開きます。

認証情報なしで作業できる内容

• src/components/ 内のすべての React コンポーネント
• src/app/ 内のページレイアウトとルーティング
• public/embed/ 内の埋め込みウィジェットスクリプト
• ユニットテストと統合テスト。いずれもデータレイヤーをモックします
• ドキュメントとアクセシビリティの改善

テストの実行

pnpm test             # full suite
pnpm test:watch       # watch mode
pnpm test:coverage    # with coverage report

---

技術スタック

レイヤー	技術
フレームワーク	Next.js 15、App Router、React 19
スタイリング	Tailwind CSS 4、CSS 変数
コンポーネント	Radix UI（アクセシブルなプリミティブ）
アイコン	Lucide React
テーマ	next-themes
認証	WorkOS AuthKit
データ	Server Actions 経由の MongoDB Atlas
テスト	Vitest、React Testing Library
デプロイ	Vercel

デザインシステム

パレット、背景スケール、文字サイズの段階設定の上流ソースはMziziです。この連携の仕組みは、「Mziziから読み込む」という表現から想像するより緩やかなため、正確に把握してください。

• src/app/globals.css には、このアプリ用にコピーした値が保存されています。ビルド時にも実行時にも取得は行われません。Mzizi パッケージへの依存も、ネットワーク呼び出しもありません。
• src/app/__tests__/design-tokens.test.ts はこのスタイルシートを解析し、テストファイル内の SNAPSHOT オブジェクトリテラルに対して各値を検証します。独立したスナップショット成果物はありません。
• このスナップショットは、日付を記録した更新時に mzizi_get_tokens が返した値のコピーです。更新は、MCP に対して人が再度クエリを行い、変更をレビューしたうえで意図的に行います。アサーションを緩めて更新することはありません。

そのため、CI は globals.css が固定されたコピーからずれていないかを検出します。Mzizi 自体の変更は検出しません。それを反映するのが、意図的な更新です。

Mzizi のフルパレットは21 の色系統で構成され、ミネラル、ヘリテージ、エクスペリメンタルがそれぞれ7色です。このアプリでは7色のミネラルを使用しており、まず目にするのは次の4色です。

役割	ライト	ダーク	ミネラル
--primary	#4B0082	#B388FF	タンザナイト
--secondary	#0047AB	#00B0FF	コバルト
--success	#004D40	#64FFDA	マラカイト
--surface	#EEEEEC	#131211	(Mzizi の surface — ミネラルではなく背景の段階色)

フォントは、Noto Serif（ディスプレイ／見出し）、Noto Sans（UI／本文）、JetBrains Mono （データとラベル）を使用し、next/font 経由でセルフホストしています。

---

埋め込みウィジェット

任意のウェブサイトに Mukoko News フィードを追加できます。

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

レイアウト：cards · compact · hero · ticker · list
フィード：top · featured · latest · location
国：ISO 3166-1 alpha-2 コード（例：ZW、KE、ZA、NG）

---

MCP サーバー

AI アシスタントとエージェントは、Model Context Protocol 経由で汎アフリカのニュースを照会できます。

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

読み取りツールは匿名で応答します。サーバー本体は mukoko-dev/mukoko-news-gateway にあり、 このアプリではなく news.mukoko.dev にデプロイされています。news.mukoko.com には /mcp ルートがありません。

---

プロジェクト構成

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 helpers
public/
└── embed/            # Self-contained widget script

---

セキュリティ

セキュリティを重視しています。脆弱性は [email protected] までメールで報告してください。公開の GitHub issue は作成しないでください。詳細は SECURITY.md を参照してください。

---

ライセンス

このリポジトリには LICENSE ファイルが含まれておらず、package.json にも license フィールドはありません。以下の記述とは異なり、現在ライセンスは付与されていません。「オープンソースのコントリビューター」という表現を正確なものにするには、LICENSE ファイルを追加する必要があります。

© Nyuchi Africa (PVT) Ltd.

---

「Ndiri nekuti tiri」— 私があるのは、私たちがあるから

Nyuchi Web Services とコントリビューターによって開発されました。