ContextBuilder (ctx)
Context-as-a-Service MCP server for Hengam's multi-agent system. Maintains app-isolated, structured, provenance-backed context for Shopify apps and delivers "just enough context" to other agents.
Features
- App-scoped context: Isolated context for 4 Shopify apps (Notify Me!, Subi, Discounty, Convi)
- Agentic Graph Memory: Graph-based retrieval with multi-hop traversal, not just vector search
- Hybrid delivery: Push starter context bundles + Pull targeted context slices
- Observation Masking: Budget-aware compression with full transparency on what was included/excluded
- Provenance tracking: Every statement traceable to source URL + snapshot timestamp + content hash
- Configurable LLM: Provider-agnostic (OpenAI, Anthropic, Gemini) with editable prompt templates
- Schema-validated: All data objects validated with Zod at boundaries
Quick Start
# Install dependencies
pnpm install
# Set up LLM API key (at least one required for refresh)
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...
# Run the MCP server
pnpm dev
# Run tests
pnpm test
MCP Tools
| Tool | Description |
|---|---|
ctx.refresh.app_sources | Refresh and rebuild context for an app |
ctx.push.starter_context | Push compact starter context bundle |
ctx.pull.context_slice | Pull targeted context slice by intent |
ctx.get.app_state_summary | Get app state summary + refresh status |
ctx.get.provenance | Get provenance for a bundle/slice |
Architecture
Ingestion → Extraction → Graph → Delivery
fetch summarize build push/pull
parse extract traverse mask
snapshot score validate provenance
Pipeline Flow
- Ingestion: Fetch public web sources (listing, website, help center), parse HTML, create snapshots with content hashes
- Extraction: LLM-powered structuring — summarize pages, extract concepts/procedures, score observations, detect conflicts
- Graph: Build context graph with nodes (features, procedures, constraints, FAQs, entities) and typed edges (explains, depends_on, resolves, etc.)
- Delivery: Serve context via push (starter bundles) or pull (targeted slices) with observation masking and provenance
Configuration
All configuration is in config/:
apps.yaml— App source URLs and crawl settingsmodel-profiles.yaml— LLM provider configs (model, temperature, rate limits)settings.yaml— Task bindings, budgets, masking thresholds, graph settingsprompt-templates/*.hbs— Handlebars templates for all 8 LLM tasks
Supported Apps (MVP)
| App | Listing | Website | Help Center |
|---|---|---|---|
| Notify Me! | apps.shopify.com | notify-me.io | help.notify-me.io |
| Subi | apps.shopify.com | subi.co | help.subi.co |
| Discounty | apps.shopify.com | discounty.ai | help.discounty.ai |
| Convi | apps.shopify.com | conviapp.com | help.conviapp.com |
Development
pnpm build # Compile TypeScript
pnpm dev # Run with tsx (dev mode)
pnpm test # Run all tests
pnpm test:unit # Run unit tests only
pnpm test:contract # Run MCP contract tests
pnpm lint # Type check
Requirements Coverage
Implements REQ-CTX-1 through REQ-CTX-38 from the ContextBuilder agent repository spec. See CLAUDE.md for architecture details.