Skip to content

Add Poppy discovery and read-only MCP tools using SDKs - #44

Open
shrey150 wants to merge 8 commits into
mainfrom
codex/bell-poppy-config-20261112
Open

shrey150 wants to merge 8 commits into
mainfrom
codex/bell-poppy-config-20261112

Conversation

@shrey150

@shrey150 shrey150 commented Nov 13, 2026 •

Copy link
Copy Markdown

Bell can discover a company's /.well-known/poppy.json, inspect its MCP tools, and perform explicitly read-only operations using published clients.

  • @datalayer/personal-agent-protocol owns discovery, protocol versions, Session signing, device authorization, resource-bound tokens, refresh, and revocation.
  • The official MCP client owns transport, negotiation, pagination, and schema validation.
  • Bell supplies agent tools, public client metadata/JWKS, authenticated owner isolation, approval requirements, encrypted SDK storage, and output limits. Authentication is handled server-side; users complete consent on the provider's website. Bell filters literal echoes of credentials held for the current request, without guessing secrets from field names or token patterns. Unknown or transformed secrets can pass through; this is not a PII or prompt-injection detector.

Compatibility and setup

The pinned Poppy SDK uses 0.4 by default. Providers serving 0.3 are unsupported; Bell contains no protocol translation or compatibility patches. This integration exposes MCP reads only. OpenAPI execution, writes, purchases, and browser handoff are excluded. Only uniquely named tools with readOnlyHint: true and without destructiveHint: true are exposed. These annotations are provider claims, not verified behavior: use providers trusted with the requested data. Bell does not infer permissions from tool or parameter names.

The encrypted file store requires one agent process with durable storage. MCP requests use the SDK session transport: a session_ended answer starts one replacement Session, retries once, and Bell keeps the replacement for later reads. A provider 429 (or 503 with Retry-After) pauses every Bell request to that provider origin for the requested time (at most one hour, in process memory), across tool calls; reads return rate_limited with retryAfterSeconds. Resource metadata is fetched before the credential-mutation checkpoint, so a metadata outage or rate limit does not force a disconnect. SDK-provided locks serialize each owner/company independently; short file checkpoints reread, merge, and atomically save current state without holding a file-wide lock during provider requests. Setup is in docs/poppy.md; the repeatable production smoke is in docs/provider-tests.md.

E2E Test Matrix

Path Evidence Limit of this verification
Production model → Bell/Eve → public Poppy demo Rebuilt and passed again after simplifying credential filtering against the live hotel sandbox: four successful calls covered discovery, API inspection, availability, and rates. The answer matched the returned dates, room, rate, raw total/currency, and citation, and identified the data as a demo. Public identity, credential non-disclosure, and session retirement checks passed. Demonstrates the complete model/tool flow using public sandbox data. It does not verify real inventory, booking quotes, authenticated account conversations, or phone delivery.
Noninteractive conversation API A scripted three-message conversation compared four rooms, selected the cheapest room, fetched its cheapest refundable rate, then changed checkout to a three-night stay and fetched the updated rate. Assertions compared dates, room, rate, raw totals/currency, and citations against the actual provider tool payloads. All three turns passed. Verifies real model decisions, retained conversation context, corrections, and task completion against public sandbox data. No stubs or direct tool invocation.
Noninteractive terminal demo Piped stdin completed the hotel request plus a follow-up in 23.1 seconds: five successful tool calls and two answers. A separate --once flower query completed three tool calls in 12 seconds. Both exited 0 and confirmed session retirement. Confirms the runnable demo works without human input. Flower evidence checks tool success and the answer; raw-payload comparison was performed for the hotel conversation.
Scripted approval denial and access control The account request paused at explicit sites:read approval. A scripted Cancel produced a persisted denied event, no successful connection or sign-in result, and a normal agent reply. Unauthenticated session creation returned HTTP 401. Verifies denial and authenticated entry; it does not prove an approved account conversation.
Real provider account access Human-approved Stacktree sites:read passed through Bell's SDK-backed client: API inspection, two successful list_sites reads, and SDK disconnect. Both reads returned an empty list. Direct client verification; no full model conversation or retrieval of populated account data was demonstrated.
Account lifecycle Actual SDKs passed controlled HTTP provider tests for persisted device authorization, owner isolation, resource-bound refresh, token rotation/revocation, interrupted-mutation recovery, approvals, and filtering of current-request credential echoes. Regression tests verify failed refresh → explicit disconnect → fresh device sign-in, independent-account progress during a held provider request, same-account serialization, preservation of concurrent file updates, session_ended recovery persisted across two later reads, a resource-metadata 503 that leaves the account connected, and a 429 Retry-After: 60 that stops the MCP initialize fallback and later tool calls until the pause ends. Controlled fixtures establish tested behavior; they do not establish compatibility with every live provider.
Linq/iMessage Automated tests cover signed inbound HTTP requests, sender checks, dispatch, and same-chat routing with provider calls and Eve dispatch mocked. No actual phone → Linq → Bell → Poppy → phone round trip has been verified.
Dependency audit and compatibility pnpm audit --prod reports zero known vulnerabilities after a scoped override updates Reactor’s transitive TOON package to 2.3.1. Thirty-two temporary compatibility/security checks passed against TOON and the installed Reactor formatter/runner. The full audit retains one preexisting moderate minimatch advisory in development lint tooling. Audit results cover known reported advisories, not a comprehensive security assessment.
MCP output policy Focused tests verify exact credential echoes and inputs, including JSON escaping and metadata; ordinary pagination tokens and unrelated provider fields are preserved. Provider names and arbitrary secret patterns are intentionally not classified.
Repository checks After merging main: pnpm test with PostgreSQL 529 passed, 34 opt-in tests skipped; typecheck, lint, and production build passed. CI and both Socket checks passed on e2ff090. Skipped opt-in tests are not counted as completed live verification.

The repeatable production demo is documented in provider tests. Authenticated model conversations and live iMessage delivery remain separate verification steps.

Code flow

Before this PR, all channels reach the existing Eve agent and its browser/integration tools:

flowchart LR
    Message["Web/API or iMessage via Linq"] --> Eve["Eve conversation and model"]
    Eve --> Existing["Existing browser and integration tools"]
    Existing --> Results["Tool results"]
    Results --> Eve
    Eve --> Reply["Reply in the same conversation"]
Loading

The PR adds a Poppy tool path alongside those existing tools. Green nodes are new Bell code; blue nodes are published packages.

flowchart TD
    Message["Existing message entrypoints"] --> Eve["Same Eve conversation and model"]
    Eve --> Existing["Existing browser and integration tools"]
    Existing --> Eve
    Eve --> Tools["New Poppy tools: owner identity and account approvals"]
    Tools --> App["client.ts: account orchestration"]
    App <--> Store["store.ts: encrypted owner/company state"]
    App --> SDK["Poppy SDK: discovery, signing and account authorization"]
    SDK --> Catalog["Official MCP client: fetch tool catalog"]
    Catalog --> Policy["apis.ts: provider read-only hints and known-credential input check"]
    Policy --> MCP["Official MCP client: schema validation and tool call"]
    MCP --> Provider["Company API"]
    Provider --> Output["apis.ts: filter known credential echoes and limit output"]
    Output --> Eve
    Eve --> Reply["Reply in the same conversation"]
    classDef added fill:#e6f4ea,stroke:#137333,color:#123
    classDef package fill:#e8f0fe,stroke:#1967d2,color:#123
    class Tools,App,Store,Policy,Output added
    class SDK,Catalog,MCP package
Loading

Account connection additionally pauses for Bell approval and the provider’s human consent flow. Public agent metadata/JWKS routes let providers verify Bell’s signing identity. The diagram shows logical control/data flow; the SDKs own their HTTP requests and responses.

@shrey150
shrey150 requested a review from a team as a code owner November 13, 2026 18:14
Comment thread server/poppy/client.ts Resolved
Comment thread server/poppy/store.ts Resolved
@socket-security

socket-security Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Added@​datalayer/​personal-agent-protocol@​0.35.06910010097100
Added@​modelcontextprotocol/​client@​2.4.0921008295100
Added@​datalayer/​reactor@​1.3.7871009796100
Addedjose@​6.2.1710010010093100

View full report

@shrey150 shrey150 changed the title Add Poppy API discovery and authenticated reads Add Poppy discovery and read-only MCP tools using SDKs Nov 13, 2026
@shrey150
shrey150 marked this pull request as draft November 13, 2026 18:41
@shrey150
shrey150 marked this pull request as ready for review November 13, 2026 21:26

@shriyatheunicorn shriyatheunicorn left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

few comments abt failure handling, other lgtm! lmk when rereview and ill stamp

Comment thread server/poppy/client.ts Resolved
Comment thread server/poppy/client.ts Resolved
Comment thread server/poppy/sdk.ts Resolved
- Send MCP requests through the Poppy SDK SessionFetchClient so a
  session_ended answer starts one replacement Session and retries once;
  persist the replacement for later reads.
- Read the MCP resource metadata before the blocked checkpoint so a
  metadata outage no longer forces disconnect; keep the checkpoint
  around the token exchange itself.
- Record 429 (and 503 with Retry-After) per provider origin in a
  process-wide SDK SharedRateLimitBudget, refuse later requests locally
  until the pause ends (including the MCP initialize fallback and
  separate tool calls), and return rate_limited with retryAfterSeconds.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants