🧠 IFS Cloud MCP Server

AI-powered Model Context Protocol server for intelligent IFS Cloud codebase analysis

A sophisticated Model Context Protocol (MCP) server that provides AI agents with deep understanding of IFS Cloud codebases through comprehensive analysis, PageRank importance ranking, and intelligent code search capabilities.

---

✨ Key Features

🎯 Intelligent Code Analysis

• Comprehensive File Analysis: Extracts API calls, procedure/function names, and dependency relationships
• PageRank Ranking: Identifies the most important files based on dependency network analysis
• Reference Graph: Maps inter-file dependencies for architectural understanding
• Multi-format Support: Handles .plsql, .entity, .client, .projection, .fragment, and more

📦 Version Management

• ZIP Import: Import complete IFS Cloud releases from ZIP files
• Multiple Versions: Manage and switch between different IFS Cloud versions
• Isolated Analysis: Each version maintains separate analysis data
• Smart Extraction: Automatically filters and organizes supported file types

🔍 Advanced Hybrid Search & Discovery

• Dual-Query Hybrid Search: Separate semantic and lexical queries for precision control
• BGE-M3 Semantic Search: AI-powered understanding using state-of-the-art embeddings
• BM25S Lexical Search: Fast exact matching for API names, functions, and keywords
• FlashRank Fusion: Neural reranking combines semantic and lexical results intelligently
• Three Search Modes: Comprehensive, semantic-only, or lexical-only via MCP tools
• PageRank Importance: Files ranked by their significance in the dependency network
• CUDA Acceleration: GPU-powered semantic search for maximum performance

---

🚀 Quick Start

1. Installation

git clone https://github.com/graknol/ifs-cloud-core-mcp-server.git
cd ifs-cloud-core-mcp-server
uv sync

2. Import IFS Cloud Version

# Import an IFS Cloud ZIP file
uv run python -m src.ifs_cloud_mcp_server.main import "IFS_Cloud_25.1.0.zip" --version "25.1.0"

3. Analyze the Codebase

# Perform comprehensive analysis
uv run python -m src.ifs_cloud_mcp_server.main analyze --version "25.1.0"

# Calculate PageRank importance scores
uv run python -m src.ifs_cloud_mcp_server.main calculate-pagerank --version "25.1.0"

4. Start the MCP Server

# Start server with analyzed version
uv run python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"

---

📋 CLI Commands Reference

Version Management

# Import a ZIP file
uv run python -m src.ifs_cloud_mcp_server.main import <zip_file> --version <version_name>

# Download pre-built indexes from GitHub (fastest setup)
uv run python -m src.ifs_cloud_mcp_server.main download --version <version> [--force]

# List all versions
uv run python -m src.ifs_cloud_mcp_server.main list

# Delete a version
uv run python -m src.ifs_cloud_mcp_server.main delete --version <version_name> [--force]

Analysis Commands

# Analyze codebase (extract dependencies, API calls, etc.)
uv run python -m src.ifs_cloud_mcp_server.main analyze --version <version> [--max-files N] [--force]

# Calculate PageRank importance scores
uv run python -m src.ifs_cloud_mcp_server.main calculate-pagerank --version <version>

# Create embeddings for semantic search (uses BGE-M3 model)
uv run python -m src.ifs_cloud_mcp_server.main embed --version <version> [--max-files N]

# Create test embeddings (top 10 files for quick testing)
uv run python -m src.ifs_cloud_mcp_server.main embed --version <version> --max-files 10

Server Operation

# Start MCP server
uv run python -m src.ifs_cloud_mcp_server.main server --version <version>

# Start web UI (if available)
uv run python -m src.ifs_cloud_mcp_server.web_ui

---

� MCP Search Tools

The server provides three sophisticated search tools for AI agents:

search_ifs_codebase - Comprehensive Hybrid Search

// Full hybrid search with separate semantic and lexical queries
search_ifs_codebase(
  query: "validation logic",           // Main query (fallback for both)
  semantic_query: "business rules",    // For FAISS semantic search
  lexical_query: "Check_Insert___",   // For BM25S exact matching
  max_results: 10,                    // Number of results
  explain: true                       // Include scoring explanations
)

search_ifs_semantic - AI-Powered Understanding

// Pure semantic search using BGE-M3 embeddings
search_ifs_semantic(
  semantic_query: "customer credit validation patterns",
  max_results: 10,
  explain: true
)

search_ifs_lexical - Exact API & Keyword Matching

// Pure lexical search using BM25S
search_ifs_lexical(
  lexical_query: "Customer_API.Get_Credit_Limit___",
  max_results: 10,
  explain: true
)

Key Features:

• Dual Query Processing: Different queries optimized for semantic vs lexical search
• BGE-M3 Embeddings: 1024-dimension vectors with 8192 token context
• CUDA Acceleration: GPU-powered semantic search when available
• FlashRank Fusion: Neural reranking for optimal result ordering
• PageRank Integration: Importance-weighted result scoring
• Detailed Explanations: Optional scoring breakdowns for transparency

---

�🔧 MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "ifs-cloud": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "src.ifs_cloud_mcp_server.main",
        "server",
        "--version",
        "25.1.0"
      ],
      "cwd": "/path/to/ifs-cloud-core-mcp-server"
    }
  }
}

Other MCP Clients

# Standard MCP server startup
uv run python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"

---

📊 Analysis Output

The system generates comprehensive analysis data:

Dependency Analysis

• API Calls: Which APIs each file calls
• Reference Graph: File-to-file dependency mappings
• Incoming Links: How many files depend on each file

PageRank Scoring

• Importance Ranking: Files ranked by network centrality
• Foundation APIs: Infrastructure files (FndSession, Site, etc.) rank highest
• Business Logic: Domain-specific files ranked by usage patterns

File Metadata

• File Size & Type: Basic file characteristics
• Procedure/Function Names: Code structure analysis
• Change Information: Extracted from comments and headers

---

🎯 Intelligent Workflow Example

AI Agent Search Workflow

💬 User: "Find customer credit validation patterns in IFS Cloud"

🧠 AI Agent automatically uses hybrid search:

1️⃣ **Semantic Search** (search_ifs_semantic):
   Query: "customer credit validation business rules"
   → BGE-M3 finds conceptually similar code patterns
   → Returns files with credit checking logic, validation routines

2️⃣ **Lexical Search** (search_ifs_lexical):
   Query: "Customer_API Credit_Limit Check_Credit"
   → BM25S finds exact API names and function calls
   → Returns specific implementation methods

3️⃣ **Hybrid Fusion** (search_ifs_codebase):
   Semantic: "credit validation patterns"
   Lexical: "Customer_API.Check_Credit___"
   → FlashRank combines both approaches intelligently
   → PageRank boosts important foundation files

✅ Result: Comprehensive understanding across:
   - Business logic patterns (semantic)
   - Exact API implementations (lexical)
   - Architectural importance (PageRank)
   - Perfect architectural consistency!

Fast Setup Workflow ⚡ (Recommended)

# 1. Import IFS Cloud version
uv run python -m src.ifs_cloud_mcp_server.main import "IFS_Cloud_25.1.0.zip"

# 2. Download pre-built indexes from GitHub (if available)
uv run python -m src.ifs_cloud_mcp_server.main download --version "25.1.0"

# 3. Start MCP server immediately
uv run python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"

Result: Ready in minutes instead of hours! ⚡

Complete Setup Workflow (If download unavailable)

# 1. Import IFS Cloud version
uv run python -m src.ifs_cloud_mcp_server.main import "IFS_Cloud_25.1.0.zip"

# 2. Analyze the codebase (extract dependencies, API calls)
uv run python -m src.ifs_cloud_mcp_server.main analyze --version "25.1.0"

# 3. Calculate importance rankings (PageRank network analysis)
uv run python -m src.ifs_cloud_mcp_server.main calculate-pagerank --version "25.1.0"

# 4. Build BM25S lexical search index
uv run python -m src.ifs_cloud_mcp_server.main reindex-bm25s --version "25.1.0"

# 5. Optional: Create semantic embeddings (BGE-M3 model, ~5-10 minutes)
uv run python -m src.ifs_cloud_mcp_server.main embed --version "25.1.0"

# 6. Start MCP server with full hybrid search capabilities
uv run python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"

Result: AI agents now have comprehensive hybrid search across your IFS Cloud codebase!

---

📁 Supported File Types

File Type	Purpose	Analysis Features
.plsql	PL/SQL Business Logic	API calls, procedures, functions
.entity	Data Entity Definitions	Entity relationships
.client	User Interface Components	UI patterns, commands
.projection	Data Access Layer	Queries, actions
.fragment	Full-Stack Components	Complete integration patterns
.views	Database Views	Data structure
.storage	Storage Definitions	Database mappings

---

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │◄──►│   MCP Server    │◄──►│ Analysis Data   │
│ (Claude, etc.)  │    │                 │    │ (JSON/JSONL)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │ Hybrid Search   │
                       │ • BGE-M3 FAISS  │
                       │ • BM25S Lexical │
                       │ • FlashRank     │
                       │ • PageRank      │
                       └─────────────────┘

Search Architecture Detail

Query Input
     │
     ▼
┌─────────────────┐
│ Query Processor │ ◄─── Semantic Query + Lexical Query
│ • Intent detect │
│ • Query split   │
└─────────────────┘
     │
     ▼
┌─────────────────┐    ┌─────────────────┐
│ FAISS Search    │    │ BM25S Search    │
│ • BGE-M3 embed  │    │ • Exact match   │
│ • Semantic sim  │    │ • Keyword score │
│ • CUDA accel    │    │ • Fast retrieval│
└─────────────────┘    └─────────────────┘
     │                          │
     └─────────┬─────────────────┘
               ▼
        ┌─────────────────┐
        │ FlashRank Fusion│
        │ • Neural rerank │
        │ • Score fusion  │
        │ • PageRank boost│
        └─────────────────┘
               ▼
        Final Ranked Results

---

📈 Performance

Search Performance

• Hybrid Search Response: <100ms for most queries with CUDA acceleration
• BGE-M3 Embedding Generation: ~50ms per query (GPU) / ~200ms (CPU)
• BM25S Lexical Search: <10ms across 10,000+ documents
• FlashRank Neural Reranking: <50ms for top-K candidate fusion
• FAISS Vector Search: <20ms with 1024-dim BGE-M3 embeddings

System Performance

• Analysis Speed: 1,000+ files/second on modern hardware
• Memory Efficient: Handles 10,000+ file codebases
• Scalable: Version isolation prevents data conflicts
• GPU Acceleration: Automatic CUDA detection for semantic search

---

🛠️ Development

# Install for development
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run black src/ tests/

# Type checking
uv run mypy src/

---

📚 Data Storage

The system stores data in versioned directories with separate indexes:

%APPDATA%/ifs_cloud_mcp_server/               # Windows
~/.local/share/ifs_cloud_mcp_server/          # Linux/macOS
├── versions/
│   └── 25.1.0/
│       ├── source/              # Extracted files
│       ├── analysis/            # Analysis results
│       ├── ranked.jsonl         # PageRank results
│       ├── bm25s/              # BM25S lexical index
│       │   ├── index.h5        # BM25S index data
│       │   └── corpus.jsonl    # Document corpus
│       └── faiss/              # FAISS semantic index
│           ├── index.faiss     # Vector index
│           ├── embeddings.npy  # BGE-M3 embeddings
│           └── metadata.jsonl  # Document metadata
└── models/                     # Downloaded models
    └── bge-m3/                # BGE-M3 model cache

---

🔮 Future Enhancements

• � Advanced AI Models: Integration with newer embedding models (BGE-M4, E5-v3)
• 🔍 Query Understanding: Natural language intent classification and query expansion
• 📊 Visual Analytics: Interactive dependency graph visualization
• 🌐 Web Interface: Enhanced browser-based exploration with search filtering
• 🚀 Performance: Further optimization of hybrid search pipeline
• 🎯 Specialized Search: Domain-specific search modes (UI patterns, business logic, etc.)

---

--connection "oracle://ifsapp:password@host:1521/IFSCDEV" 25.1.0 ```

📦 Use Production Data (Ready-to-use):

• Complete system with pre-extracted production metadata
• Enhanced search with business term matching and metadata enrichment
• Ready-to-use with real IFS Cloud files

cd production
uv run python test_setup.py  # Verify production setup
uv run python demos/demo_real_files.py  # See the magic happen!

� Custom ZIP Import (For specific versions):

# Import any IFS Cloud ZIP file to create versioned catalog
uv run python -m src.ifs_cloud_mcp_server.main import "IFS_Cloud_24.2.1.zip" --version "24.2.1"

3. Start Intelligent AI Agent

# Start with your imported version
uv run python -m src.ifs_cloud_mcp_server.main server --version "24.2.1"

4. Connect GitHub Copilot

Configure your MCP client to connect to the intelligent AI agent and experience AI that truly understands your IFS Cloud patterns!

---

🔧 Intelligent Features

🧠 Intelligent Context Analysis	📊 Deep Code Analysis
• Automatic pattern discovery • Business requirement understanding • Existing API identification • Best practice recommendations	• PLSQL business logic analysis • Client UI pattern recognition • Projection data model mapping • Fragment full-stack understanding

📦 Version Management	⚡ High Performance
• ZIP file import/extraction • Multiple version support • Isolated environments • Easy switching between versions	• 1000+ files/second indexing • <100ms search response • Intelligent caching system • Batch processing optimization

---

📁 Supported IFS Cloud Files

File Type	Purpose	AI Understanding
.plsql	Business Logic	APIs, validations, business rules
.entity	Data Models	Entity relationships, attributes
.client	User Interface	UI patterns, commands, navigation
.projection	Data Access	Queries, actions, data surface
.fragment	Full-Stack Components	Complete UI-to-data integration
.views, .storage	Database Layer	Data structure and access patterns

---

🎯 Intelligent Workflow Example

💬 User: "Add customer order validation to check credit limits"

🧠 AI Agent automatically:
   1. Searches for "validation", "customer", "order", "credit" patterns
   2. Finds existing CustomerOrder.plsql, validation methods
   3. Analyzes business logic with PLSQL analyzer
   4. Discovers Check_Insert___ validation patterns
   5. Identifies existing Customer_API methods
   6. Generates implementation matching your exact patterns

✅ Result: Perfect architectural consistency!

---

📋 Commands Reference

Database Metadata Extraction

# Extract metadata from your database (recommended)
export IFS_DB_PASSWORD="secure_password"
uv run python -m src.ifs_cloud_mcp_server.main extract \
  --host db-host --username ifsapp --service IFSCDEV 25.1.0

# Extract with connection string
uv run python -m src.ifs_cloud_mcp_server.main extract \
  --connection "oracle://user:pass@host:1521/service" 25.1.0

# JSON output for automation
uv run python -m src.ifs_cloud_mcp_server.main extract \
  --connection "oracle://..." --quiet --json 25.1.0

ZIP Management

# Import IFS Cloud ZIP file
uv run python -m src.ifs_cloud_mcp_server.main import <zip_file> <version>

# List available versions
uv run python -m src.ifs_cloud_mcp_server.main list

# Start server with specific version
uv run python -m src.ifs_cloud_mcp_server.main server --version <version>

Server Management

# Start MCP server (default - uses ./index)
uv run python -m src.ifs_cloud_mcp_server.main server

# Start with specific version
uv run python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"

# Start with custom index path
uv run python -m src.ifs_cloud_mcp_server.main server --index-path ./my_index

---

� MCP Client Configuration

GitHub Copilot

{
  "mcpServers": {
    "ifs-cloud-intelligent-agent": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "src.ifs_cloud_mcp_server.main",
        "server",
        "--version",
        "24.2.1"
      ],
      "cwd": "/path/to/ifs-cloud-core-mcp-server"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "ifs-cloud": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "src.ifs_cloud_mcp_server.main",
        "server",
        "--version",
        "24.2.1"
      ],
      "cwd": "/path/to/ifs-cloud-core-mcp-server"
    }
  }
}

---

📚 Documentation

• � Metadata Extraction CLI - Extract metadata from YOUR database
• �📖 ZIP Indexing Walkthrough - Step-by-step import example
• 📋 ZIP Indexing Instructions - Complete import documentation
• 🧠 Intelligent Agent Guide - How the AI agent works
• 🌐 Web UI Documentation - Interactive exploration interface

Note: All metadata extraction including GUI mappings is now integrated into the main CLI. Use the extract command to gather data from your IFS Cloud database.

---

🎉 The Result

Your AI agent now has comprehensive IFS Cloud intelligence and will:

• ✅ Automatically understand your specific IFS Cloud patterns
• ✅ Discover existing APIs and validation approaches
• ✅ Generate consistent code that matches your architecture
• ✅ Follow naming conventions and business rule patterns
• ✅ Leverage existing components instead of reinventing
• ✅ Maintain quality standards across all implementations

Transform your development workflow with AI that truly understands IFS Cloud! 🚀

---

```

3. Open browser: Navigate to http://localhost:5700 (or the port shown in the startup message) and start exploring!

🔌 MCP Server Mode (For AI integration)

1. Start MCP server:

# For Claude Desktop or other MCP clients
uv run python -m src.ifs_cloud_mcp_server.main

2. Configure in Claude Desktop:

{
  "mcpServers": {
    "ifs-cloud": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.ifs_cloud_mcp_server.main"],
      "cwd": "/path/to/ifs-cloud-core-mcp-server"
    }
  }
}

Installation

# Clone the repository
git clone https://github.com/graknol/ifs-cloud-core-mcp-server.git
cd ifs-cloud-core-mcp-server

# Install dependencies with UV (recommended)
uv sync

# Or with pip
pip install -e .

# For development
pip install -e ".[dev]"

🤖 AI Intent Classification Models

The server uses FastAI models for intelligent query classification. Models are automatically downloaded from GitHub releases when first needed:

# Models download automatically, but you can also:

# Download manually
uv run python -m src.ifs_cloud_mcp_server.model_downloader

# Train your own model (optional)
uv run python scripts/train_proper_fastai.py

# Prepare model for release (maintainers)
uv run python scripts/prepare_model_release.py

Model Details:

• Size: ~121MB (FastAI ULMFiT model)
• Storage: Downloaded from GitHub releases (not in repo)
• Fallback: Graceful degradation if model unavailable
• GPU Support: Automatic CUDA detection and acceleration

Quick Start

# Start the MCP server
ifs-cloud-mcp-server --port 8000 --index-path ./index

# Index your IFS Cloud codebase
curl -X POST http://localhost:8000/index \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/ifs/cloud/project"}'

# Search for entities
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "CustomerOrder", "type": "entity"}'

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│   MCP Server    │◄──►│ Tantivy Index   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │ File Processors │
                       │  - Entity       │
                       │  - PL/SQL       │
                       │  - Views        │
                       │  - Storage      │
                       │  - Fragment     │
                       │  - Client       │
                       │  - Projection   │
                       └─────────────────┘

Development

# Run tests
pytest

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

Performance

• Indexing Speed: ~1000 files/second on typical hardware
• Search Response: <100ms for most queries
• Memory Usage: ~200MB for 1GB codebase index
• Incremental Updates: Real-time file change tracking

Future Roadmap

• 🤖 AI Integration: FastAI/PyTorch for semantic search
• 🧠 Pattern Recognition: ML-based code pattern detection
• 📈 Analytics: Advanced codebase insights and metrics
• 🔗 IDE Integration: VS Code and IntelliJ plugins

License

Licensed under the terms specified in the LICENSE file.