Arda Vector Database MCP Server

Semantic Code Search MCP Server - A FastMCP server providing semantic code search capabilities through Qdrant vector database integration. Designed for Cursor IDE and other MCP-compatible AI coding assistants.

🎯 What is Arda Vector Database?

Arda Vector Database is an MCP (Model Context Protocol) server that provides read-only semantic search across the Arda Credit platform codebase (Rust backend, TypeScript frontend, and Solidity smart contracts) using natural language queries.

Key Features

• ⭐ Smart Search - NEW: Intelligent query routing to best tool
• ⭐ Specialized Tools - NEW: 5 tools for common patterns (auth, stack, services, location, dependencies)
• ⚡ Caching - NEW: 30-minute cache, < 500ms responses
• 🔍 Semantic Code Search - Natural language queries across multiple programming languages
• 🎯 Domain-Specific Prompts - Pre-built search templates for Arda Credit features
• 📚 MCP Resources - Static documentation and search best practices
• 🔄 Batch Search - Query multiple aspects efficiently (up to 100 results)
• 🌐 Cross-Collection Search - Full-stack exploration (backend, frontend, contracts)
• 🗄️ Multi-Language Support - Rust, TypeScript, Solidity, Python, YAML, Terraform
• 📊 Collection Management - Health monitoring and statistics for vector collections
• 🚀 High Performance - Embeddings via Cloudflare AI gateway (4096-dimensional vectors)
• 🔒 Read-Only Operations - Safe integration without ingestion capabilities

🚀 Quick Start

Prerequisites

• Python 3.11+
• Qdrant Cloud account or local Qdrant instance
• Embedding endpoint (Cloudflare AI gateway)
• Cursor IDE or MCP-compatible coding assistant

Installation

# Clone the repository
git clone https://github.com/ardaglobal/arda-mcp.git
cd arda-mcp

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials:
# QDRANT_URL=https://xxxxx.gcp.cloud.qdrant.io
# QDRANT_API_KEY=your_qdrant_api_key
# EMBEDDING_ENDPOINT=https://gateway.ai.cloudflare.com/v1/{account_id}/aig/compat
# CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
# DEEPINFRA_API_KEY=your_deepinfra_api_key

Running the Server

# Start the MCP server
python server.py

# Or with explicit environment
QDRANT_URL=https://your-qdrant.io QDRANT_API_KEY=your-key CLOUDFLARE_API_TOKEN=your-token python server.py

MCP Integration

Cursor IDE Configuration

Add to your MCP settings (typically ~/.cursor/mcp.json or project-specific .mcp.json):

{
  "mcpServers": {
    "arda-vector-db": {
      "command": "python",
      "args": ["/path/to/arda-mcp/server.py"],
      "env": {
        "QDRANT_URL": "https://xxxxx.gcp.cloud.qdrant.io",
        "QDRANT_API_KEY": "your_qdrant_api_key",
        "EMBEDDING_ENDPOINT": "https://gateway.ai.cloudflare.com/v1/{account_id}/aig/compat",
        "CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token",
        "DEEPINFRA_API_KEY": "your_deepinfra_api_key"
      }
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "arda-vector-db": {
      "command": "python",
      "args": ["/path/to/arda-mcp/server.py"],
      "env": {
        "QDRANT_URL": "https://xxxxx.gcp.cloud.qdrant.io",
        "QDRANT_API_KEY": "your_qdrant_api_key",
        "EMBEDDING_ENDPOINT": "https://gateway.ai.cloudflare.com/v1/{account_id}/aig/compat",
        "CLOUDFLARE_API_TOKEN": "your_cloudflare_api_token",
        "DEEPINFRA_API_KEY": "your_deepinfra_api_key"
      }
    }
  }
}

📖 Available MCP Features

MCP Tools (19 Total - Expanded in v1.2.0)

Core Search Tools

smart_search ⭐ NEW in v1.2.0

Intelligent search that automatically routes queries to the best specialized tool.

# Arguments:
# - query: str (required) - Natural language query
# - context: dict (optional) - Additional context

# Example:
# query="What are the authentication systems?"

# Returns: Routing information + formatted result
{
  "routing": {
    "tool": "get_auth_systems",
    "params": {},
    "explanation": "Query is asking about authentication systems"
  },
  "result": { /* Formatted auth systems data */ }
}

This is the recommended tool for general queries! The smart search automatically:

• Detects query intent
• Routes to the appropriate specialized tool
• Formats results for IDE consumption
• Provides quick actions and related queries

health_check

Check Qdrant connection health and return system status.

# Returns:
{
  "status": "healthy",
  "connected": True,
  "collections_count": 10,
  "collections": ["arda_code_rust", "arda_code_typescript", "arda_frontend", "arda_backend", ...],
  "server_version": "1.2.0"
}

refresh_repo_cache (New in v1.1.0)

Manually refresh GitHub repository structure cache to get latest updates immediately.

# No arguments required

# Returns:
{
  "status": "success",
  "message": "Repository cache refreshed successfully",
  "cache_ttl_seconds": 3600,
  "repositories": [
    {
      "name": "arda-credit",
      "owner": "ardaglobal",
      "updated_at": "2025-10-06T20:30:15Z",
      "file_count": 247
    },
    {
      "name": "arda-credit-app",
      "owner": "ardaglobal",
      "updated_at": "2025-10-06T19:45:22Z",
      "file_count": 183
    }
  ]
}

Use cases:

• After pushing major changes to repositories
• When you need fresh structure data immediately
• To verify GitHub API connectivity
• Cache normally refreshes automatically every hour

list_collections

List all available Qdrant collections with basic statistics.

# Returns:
{
  "collections": [
    {
      "name": "arda_code_rust",
      "points_count": 25000,
      "vectors_count": 25000,
      "status": "green"
    },
    # ... more collections
  ],
  "total_collections": 4
}

get_collection_info

Get detailed information about a specific collection.

# Arguments:
# - collection_name: str (e.g., "arda_code_rust")

# Returns:
{
  "name": "arda_code_rust",
  "status": "green",
  "points_count": 25000,
  "vectors_count": 25000,
  "indexed_vectors_count": 25000,
  "segments_count": 2,
  "vector_size": 4096,
  "distance": "cosine"
}

semantic_search (Enhanced in v1.2.0)

Perform semantic search across code embeddings using natural language queries. Now with 30-minute caching!

# Arguments:
# - query: str (required) - Natural language search query
# - collection_name: str (default: "arda_code_rust") - Target collection
# - limit: int (default: 20) - Maximum results (1-50)
# - score_threshold: float (default: 0.5) - Minimum similarity score (0.0-1.0)

# Example:
# query="authentication logic with JWT tokens"
# collection_name="arda_code_rust"
# limit=20
# score_threshold=0.5

# Returns:
{
  "query": "authentication logic with JWT tokens",
  "collection": "arda_code_rust",
  "results_count": 18,
  "results": [
    {
      "id": "rust_chunk_1234",
      "score": 0.87,
      "payload": {
        "file_path": "api/src/authentication_handlers.rs",
        "content": "pub async fn verify_jwt_token(token: &str) -> Result<Claims, AuthError> { ... }",
        "language": "rust",
        "chunk_type": "function"
      }
    },
    # ... more results
  ],
  "parameters": {
    "limit": 20,
    "score_threshold": 0.5
  },
  "from_cache": false  # True if result was cached
}

Performance: < 500ms for cached queries, < 2s for uncached queries.

batch_semantic_search

Perform multiple semantic searches efficiently to get comprehensive context.

# Arguments:
# - queries: List[str] (required) - List of search queries (max 10)
# - collection_name: str (default: "arda_code_rust") - Target collection
# - limit_per_query: int (default: 10) - Results per query (1-20)
# - score_threshold: float (default: 0.6) - Minimum similarity score

# Example:
batch_semantic_search(
    queries=[
        "deal origination API handler",
        "KYC validation for deals",
        "database schema for deals table"
    ],
    collection_name="arda_code_rust",
    limit_per_query=10
)

# Returns: Up to 100 results (10 queries × 10 results)
{
  "batch_size": 3,
  "collection": "arda_code_rust",
  "total_results": 28,
  "queries": {
    "deal origination API handler": { /* search results */ },
    "KYC validation for deals": { /* search results */ },
    "database schema for deals table": { /* search results */ }
  }
}

cross_collection_search (Enhanced in v1.2.0)

Search across multiple collections for full-stack feature exploration. Now with better error handling!

# Arguments:
# - query: str (required) - Natural language search query
# - collections: List[str] (optional) - Collections to search (default: all 3 code collections)
# - limit_per_collection: int (default: 10) - Results per collection (1-20)
# - score_threshold: float (default: 0.6) - Minimum similarity score

# Example:
cross_collection_search(
    query="USDC deposit flow from frontend to smart contract",
    collections=["arda_code_typescript", "arda_code_rust", "arda_code_solidity"],
    limit_per_collection=10
)

# Returns: Up to 30 results (3 collections × 10 results)
{
  "query": "USDC deposit flow from frontend to smart contract",
  "collections_searched": 3,
  "successful_searches": 3,
  "failed_searches": 0,
  "total_results": 27,
  "results_by_collection": {
    "arda_code_typescript": { /* frontend results */ },
    "arda_code_rust": { /* backend results */ },
    "arda_code_solidity": { /* contract results */ }
  }
}

Improvement in v1.2.0: Gracefully handles missing collections and provides detailed error information.

Specialized Query Tools ⭐ NEW in v1.2.0

These tools answer specific common questions about the Arda codebase:

get_auth_systems

Find all authentication implementations across the Arda stack.

# No arguments required

# Returns:
{
  "summary": "Authentication systems across Arda stack",
  "by_layer": {
    "frontend": [ /* auth components */ ],
    "backend": [ /* auth handlers */ ],
    "middleware": [ /* auth middleware */ ]
  },
  "key_implementations": [
    {
      "layer": "backend",
      "file": "repos/arda-credit/api/src/handlers/auth/jwt.rs",
      "type": "jwt_handler",
      "repo": "arda-credit",
      "preview": "..."
    }
  ],
  "auth_flows": ["JWT-based authentication", "OAuth 2.0 authorization"]
}

Use this to answer: "What are the authentication systems used across the ARDA stack?"

get_stack_overview

Get comprehensive overview of the entire Arda technical stack.

# No arguments required

# Returns:
{
  "summary": "Complete Arda technical stack",
  "services_by_type": {
    "frontend": ["arda-platform", "arda-homepage"],
    "backend": ["arda-credit"],
    "middleware": ["arda-chat-agent", "arda-ingest"]
  },
  "technology_stack": {
    "frontend": ["TypeScript", "React", "Next.js"],
    "backend": ["Rust", "Axum", "Tokio"],
    "infrastructure": ["Kubernetes", "Helm", "Terraform"]
  },
  "deployment_info": { /* helm charts */ }
}

Use this to answer: "Walk me through the ARDA technical stack"

get_deployed_services

List all deployed services with their configurations.

# Arguments:
# - environment: str (optional) - "production" (default), "staging", "dev"

# Returns:
{
  "environment": "production",
  "services_count": 8,
  "services": {
    "arda-credit": {
      "type": "Deployment",
      "container_images": ["arda-credit:v1.2.3"],
      "env_vars": { /* environment variables */ },
      "ports": [8080, 8443]
    }
  }
}

Use this to answer: "What services are deployed in production?"

find_service_location

Find where a service, function, or feature is implemented.

# Arguments:
# - query: str (required) - What to search for
# - search_scope: str (optional) - "all", "frontend", "backend", "middleware", "infrastructure"

# Returns:
{
  "query": "balance calculation",
  "search_scope": "backend",
  "total_results": 12,
  "locations": [
    {
      "repo": "arda-credit",
      "file": "repos/arda-credit/lib/src/balance.rs",
      "lines": "45-67",
      "item_name": "calculate_balance",
      "relevance_score": 0.89,
      "preview": "..."
    }
  ],
  "top_match": { /* best match */ }
}

Use this to answer: "Where does X occur?" or "Find the implementation of Y"

trace_service_dependencies

Show complete dependency tree for a service.

# Arguments:
# - service_name: str (required) - e.g., "arda-credit"

# Returns:
{
  "service": "arda-credit",
  "depends_on": {
    "services": [],
    "databases": ["postgresql"],
    "external_apis": ["blockchain-rpc"]
  },
  "depended_by": ["arda-platform", "arda-chat-agent"],
  "api_endpoints": [ /* API endpoints */ ],
  "deployment": { /* deployment config */ },
  "dependency_graph": {
    "nodes": [...],
    "edges": [...]
  }
}

Use this to answer: "What does X depend on?" or "What calls service Y?"

---

MCP Metadata Tools ⭐ NEW in v1.2.0

These tools provide programmatic discovery of available resources and prompts according to the MCP specification:

list_resources

List all available MCP resources exposed by the server.

# No arguments required

# Returns:
{
  "resources": [
    {
      "uri": "arda://collections",
      "name": "Collection Information",
      "description": "Live collection stats, repository structure...",
      "mime_type": "text/markdown"
    },
    # ... 9 more resources
  ],
  "count": 10,
  "server": "arda-vector-db"
}

Use this to answer: "What resources are available?"

read_resource

Read a specific MCP resource by its URI.

# Arguments:
# - uri: str (required) - Resource URI (e.g., "arda://collections")

# Example:
read_resource("arda://collections")

# Returns:
{
  "uri": "arda://collections",
  "content": "# Arda Credit Vector Collections\n\n...",
  "mime_type": "text/markdown",
  "length": 5432
}

Use this to answer: "Show me the collections resource", "What's in arda://dashboard?"

list_prompts

List all available pre-configured prompts (search templates).

# No arguments required

# Returns:
{
  "prompts": [
    {
      "name": "search_deal_operations",
      "description": "Search for deal management operations...",
      "parameters": [
        {
          "name": "operation_type",
          "type": "string",
          "default": "all",
          "options": ["origination", "payment", "transfer", "marketplace", "all"]
        }
      ],
      "example_use": "Find deal payment processing logic in the backend"
    },
    # ... 11 more prompts
  ],
  "count": 12
}

Use this to answer: "What prompts are available?", "Show me search templates"

get_prompt (Enhanced in v1.2.1)

Get details about a specific prompt and generate its search instructions. Now handles required parameters gracefully with placeholders!

# Arguments:
# - name: str (required) - Prompt name (e.g., "search_deal_operations")

# Example:
get_prompt("search_deal_operations")

# Returns:
{
  "name": "search_deal_operations",
  "description": "Search for deal management operations...",
  "parameters": [
    {
      "name": "operation_type",
      "type": "string",
      "default": "all",
      "required": false
    }
  ],
  "instructions": "Find deal management code in Arda Credit platform...",
  "has_required_params": false
}

# For prompts with required params (e.g., search_frontend_feature):
get_prompt("search_frontend_feature")
# Returns instructions with placeholder: "Search for <feature_name> in frontend..."

Use this to answer: "Show me the deal operations prompt", "What does debug_arda_issue do?"

execute_prompt ⭐ NEW in v1.2.1

Execute a prompt's search strategy automatically by parsing instructions and running searches.

# Arguments:
# - name: str (required) - Prompt name
# - **kwargs: Prompt-specific parameters (varies by prompt)

# Example:
execute_prompt("search_deal_operations", operation_type="payment")

# Returns:
{
  "prompt_name": "search_deal_operations",
  "parameters": {"operation_type": "payment"},
  "instructions": "Find deal payment processing...",
  "searches_executed": 3,
  "total_results": 42,
  "results": [ /* Top 50 results */ ],
  "execution_summary": "Executed 3 searches across 3 collections, found 42 total results"
}

# More examples:
execute_prompt("debug_arda_issue", issue_description="deal payment failure")
execute_prompt("search_frontend_feature", feature_name="investor portfolio")
execute_prompt("search_zkproof_implementation")  # No params required

Use this to answer: "Execute the deal operations search", "Run the zkproof prompt"

Benefits:

• Automatic parsing of search strategy from prompt instructions
• Executes multiple collection searches in parallel
• Aggregates and ranks results by score
• Returns top 50 results across all searches

---

MCP Prompts (12 Total - Expanded in v1.2.0)

Pre-built search templates that guide AI assistants to search the Arda Credit codebase effectively:

1. search_deal_operations(operation_type) - Find deal management code (origination, payment, transfer, marketplace)
2. search_zkproof_implementation() - Find SP1 zero-knowledge proof implementation
3. search_authentication_system(auth_type) - Find magic link auth, JWT, sessions
4. search_usdc_integration() - Find USDC deposit/withdrawal smart contract integration
5. search_frontend_feature(feature_name) - Find React components and features
6. debug_arda_issue(issue_description) - Debug-focused multi-collection search
7. explore_architecture_layer(layer) - Explore presentation, business, data, or blockchain layers
8. find_api_endpoint(endpoint_pattern) - Find API endpoint implementations
9. trace_data_flow(entity) - Trace data flow for an entity through the stack
10. find_test_coverage(feature) - Find test coverage for a feature
11. explore_deployment_config(service) - Explore deployment configurations
12. audit_security_patterns(concern) - Audit security implementations

Use list_prompts() and get_prompt(name) tools to discover and explore these templates programmatically.

MCP Resources (10 Total - Expanded in v1.2.1)

Dynamic documentation that stays synchronized with GitHub repositories:

1. arda://collections - Live repository structure and collection information
2. arda://search-tips - Enhanced search best practices with live repository insights
3. arda://dashboard - Real-time collection health metrics and status
4. arda://api-catalog - Complete catalog of all API endpoints
5. arda://patterns - Common code patterns and best practices
6. arda://stats - Live codebase statistics (LOC, files, languages)
7. arda://dependencies - Service dependency map and integration points
8. arda://changelog ⭐ NEW - Recent code changes and repository updates
9. arda://metrics ⭐ NEW - Performance metrics and operational insights
10. arda://architecture ⭐ NEW - System architecture with Mermaid diagrams

Use list_resources() and read_resource(uri) tools to discover and access these resources programmatically.

How it works:

• Server fetches repository structure via GitHub API on startup
• Cache refreshes automatically every hour (configurable with _repo_cache_ttl)
• Use refresh_repo_cache() tool to manually force immediate refresh
• Requires GHCR_TOKEN, ARDA_CREDIT_REPO_URL, and ARDA_CREDIT_APP_REPO_URL in .env (optional)

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                    MCP Client (Cursor/Claude)                │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol
┌─────────────────────▼───────────────────────────────────────┐
│              Arda Vector Database MCP Server                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  FastMCP Features:                                  │    │
│  │  Tools (6):                                         │    │
│  │  - health_check()                                   │    │
│  │  - list_collections()                               │    │
│  │  - get_collection_info(collection_name)             │    │
│  │  - semantic_search(query, collection, limit, ...)   │    │
│  │  - batch_semantic_search(queries, ...)              │    │
│  │  - cross_collection_search(query, collections, ...) │    │
│  │  Prompts (6): search_deal_operations, etc.          │    │
│  │  Resources (2): arda://collections, arda://search-tips │ │
│  └─────────────────────────────────────────────────────┘    │
└────────────┬──────────────────────────┬─────────────────────┘
             │                          │
             │                          │
  ┌──────────▼──────────┐    ┌─────────▼────────────┐
  │  Qdrant Vector DB   │    │  Embedding Endpoint  │
  │  - 4096-dim vectors │    │   Service (L4 GPU)   │
  │  - Cosine distance  │    │   - Qwen3-8B model   │
  │  - Multi-collection │    │   - 45 emb/sec       │
  └─────────────────────┘    └──────────────────────┘

Data Flow

1. Query Processing - AI assistant sends natural language query via MCP
2. Embedding Generation - Server forwards query to embedding endpoint (Cloudflare AI gateway)
3. Vector Search - Embedding used to search Qdrant collections
4. Result Formatting - Top results returned with scores and metadata
5. Context Enhancement - AI assistant uses results for code understanding

Technology Stack

• FastMCP - MCP server framework
• Qdrant - Vector database (cloud or self-hosted)
• Cloudflare AI Gateway - Embedding service endpoint
• Qwen3-Embedding-8B - 4096-dimensional embedding model
• httpx - HTTP client for embedding endpoint communication

📊 Available Collections

Code Collections (Arda Credit Platform)

• arda_code_rust - Rust backend for Arda Credit

  • API server, database layer, SP1 zkVM program, Ethereum client
  • Technologies: Rust, Axum, SQLx, Alloy, SP1 zkVM

• arda_code_typescript - React frontend for Arda Credit

  • Components (deals, investments, auth, portfolio, profile), pages, utilities
  • Technologies: React 18, TypeScript, Vite, shadcn/ui, React Query

• arda_code_solidity - Smart contracts for Arda Credit

  • ARDA.sol (proof verification), MockUSDC.sol, ARDAFaucet.sol
  • Technologies: Solidity 0.8.28, Foundry, SP1 Groth16 verifier

Documentation Collection

• arda_documentation - Architecture docs, API specs, deployment guides
  • Three-component architecture, deal system design, privacy guarantees

Collection Metadata

Each code chunk includes:

• file_path - Relative path from repository root
• content - Code snippet (typically 500 tokens)
• language - Programming language (rust, typescript, solidity)
• chunk_type - Type of code (function, struct, class, module, etc.)
• start_line / end_line - Line numbers in source file

🔍 Search Examples

Finding Authentication Logic

semantic_search(
    query="JWT token validation and authentication middleware",
    collection_name="arda_code_rust",
    limit=5,
    score_threshold=0.6
)

Finding React Components

semantic_search(
    query="credit score display component with charts",
    collection_name="arda_code_typescript",
    limit=10,
    score_threshold=0.5
)

Finding Smart Contract Functions

semantic_search(
    query="loan approval logic with zero-knowledge proof verification",
    collection_name="arda_code_solidity",
    limit=5,
    score_threshold=0.7
)

Architecture Documentation

semantic_search(
    query="system architecture and component interactions",
    collection_name="arda_documentation",
    limit=3,
    score_threshold=0.5
)

⚙️ Configuration

Environment Variables

Variable	Required	Description
QDRANT_URL	Yes	Qdrant instance URL (e.g., https://xxxxx.gcp.cloud.qdrant.io)
QDRANT_API_KEY	Yes	Qdrant JWT authentication token
EMBEDDING_ENDPOINT	Yes	Embedding service base URL (format: https://gateway.ai.cloudflare.com/v1/{account_id}/aig/compat)
CLOUDFLARE_API_TOKEN	Yes	Cloudflare API token for authentication
DEEPINFRA_API_KEY	Yes	Deep Infra provider API key (required for embeddings)
OPENROUTER_API_KEY	Optional	For LLM features (not used by MCP server)

Qdrant Setup

Option 1: Qdrant Cloud (Recommended)

1. Create account at cloud.qdrant.io
2. Create a cluster (free tier available)
3. Copy cluster URL and API key to .env

Option 2: Self-Hosted

# Using Docker
docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

# Set in .env
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=  # Leave empty for local instance

Embedding Endpoint

The server uses Cloudflare AI gateway for embedding generation. The EMBEDDING_ENDPOINT should be the full base URL in the format: https://gateway.ai.cloudflare.com/v1/{account_id}/aig/compat

The server will automatically append /embeddings to this base URL. You must provide both:

• CLOUDFLARE_API_TOKEN - Cloudflare Gateway authentication token
• DEEPINFRA_API_KEY - Deep Infra provider API key (for the actual embedding service)

Example:

EMBEDDING_ENDPOINT=https://gateway.ai.cloudflare.com/v1/2de868ad9edb1b11250bc516705e1639/aig/compat
CLOUDFLARE_API_TOKEN=your_cloudflare_token
DEEPINFRA_API_KEY=your_deepinfra_api_key

🎯 Arda Credit Specific Features

Domain-Specific Search Patterns

The server includes 6 pre-built prompts optimized for Arda Credit development:

1. Deal Operations - Search for deal origination, payments, transfers, marketplace
2. ZK Proof System - Find SP1 zkVM implementation, batch processing, privacy guarantees
3. Authentication - Locate magic link auth, KYC validation, user management
4. USDC Integration - Find deposit/withdrawal flows across frontend, backend, contracts
5. Frontend Features - Search React components with specific feature names
6. Debugging - Multi-collection search with lower thresholds for issue investigation

Collection-Specific Guidance

The server provides 2 resources with static documentation:

1. arda://collections - Detailed breakdown of each collection's structure and tech stack
2. arda://search-tips - Best practices for query formulation and parameter tuning

Context Limit Optimization

v1.1.0 increases default limits by 2x to better handle Arda Credit's codebase size:

Search Type	Results	Use Case
Single query	20 (was 10)	Standard code search
Batch search	100 (10×10)	Comprehensive feature understanding
Cross-collection	30 (3×10)	Full-stack feature exploration
Combined max	300 (10×3×10)	Deep architectural analysis

🛡️ Security & Best Practices

Read-Only Operations

The MCP server is designed for read-only vector search operations. It does not support:

• Writing new vectors to Qdrant
• Modifying existing collections
• Creating or deleting collections
• Updating collection configuration

API Key Security

• Store credentials in .env file (never commit to git)
• Use environment variables in MCP configuration
• Rotate Qdrant API keys periodically
• Use separate API keys for development and production

Network Security

• Qdrant Cloud provides TLS encryption by default
• Use HTTPS for embedding endpoints
• Consider VPC networking for production deployments
• Monitor API usage through Qdrant dashboard

📈 Performance

Typical Metrics (v1.2.0)

• Search Latency (Cached): < 500ms ⚡ NEW
• Search Latency (Uncached): < 2s
• Cache Hit Rate: > 60% after warmup ⚡ NEW
• Embedding Generation: Via Cloudflare AI gateway
• Vector Dimensions: 4096 (Qwen3-Embedding-8B)
• Search Algorithm: HNSW (Hierarchical Navigable Small World)
• Distance Metric: Cosine similarity

Caching ⭐ NEW in v1.2.0

Query results are automatically cached for 30 minutes:

• First query: Full search (< 2s)
• Repeated query: From cache (< 500ms)
• Cache size: Up to 1000 queries
• TTL: 30 minutes
• Automatic eviction: Oldest entries removed when cache is full

Optimization Tips

1. Use Smart Search - ⭐ NEW: Automatically routes to the best tool
2. Score Threshold - Use higher thresholds (0.6-0.8) for precision, lower (0.4-0.5) for recall
3. Limit - Default 20 results balances context and speed (max 50)
4. Batch Search - Use for comprehensive understanding (10 queries × 10 results = 100 total)
5. Cross-Collection - Use for full-stack features (3 collections × 10 results = 30 total)
6. Collection Selection - Search specific language collections for better accuracy
7. Query Quality - More specific queries yield better results
8. Use Prompts - Pre-built templates provide optimized search strategies
9. Specialized Tools - ⭐ NEW: Use get_auth_systems, get_stack_overview, etc. for common queries

🧪 Testing

Quick Local Testing

Run the comprehensive test script to verify all components:

# Make sure your .env file is set up with:
# - QDRANT_URL
# - QDRANT_API_KEY
# - CLOUDFLARE_API_TOKEN
# - EMBEDDING_ENDPOINT (optional, defaults to https://gateway.ai.cloudflare.com)

# Run the test script
python test_local.py

The test script will verify:

1. ✅ Environment variable validation
2. ✅ Qdrant connection and collections
3. ✅ Embedding endpoint connection (with Cloudflare token)
4. ✅ Semantic search functionality

Manual Testing

# Start the server
python server.py

# The server will:
# - Validate environment variables
# - Connect to Qdrant
# - Warm up the embedding endpoint
# - Be ready to accept MCP connections

Quick Health Check

# Verify environment and Qdrant connection
python -c "
from server import validate_environment, initialize_qdrant_client
config = validate_environment()
client = initialize_qdrant_client(config)
print('✅ All systems operational')
"

Testing Embedding Endpoint Directly

# Test Cloudflare embedding endpoint with curl
curl -X POST https://gateway.ai.cloudflare.com \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["test query"]}'

🐛 Troubleshooting

"Qdrant client not initialized"

Cause: Server failed to connect to Qdrant during startup.

Solutions:

• Verify QDRANT_URL is accessible from your network
• Check QDRANT_API_KEY is valid and has read permissions
• Ensure Qdrant service is running and healthy

"Cloudflare API token not configured"

Cause: CLOUDFLARE_API_TOKEN environment variable is missing.

Solutions:

• Obtain a Cloudflare API token from your Cloudflare account
• Add CLOUDFLARE_API_TOKEN to your .env file
• The EMBEDDING_ENDPOINT defaults to https://gateway.ai.cloudflare.com if not specified
• Verify endpoint is accessible with authentication

"Collection 'X' not found"

Cause: Requested collection doesn't exist in Qdrant.

Solutions:

• Run health_check() to list available collections
• Ingest codebase using i2p ingestion pipeline
• Verify collection names match expected values

"Failed to generate query embedding"

Cause: Embedding endpoint is unreachable or erroring.

Solutions:

• Check embedding endpoint (Cloudflare AI gateway) status
• Verify EMBEDDING_ENDPOINT URL is correct
• Check endpoint logs for service errors

"Invalid embedding dimensions"

Cause: Embedding endpoint returned embedding with wrong dimensions.

Solutions:

• Verify embedding endpoint is using Qwen3-Embedding-8B model
• Check embedding endpoint configuration
• Check endpoint logs for configuration issues

📚 Documentation

• docs/TOOLS_GUIDE.md ⭐ NEW - Comprehensive guide for all tools
• docs/MANUAL_TESTS.md ⭐ NEW - Manual test scenarios
• DEPLOYMENT.md ⭐ NEW - Deployment checklist and verification
• server.py - Complete MCP server implementation with inline documentation
• src/cache.py ⭐ NEW - Query result caching implementation
• src/query_router.py ⭐ NEW - Intelligent query routing
• src/response_formatter.py ⭐ NEW - IDE-optimized response formatting
• src/collections.py ⭐ NEW - Collection schema and aliases
• FastMCP Documentation - MCP framework reference
• Qdrant Documentation - Vector database reference

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Follow the i2p coding standards
2. Keep files under 500 lines
3. Use single responsibility principle
4. Add comprehensive tests for new features
5. Update documentation for all changes

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• I2P Meta-Reasoning System - Strategic technical advisory for AI agents
• FastMCP - Model Context Protocol framework
• Qdrant - Vector database for semantic search
• Cloudflare AI Gateway - Embedding service endpoint

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@arda.global

📋 Version History

v1.2.1 (Current)

Release Date: 2025-11-19

New Features:

• ⭐ execute_prompt Tool - Automatically execute prompt search strategies with parameter support
• ⭐ 3 New Resources - changelog (recent updates), metrics (performance insights), architecture (Mermaid diagrams)

Improvements:

• Enhanced get_prompt to handle required parameters gracefully with placeholders
• Fixed dashboard resource hit_rate variable bug
• Fixed search-tips and stats resources missing import errors
• All resources now properly reference dependencies

Bug Fixes:

• Dashboard: Use hit_rate_percent instead of hit_rate
• Search tips: Import get_cached_repo_structures function
• Stats: Import get_cached_repo_structures function
• Get prompt: Handle prompts with required parameters without throwing errors

Total Counts:

• 19 tools (added 1: execute_prompt)
• 12 prompts (unchanged)
• 10 resources (added 3: changelog, metrics, architecture)

v1.2.0

Release Date: 2025-11-19

New Features:

• ⭐ Smart Search - Intelligent query routing to best tool
• ⭐ 5 Specialized Tools - Common query patterns (auth, stack, deployed services, location finder, dependencies)
• ⭐ 4 MCP Metadata Tools - Programmatic discovery (list_resources, read_resource, list_prompts, get_prompt)
• ⭐ Query Caching - 30-minute TTL, < 500ms cached responses
• ⭐ Response Formatting - IDE-optimized responses for Cursor/Claude Code
• ⭐ Query Router - Automatic intent detection and tool selection
• ⭐ Collection Schema - Comprehensive collection definitions and aliases
• ⭐ Expanded Prompts - 12 prompts (was 6) with new architecture, API, testing, deployment, and security templates
• ⭐ Expanded Resources - 7 resources (was 2) with API catalog, code patterns, stats, and dependencies

Improvements:

• Enhanced cross_collection_search with better error handling
• All search tools now async for better performance
• Graceful degradation when collections are missing
• Detailed error reporting with error types
• Cache statistics tracking
• Comprehensive documentation (Tools Guide, Manual Tests, Deployment Guide)
• MCP specification compliance for resource and prompt discovery

Performance:

• Response time: < 500ms (cached), < 2s (uncached)
• Cache hit rate: > 60% after warmup
• Supports up to 1000 cached queries
• 18 tools total (was 13) for comprehensive codebase exploration

v1.1.0

Release Date: 2025-01-06

New Features:

• ✨ Added 6 domain-specific MCP prompts for Arda Credit codebase
• ✨ Added 2 MCP resources (collections guide, search tips)
• ✨ Added batch_semantic_search tool (up to 100 results per call)
• ✨ Added cross_collection_search tool (full-stack exploration)
• 🚀 Increased default limits by 2x (20 results vs 10)
• 📚 Updated README with comprehensive v1.1.0 documentation

Improvements:

• Better context retrieval for large Arda Credit codebase
• Pre-built search strategies for common development tasks
• Static documentation accessible through MCP resources
• Enhanced full-stack feature exploration capabilities

v1.0.0

Release Date: 2025-01-05

Initial Release:

• Basic semantic search functionality
• Collection health monitoring
• Embedding endpoint integration (Cloudflare AI gateway)
• Qdrant vector database connectivity
• Support for 4 collections (rust, typescript, solidity, documentation)

---

Arda Vector Database MCP Server - Semantic code search for AI-powered development.