# ๐ง 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**
```bash
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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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
```typescript
// 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
```typescript
// 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
```typescript
// 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:
```json
{
"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**
```bash
# 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)_
```bash
# 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)_
```bash
# 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**
```bash
# 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.)
---
<div align="center">
**[โญ Star this repo](https://github.com/graknol/ifs-cloud-core-mcp-server)** โข **[๐ Report Issues](https://github.com/graknol/ifs-cloud-core-mcp-server/issues)** โข **[๐ฌ Discussions](https://github.com/graknol/ifs-cloud-core-mcp-server/discussions)**
_Built with โค๏ธ for IFS Cloud developers_
</div>
--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
```bash
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):
```bash
# 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**
```bash
# 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**
<table>
<tr>
<td><strong>๐ง Intelligent Context Analysis</strong></td>
<td><strong>๐ Deep Code Analysis</strong></td>
</tr>
<tr>
<td>
โข Automatic pattern discovery<br>
โข Business requirement understanding<br>
โข Existing API identification<br>
โข Best practice recommendations
</td>
<td>
โข PLSQL business logic analysis<br>
โข Client UI pattern recognition<br>
โข Projection data model mapping<br>
โข Fragment full-stack understanding
</td>
</tr>
</table>
<table>
<tr>
<td><strong>๐ฆ Version Management</strong></td>
<td><strong>โก High Performance</strong></td>
</tr>
<tr>
<td>
โข ZIP file import/extraction<br>
โข Multiple version support<br>
โข Isolated environments<br>
โข Easy switching between versions
</td>
<td>
โข 1000+ files/second indexing<br>
โข <100ms search response<br>
โข Intelligent caching system<br>
โข Batch processing optimization
</td>
</tr>
</table>
---
## ๐ **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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```json
{
"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**
```json
{
"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](./METADATA_EXTRACTION_CLI.md)** - Extract metadata from YOUR database
- **[๏ฟฝ๐ ZIP Indexing Walkthrough](./ZIP_WALKTHROUGH.md)** - Step-by-step import example
- **[๐ ZIP Indexing Instructions](./ZIP_INDEXING_INSTRUCTIONS.md)** - Complete import documentation
- **[๐ง Intelligent Agent Guide](./INTELLIGENT_AGENT.md)** - How the AI agent works
- **[๐ Web UI Documentation](./WEB_UI_README.md)** - 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!** ๐
---
<div align="center">
**[โญ Star this repo](https://github.com/graknol/ifs-cloud-core-mcp-server)** โข **[๐ Report Issues](https://github.com/graknol/ifs-cloud-core-mcp-server/issues)** โข **[๐ฌ Discussions](https://github.com/graknol/ifs-cloud-core-mcp-server/discussions)**
_Built with โค๏ธ for IFS Cloud developers_
</div>
```
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:**
```bash
# For Claude Desktop or other MCP clients
uv run python -m src.ifs_cloud_mcp_server.main
```
2. **Configure in Claude Desktop:**
```json
{
"mcpServers": {
"ifs-cloud": {
"command": "uv",
"args": ["run", "python", "-m", "src.ifs_cloud_mcp_server.main"],
"cwd": "/path/to/ifs-cloud-core-mcp-server"
}
}
}
```
## Installation
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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.
