vowser-agent-server by Vovvser - MCP Server

Vowser Agent Server

LangGraph-based Agent Server for Web Navigation Path Recommendation

Overview

Vowser Agent Server is an intelligent server that recommends optimal web navigation paths using natural language queries. It leverages Neo4j graph database and LangGraph workflows to provide path analysis and search functionality for web automation.

Key Features

Natural Language Search: Search web paths using natural language like "Check weather on Naver"
Intelligent Recommendations: LangGraph-based parallel analysis for optimal path suggestions
Real-time Communication: Bi-directional real-time data exchange via WebSocket

System Architecture

LangGraph Workflow Structure

graph TB
    Start([User Query]) --> Similarity[Neo4j Embedding Vector<br/>Cosine Similarity Analysis<br/>text-embedding-3-small]
    
    Similarity --> Decision{Similarity >= 0.43?}
    
    Decision -->|True| RankPaths[Top K Path Ranking or<br/>Use Cached Results]
    Decision -->|False| Intent[Intent Analysis & Keyword Extraction<br/>GPT-4o-mini]
    
    Intent --> Rediscover[Keyword-based Rediscovery<br/>Parallel Search]
    
    RankPaths --> End([Return Results])
    Rediscover --> End
    
    classDef orange fill:#F5A623,stroke:#C17D11,stroke-width:2px,color:#000,font-weight:bold
    classDef green fill:#6CB51C,stroke:#5FA319,stroke-width:2px,color:#000,font-weight:bold
    classDef skyblue fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff,font-weight:bold
    class Start,End skyblue
    class Decision orange
    class Similarity,RankPaths,RankPaths,Intent,Rediscover green

Key Optimizations

Conditional Branching: Skip unnecessary LLM calls based on similarity (intent analysis skipped for high similarity)
Result Caching: Prevent duplicate Neo4j queries for performance improvement
Embedding Caching: Skip OpenAI API calls for repeated queries
Keyword Parallel Search: Parallel keyword-based search after intent analysis for low similarity

Performance Improvement: High similarity paths return immediately without LLM calls, low similarity paths reduce processing time with parallel keyword search

Quick Start

1. Conda Environment Setup

# Option 1: Create Conda environment from yaml file
conda env create -f environment.yml
conda activate env

# Option 2: Create Conda environment and install pip dependencies
conda create -n env python=3.11
conda activate env
pip install -r requirements.txt

2. Environment Variables

Create a .env file and fill in the values:

# API Keys
OPENAI_API_KEY=
GOOGLE_API_KEY=

# Neo4j Configuration - AuraDB
# Wait 60 seconds before connecting using these details,
# or login to https://console.neo4j.io to validate the Aura Instance is available
NEO4J_URI=
NEO4J_USERNAME=
NEO4J_PASSWORD=

NEO4J_DATABASE=
AURA_INSTANCEID=
AURA_INSTANCENAME=

3. Run FastAPI Server

uvicorn app.main:app --port 8000 --reload

Main Message Types

1. Save Path

{
  "type": "save_new_path",
  "data": {
    "sessionId": "session-123",
    "taskIntent": "Find music on YouTube",
    "domain": "youtube.com",
    "steps": [...]
  }
}

2. Search Path (LangGraph)

{
  "type": "search_new_path",
  "data": {
    "query": "Like videos on YouTube",
    "limit": 3,
    "domain_hint": null
  }
}

3. Find Popular Paths

{
  "type": "find_popular_paths",
  "data": {
    "domain": "naver.com",
    "limit": 10
  }
}

Project Structure

vowser-mcp-server/
├── app/
│   ├── main.py                      # FastAPI WebSocket Server
│   ├── models/                      # Pydantic Data Models
│   │   ├── step.py                  # STEP Node Model
│   │   └── root.py                  # ROOT Node Model
│   └── services/
│       ├── langgraph_service.py     # LangGraph Workflow (Parallel Execution)
│       ├── neo4j_service.py         # Neo4j Graph DB Service
│       ├── embedding_service.py     # OpenAI Embeddings (with Caching)
│       └── db_setup.py              # Vector Index Setup
├── test/
│   └── test_single.py               # WebSocket Integration Tests
├── docs/                            # Technical Documentation
└── requirements.txt                 # Python Dependencies

Neo4j Graph Structure

graph LR
    ROOT["ROOT: Domain<br/>naver.com"]
    STEP1["STEP: First Step<br/>Click/Input"]
    STEP2["STEP: Second Step<br/>Click/Input"]
    STEP3["STEP: Last Step<br/>Click/Input"]
    
    ROOT -->|HAS_STEP<br/>Naver Today Weather| STEP1
    STEP1 -->|NEXT_STEP<br/>1| STEP2
    STEP2 -->|NEXT_STEP<br/>2| STEP3
    
    classDef orange fill:#F5A623,stroke:#C17D11,stroke-width:2px,color:#000,font-weight:bold
    classDef green fill:#6CB51C,stroke:#5FA319,stroke-width:2px,color:#000,font-weight:bold
    classDef skyblue fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff,font-weight:bold
    
    class ROOT skyblue
    class STEP1,STEP2,STEP3 green

Node Types

ROOT: Domain information (naver.com, google.com, etc.)
STEP: Web page interaction steps (click, input, etc.)

Relationship Types

HAS_STEP: ROOT → First STEP (includes taskIntent, intentEmbedding)
NEXT_STEP: STEP → STEP (sequential connection, tracks sequenceOrder)

Tech Stack

FastAPI: Asynchronous web framework
LangGraph: AI workflow orchestration
Neo4j: Graph database (with vector index)
OpenAI API: GPT-4o-mini (Intent Analysis Agent), text-embedding-3-small (Embeddings)
LangChain: AI integration framework

LangGraph Performance Improvements

Performance improvements through workflow restructuring and caching after LangGraph implementation

Path Type	Before	Optimized	Improvement
High Similarity (>=0.43)	7,000ms	4,000ms	~43%
Low Similarity (<0.43)	19,000ms	6,000ms	~68%
Repeated Queries (Embedding Cache)	4,000ms	2,500ms	~37.5%

License

Apache License 2.0 - See file for details

Related Projects

vowser-backend: Kotlin/Spring Boot API Gateway
vowser-client: Kotlin Multiplatform Client Application