# Doggo Pokko HTTP/MCP API v1

2026-10-06. Backend default `http://127.0.0.1:18183`, production `https://doggopokko.sandboxmcp.app`. HTTP API responses are JSON; static assets/documents retain their own MIME types. Same-origin requests; JSON bodies≤32KiB. Error shape `{error:{code,message}}` with400invalid input,403host/origin,413too large,415unsupported MIME,429rate limit. Unknown keys, raw files/URLs/base64 rejected; no image bytes accepted. Optional image is local frontend preview only.

`GET /api/use-cases` → `{version:"1.0",use_cases:[{id,title,summary,photo_role,required_context,source_ids,example_context}]}`. IDs:grooming/local_services/training/vet/boarding/costs/travel.

`POST /api/prepare` body:
```json
{"use_case":"grooming","consent":true,"context":{"city":"Bengaluru","locality":"Koramangala","goal":"Prepare a grooming enquiry","handling_concern":"unknown","budget_inr":1200,"budget_unit":"per_visit"},"photo_context":{"description":"Owner says the coat looks tangled","owner_confirmed":true,"source":"owner_report"}}
```

The top-level use_case, consent:true and context object are required. context:{} is valid; each individual context field is optional/null. missing meaningful fields produce questions, not fabricated answers. Strings≤500characters (`goal`/medical_needs≤1000); numeric fields finite/nonnegative:dog_age_months≤360,weight_kg≤200,budget_inr≤1000000,carrier dimensions≤500cm. budget_unit:per_visit/per_session/per_night/per_month/whole_trip/unknown. handling_concern:yes/no/unknown. emergency_signs,pain_or_skin_change:boolean|null (owner reports; omitted unknown). travel_mode:air/rail/road/unknown. Other optional text:city,locality,goal,duration,last_grooming,medical_needs,vaccination_status,dates,travel_origin,travel_destination. No date/timetable verification implied.

`care_costs` strict optional object: food_monthly,grooming_per_visit,grooming_visits_per_year,consult_per_visit,consult_visits_per_year,boarding_per_day,boarding_days_per_year,supplies_monthly,emergency_reserve_monthly. Amount≤1000000; count≤3660 (days≤366); null/omitted unknown, explicit0valid. Spending excludes emergency reserve. Partial subtotal labelled incomplete; annual total null until all consumed fields known. No financial advice or nutrition recommendations.

photo_context optional/null. source:none/owner_report/chatgpt_observation. Description≤1000characters; nonempty description requires owner_confirmed:true and source other than none. ChatGPT text is not server pixel analysis. The response photo-context card preserves the owner-confirmed source basis; the handoff does not currently include the photo description. No owner data is saved.

Common response shape example (illustrative card values; actual cards/questions depend on input):
```json
{"version":"1.0","mode":"stateless_preparation","use_case":"grooming","status":"questions_needed","questions":[{"field":"city","prompt":"Which city are you in?"}],"cards":[{"id":"context","title":"Prepare your context","text":"Answer the questions to complete a draft.","source_ids":[],"evidence_type":"product_design_inference","confidence":"preparation_only","professional_review":"pending"}],"providers":[],"handoff":null,"calculation":null,"sources":[],"limitations":{"server_analyzed_image":false,"raw_images_accepted":false,"external_actions":false,"provider_live_lookup":false,"owner_data_saved":false,"clinical_validation":false},"generated_at":"2026-10-06T09:35:00Z"}
```
status:questions_needed/prepared/vet_handoff/urgent_handoff. Strict card evidence_type enum:product_design_inference/professional_guidance/provider_published/owner_anecdote_informs_design. Strict confidence enum:preparation_only/guidance_not_individual_assessment/dated_provider_claim. Design-inference cards may have no source IDs; sourced guidance/provider/anecdote cards retain their evidence IDs. Handoff `{text,sent:false}`. Sources array contains `{id,title,url,access,retrieved_at}`; only HTTP(S) source links, selected research evidence. Provider shape:name,url,city,service,published_price_inr:number|null,price_unit,verified_at,price_freshness,availability:null,credentials_verified:false,limitations:string[],source_ids:string[]. Published baseline is not total quote/budget fit; stale/future date (>7days old or date after now)price becomes null. Other cities get no Bengaluru pointers.

`GET /api/evidence?ids=OWN-048,LEAD-009` → `{version:"1.0",sources:[source...]}`.1–20known IDs; optional omitted returns11selected guidance/data sources; unknown/malformed IDs400. No URL fetch.

Additional read-only endpoints:
- `POST /api/compare` → common local_services response; body `{city,service:"grooming"|"training"|"vet"|"boarding",budget_inr?,budget_unit?}`.
- `POST /api/calculate` → common costs response; body `{care_costs:{...}}`.

MCP tool names/arguments (all readOnlyHint:true,destructiveHint:false,openWorldHint:false):
- `list_use_cases` `{}` → case listing.
- `prepare_owner_enquiry` same `/api/prepare` body → common response.
- `compare_published_prices` same `/api/compare` body → common response. No live quote.
- `calculate_care_costs` same `/api/calculate` body → common response.
- `inspect_research_evidence` `{ids?:string[]}`max20 → evidence listing.

Stateless Streamable HTTP `/mcp`:POST initialize/list/call using official client. GET/DELETE405. JSON responses; no persistent sessions. Validation failures are MCP protocol/tool errors without raw argument echo. Health `/health` returns status,app,version,revision,mode,mcp,image_inference:false. Research wrapper/static routes and plugin archive documented in backend README after build. Presentation files are served verbatim, no SPA rewrite.

Implementation metadata: all five MCP tools now publish strict outputSchema as well as strict inputSchema. Output keys and values remain as frozen above; catalogue/evidence/common preparation schemas are in server/schemas.mjs. SDK validates structured output; no frontend shape change. Rate counters are operational IP/count/expiry in bounded process memory only, pruned within90s; owner context/responses are never persisted or logged. Actual compatibility: official-client legacy initialize2025-11-25 and current modern discovery2026-07-28, both local verified.

Public sanitized delivery-doc routes are exact: /docs and /docs/ serve docs/public/index.html; /docs/api.md serves docs/public/api.md; /docs/tool-schemas.json serves docs/public/tool-schemas.json. No other docs paths are public; docs/work remains denied. Content owned by lead, passed through without arbitrary path access.

## Native UI candidate extension

The candidate adds exactly one MCP tool: `open_owner_workspace` with strict empty arguments `{}` and catalogue structured output. The five data tool contracts above remain usable independently. Opener `_meta.ui.resourceUri` points to `ui://doggopokko/owner-workspace-v1.html` (with optional OpenAI compatibility alias). `resources/list` and `resources/read` expose this resource as `text/html;profile=mcp-app`; resource bytes match `/chat-ui/widget.html`. Unknown resource URIs fail.

`/chat-ui/` is a labelled same-origin browser preview embedding the same widget; it is not a ChatGPT-hosted conversation. Widget HTTP framing is scoped to same-origin. The bundled widget uses MCP Apps JSON-RPC initialization and tool calls over parent `postMessage`, validating parent source and request IDs, bounding timeouts and invalidating stale responses after edits/reset. Native resources need no external executable/CDN assets. Photo preview needs local blob support only; server accepts no image transfer. Resource metadata declares narrowly needed CSP domains. See [OpenAI UI documentation](https://developers.openai.com/plugins/build/chatgpt-ui) and [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps).

Native UI availability requires activation of a revision exposing six tools and the resource; the earlier five-tool deployed revision has no native UI. Check `/health` and actual discovery. Public endpoint/resource verification and the browser harness do not prove account registration or actual ChatGPT rendering. Registration/binding remain host-side steps documented in the owner manual.