langchain-mcp-deepeval-trajectory-eval: Instructions file for Claude Code

CLAUDE.md

Project Overview

A LangChain + LangGraph agent that connects to multiple MCP (Model Context Protocol) servers via streamable HTTP, featuring Human-in-the-loop (HITL) confirmation for sensitive operations. The agent is named "周香" and acts as a navigation and device-control assistant.

The name includes "deepeval-trajectory-eval" — this project is designed as a test bed for evaluating agent trajectories (tool call sequences) using DeepEval.

---

CLI Commands

All commands use uv run (the project uses uv as the package manager).

Setup

uv sync                          # Install all dependencies
cp .env.example .env             # Create env file, then fill in API keys

Run Services

# Step 1: Start the custom MCP server (must be running before the agent)
uv run python -m agent_call.custom_mcp_server

# Step 2a (recommended): Start the LangGraph dev server with Studio UI
uv run langgraph dev

# Step 2b (alternative): Run the agent directly as a script (no server)
uv run python -m agent_call.agent

Run the Chat Client (against a running langgraph dev server)

uv run python -m client_apis.agent_client

On startup, choose from:

• 1 — Auto-detect: classify whether the new query is related to the last session (kimi-k2-turbo-preview), inject compressed context if yes.
• 2 — Pick a historical thread to resume.
• 3 — Force a fresh new session.

Within a session, type new to force a new session start.

Inspect MCP Tool List

uv run python -m agent_call.mcp_config    # Prints available tools from all MCP servers

Note: There is no Makefile, no test command, and no lint command defined in this project.

---

Architecture

System Overview

┌────────────────────────────────────────────────────────────────┐
│                      LangGraph Dev Server                      │
│                    (uv run langgraph dev)                       │
│                      localhost:2024                             │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │               LangGraph Agent (build_graph)              │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐ │  │
│  │  │  ChatOpenAI  │  │  MCP Tools   │  │  HITL Middle-  │ │  │
│  │  │  (Kimi K2.5) │  │  (dynamic)   │  │  ware          │ │  │
│  │  └──────────────┘  └──────────────┘  └────────────────┘ │  │
│  │              InMemorySaver (checkpointer)                  │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────┬───────────────────────────────────────┘
                         │ SSE streaming (LangGraph API)
                         ▼
              ┌──────────────────────┐
              │  AgentClient         │
              │  (client_apis/)      │
              │  CLI chat interface   │
              │                       │
              │  ┌──────────────────┐ │
              │  │  MemoryRouter   │ │  ← 跨 Session 记忆
              │  │  · /threads/    │ │
              │  │    search API   │ │
              │  │  · kimi-k2-     │ │
              │  │    turbo 二分类  │ │
              │  │  · kimi-k2-     │ │
              │  │    0905 压缩    │ │
              │  └──────────────────┘ │
              └──────────────────────┘

Agent connects to MCP servers via streamable HTTP:
  ┌──────────────────────────────────────────────────────┐
  │  MultiServerMCPClient (langchain-mcp-adapters)       │
  │                                                      │
  │  "Phone-use" → localhost:8000/mcp  (custom server)   │
  │  "Amap"      → mcp.amap.com/mcp   (Amap Maps API)   │
  └──────────────────────────────────────────────────────┘
           ↑
  ┌────────────────────────┐
  │  custom_mcp_server.py  │  (FastMCP, must be started separately)
  │  Tools:                │
  │    get_gps             │
  │    get_contact_phone   │
  │    make_call           │
  │    send_sms            │
  └────────────────────────┘