# IFS Cloud MCP Server CLI API Specification
**Version**: 1.0
**Target**: AI Agent Implementation of VS Code Extension
**Purpose**: Complete technical specification for implementing VS Code extension CLI integration
---
## π― **CLI Overview**
The IFS Cloud MCP Server CLI provides comprehensive management of IFS Cloud codebase versions with advanced hybrid search capabilities. The CLI ---
### **9. SERVER Command** *(Default)*designed for programmatic integration and supports both interactive and automated workflows.
### **Core Architecture**
- **Entry Point**: `python -m src.ifs_cloud_mcp_server.main`
- **Alternative**: `uv run python -m src.ifs_cloud_mcp_server.main`
- **Command Structure**: `<entry_point> <command> [options] [arguments]`
- **Exit Codes**: 0 = success, 1 = error
- **Logging**: Structured JSON-compatible logging to stderr
---
## π **Command Reference**
### **1. IMPORT Command**
**Purpose**: Import IFS Cloud ZIP files with automatic version detection
```bash
python -m src.ifs_cloud_mcp_server.main import <zip_file> [OPTIONS]
```
**Arguments:**
- `zip_file` (required): Path to IFS Cloud ZIP file
**Options:**
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Auto-detects version from `checkout/fndbas/source/version.txt` inside ZIP
2. Extracts only supported file types (see **Supported Files** section)
3. Creates versioned directory structure in data directory
4. Provides next-step guidance in output
**Output Format:**
```
π Detecting version from path/to/file.zip
π Detected version: 25.1.0
β
Import completed successfully!
π Extracted files: /path/to/data/versions/25.1.0/source
π·οΈ Version: 25.1.0
Files extracted successfully. To work with this version:
Analyze: python -m src.ifs_cloud_mcp_server.main analyze --version "25.1.0"
MCP Server: python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"
```
**Error Handling:**
- FileNotFoundError: ZIP file doesn't exist
- ValueError: Invalid ZIP or version.txt not found
- Returns exit code 1 on failure
---
### **2. LIST Command**
**Purpose**: List all available IFS Cloud versions and their analysis status
```bash
python -m src.ifs_cloud_mcp_server.main list [OPTIONS]
```
**Options:**
- `--json`: Output in JSON format for programmatic parsing
**Human-Readable Output:**
```
Available IFS Cloud versions:
οΏ½ 25.1.0
Status: β
Ready (Hybrid Search)
Files: 42,603
Created: 2025-08-20 06:12:56
Components: BM25s, FAISS, PageRank
Command: python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"
π¦ 24.2.1
Status: β οΈ Not analyzed
Files: 38,421
Created: 2025-08-15 10:15:30
To analyze: python -m src.ifs_cloud_mcp_server.main analyze --version "24.2.1"
```
**JSON Output:**
```json
[
{
"version": "25.1.0",
"extract_path": "C:\\Users\\sindre\\AppData\\Roaming\\ifs_cloud_mcp_server\\versions\\25.1.0",
"analysis_path": "C:\\Users\\sindre\\AppData\\Roaming\\ifs_cloud_mcp_server\\versions\\25.1.0\\analysis\\comprehensive_plsql_analysis.json",
"bm25s_path": "C:\\Users\\sindre\\AppData\\Roaming\\ifs_cloud_mcp_server\\versions\\25.1.0\\bm25s",
"faiss_path": "C:\\Users\\sindre\\AppData\\Roaming\\ifs_cloud_mcp_server\\versions\\25.1.0\\faiss",
"pagerank_path": "C:\\Users\\sindre\\AppData\\Roaming\\ifs_cloud_mcp_server\\versions\\25.1.0\\ranked.jsonl",
"has_analysis": false,
"has_bm25s": true,
"has_faiss": true,
"has_pagerank": true,
"has_hybrid_search": true,
"has_full_analysis": false,
"is_ready": true,
"file_count": 42603,
"created": "2025-08-20 06:12:56"
}
]
```
---
### **3. DELETE Command**
**Purpose**: Remove a version and all associated data
```bash
python -m src.ifs_cloud_mcp_server.main delete --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier to delete
**Options:**
- `--force`: Skip interactive confirmation
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Validates version exists
2. Shows confirmation prompt (unless --force)
3. Recursively deletes version directory and all indexes
4. Provides confirmation of deletion
**Interactive Output:**
```
β οΈ This will permanently delete version '25.1.0' and ALL associated data:
π Source files: C:\...\versions\25.1.0
π Analysis data
π Search indexes
π§ Embeddings
Are you sure? (y/N):
```
---
### **4. DOWNLOAD Command**
**Purpose**: Download pre-built indexes from GitHub releases for faster setup
```bash
python -m src.ifs_cloud_mcp_server.main download --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier to download indexes for
**Options:**
- `--force`: Overwrite existing indexes
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Validates that version directory exists (must import first)
2. Checks GitHub releases for matching index files
3. Downloads BM25S and FAISS indexes if available
4. Extracts indexes to appropriate directories
5. Provides confirmation and next steps
**Output:**
```
π Starting download for version 25.1.0...
π Checking GitHub releases for version 25.1.0...
β
Found release: IFS Cloud 25.1.0 Pre-built Indexes
π₯ Downloading BM25S index (45,328,992 bytes)...
β
BM25S index extracted to C:\...\versions\25.1.0\bm25s
π₯ Downloading FAISS index (124,857,344 bytes)...
β
FAISS index extracted to C:\...\versions\25.1.0\faiss
π Successfully downloaded indexes for version 25.1.0
BM25S: C:\...\versions\25.1.0\bm25s
FAISS: C:\...\versions\25.1.0\faiss
β
Download completed successfully for version 25.1.0!
Ready to start MCP server:
python -m src.ifs_cloud_mcp_server.main server --version "25.1.0"
```
**Error Handling:**
- Version directory doesn't exist β Guidance to import first
- No matching GitHub release β Lists available releases, suggests local generation
- Network errors β Clear error messages with fallback suggestions
- Missing or invalid index files β Detailed asset information
**GitHub Release Format:**
- **Release Tag**: `indexes-{version}` (e.g., `indexes-25.1.0`)
- **Assets**: `{version}-bm25s.zip`, `{version}-faiss.zip`
- **Repository**: `graknol/ifs-cloud-core-mcp-server`
---
### **5. ANALYZE Command**
**Purpose**: Generate comprehensive codebase analysis
```bash
python -m src.ifs_cloud_mcp_server.main analyze --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier to analyze
**Options:**
- `--max-files INTEGER`: Limit analysis to N files (testing)
- `--force`: Overwrite existing analysis
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Scans source directory for supported files
2. Extracts API calls, dependencies, procedures, functions
3. Builds inter-file dependency graph
4. Creates comprehensive analysis JSON file
5. Updates version metadata
**Output:**
```
π Starting comprehensive analysis for version 25.1.0...
π Source directory: /path/to/versions/25.1.0/source
π Found 15,432 supported files
Processing files: 100%|ββββββββββββ| 15432/15432 [02:34<00:00, 125.7files/s]
β
Analysis completed successfully!
π Analysis file: /path/to/analysis/comprehensive_plsql_analysis.json
π Total files analyzed: 15,432
π Dependencies found: 89,541
β±οΈ Processing time: 2m 34s
```
---
### **6. CALCULATE-PAGERANK Command**
**Purpose**: Calculate PageRank importance scores based on dependencies
```bash
python -m src.ifs_cloud_mcp_server.main calculate-pagerank --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier
**Options:**
- `--damping-factor FLOAT`: PageRank damping factor (default: 0.85)
- `--max-iterations INTEGER`: Maximum iterations (default: 100)
- `--convergence-threshold FLOAT`: Convergence threshold (default: 1e-6)
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Loads dependency graph from analysis
2. Runs PageRank algorithm with specified parameters
3. Ranks files by importance in dependency network
4. Saves ranked results to JSONL file
**Output:**
```
π Starting PageRank calculation for version 25.1.0...
π Building dependency graph from 15,432 files
π Graph contains 89,541 directed edges
Running PageRank algorithm:
π― Damping factor: 0.85
π Max iterations: 100
π Convergence threshold: 1e-06
Iteration 45: Converged (delta: 8.23e-07)
β
PageRank calculation completed!
π Results saved: /path/to/analysis/ranked.jsonl
π Top 5 most important files:
1. FndSession.plsql (score: 0.0342)
2. Site_API.plsql (score: 0.0298)
3. Company_API.plsql (score: 0.0276)
4. User_Default_API.plsql (score: 0.0245)
5. Security_SYS.plsql (score: 0.0221)
```
---
### **7. EMBED Command**
**Purpose**: Create semantic embeddings using BGE-M3 model
```bash
python -m src.ifs_cloud_mcp_server.main embed --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier
**Options:**
- `--model STRING`: Ollama model for summarization (default: phi4-mini:3.8b-q4_K_M)
- `--max-files INTEGER`: Limit to N files for testing
- `--no-resume`: Start fresh, ignore checkpoints
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. **Phase 1**: Ollama summarization of code files
2. **Phase 2**: BGE-M3 embedding generation
3. **Phase 3**: FAISS index creation
4. Supports checkpointing and resume functionality
5. GPU acceleration when available
**Output:**
```
π EMBEDDING GENERATION STARTED
π Version: 25.1.0 | Model: phi4-mini:3.8b-q4_K_M | Max files: unlimited
ποΈ PHASE 1: AI Summarization (Ollama)
π Processing 15,432 files with Ollama model
π€ Generated summaries: 12,450/15,432 [80%]
π§ PHASE 2: Embedding Generation (BGE-M3)
π§ Loading BGE-M3 model (CUDA detected)
π Creating 1024-dim embeddings for 12,450 summaries
β‘ GPU acceleration: Active
π PHASE 3: FAISS Index Creation
πΎ Building FAISS index with 9,733 embeddings
π Saved to: /path/to/versions/25.1.0/faiss/
β
EMBEDDING GENERATION COMPLETED
β±οΈ Total time: 8m 42s
π― Ready for semantic search
```
---
### **8. REINDEX-BM25S Command**
**Purpose**: Rebuild BM25S lexical search index
```bash
python -m src.ifs_cloud_mcp_server.main reindex-bm25s --version <version> [OPTIONS]
```
**Arguments:**
- `--version` (required): Version identifier
**Options:**
- `--max-files INTEGER`: Limit to N files for testing
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Loads analysis data
2. Preprocesses source code for lexical search
3. Creates BM25S index with enhanced tokenization
4. Saves index to version-specific directory
**Output:**
```
π Starting BM25S index rebuild for version 25.1.0...
π Loading analysis from: /path/to/analysis.json
π Processing 15,432 files for indexing
π§ Enhanced preprocessing:
π Tokenizing source code
π Extracting API names and keywords
π Creating BM25S corpus
πΎ Building BM25S index...
β
BM25S reindexing completed!
π Index saved: /path/to/versions/25.1.0/bm25s/
π Indexed documents: 9,750
π― Ready for lexical search
```
---
### **8. SERVER Command** _(Default)_
**Purpose**: Start MCP server for AI agent integration
```bash
python -m src.ifs_cloud_mcp_server.main server --version <version> [OPTIONS]
python -m src.ifs_cloud_mcp_server.main --version <version> # Default command
```
**Arguments:**
- `--version` (required): Version identifier to serve
**Options:**
- `--name STRING`: Server name (default: ifs-cloud-mcp-server)
- `--transport STRING`: Transport type (default: stdio)
- `--log-level {DEBUG,INFO,WARNING,ERROR}`: Logging level (default: INFO)
**Behavior:**
1. Validates version exists and is analyzed
2. Initializes hybrid search engine (BM25S + FAISS + FlashRank)
3. Loads BGE-M3 model for semantic search
4. Starts MCP server with stdio transport
5. Provides search tools to AI agents
**Startup Output:**
```
π Starting IFS Cloud MCP Server
π Version: 25.1.0
π Directory: C:\...\ifs_cloud_mcp_server\versions\25.1.0
π Initializing Hybrid Search Engine:
π Loading BM25S index... β
(9,750 documents)
π§ Loading FAISS index... β
(9,733 embeddings)
π€ Loading BGE-M3 model... β
(CUDA acceleration)
β‘ Initializing FlashRank... β
π― MCP Tools Available:
β’ search_ifs_codebase (hybrid search)
β’ search_ifs_semantic (BGE-M3 embeddings)
β’ search_ifs_lexical (BM25S exact match)
β
Server ready on stdio transport
```
---
## π **Directory Structure**
### **Data Directory Locations**
- **Windows**: `%APPDATA%\ifs_cloud_mcp_server`
- **macOS**: `~/Library/Application Support/ifs_cloud_mcp_server`
- **Linux**: `~/.local/share/ifs_cloud_mcp_server`
### **Version Directory Layout**
```
{data_dir}/
βββ versions/
β βββ {version}/
β βββ source/ # Extracted IFS files
β β βββ fndbas/ # Foundation components
β β βββ accrul/ # Accounting components
β β βββ order/ # Order management
β β βββ ... # Other IFS modules
β βββ analysis/
β β βββ comprehensive_plsql_analysis.json
β βββ 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
```
---
## π **Supported File Types**
The CLI processes the following IFS Cloud file types:
| Extension | Purpose | Analysis Features |
| ------------- | ------------------------- | ----------------------------------------- |
| `.entity` | Data Entity Definitions | Entity relationships, attributes |
| `.plsql` | PL/SQL Business Logic | API calls, procedures, functions, queries |
| `.views` | Database Views | View definitions, column mappings |
| `.storage` | Storage Definitions | Table mappings, database structure |
| `.fragment` | Full-Stack Components | UI-to-data integration patterns |
| `.projection` | Data Access Layer | Projection queries, actions, CRUD |
| `.client` | User Interface Components | UI patterns, commands, navigation |
**File Filtering**: During import, only files with these extensions are extracted and processed.
---
## π§ **Integration Guidelines for VS Code Extension**
### **Command Execution**
```typescript
// Recommended approach for VS Code extension
const executeCommand = async (
command: string,
args: string[]
): Promise<CommandResult> => {
const fullCommand = [
"python",
"-m",
"src.ifs_cloud_mcp_server.main",
command,
...args,
];
const result = await exec(fullCommand.join(" "), {
cwd: workspaceRoot,
encoding: "utf-8",
});
return {
exitCode: result.code || 0,
stdout: result.stdout,
stderr: result.stderr,
};
};
```
### **Progress Monitoring**
- Monitor stderr for structured logging output
- Parse progress indicators from log messages
- Handle long-running commands (analyze, embed) with progress bars
### **Error Handling**
```typescript
interface CLIError {
exitCode: number;
message: string;
command: string;
suggestions?: string[];
}
const handleCLIError = (command: string, result: CommandResult): CLIError => {
// Parse structured error messages from stderr
// Extract suggestions for next steps
// Map common error patterns to user-friendly messages
};
```
### **Version Management**
```typescript
interface Version {
version: string;
extract_path: string;
analysis_path: string;
bm25s_path: string;
faiss_path: string;
pagerank_path: string;
has_analysis: boolean;
has_bm25s: boolean;
has_faiss: boolean;
has_pagerank: boolean;
has_hybrid_search: boolean;
has_full_analysis: boolean;
is_ready: boolean;
file_count: number;
created: string;
}
const listVersions = async (): Promise<Version[]> => {
const result = await executeCommand("list", ["--json"]);
return JSON.parse(result.stdout); // Note: returns array directly, not .versions
};
```
### **Workflow Automation**
```typescript
// Fast setup workflow - try download first (recommended)
const setupVersionFast = async (zipPath: string): Promise<void> => {
// 1. Import ZIP file
await executeCommand("import", [zipPath]);
// 2. Get version from output
const versions = await listVersions();
const latestVersion = versions[0].version;
// 3. Try to download pre-built indexes first
const downloadResult = await executeCommand("download", [
"--version",
latestVersion,
]);
if (downloadResult.exitCode === 0) {
// Success! Ready to use immediately
console.log("β
Fast setup complete - ready for MCP server");
return;
}
// 4. Fallback to local generation if download fails
console.log("π¦ Download failed, generating indexes locally...");
await executeCommand("analyze", ["--version", latestVersion]);
await executeCommand("calculate-pagerank", ["--version", latestVersion]);
await executeCommand("reindex-bm25s", ["--version", latestVersion]);
// Optional: await executeCommand('embed', ['--version', latestVersion]);
};
// Complete setup workflow for new version (local generation)
const setupVersion = async (zipPath: string): Promise<void> => {
// 1. Import
await executeCommand("import", [zipPath]);
// 2. Get version from output
const versions = await listVersions();
const latestVersion = versions[0].version;
// 3. Analyze (with progress monitoring)
await executeCommand("analyze", ["--version", latestVersion]);
// 4. Calculate PageRank
await executeCommand("calculate-pagerank", ["--version", latestVersion]);
// 5. Build BM25S index
await executeCommand("reindex-bm25s", ["--version", latestVersion]);
// 6. Optional: Create embeddings (resource intensive)
// await executeCommand('embed', ['--version', latestVersion]);
};
```
---
## π **MCP Server Integration**
### **Server Lifecycle**
1. **Validation**: Ensure version exists and is analyzed
2. **Initialization**: Load search indexes and models
3. **Runtime**: Provide search tools via MCP protocol
4. **Cleanup**: Graceful shutdown and resource cleanup
### **Search Tools Available**
- `search_ifs_codebase`: Hybrid search with semantic + lexical
- `search_ifs_semantic`: Pure semantic search with BGE-M3
- `search_ifs_lexical`: Pure lexical search with BM25S
### **Performance Characteristics**
- **Cold Start**: 10-30 seconds (model loading)
- **Search Response**: <100ms with GPU, <500ms without
- **Memory Usage**: ~2GB for full indexes + models
- **CUDA Support**: Automatic detection and acceleration
---
## π **CLI Return Codes & Error Handling**
### **Exit Codes**
- `0`: Success
- `1`: General error (file not found, validation failed, etc.)
### **Common Error Patterns**
```
β Import failed: <specific error>
β Version error: <validation issue>
β Analysis failed: <processing error>
β Server error: <runtime issue>
```
### **Structured Logging**
- All logging goes to stderr
- Structured format for programmatic parsing
- Progress indicators in standardized format
- Error messages include actionable suggestions
---
This specification provides complete technical details for implementing a VS Code extension that integrates with the IFS Cloud MCP Server CLI. The CLI is designed for programmatic use with comprehensive error handling, structured output, and clear integration patterns.
