Sub-Agents — MangaAssist MCP Server Reference

MangaAssist exposes seven MCP (Model Context Protocol) servers as sub-agents. Each server owns a specific data domain, implements RAG-backed retrieval, and exposes a typed tool interface to the orchestrator. This document covers each server's purpose, data sources, tool contracts, and failure modes.

Overview

Orchestrator Agent (Claude 3.5 Sonnet)
│
├── catalog-search-mcp          → Product discovery
├── user-preferences-mcp        → Personalisation
├── order-inventory-mcp         → Transactions & stock
├── review-sentiment-mcp        → Community signals
├── support-policy-mcp          → FAQ & governance
├── trending-discovery-mcp      → Real-time trends
└── cross-title-link-mcp        → Graph recommendations

Each MCP server runs as an independent ECS Fargate task. The orchestrator invokes them over an internal VPC endpoint; no server is publicly addressable.

1. Catalog Search MCP

File: RAG-MCP-Integration/01-catalog-search-mcp.md

Purpose: Manga title discovery — search, filter, and retrieve product metadata.

Data Sources - OpenSearch Serverless (5 M+ titles, hybrid BM25 + dense index) - Amazon Titan Embeddings V2 (1024-dim) for dense vectors - S3 for editorial content chunks

Tool Interface | Tool | Inputs | Returns | |---|---|---| | search_catalog | query, genre, language, volume | ranked product list with ASINs | | get_product_detail | asin | full metadata (price, availability, description) | | search_by_author | author_name | titles with scores |

RAG Pipeline 1. Embed query → Titan V2 2. Hybrid retrieve → OpenSearch (BM25 weight 0.3, dense 0.7) 3. Metadata filter by intent (genre, language, age-rating) 4. Rerank top-20 with cross-encoder (BGE-reranker-v2-m3 on SageMaker) 5. Return top-5 with provenance metadata

Chunk Strategy: 256–512 tokens, 25–50 token overlap, per-product document boundaries

2. User Preferences & Recommendation MCP

File: RAG-MCP-Integration/02-user-preferences-recommendation-mcp.md

Purpose: Personalised recommendations based on purchase history, reading behaviour, and explicit preferences.

Data Sources - DynamoDB user profile table (genre affinities, read history, language preference) - Amazon Personalize (collaborative filtering model) - ElastiCache Redis (preference vector cache, TTL 1 hour)

Tool Interface | Tool | Inputs | Returns | |---|---|---| | get_recommendations | user_id, context, limit | ranked list of ASINs with explanation signals | | update_preference | user_id, signal_type, value | acknowledgement | | get_user_profile | user_id | genre weights, history summary |

Personalisation Logic - Preference vector is a weighted blend: 60 % purchase signals, 30 % browse signals, 10 % explicit ratings - Cold-start fallback: trending titles filtered by onboarding genre selection - Explanation generation: orchestrator uses explanation_signals field to ground the LLM's recommendation narrative

3. Order & Inventory MCP

File: RAG-MCP-Integration/03-order-inventory-mcp.md

Purpose: Real-time order status, inventory checks, return and refund initiation.

Data Sources - Amazon RDS (PostgreSQL) — order records, return cases - ElastiCache Redis — stock level cache (TTL 30 seconds for high-velocity SKUs) - DynamoDB — inventory delta stream (Kinesis → Lambda → DynamoDB)

Tool Interface | Tool | Inputs | Returns | |---|---|---| | get_order_status | order_id, user_id | order state, estimated delivery | | check_inventory | asin | stock level, fulfilment centre | | initiate_return | order_id, reason_code | return case ID, instructions | | get_return_status | return_case_id | current state, refund ETA |

Consistency Model - Stock levels served from Redis cache for speed; RDS is source of truth - Cache invalidation on inventory delta events (sub-30-second lag) - Return initiation is not idempotent — the orchestrator checks for an existing open return case before calling initiate_return

4. Review & Sentiment MCP

File: RAG-MCP-Integration/04-review-sentiment-mcp.md

Purpose: Surface community reviews, aggregate ratings, and sentiment signals.

Data Sources - OpenSearch (50 M+ reviews, BM25 + dense index) - Pre-computed sentiment scores stored alongside each review document - S3 for bulk review archives (cold retrieval)

Tool Interface | Tool | Inputs | Returns | |---|---|---| | search_reviews | asin, query, min_rating | top review excerpts with sentiment | | get_aggregate_rating | asin | star distribution, review count, sentiment summary | | get_top_pros_cons | asin | structured pros/cons extracted from reviews |

Review RAG - Query is semantically matched against review bodies - Sentiment score acts as a metadata filter (e.g., only surface positive reviews for a recommendation context) - Results are deduplicated by reviewer to avoid sock-puppet amplification

5. Support & Policy MCP

File: RAG-MCP-Integration/05-support-policy-mcp.md

Purpose: Answer FAQ and policy questions (returns, subscriptions, regional availability, content ratings).

Data Sources - S3 — policy documents (Markdown/PDF, versioned) - OpenSearch — chunked policy document index - Knowledge base updated via CI/CD pipeline on policy doc change

Tool Interface | Tool | Inputs | Returns | |---|---|---| | search_policy | query, policy_category | relevant policy excerpts with source reference | | get_faq_answer | question | grounded answer + source document | | list_policy_categories | — | available policy domains |

Grounding Constraint The orchestrator is instructed to cite the source_document field from every policy result. Hallucinated policy answers are the highest-risk failure mode in this domain; citation enforces accountability.

6. Trending & Discovery MCP

File: RAG-MCP-Integration/06-trending-discovery-mcp.md

Purpose: Real-time trending titles, new releases, and promotional discovery.

Data Sources - Amazon Kinesis Data Streams — click, purchase, and add-to-cart events - DynamoDB Streams — inventory and pricing change events - DynamoDB trending table — pre-aggregated top-N lists (TTL 5 seconds for hot slots)

Tool Interface | Tool | Inputs | Returns | |---|---|---| | get_trending | genre, time_window, limit | ranked trending titles | | get_new_releases | genre, days_ago | recent releases | | get_promotions | user_id, limit | personalised promotional offers |

Freshness - Trending aggregation runs every 5 seconds via a Lambda consumer on the Kinesis stream - Stale trending data is surfaced with a data_age_seconds field — the orchestrator can decide to caveat the response if age > 60 seconds

7. Cross-Title Link MCP

File: RAG-MCP-Integration/07-cross-title-link-mcp.md

Purpose: Graph-based "if you liked X, try Y" recommendations using semantic and co-purchase relationships.

Data Sources - Amazon Neptune — title relationship graph (co-purchase edges, same-author edges, genre-similarity edges) - OpenSearch — semantic similarity index for fallback when graph traversal yields sparse results

Tool Interface | Tool | Inputs | Returns | |---|---|---| | get_similar_titles | asin, limit | similar titles with relationship type and score | | get_series_context | asin | series graph (volumes, spin-offs, related series) | | get_co_purchased | asin, limit | frequently co-purchased titles |

Graph Traversal - Default: 2-hop traversal from source ASIN weighted by edge strength - Fallback to OpenSearch semantic similarity when graph result count < 3 - Edge weights decay daily; purchase events within 30 days carry 3× weight

Orchestration Patterns

Parallel Invocation

Independent sub-agents are always called in parallel. The orchestrator uses asyncio.gather to fan out calls and merges results before generation.

Example: "Is Demon Slayer vol 5 in stock and well reviewed?"
  Parallel:
    catalog_search_mcp.search_catalog(...)   → ASIN
    review_sentiment_mcp.get_aggregate_rating(asin)
    order_inventory_mcp.check_inventory(asin)

Sequential Chaining

When one result is required as input to the next call:

1. catalog_search_mcp.search_catalog → asin
2. cross_title_link_mcp.get_similar_titles(asin=<step 1 result>)

The model produces this chain emergently from its reasoning; no code specifies the sequence.

Conditional Invocation

Some sub-agents are only called when the intent warrants them:

• support_policy_mcp is only invoked for faq, return, policy intents
• order_inventory_mcp requires an authenticated session (JWT validated before dispatch)
• user_preferences_mcp.update_preference is only called at session close, never mid-turn

Degraded-Mode Behaviour

Each sub-agent is independently observable. The orchestrator degrades gracefully when a server is unavailable:

Deployment

Each sub-agent runs as a containerised ECS Fargate service:

• Scaling: ECS auto-scaling on CPU and custom CloudWatch metrics (tool call queue depth)
• Discovery: AWS Cloud Map for internal DNS; orchestrator resolves sub-agent endpoints at startup
• IAM: Each MCP server has its own execution role scoped to its specific data sources only
• Observability: X-Ray traces link every orchestrator tool call to its sub-agent invocation

Detailed deployment patterns: ECS-Fargate-Lambda/

Related Documents

• RAG-MCP-Integration/00-overview-rag-mcp-architecture.md — Architecture overview
• RAG-MCP-Integration/08-mcp-orchestration-router.md — How the orchestrator selects and sequences tools
• RAG-MCP-Integration/09-rag-retrieval-pipeline-deep-dive.md — RAG pipeline internals
• agents.md — Orchestrator agent and lifecycle
• skills.md — AWS AIP-C01 Domain 2 skills inventory