AI-Powered Genealogy Research Agent built with the GitHub Copilot SDK
Built for the Copilot SDK Weekend Contest
- GEDCOM Import - Load your family tree from standard GEDCOM files
- Interactive Ancestor Tree - D3.js visualization of your ancestors
- AI Research Agent - Powered by GitHub Copilot SDK with custom tools
- Multi-Source Research - Searches Wikipedia, Wikidata, historical newspapers, and Google Books
- Python 3.9+ with FastAPI
- GitHub Copilot SDK for agent orchestration
- python-gedcom for GEDCOM parsing
- Custom research tools:
- Wikipedia REST API
- Wikidata SPARQL queries
- Chronicling America (historical newspapers 1770-1963)
- Google Books API
- React 18 with TypeScript
- Vite for fast development
- TailwindCSS for styling
- D3.js for family tree visualization
- React Markdown for rendering AI responses
- For decent results enable bing websearch tool use in your copilot settings
- GitHub Copilot subscription and a git PAT token
- Copilot CLI installed
- Python 3.9+ and Node.js 18+
git clone https://github.com/yourusername/treepilot.git
cd treepilotConfig your .env file with your GITHUB token, and google books token (optional)
cd backend
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
# Install dependencies
pip install -r requirements.txt
# Start the server
.\venv\Scripts\python.exe main.pyThe backend runs on http://localhost:8000
cd frontend
# Install dependencies
npm install
# Start development server
npm run devThe frontend runs on http://localhost:5173
Navigate to http://localhost:5173 in your browser.
- Import GEDCOM - Upload your family tree file (or use the included
sample-family.ged) - Browse Tree - Click on individuals to see their ancestor tree
- Research - Click a person and switch to the Research tab to have the AI agent search for information
A sample GEDCOM file is included (sample-family.ged) with a fictional 4-generation family including:
- Immigration from Ireland, Poland, and Sweden
- Various occupations and locations across the US
- 20 individuals spanning 1880-1992
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check |
/upload-gedcom |
POST | Upload and parse GEDCOM file |
/individuals |
GET | List all individuals |
/tree/{person_id} |
GET | Get ancestor tree for a person |
/youngest |
GET | Get youngest generation |
/export-gedcom |
GET | Download modified GEDCOM file |
/change-history |
GET | View metadata change history |
/chat |
POST | Non-streaming chat |
/chat/stream |
POST | Streaming chat (SSE) |
The AI agent has access to:
-
Wikipedia (
search_wikipedia)- Biographical information
- Historical context
- Notable individuals
-
Wikidata (
search_wikidata)- Structured data (birth/death dates, places)
- Family relationships
- Occupations
-
Chronicling America (
search_newspapers)- Historical newspapers 1770-1963
- Obituaries, birth/marriage announcements
- Local news mentions
-
Google Books (
search_books)- Genealogy guides
- Local histories
- Biographical works
The AI can query and update your family tree directly:
Read Tools:
get_person_metadata- Full details (name, dates, places, occupation, notes)get_person_parents- Get a person's parentsget_person_children- Get a person's childrenget_person_spouses- Get a person's spouse(s)get_person_siblings- Get a person's siblingsget_person_grandparents- Get a person's grandparentsget_person_aunts_uncles- Get a person's aunts and unclesget_person_cousins- Get a person's cousins
Write Tools:
update_person_metadata- Add/update notes, occupation, birth/death places, custom factsundo_last_change- Revert the most recent metadata update
Create a .env file in the backend folder:
# GitHub token for MCP server authentication (required)
GITHUB_TOKEN=your_github_token_here
# Optional: Google Books API key for higher rate limits
GOOGLE_BOOKS_API_KEY=your_api_key_here- Go to GitHub Settings > Personal Access Tokens
- Click "Generate new token (classic)"
- Give it a descriptive name (e.g., "TreePilot MCP")
- Select appropriate scopes (minimal permissions needed)
- Generate and copy the token
- Add it to your
.envfile asGITHUB_TOKEN=ghp_...
MIT License - see LICENSE for details.
- GitHub Copilot SDK - Agent framework
- Chronicling America - Library of Congress newspaper archive
- Wikidata - Free knowledge base
- python-gedcom - GEDCOM parsing library
Built with ❤️ for the Copilot SDK Weekend Contest