MCP OCI Logan Server
by adibirzu
README.md
# MCP OCI Logan Server
## ⚠️ Disclaimer
This software was created to showcase Oracle Cloud Infrastructure (OCI) Logging Analytics capabilities and demonstrate how to expand them using third-party services and AI tools. The architecture and code were written by me with the assistance of Oracle Code Assist and multiple LLMs including Claude, OpenAI GPT-4o, Meta Llama 3.2, and Grok 3. This is an educational project designed to learn more about OCI's service capabilities and how to optimize security monitoring tasks through AI integration.
**This is NOT an official Oracle product** - it is a personal project demonstrating integration possibilities with OCI Logging Analytics and AI assistants.
---
## Standards
- `docs/OCI_MCP_SERVER_STANDARD.md`
## Runbooks
- `docs/runbooks/README.md`
## Transport & Auth
- **Local development**: STDIO only
- **Production/remote**: Streamable HTTP with OAuth enabled
## 🚀 v2.0.0 Update - HTTP Transport with OAuth Authentication
**NEW IN v2.0.0**: Full HTTP transport support with OAuth 2.0 authentication for production deployments!
**Key Features**:
- **HTTP Transport**: Run as a web service with SSE (Server-Sent Events) support
- **OAuth 2.0**: Token introspection, scope validation, audience verification
- **IDCS Ready**: Configured for OCI Identity Cloud Service integration (port 8001)
- **Dual Transport**: Supports both stdio (Claude Desktop) and HTTP (web services)
See [HTTP Transport & OAuth](#http-transport--oauth-authentication) for setup details.
---
A Model Context Protocol (MCP) server that connects Claude to Oracle Cloud Infrastructure (OCI) Logging Analytics, enabling natural language querying and analysis of security logs from the Logan Security Dashboard.
## Current Contract
This repository now has a canonical production path:
- Canonical server: `src/mcp_logan/server.py`
- Canonical data policy: real OCI Log Analytics data only
- Canonical detection content source: `DETECTION_RULES_PATH` pointing at `oci-log-analytics-detections/queries`
Important:
- The canonical FastMCP server does **not** return mock, sample, or generated Logan data.
- Logan tools are expected to use OCI Log Analytics APIs, not OCI Logging Search fallbacks.
- Historical sections in this README may reference older Python/TypeScript implementations; when they conflict with source, `src/mcp_logan/` is authoritative.
- Current canonical surface: 44 tools across query, management, analytics, dashboard, detections, and utility categories.
## Features
### 🔍 Core Query Execution (Fully Implemented)
- **Execute Logan Queries**: Direct execution against OCI Logging Analytics APIs
- **Detection-first workflows**: Search the detection catalog and execute detections by ID
- **MITRE ATT&CK Integration**: Search for specific MITRE techniques and tactics with 90-day default range
- **IP Activity Analysis**: Comprehensive analysis with multiple analysis types (authentication, network, threat_intel)
- **Time Correlation**: Precise UTC timezone handling for accurate cross-log correlation
- **Query Syntax Fixing**: Automatic OCI compatibility fixes for common syntax issues
- **Real-time Data**: Direct OCI API integration with NO mock data policy
### 🛡️ Security Analysis (Fully Implemented)
- **Security Event Search**: Advanced pattern matching for authentication failures, privilege escalations
- **Threat Intelligence**: Statistical analysis and anomaly detection
- **Advanced Analytics**: Clustering, NLP processing, outlier detection, correlation analysis
- **Field Operations**: Dynamic field extraction, pattern searching, data transformation
- **Statistical Analysis**: Comprehensive statistical operations on log data
- **Cross-Log Correlation**: Synchronized time periods across different log sources
### 📊 Dashboard And Saved Search Operations
- **List Dashboards**: Real OCI-backed listing
- **Dashboard Details**: Retrieve dashboard metadata and tiles
- **Create/Update Dashboards**: OCI-backed dashboard operations via the canonical server path
- **Export/Import**: JSON-based dashboard portability
- **Saved Searches**: Real OCI-backed list and execute operations in the canonical FastMCP implementation
- **Log Groups**: Real OCI-backed log-group discovery exposed from the canonical server
### 🎯 Detection Catalog
- **Run Detection Rules**: Execute catalog-backed detections against live OCI data
- **Run Hunting Queries**: Execute advanced hunting queries from the external content catalog
- **Detection Search**: Search by platform, severity, MITRE, STIG, or keyword
- **Detection Testing**: Validate and execute rules while checking field/log source issues
- **Detection Resources**: `detection://` resources expose rules, hunting queries, MITRE coverage, and STIG mapping
### 🔧 Developer Tools
- **Query Validation**: Syntax validation with automatic error fixing
- **Documentation Lookup**: Built-in help system for OCI query syntax
- **Connection Testing**: Verify OCI authentication and connectivity
- **Error Handling**: Comprehensive error reporting and troubleshooting
- **Debug Logging**: Extensive debugging capabilities for troubleshooting
### 🏢 Enterprise Features
- **Multi-tenant Support**: Query across multiple OCI environments
- **Authentication Methods**: Support for config files, instance principals, and resource principals
- **Performance Optimization**: Intelligent query optimization and syntax fixing
- **Compartment Management**: Support for multiple compartments with proper access control
## Prerequisites
1. **OCI Account**: Access to Oracle Cloud Infrastructure
2. **OCI CLI**: Configured with appropriate credentials
3. **Logan Security Dashboard**: Working installation (optional, for predefined queries)
4. **Claude Desktop**: For MCP integration
## Installation
### Quick Install (Recommended) 🚀
For a complete automated installation with all checks and configuration:
```bash
git clone https://github.com/adibirzu/mcp-oci-logan-server.git
cd mcp-oci-logan-server
./install.sh
```
The installer will:
- ✅ Check prerequisites (Node.js 18+, Python 3.8+, OCI CLI)
- ✅ Install Node.js dependencies
- ✅ Setup Python virtual environment
- ✅ Build TypeScript code
- ✅ Test the installation
- ✅ Optionally configure Claude Desktop
- ✅ Verify the canonical tool surface is available
**That's it!** The script handles everything automatically.
### Manual Installation
If you prefer to install manually or already have some components installed:
#### 1. Clone and Install Node Dependencies
```bash
git clone https://github.com/adibirzu/mcp-oci-logan-server.git
cd mcp-oci-logan-server
npm install
```
#### 2. Setup Python Environment
```bash
./setup-python.sh
```
#### 3. Build TypeScript
```bash
npm run build
```
#### 4. OCI Configuration
**Option A: OCI CLI Configuration (Recommended)**
```bash
oci setup config
```
**Option B: Environment Variables**
```bash
export OCI_USER_ID="[Link to Secure Variable: OCI_USER_ID]"
export OCI_FINGERPRINT="[Link to Secure Variable: OCI_FINGERPRINT]"
export OCI_TENANCY_ID="[Link to Secure Variable: OCI_TENANCY_ID]"
export OCI_REGION="us-ashburn-1"
export OCI_KEY_FILE="/path/to/private/key.pem"
export OCI_COMPARTMENT_ID="[Link to Secure Variable: OCI_COMPARTMENT_ID]"
```
**Option C: Instance Principal (for OCI Compute)**
No configuration needed - automatically detected when running on OCI.
#### 5. Claude Desktop Configuration
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"oci-logan": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/mcp-oci-logan-server/dist/index.js"],
"env": {
"OCI_COMPARTMENT_ID": "[Link to Secure Variable: OCI_COMPARTMENT_ID]",
"OCI_REGION": "us-ashburn-1",
"SUPPRESS_LABEL_WARNING": "True",
"LOGAN_DEBUG": "false"
}
}
}
}
```
**Important**: Use absolute paths for the `args` field.
#### 6. Test Installation
```bash
# Test Python client
python python/logan_client.py --help
# Quick rebuild and start
./quick-start.sh
# Test specific features (optional)
node test-server.js
```
### Optional: Python FastMCP server (stdio-safe)
If you prefer a pure Python MCP server using FastMCP (no Node runtime) and you have Python 3.10+:
```bash
# From repo root
./setup-python.sh # sets up python/venv and installs requirements (includes mcp[cli])
source python/venv/bin/activate
python python/fastmcp_server.py
```
Claude Desktop config example:
```json
{
"mcpServers": {
"oci-logan-fastmcp": {
"command": "python",
"args": ["/ABSOLUTE/PATH/TO/mcp-oci-logan-server/python/fastmcp_server.py"],
"env": {
"LOGAN_COMPARTMENT_ID": "[Link to Secure Variable: LOGAN_COMPARTMENT_ID]",
"LOGAN_REGION": "us-ashburn-1",
"LOGAN_DEBUG": "false"
}
}
}
}
```
Notes:
- Uses stdio-safe logging (stderr/file only) and snake_case tool names.
- Blocking OCI calls are offloaded to threads for responsiveness.
- Set OCI config via `~/.oci/config` or environment variables as in the Node flow.
### Quick Start for Updates
If you already have everything installed and just need to rebuild:
```bash
./quick-start.sh
```
This script:
- Updates dependencies
- Rebuilds TypeScript
- Shows next steps
## HTTP Transport & OAuth Authentication
### Overview
The OCI Logan MCP Server supports two transport modes:
| Transport | Use Case | Port | Authentication |
|-----------|----------|------|----------------|
| **stdio** | Claude Desktop, local development | N/A | None (process-level) |
| **HTTP** | Web services, API access, production | 8001 (default) | OAuth 2.0 |
### Running with HTTP Transport
#### Python FastMCP Server (Recommended for Production)
```bash
# Without OAuth (development)
cd python
source venv/bin/activate
MCP_TRANSPORT=http MCP_HTTP_PORT=8001 python main.py
# With OAuth (production)
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8001 \
MCP_OAUTH_ENABLED=true \
MCP_OAUTH_ISSUER_URL=[Link to Secure Variable: MCP_OAUTH_ISSUER_URL] \
MCP_OAUTH_INTROSPECTION_URL=[Link to Secure Variable: MCP_OAUTH_INTROSPECTION_URL] \
MCP_OAUTH_CLIENT_ID=[Link to Secure Variable: MCP_OAUTH_CLIENT_ID] \
MCP_OAUTH_CLIENT_SECRET=[Link to Secure Variable: MCP_OAUTH_CLIENT_SECRET] \
MCP_OAUTH_REQUIRED_SCOPES=mcp:tools \
python main.py
```
#### TypeScript Server
```bash
# Build first
npm run build
# Without OAuth
MCP_TRANSPORT=http MCP_HTTP_PORT=8000 node dist/index.js
# With OAuth
MCP_TRANSPORT=http \
MCP_HTTP_PORT=8000 \
MCP_OAUTH_ENABLED=true \
MCP_OAUTH_ISSUER_URL=[Link to Secure Variable: MCP_OAUTH_ISSUER_URL] \
MCP_OAUTH_INTROSPECTION_URL=[Link to Secure Variable: MCP_OAUTH_INTROSPECTION_URL] \
MCP_OAUTH_CLIENT_ID=[Link to Secure Variable: MCP_OAUTH_CLIENT_ID] \
MCP_OAUTH_CLIENT_SECRET=[Link to Secure Variable: MCP_OAUTH_CLIENT_SECRET] \
node dist/index.js
```
### HTTP Endpoints
| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| `/health` | GET | No | Health check |
| `/.well-known/oauth-protected-resource` | GET | No | OAuth resource metadata |
| `/sse` | GET | Yes* | SSE connection for MCP |
| `/messages/` | POST | Yes* | MCP message endpoint |
*Authentication required only when `MCP_OAUTH_ENABLED=true`
### OAuth Configuration
For OCI IDCS (Identity Cloud Service):
1. **Create an Application** in IDCS:
- Application Type: Confidential
- Grant Types: Client Credentials
- Callback URL: `http://localhost:8001` (or your server URL)
2. **Configure Scopes**:
- Add custom scope: `mcp:tools`
3. **Set Environment Variables**:
```bash
export MCP_OAUTH_ENABLED=true
export MCP_OAUTH_ISSUER_URL=[Link to Secure Variable: MCP_OAUTH_ISSUER_URL]
export MCP_OAUTH_INTROSPECTION_URL=[Link to Secure Variable: MCP_OAUTH_INTROSPECTION_URL]
export MCP_OAUTH_CLIENT_ID=[Link to Secure Variable: MCP_OAUTH_CLIENT_ID]
export MCP_OAUTH_CLIENT_SECRET=[Link to Secure Variable: MCP_OAUTH_CLIENT_SECRET]
export MCP_OAUTH_REQUIRED_SCOPES=mcp:tools
export MCP_OAUTH_AUDIENCE=[Link to Secure Variable: MCP_OAUTH_AUDIENCE] # optional
```
### Testing HTTP Transport
```bash
# Health check (no auth required)
curl http://localhost:8001/health
# OAuth metadata
curl http://localhost:8001/.well-known/oauth-protected-resource
# With OAuth token
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8001/sse
```
### Environment Variables Reference
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_TRANSPORT` | Transport type: `stdio`, `http`, `sse`, or `streamable-http` | `stdio` |
| `MCP_HOST` | Bind host for network transports | `0.0.0.0` |
| `MCP_PORT` | Port for network transports | `8001` |
| `MCP_HTTP_HOST` | Legacy HTTP bind address (fallback) | `0.0.0.0` |
| `MCP_HTTP_PORT` | Legacy HTTP port (fallback) | `8001` |
| `MCP_HTTP_CORS` | Enable CORS | `true` |
| `MCP_HTTP_CORS_ORIGINS` | Allowed origins (comma-separated) | `*` |
| `MCP_OAUTH_ENABLED` | Enable OAuth authentication | `false` |
| `MCP_OAUTH_ISSUER_URL` | OAuth issuer URL | - |
| `MCP_OAUTH_INTROSPECTION_URL` | Token introspection endpoint | - |
| `MCP_OAUTH_CLIENT_ID` | OAuth client ID | - |
| `MCP_OAUTH_CLIENT_SECRET` | OAuth client secret | - |
| `MCP_OAUTH_REQUIRED_SCOPES` | Required scopes (comma-separated) | `mcp:tools` |
| `MCP_OAUTH_AUDIENCE` | Expected token audience | - |
| `MCP_OAUTH_TOKEN_CACHE_TTL` | Token cache TTL in seconds | `300` |
| `MCP_SESSION_TIMEOUT` | Session timeout in ms | `3600000` |
| `MCP_MAX_SESSIONS` | Maximum concurrent sessions | `100` |
| `OTEL_TRACING_ENABLED` | Enable tracing | `true` |
| `OCI_APM_ENDPOINT` | OCI APM OTLP endpoint | - |
| `OCI_APM_PRIVATE_DATA_KEY` | OCI APM private data key | - |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Generic OTLP endpoint | - |
| `OTEL_DISABLE_LOCAL` | Disable local collector fallback | `false` |
---
## Usage Examples
### Basic Query Execution
```
Execute this Logan query with your compartment ID:
'Event Name' = 'UserLoginFailed' and Time > dateRelative(24h) | stats count by 'User Name'
```
### Natural Language Security Search
```
Search for failed login attempts in the last 24 hours
```
### MITRE ATT&CK Analysis
```
Find all credential access techniques in the last 30 days (default for Sysmon data)
```
### IP Investigation
```
Analyze all activity for IP address 192.168.1.100 in the last 24 hours
```
### Dashboard Management
```
List all active dashboards in your compartment
Get dashboard details for [Link to Secure Variable: LOGAN_DASHBOARD_OCID]
Export dashboard [Link to Secure Variable: LOGAN_DASHBOARD_OCID] as JSON
```
### Saved Search Management
```
Create a saved search named "Failed Logins" with query: 'Event Name' = 'UserLoginFailed' | stats count by 'User Name'
List all saved searches in my compartment
```
### Documentation Lookup
```
Show me the documentation for OCI query syntax
Get help with MITRE technique mapping
```
## Available Tools (33 Total Implemented)
### Core Query Tools (Fully Functional)
#### `execute_logan_query`
Direct execution of OCI Logging Analytics queries via Python backend with comprehensive validation, syntax fixing, and error handling. Supports real-time data retrieval with NO mock data.
**Parameters:**
- `query` (required): OCI Logging Analytics query
- `queryName` (optional): Name/identifier for the query
- `timeRange` (optional): Time range (1h, 6h, 12h, 24h, 1d, 7d, 30d, 1w, 1m) - Default: 24h
- `compartmentId` (optional): OCI compartment ID (required for execution)
- `environment` (optional): Multi-tenant environment name
#### `search_security_events`
AI-powered natural language to OCI query conversion for security event searching with advanced pattern matching.
**Parameters:**
- `searchTerm` (required): Natural language description
- `eventType` (optional): Event type filter (login, privilege_escalation, network_anomaly, data_exfiltration, malware, all)
- `timeRange` (optional): Time range - Default: 24h
- `limit` (optional): Maximum results - Default: 100
#### `get_mitre_techniques`
Comprehensive MITRE ATT&CK technique analysis with 90-day default range optimized for security data.
**Parameters:**
- `techniqueId` (optional): Specific technique ID (e.g., T1003, T1110) or "all"
- `category` (optional): MITRE tactic category (initial_access, execution, persistence, etc.)
- `timeRange` (optional): Time range - Default: 30d (recommended for Sysmon data)
#### `analyze_ip_activity`
Advanced IP address behavioral analysis with multiple analysis types: full, authentication, network, threat_intel, communication_patterns.
**Parameters:**
- `ipAddress` (required): IP address to analyze
- `analysisType` (optional): Type of analysis (full, authentication, network, threat_intel, communication_patterns) - Default: full
- `timeRange` (optional): Time range - Default: 24h
### Advanced Analytics Tools (Fully Implemented)
#### `perform_statistical_analysis`
Advanced statistical operations on query results including clustering, outlier detection, and trend analysis.
#### `perform_advanced_analytics`
ML-powered analytics including clustering algorithms, NLP processing, and anomaly detection.
#### `search_field_patterns`
Dynamic field pattern searching and extraction from log data.
#### `correlate_events`
Cross-log event correlation with time synchronization and pattern matching.
#### `perform_field_operations`
Field extraction, transformation, and manipulation operations.
### Dashboard Management Tools
#### `list_dashboards`
Lists OCI-backed dashboards from the canonical FastMCP implementation.
**Parameters:**
- `compartmentId` (optional): OCI compartment OCID
- `displayName` (optional): Filter dashboards by display name
- `lifecycleState` (optional): Filter by lifecycle state - Default: ACTIVE
- `limit` (optional): Maximum number of dashboards to return - Default: 50
**Note:** Results depend on OCI permissions and available dashboard content in the target compartment.
#### `get_dashboard`
Retrieve detailed dashboard metadata from OCI.
**Parameters:**
- `dashboardId` (required): OCID of the dashboard to retrieve
- `compartmentId` (optional): OCI compartment OCID (for validation)
#### `get_dashboard_tiles`
Get tiles/widgets from a specific OCI dashboard.
**Parameters:**
- `dashboardId` (required): OCID of the dashboard
- `tileType` (optional): Filter tiles by type (all, query, visualization, metric, text)
#### `create_dashboard`
Create a dashboard using the canonical FastMCP implementation.
**Parameters:**
- `displayName` (required): Display name for the dashboard
- `description` (optional): Description of the dashboard
- `compartmentId` (optional): OCI compartment OCID
- `dashboardConfig` (optional): Dashboard configuration
**Note:** Successful execution depends on OCI permissions and the target dashboard service configuration.
#### `update_dashboard`
Update an existing OCI dashboard.
**Parameters:**
- `dashboardId` (required): OCID of the dashboard to update
- `displayName` (optional): New display name
- `description` (optional): New description
- `addWidgets` (optional): Array of widgets to add
- `removeWidgetIds` (optional): Array of widget IDs to remove
#### `export_dashboard`
Export dashboard configuration as JSON.
**Parameters:**
- `dashboardId` (required): OCID of the dashboard to export
- `includeQueries` (optional): Include full query definitions - Default: true
#### `import_dashboard`
Import dashboard from JSON configuration.
**Parameters:**
- `dashboardJson` (required): JSON string containing dashboard configuration
- `compartmentId` (optional): Target compartment OCID (uses default if not provided)
- `newDisplayName` (optional): Override display name
### Saved Search Tools
#### `create_saved_search`
Create a real OCI-backed saved search.
**Parameters:**
- `displayName` (required): Display name for the saved search
- `query` (required): Logan query to save
- `description` (optional): Description of the saved search
- `compartmentId` (optional): OCI compartment OCID
- `widgetType` (optional): Preferred visualization type - Default: SEARCH
#### `list_saved_searches`
List real OCI-backed saved searches.
**Parameters:**
- `compartmentId` (optional): OCI compartment OCID
- `displayName` (optional): Filter by display name
- `limit` (optional): Maximum number of results - Default: 50
### Utility Tools
#### `get_logan_queries`
Get predefined Logan Security Dashboard queries.
**Parameters:**
- `category` (optional): Query category (mitre-attack, security, network, authentication, privilege-escalation, all)
- `queryName` (optional): Specific query name
#### `validate_query`
Validate OCI query syntax with auto-fix suggestions.
**Parameters:**
- `query` (required): Query to validate
- `fix` (optional): Attempt automatic fixes - Default: false
#### `get_documentation`
Get documentation and help for OCI queries.
**Parameters:**
- `topic` (optional): Documentation topic (query_syntax, field_names, functions, time_filters, operators, mitre_mapping, examples, troubleshooting)
- `searchTerm` (optional): Specific term to search for in documentation
#### `check_oci_connection`
Test OCI connection and authentication.
**Parameters:**
- `testQuery` (optional): Run test query - Default: true
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `OCI_COMPARTMENT_ID` | Default compartment ID | Required |
| `OCI_REGION` | OCI region | us-ashburn-1 |
| `OCI_NAMESPACE` | Object storage namespace | Auto-detected |
| `OCI_USER_ID` | User OCID | From config file |
| `OCI_TENANCY_ID` | Tenancy OCID | From config file |
| `OCI_FINGERPRINT` | Key fingerprint | From config file |
| `OCI_KEY_FILE` | Private key file path | From config file |
### Multi-tenant Configuration
For multiple OCI environments, create a configuration file:
```json
{
"environments": {
"production": {
"compartmentId": "[Link to Secure Variable: OCI_COMPARTMENT_ID]",
"region": "us-ashburn-1"
},
"development": {
"compartmentId": "[Link to Secure Variable: OCI_COMPARTMENT_ID]",
"region": "us-phoenix-1"
}
}
}
```
## Query Syntax Guide
### Field Names
Always quote field names with spaces:
```
'Event Name' = 'UserLogin'
'User Name' contains 'admin'
'IP Address' = '192.168.1.100'
```
### Time Filters
Use capitalized 'Time' field:
```
Time > dateRelative(24h) # Last 24 hours
Time > dateRelative(7d) # Last 7 days
```
### Common Patterns
```sql
-- Failed logins
'Event Name' = 'UserLoginFailed' and Time > dateRelative(24h) | stats count by 'User Name'
-- Network connections
'Log Source' = 'VCN Flow Logs' and Time > dateRelative(1h) | stats count by 'Source IP'
-- MITRE techniques
'Technique_id' is not null and Time > dateRelative(7d) | stats count by 'Technique_id'
```
## Troubleshooting
### Common Issues
**"Missing input" Error**
- Check field name capitalization: use 'Time' not 'time'
- Quote field names with spaces
- Verify operator syntax
**Authentication Errors**
- Verify OCI CLI configuration: `oci iam user get --user-id <user-ocid>`
- Check compartment permissions
- Validate key file permissions
**No Results**
- Verify time range is appropriate
- Check compartment has log data
- Ensure log sources are configured
### Performance Tips
1. Always include time filters
2. Use specific field filters early in queries
3. Limit result sets with `| head 100`
4. Use indexed fields for filtering
## Development
### Building from Source
```bash
npm run build # Compile TypeScript
npm run dev # Development mode
npm run test # Run tests
```
### Implementation Status & Limitations
#### ✅ **Fully Implemented Features:**
- Core query execution with real OCI API integration
- 40 MCP tools across query, management, analytics, dashboard, detection, and utility categories
- Canonical FastMCP server in `src/mcp_logan/`
- Advanced analytics (clustering, NLP, statistical analysis)
- Query syntax validation and automatic fixing
- MITRE ATT&CK technique mapping
- IP address behavioral analysis
- Time correlation with UTC timezone handling
- NO mock data policy - all data is real from OCI
- Detection catalog-backed execution and hunting queries
- Health reporting for canonical detection content path
#### ⚠️ **Operational Caveats:**
- Dashboard and saved-search operations depend on OCI permissions and service availability
- The external detection catalog path must exist for detection/hunting features to be available
- Historical legacy implementations remain in the repo and may not match the canonical server contract
#### 🔧 **Known Technical Issues:**
- Legacy docs in `docs/` and `wiki/` still contain older tool counts and older implementation history
- Some legacy compatibility paths in `python/` and `src/` remain and should not be treated as canonical
### Git Repository Setup
The repository is configured to exclude unnecessary files from version control:
**Ignored Files:**
- `python/venv/` - Python virtual environment (created by setup-python.sh)
- `dist/` (optional) - TypeScript compiled output
- `claude_desktop_config.json` - Local Claude Desktop configuration
- Debug logs (`*.log`, `/tmp/mcp-*.log`)
- Credentials (`*.pem`, `*.key`, `config`)
- Test files (`test-*.js`, `test-*.ts`)
**Setup for New Developers:**
1. Copy `claude_desktop_config.json.template` to `claude_desktop_config.json`
2. Update paths and OCI compartment ID in the config
3. Run `./setup-python.sh` to create Python virtual environment
4. The `python/venv/` directory will be automatically ignored
### Actual Architecture & Data Flow
```
┌─────────────────────────────────────────┐
│ Client Applications │
│ Claude Desktop / Web Apps / APIs │
└─────────────────┬───────────────────────┘
│
┌──────────────────────────────┴──────────────────────────────┐
│ │
┌───────▼───────┐ ┌─────────────▼─────────────┐
│ stdio Transport│ │ HTTP Transport (SSE) │
│ (Claude Desktop)│ │ Port 8001 (Python) │
│ │ │ Port 8000 (TypeScript) │
└───────┬───────┘ └─────────────┬─────────────┘
│ │
│ ┌───────────▼───────────┐
│ │ OAuth 2.0 Middleware │
│ │ Token Introspection │
│ │ (IDCS / Custom IDP) │
│ └───────────┬───────────┘
│ │
└───────────────────────┬──────────────────────────────────────┘
│
┌───────────────────────▼───────────────────────┐
│ MCP Server Layer │
│ ┌─────────────────────────────────────────┐ │
│ │ Python FastMCP (main.py) │ │
│ │ 25+ Tools: Log Analysis, Security, │ │
│ │ Alert Correlation, Compliance │ │
│ └─────────────────────────────────────────┘ │
│ OR │
│ ┌─────────────────────────────────────────┐ │
│ │ TypeScript Server (src/index.ts) │ │
│ │ 33 MCP Tools + Python Backend │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────┬───────────────────────┘
│
┌───────────────────────▼───────────────────────┐
│ Skills & Business Logic │
│ ┌────────────┐ ┌───────────┐ ┌────────────┐ │
│ │LogAnalysis │ │ Security │ │ Alert │ │
│ │ Skill │ │ Audit │ │Correlation │ │
│ └────────────┘ └───────────┘ └────────────┘ │
└───────────────────────┬───────────────────────┘
│
┌───────────────────────▼───────────────────────┐
│ OCI SDK (Python) - Direct API │
└───────────────────────┬───────────────────────┘
│
┌───────────────────────▼───────────────────────┐
│ OCI Log Analytics API (Real Data) │
│ NO Mock Data Policy │
└───────────────────────────────────────────────┘
```
### Project Structure (Actual Implementation)
```
src/
├── index.ts # Main MCP server entry point (stdio/http transport selection)
├── auth/
│ └── oauth.ts # OAuth 2.0 authentication (NEW in v2.0.0)
├── transport/
│ └── http.ts # HTTP transport with session management (NEW in v2.0.0)
├── oci/
│ └── LogAnalyticsClient.ts # OCI integration with Python backend spawning
└── utils/
├── QueryValidator.ts # Query validation and syntax fixing
├── QueryTransformer.ts # Query transformation and MITRE mapping
├── DocumentationLookup.ts # Built-in help system
└── logger.ts # Logging utility
python/
├── venv/ # Python virtual environment (created by setup-python.sh)
├── main.py # FastMCP server with HTTP/OAuth support (v2.0.0)
├── fastmcp_server.py # Minimal FastMCP server (stdio only)
├── logan_client.py # Primary OCI Log Analytics client (fully functional)
├── dashboard_client.py # Dashboard operations (partial implementation)
├── security_analyzer.py # Security event analysis (fully functional)
├── query_mapper.py # Query mapping utilities
├── query_validator.py # Python-side query validation
├── skills/ # Skill modules for main.py
│ ├── log_analysis.py # Log analysis skill
│ ├── security_audit.py # Security audit skill
│ └── alert_correlation.py # Alert correlation skill
└── requirements.txt # Python dependencies (oci-sdk, uvicorn, starlette)
config files:
├── .env.template # Environment configuration template (updated for OAuth)
├── claude_desktop_config.json.template # Claude Desktop MCP configuration
├── setup-python.sh # Python environment setup script
└── .gitignore # Excludes venv/, test files, credentials
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Documentation
Complete documentation is available in the [`docs/`](docs/) folder:
- **[Installation Guide](docs/INSTALLATION.md)** - Complete installation instructions
- **[User Guide](docs/USER_GUIDE.md)** - How to use the MCP server effectively
- **[Release Notes](docs/RELEASE_NOTES_v1.3.0.md)** - v1.3.0 changelog
- **[Critical Fix](docs/CRITICAL_FIX_README.md)** - Important v1.3.0 fix details
- **[Improvements](docs/IMPROVEMENTS.md)** - Detailed changes
- **[Technical Docs](docs/technical/)** - API coverage, security audits, etc.
See [`docs/README.md`](docs/README.md) for a complete documentation index.
## Support
- **Documentation**: See [`docs/`](docs/) folder
- **Built-in Help**: Ask Claude to use the MCP tools
- **Issues**: GitHub issues
- **Security**: Report security issues privately
---
## Recent Updates
### v2.0.0 - HTTP Transport with OAuth Authentication (December 2025)
**MAJOR RELEASE**: Full HTTP transport support with OAuth 2.0 authentication for production deployments!
**New Features**:
- **HTTP Transport**: Run as a web service with SSE (Server-Sent Events) support
- Python FastMCP server on port 8001 (recommended for production)
- TypeScript server on port 8000 (alternative)
- **OAuth 2.0 Authentication**:
- Token introspection with configurable endpoint
- Scope validation (default: `mcp:tools`)
- Audience verification
- Token caching with configurable TTL
- **IDCS Ready**: Configured for OCI Identity Cloud Service integration
- **Dual Transport**: Supports both stdio (Claude Desktop) and HTTP (web services)
- **New Endpoints**:
- `/health` - Health check (no auth required)
- `/.well-known/oauth-protected-resource` - OAuth metadata
- `/sse` - SSE connection for MCP protocol
- `/messages/` - MCP message endpoint
**New Files**:
- `src/auth/oauth.ts` - OAuth 2.0 authentication module (TypeScript)
- `src/transport/http.ts` - HTTP transport with session management (TypeScript)
- `python/main.py` - Updated with HTTP transport & OAuth support
**Environment Variables Added**:
- `MCP_TRANSPORT` - Transport type: `stdio`, `http`, `sse`, or `streamable-http`
- `MCP_HOST`, `MCP_PORT` - Network transport bind configuration
- `MCP_HTTP_HOST`, `MCP_HTTP_PORT` - Legacy HTTP bind configuration (fallback)
- `MCP_OAUTH_ENABLED`, `MCP_OAUTH_*` - OAuth configuration
- `OTEL_TRACING_ENABLED`, `OCI_APM_ENDPOINT`, `OCI_APM_PRIVATE_DATA_KEY` - Optional OCI APM tracing
- See [HTTP Transport & OAuth](#http-transport--oauth-authentication) for full reference
### v1.3.0 - Critical Fix & Complete Documentation (October 2025)
**CRITICAL FIX**: `list_active_log_sources` now returns complete results!
- **CRITICAL BUG FIX**: Fixed `list_active_log_sources` returning incomplete results
- **Fixed Hardcoded Path**: Removed hardcoded path in QueryTransformer.ts
- **Tool Inventory Corrected**: historical inventory update for that release line
### v1.2.0 - Architecture Analysis & Documentation Update (August 2025)
- Code analysis revealing actual vs documented features
- Dashboard status clarified with partial/mock implementations
- Architecture documented with real data flow details
### Current Canonical Implementation Status
| Feature | Status |
|---------|--------|
| Query Execution | ✅ Fully functional with real OCI API |
| HTTP Transport | ✅ **NEW in v2.0.0** |
| OAuth Authentication | ✅ **NEW in v2.0.0** |
| Security Analytics | ✅ Complete implementation |
| Resource Discovery | ✅ Fixed in v1.3.0 |
| Dashboard Management | ✅ Canonical FastMCP path is OCI-backed |
| Saved Search Management | ✅ Canonical FastMCP path is OCI-backed |
| Detection Catalog | ✅ External canonical catalog-backed |
| Python Backend | ✅ Robust OCI SDK integration remains available |
| Time Correlation | ✅ Accurate UTC timezone handling |
### Next Development Priorities
1. ✅ ~~HTTP Transport Support~~ **COMPLETED in v2.0.0**
2. ✅ ~~OAuth Authentication~~ **COMPLETED in v2.0.0**
3. Reconcile legacy docs with the canonical FastMCP implementation
4. Strengthen downstream consumer contracts for coordinator/observatory integrations
5. Add comprehensive contract tests around canonical detection content loading
6. Continue reducing legacy implementation drift in `python/` and older `src/` paths
**Version**: 2.0.0
**Last Updated**: December 2025
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues