🚀 femtech-radar

[!IMPORTANT]

🤖 Read this with your AI agent — don't read it by hand.

This repo is written agent-first. Point Claude Code, GitHub Copilot, Cursor, or any agent at it:"Read the README and AGENTS.md, then help me run / extend this."Structure + AGENTS.md are optimized for agent comprehension.

• 🌟 Introduction
• ✨ Key Features
• 🛠️ Tech Stack
• 🏗️ Architecture
• 🚀 Getting Started
• 🛳 Project Status & Roadmap
• 📖 Usage Guide
• ⌨️ Development
• 🤝 Contributing
• ❤️ Sponsor
• 📄 License
• 🙋‍♀️ Author

🌟 Introduction

The FemTech and women's-health world produces a scattered firehose of signal — research preprints, funding and product news, community opportunities, technical discussion — across dozens of sources. femtech-radar turns that noise into a curated, deduplicated, ranked digest, using only GitHub-native primitives plus a reusable Model Context Protocol (MCP) server.

This repository is v1: the MCP server — the deterministic "brain" of the pipeline. It fetches items from multiple sources, normalizes them into one shape, removes duplicates, and scores each item by relevance × popularity × freshness, then exposes the result over MCP so it can be driven by a GitHub Agentic Workflow (gh aw), Claude Desktop, or any MCP client.

It's built for FemTech / women-in-tech practitioners who want signal without the noise — and as a reference implementation of the gh aw × MCP × GitHub Pages pattern. The eventual product (see Roadmap) is a subscribable weekly intelligence site that updates itself for free on a public GitHub repo.

✨ Key Features

1 One MCP tool, a whole radar — radar_collect returns normalized, deduped, scored items per section. v1 ships industry (Google News) and research (arXiv); opportunities and discussions are defined and roadmapped.

2 Deterministic, testable core — fetch → normalize → dedupe → score. The server makes no editorial judgment; that's left to the agent that drives it. 28 unit tests, and zero real network calls in tests (all I/O is injected).

3 Pluggable source adapters — each source is one file behind a uniform Adapter interface. Add a feed by writing a collect() that returns RadarItem[].

4 Resilient by construction — every source failure degrades to an empty result plus a warning; a malformed URL or date never throws out of a run.

5 GitHub-native, near-zero cost — designed to run inside GitHub Actions on a public repo, where Actions and Pages are free; the only metered resource is a few Copilot credits per week.

6 Reusable anywhere MCP runs — drop it into Claude Desktop or any MCP client; it isn't coupled to this project.

🛠️ Tech Stack

• Language / Runtime: TypeScript 5 (strict, ESM) · Node.js ≥ 20
• MCP: @modelcontextprotocol/sdk (stdio server)
• Parsing / validation: Zod (schema & runtime validation) · fast-xml-parser (Atom/RSS)
• Tooling: pnpm workspaces (monorepo) · Vitest (tests) · tsup (build)
• Roadmap layers: GitHub Agentic Workflows (gh aw) orchestration · Astro + RSS site on GitHub Pages

🏗️ Architecture

graph TD
    subgraph Sources
      A1[arXiv API]
      A2[Google News RSS]
    end
    A1 --> AD[Source adapters<br/>normalize → RadarItem]
    A2 --> AD
    AD --> P["collect()<br/>dedupe → score → sort → since-filter"]
    P --> T[MCP tools<br/>radar_collect · radar_sources]
    T --> C[MCP clients]
    C -.roadmap.-> W[Weekly gh aw workflow]
    W -.roadmap.-> S[Astro + RSS site on GitHub Pages]

Separation of determinism vs judgment: the MCP server does only deterministic work (fetch, normalize, dedupe, score). Editorial choices — which items to feature, how to summarize — belong to the agent (gh aw + Copilot) that drives it. This keeps the core unit-testable and reusable.

🚀 Getting Started

Prerequisites

• Node.js ≥ 20 (the server uses global fetch)
• pnpm ≥ 9 (npm i -g pnpm)
• (optional) an MCP client such as Claude Desktop, or the gh aw CLI

Installation

git clone https://github.com/ChanMeng666/femtech-radar.git
cd femtech-radar
pnpm install

# Build the MCP server
pnpm --filter @chanmeng666/femtech-radar-mcp build

# Run the test suite (28 tests)
pnpm --filter @chanmeng666/femtech-radar-mcp test

The built server is an executable stdio MCP server at packages/mcp-server/dist/index.js.

🛳 Project Status & Roadmap

This is the first of three planned layers (see docs/superpowers/specs for the full design):

• ✅ v1 — MCP server (this release): industry (Google News) + research (arXiv) adapters, dedupe/score pipeline, radar_collect / radar_sources tools, resilient error handling, 28 tests.
• ⏳ v2 — orchestration: opportunities + discussions adapters, publish to npm, a weekly gh aw workflow that curates a digest, ChatOps slash commands.
• ⏳ v3 — publishing: an Astro + RSS site auto-deployed to GitHub Pages from the weekly data.

📖 Usage Guide

femtech-radar is consumed as an MCP server. It exposes two tools:

In v1 only industry and research have adapters; opportunities and discussions return an empty list with a "no adapter for …" warning.

Use with GitHub Agentic Workflows (gh aw)

mcp-servers:
  femtech-radar:
    command: npx
    args: ["-y", "@chanmeng666/femtech-radar-mcp"]

Use with Claude Desktop

{
  "mcpServers": {
    "femtech-radar": {
      "command": "node",
      "args": ["/absolute/path/to/femtech-radar/packages/mcp-server/dist/index.js"]
    }
  }
}

npx @chanmeng666/femtech-radar-mcp works once the package is published to npm (v2). Until then, build locally and point your client at dist/index.js as shown above.

See packages/mcp-server/README.md for the full tool reference.

⌨️ Development

pnpm install                                              # install workspace deps
pnpm --filter @chanmeng666/femtech-radar-mcp test         # run tests (Vitest)
pnpm --filter @chanmeng666/femtech-radar-mcp build        # build with tsup

Project layout

packages/mcp-server/src/
├── schema.ts          # Zod RadarItem / WeeklyData (the shared data contract)
├── dedup.ts           # URL canonicalization + title-similarity dedupe
├── score.ts           # relevance × popularity × freshness scoring
├── adapters/          # one file per source (research = arXiv, industry = Google News)
├── collect.ts         # orchestration: adapter → dedupe → score → sort → since-filter
├── tools.ts           # radar_collect / radar_sources handlers
└── index.ts           # stdio MCP server entry

Adding a source adapter: implement the Adapter interface in adapters/, return RadarItem[] from collect(opts) using the injected fetcher (never call fetch directly — that keeps it testable), then wire it into ADAPTERS in collect.ts.

See AGENTS.md for AI-agent-oriented project conventions and gotchas.

🤝 Contributing

Contributions make the open-source community an amazing place to learn and create. Please read theContributing Guide and the Code of Conduct before you start,and use the provided issue / pull-request templates.

❤️ Sponsor

If this project helps you, please consider supporting its development:

For questions and help, see SUPPORT.md. For security issues, see SECURITY.md.

📄 License

This project is released under the MIT license.

🙋‍♀️ Author

Chan Meng