ParcelPilot Server

Intelligent customer-support operations agent built with LangGraph, MCP, Agentic RAG, and Streamlit.

ParcelPilot AI can retrieve customer/account/order/ticket information, answer policy questions using hybrid retrieval, apply customer-specific agreements, and enforce confirmation before state-changing operations.

✨ Features

• LangGraph-based agent orchestration
• Remote FastMCP server over Streamable HTTP
• 9 MCP tools for customer-support operations
• Hybrid Agentic RAG using Chroma + BM25
• Customer-specific agreement retrieval
• Source authority and document precedence handling
• Structured Excel data for accounts, orders, and tickets
• Mock role-based access control
• Human-in-the-loop confirmation for escalations and follow-ups
• Streamlit interface for interacting with the agent

🏗️ Architecture

                    ┌─────────────────────┐
                    │   Streamlit App     │
                    │      app.py         │
                    └──────────┬──────────┘
                               │
                               │ MCP / HTTP
                               ▼
                    ┌─────────────────────┐
                    │   FastMCP Server     │
                    │   mcp_server.py      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       Structured Data    Agentic RAG       Security
       Excel workbook    Chroma + BM25     Access checks
              │                │
              └────────────────┼────────────────┘
                               ▼
                    Grounded Tool Results
                               │
                               ▼
                         LangGraph Agent
                               │
                               ▼
                         Final Response

🔧 MCP Tools

The MCP server exposes:

1. get_account
2. get_order
3. get_ticket
4. search_knowledge
5. search_customer_agreement
6. calculate_service_credit
7. prepare_escalation
8. execute_escalation
9. create_followup

State-changing operations use a confirmation step before execution.

📚 Agentic RAG

The retrieval pipeline combines:

User Query
    ↓
Chroma Semantic Retrieval
    +
BM25 Keyword Retrieval
    ↓
Source Authority
    ↓
Customer-Aware Ranking
    ↓
Conflict / Precedence Handling
    ↓
Grounded Evidence
    ↓
LLM Answer

Document precedence:

1. Current signed customer agreement
2. Current ParcelPilot policy/SOP
3. Other valid documentation

Deprecated documents are given lower authority and should not override current sources.

📁 Project Structure

ParcelPilot/
│
├── app.py
├── mcp_server.py
├── PARCELPILOT.ipynb
├── ParcelPilot_Assessment_Data.xlsx
│
├── 01_Support_Policy_v3_CURRENT.pdf
├── 02_Support_Policy_v2_DEPRECATED.pdf
├── 03_Cancellation_and_Service_Credit_SOP_v4.pdf
├── 04_Product_Operations_Guide_and_Known_Issues.pdf
├── 05_Northstar_Logistics_Enterprise_Agreement.pdf
├── 06_LumenWorks_Service_Agreement.pdf
│
├── pyproject.toml
└── README.md

⚙️ Setup

1. Clone the repository

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd ParcelPilot

2. Install dependencies

This project uses pyproject.toml.

With uv:

uv sync

Or install the required packages using your preferred Python environment.

3. Create .env

Create a .env file in the project root:

OPENAI_API_KEY=your_openai_api_key
PARCELPILOT_USER=support_agent
MCP_HOST=0.0.0.0
MCP_PORT=8000

For the Streamlit client, set the MCP URL:

PARCELPILOT_MCP_URL=http://127.0.0.1:8000/mcp

Do not commit .env or API keys to GitHub.

▶️ Run the MCP Server

Start the MCP server first:

uv run python mcp_server.py

The server runs at:

http://127.0.0.1:8000/mcp

You should see the ParcelPilot MCP server startup information in the terminal.

▶️ Run Streamlit

In a second terminal:

uv run streamlit run app.py

Open the Streamlit URL shown in the terminal, normally:

http://localhost:8501

🔐 Prototype Access Control

This submission includes mock authenticated-user context for demonstrating authorization behavior.

Supported prototype users include:

support_agent
customer_acct_002
customer_acct_003
admin

The server uses PARCELPILOT_USER to select the current prototype user.

In a production system, this would be replaced with real authentication and authorization, such as identity-provider-issued tokens, tenant/account claims, and server-side permission checks.

🧑‍💼 Human-in-the-Loop

For state-changing actions, the agent first prepares the operation.

Example:

User
  ↓
prepare_escalation
  ↓
Preview
  ↓
Explicit confirmation
  ↓
execute_escalation

The prototype does not modify persistent operational data during execution.

🧪 Example Queries

Try these in the Streamlit application:

What is the current status of ORD-1001?

Show me the account details for ACCT-001.

What is the cancellation fee for a BOOKED shipment?

Can Northstar Logistics cancel a BOOKED shipment without a fee?

What is Northstar Logistics' P1 response target?

What are the failed-pickup service-credit rules for LumenWorks?

What is the current Enterprise P1 response target?

Escalate ticket TKT-501 because the customer needs urgent assistance.

For the escalation example, the agent should prepare the escalation and request confirmation before execution.

🎯 Product Decisions

The solution focuses on reducing support-agent effort while keeping operational actions controlled.

Key decisions:

• Use MCP to separate the agent from operational tools.
• Keep retrieval inside the MCP server rather than duplicating it in the UI.
• Combine structured data and document retrieval.
• Give customer agreements higher authority than general policies.
• Require explicit confirmation for state-changing actions.
• Include authorization checks at the tool layer rather than relying only on the UI.

🚀 Future Improvements

If continuing development, I would prioritize:

1. Production authentication and tenant isolation
2. Persistent audit logs for every tool call and action
3. Real ticket/order updates through production APIs
4. Better retrieval evaluation and automated RAG testing
5. Observability for latency, tool failures, and answer quality
6. Approval workflows for high-impact actions
7. Support analytics and customer-risk detection

📊 Success Metric

A primary product metric would be:

Support resolution time per ticket

The goal would be to reduce average resolution time while maintaining high accuracy and preventing unauthorized or incorrect operational actions.

📌 Submission

Demo Video

https://drive.google.com/file/d/1gTZlT4bx4oSflD68SWqcN6-uHPtcaT8l/view?usp=sharing

---

Built as a ParcelPilot assessment prototype.