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

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.

Related MCP server: KinKeep

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).

5. The science: research/RESEARCH_LIBRARY.md — 28 verified sources, each link opened and logged in 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)

Evidence grounding

PetPulse is grounded in a 28-source verified library (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 (12/12 scenarios passed) and docs/DEPLOYMENT.md for deployment.

License

MIT — see LICENSE.