# PetPulse MCP

> "Did anyone feed the dog?" — answered, attributed, and evidence-grounded.

PetPulse is an evidence-grounded household pet-care companion for Alexa+: an MCP
server (Streamable HTTP, spec 2025-11-25+) that maintains a shared, voice-attributed
memory of feeding, medication, activity, care, and health observations for dogs and
cats. Every analysis, forecast, and recommendation is grounded in verified veterinary
research and official guidelines, with citations in the output.

## Quick start

```bash
npm install
npm test            # 56 unit tests
npm run scenarios   # 12 household scenarios, citation gate enforced
npm run dev         # Streamable HTTP MCP server at http://localhost:3000/mcp
```

No environment variables required for local use (in-memory store, structured
fallbacks when Bedrock is absent). Set `PETPULSE_TABLE` for DynamoDB and
`BEDROCK_MODEL_ID` for narrative synthesis — see docs/DEPLOYMENT.md.

## For judges — 60-second tour

1. `npm run dev`, then `npx @modelcontextprotocol/inspector` → connect
   Streamable HTTP to `http://localhost:3000/mcp` → 17 tools appear.
2. Try the story: `add_pet` (Luna, cat) → `tell` ("Luna is straining in the
   litter box and no urine is coming out") → `triage` → **EMERGENCY** with the
   Cornell Feline Health Center citation attached.
3. `ask` "how fast can my cat safely lose weight" → answered from verified
   sources with citations; ask it something unrelated → it admits "I can only
   answer from my verified library."
4. `npm run scenarios` → 12/12 pass with the citation gate enforced on every
   output ([docs/EVALUATION.md](docs/EVALUATION.md)).
5. The science: [research/RESEARCH_LIBRARY.md](research/RESEARCH_LIBRARY.md)
   — 28 verified sources, each link opened and logged in
   [research/verification-log.md](research/verification-log.md), including
   honest exclusions of what we could not verify.

## Why

- Most US dogs and cats are overweight (a ~4.9M-dog study puts overweight/obese
  body condition at 26%/40%+ depending on life stage); double-feeding is a daily,
  silent failure of household coordination.
- Chronic and preventive care (meds, dental, vaccines) fails quietly at home.
- Cats hide illness; changes in litter-box and activity patterns are the earliest
  signals owners can actually catch.
- Generic AI advice is ungrounded. PetPulse's LLM layer only synthesizes from real
  household state plus a verified research library — never invents facts.

## Tools (17)

| Tool | What it does | Grounded in |
|---|---|---|
| add_pet | Register a pet (species, breed, age, weight baseline) | baselines |
| feed_pet | Log a feeding event with portion and household member | montoya2025 |
| query_pet_state | Query current state: last fed, meds due, schedules | baselines |
| log_activity | Log play/exercise session | chambers2021, henning2023 |
| log_litter | Log litter-box observation (cats) | cornell_flutd, cornell_ckd |
| log_weight | Record weight / body condition trend | hoelmkjaer2014, bjornvad2011, teixeira2020 |
| add_observation | Log a free-form health observation | baselines |
| log_care | Log dental/home-care events | avdc_periodontal, vohc_registry |
| add_vaccination | Record vaccination and next-due schedule | wsava2024 |
| add_medication | Start a medication course with schedule | baselines |
| log_medication | Record a medication dose given (or missed) | booth2021 |
| check_food_safety | Check whether a food is safe for the species | aspca_foods, lovell2025 |
| get_daily_briefing | Household briefing: feeds, meds due, health flags | booth2021 + baselines |
| vet_visit_summary | Structured summary for veterinary visits | hoelmkjaer2014, cornell_flutd, booth2021 |
| tell | Split a natural-language update into structured observations | fallback + Bedrock |
| triage | Red-flag classification of recent observations | cornell_flutd, cornell_ckd |
| ask | Q&A answered only from the verified library | retrieval + any |

## Evidence grounding

PetPulse is grounded in a 28-source verified library
([research/RESEARCH_LIBRARY.md](research/RESEARCH_LIBRARY.md)) with a citation
gate: every citation in every output must exist in the library. The LLM (Bedrock)
only narrates deterministic facts; ungrounded narration is discarded in favor of
the structured fallback. This matters because reference hallucination in LLM
outputs has been measured at up to 91% (Chelli 2024).

## Architecture

```
Alexa+ (voice, household, speaker attribution *)
        |  MCP — Streamable HTTP (spec 2025-11-25+), JSON-RPC
        v
PetPulse MCP Server (TypeScript, @modelcontextprotocol/sdk)
        |            hosted on AWS Lambda + Function URL
   ----+----+------------------+
   |        |                  |
Tools    Grounding         Bedrock (Nova / Claude)
(17)     Engine            synthesis only: briefing,
         |                 vet summary, trend flags
         v
   research/ library        DynamoDB single-table
   (papers + guidelines,    (pets, events, schedules,
    verified links only)     weights, observations)
* Speaker-identity passthrough to MCP: confirm at hackathon office hours;
  fallback = conversational attribution. Uncertainty itself is friction-log material.
```

## Stack

TypeScript · `@modelcontextprotocol/sdk` (protocol 2025-11-25) · zod · express ·
AWS Lambda + Function URL · DynamoDB single-table · Amazon Bedrock (Nova Lite
default, synthesis only) · vitest.

Built for the Amazon Developer Hackathon "Build, Ship, Shape" (Alexa+ track,
AWS Builder + Open Source mini challenges).

See [docs/EVALUATION.md](docs/EVALUATION.md) (12/12 scenarios passed) and
[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for deployment.

## License

MIT — see [LICENSE](LICENSE).