Skip to main content
Glama
graknol

IFS Cloud MCP Server

by graknol
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid
README.md
# ๐Ÿง  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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources