Oci Logan Server

MCP OCI Logan服务器

⚠️ 免责声明

该软件旨在展示Oracle云基础设施（OCI）日志分析功能，并演示如何使用第三方服务和人工智能工具进行扩展。架构和代码是由我在Oracle code Assist和多个LLM（包括Claude、OpenAI GPT-4o、Meta Llama 3.2和Grok 3）的帮助下编写的。这是一个教育项目，旨在深入了解OCI的服务能力，以及如何通过人工智能集成优化安全监控任务。

这不是Oracle官方产品 -这是一个个人项目，展示了与OCI日志分析和人工智能助手的集成可能性。

______________________________________________________________________

标准

• docs/OCI_MCP_SERVER_STANDARD.md

Runbook

• docs/runbooks/README.md

传输与认证

• 本地开发：仅限STDIO
• 生产/远程：启用OAuth的流式HTTP

🚀 v2.0.0更新-使用OAuth身份验证的HTTP传输

v2.0.0中的新功能：为生产部署提供OAuth 2.0身份验证的完整HTTP传输支持！

主要特点:

• HTTP传输：作为支持SSE（服务器发送事件）的web服务运行
• OAuth 2.0：令牌自省、范围验证、受众验证
• IDCS就绪：已配置OCI身份云服务集成（端口8001）
• 双重运输：支持stdio（克劳德桌面）和HTTP（web服务）

看 HTTP传输和OAuth 有关设置的详细信息。

______________________________________________________________________

一个模型上下文协议（MCP）服务器，将Claude连接到Oracle云基础设施（OCI）日志分析，支持从Logan安全仪表板对安全日志进行自然语言查询和分析。

当前合同

此存储库现在有一个规范的生产路径：

• 规范服务器： src/mcp_logan/server.py
• 规范数据政策：仅限真实OCI日志分析数据
• 规范检测内容来源： DETECTION_RULES_PATH 指着 oci-log-analytics-detections/queries

重要提示：

• 规范的FastMCP服务器可以 不 返回模拟、采样或生成的Logan数据。
• Logan工具预计将使用OCI日志分析API，而不是OCI日志搜索回退。
• 本README中的历史部分可能会引用旧的Python/TypeScript实现；当它们与来源冲突时， src/mcp_logan/ 是权威的。
• 当前的规范界面：44个工具，涵盖查询、管理、分析、仪表板、检测和实用程序类别。

特性

🔍 核心查询执行（完全实现）

• 执行Logan查询：直接执行OCI日志分析API
• 检测优先工作流：搜索检测目录并按ID执行检测
• MITRE ATT&CK 集成：搜索具有90天默认范围的特定MITRE技术和战术
• IP活动分析：具有多种分析类型（身份验证、网络、威胁_电话）的综合分析
• 时间相关：精确的UTC时区处理，实现准确的交叉日志相关性
• 查询语法修复：针对常见语法问题的OCI兼容性自动修复
• 实时数据：直接OCI API集成，无模拟数据策略

🛡️ 安全分析（已完全实施）

• 安全事件搜索：用于身份验证失败、权限升级的高级模式匹配
• 威胁情报：统计分析和异常检测
• 高级分析：聚类、NLP处理、异常检测、相关性分析
• 现场操作：动态字段提取、模式搜索、数据转换
• 统计分析：对日志数据进行全面的统计操作
• 交叉日志相关性：跨不同日志源的同步时间段

📊 仪表板和已保存的搜索操作

• 列出仪表板：真正的OCI支持上市
• 仪表板详细信息：检索仪表板元数据和互动程序
• 创建/更新仪表板：OCI通过规范服务器路径支持仪表板操作
• 导出/导入：基于JSON的仪表板可移植性
• 保存的搜索：在规范的FastMCP实现中，真正的OCI支持列表和执行操作
• 日志组：从规范服务器公开的真正OCI支持的日志组发现

🎯 检测目录

• 运行检测规则：对实时OCI数据执行目录支持的检测
• 跑步查询：从外部内容目录执行高级搜索查询
• 探测搜索：按平台、严重性、MITRE、STIG或关键字搜索
• 检测测试：在检查字段/日志源问题时验证并执行规则
• 检测资源: detection:// 资源公开规则、搜索查询、MITRE覆盖率和STIG映射

🔧 开发者工具

• 查询验证：语法验证，自动修复错误
• 文档查找：OCI查询语法的内置帮助系统
• 连接测试：验证OCI身份验证和连接
• 错误处理：全面的错误报告和故障排除
• 调试日志：用于故障排除的广泛调试功能

🏢 企业功能

• 多租户支持：跨多个OCI环境查询
• 认证方法：支持配置文件、实例主体和资源主体
• 性能优化：智能查询优化和语法修复
• 隔间管理：支持具有适当访问控制的多个隔间

先决条件

1. OCI账户：访问Oracle云基础架构
2. OCI-CLI：配置了适当的凭据
3. Logan安全仪表板：工作安装（可选，用于预定义查询）
4. 克劳德桌面版：用于MCP集成

安装

快速安装（推荐）🚀

对于具有所有检查和配置的完整自动化安装：

git clone https://github.com/adibirzu/mcp-oci-logan-server.git
cd mcp-oci-logan-server
./install.sh

安装程序将：

• ✅ 检查先决条件（Node.js 18+、Python 3.8+、OCI CLI）
• ✅ 安装Node.js依赖项
• ✅ 设置Python虚拟环境
• ✅ 构建TypeScript代码
• ✅ 测试安装
• ✅ 可选配置克劳德桌面
• ✅ 验证规范刀具曲面是否可用

就是这样！ 脚本会自动处理一切。

手动安装

如果您更喜欢手动安装或已经安装了一些组件：

1.克隆和安装节点依赖关系

git clone https://github.com/adibirzu/mcp-oci-logan-server.git
cd mcp-oci-logan-server
npm install

2.设置Python环境

./setup-python.sh

3.构建TypeScript

npm run build

4.OCI配置

选项A:OCI CLI配置（推荐）

oci setup config

选项B：环境变量

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]"

选项C：实例主体（用于OCI计算） 无需配置-在OCI上运行时自动检测到。

5.克劳德桌面配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

重要：使用绝对路径 args 现场。

6.测试安装

# Test Python client
python python/logan_client.py --help

# Quick rebuild and start
./quick-start.sh

# Test specific features (optional)
node test-server.js

可选：Python FastMCP服务器（stdio安全）

如果你更喜欢使用FastMCP（无节点运行时）的纯Python MCP服务器，并且你有Python 3.10+：

# 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桌面配置示例：

{
  "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"
      }
    }
  }
}

笔记：

• 使用stdio安全日志记录（仅限stderr/file）和snake_case工具名称。
• 阻止OCI调用被卸载到线程以获得响应。
• 通过以下方式设置OCI配置 ~/.oci/config 或节点流中的环境变量。

快速开始更新

如果您已经安装了所有内容，只需要重建：

./quick-start.sh

此脚本：

• 更新依赖关系
• 重建TypeScript
• 显示下一步

HTTP传输和OAuth身份验证

概述

OCI Logan MCP服务器支持两种传输模式：

使用HTTP传输运行

Python FastMCP服务器（推荐用于生产环境）

# 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服务器

# 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端点

\*仅在以下情况下需要身份验证 MCP_OAUTH_ENABLED=true

OAuth配置

对于OCI IDCS（身份云服务）：

1. 创建应用程序 在IDCS中：

- 申请类型：机密 - 授权类型：客户端凭据 - 回调URL： http://localhost:8001 （或您的服务器URL）

1. 配置作用域:

- 添加自定义范围： mcp:tools

1. 设置环境变量:

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

测试HTTP传输

# 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

环境变量引用

______________________________________________________________________

使用示例

基本查询执行

Execute this Logan query with your compartment ID:
'Event Name' = 'UserLoginFailed' and Time > dateRelative(24h) | stats count by 'User Name'

自然语言安全搜索

Search for failed login attempts in the last 24 hours

MITRE ATT&CK 分析

Find all credential access techniques in the last 30 days (default for Sysmon data)

知识产权调查

Analyze all activity for IP address 192.168.1.100 in the last 24 hours

仪表板管理

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

已保存的搜索管理

Create a saved search named "Failed Logins" with query: 'Event Name' = 'UserLoginFailed' | stats count by 'User Name'

List all saved searches in my compartment

文档查找

Show me the documentation for OCI query syntax

Get help with MITRE technique mapping

可用工具（共实施33个）

核心查询工具（功能齐全）

execute_logan_query

通过Python后端直接执行OCI日志分析查询，具有全面的验证、语法修复和错误处理功能。支持无模拟数据的实时数据检索。

参数：

• query （必填）：OCI日志分析查询
• queryName （可选）：查询的名称/标识符
• timeRange （可选）：时间范围（1h、6h、12h、24h、1d、7d、30d、1w、1m）-默认值：24h
• compartmentId （可选）：OCI隔间ID（执行时需要）
• environment （可选）：多租户环境名称

search_security_events

基于人工智能的自然语言到OCI查询转换，用于安全事件搜索，具有高级模式匹配功能。

参数：

• searchTerm （必填）：自然语言描述
• eventType （可选）：事件类型过滤器（登录、特权_扩展、网络_正常、数据_过滤、恶意软件，全部）
• timeRange （可选）：时间范围-默认值：24小时
• limit （可选）：最大结果-默认值：100

get_mitre_techniques

MITRE ATT&CK技术综合分析，针对安全数据优化了90天默认范围。

参数：

• techniqueId （可选）：特定技术ID（例如T1003、T1110）或“全部”
• category （可选）：MITRE策略类别（initial_access、execution、persistence等）
• timeRange （可选）：时间范围-默认值：30d（建议用于Sysmon数据）

analyze_ip_activity

高级IP地址行为分析，具有多种分析类型：完整、身份验证、网络、威胁电话、通信模式。

参数：

• ipAddress （必填）：要分析的IP地址
• analysisType （可选）：分析类型（完整、身份验证、网络、威胁_电话、通信_模式）-默认值：完整
• timeRange （可选）：时间范围-默认值：24小时

高级分析工具（已完全实施）

perform_statistical_analysis

对查询结果进行高级统计操作，包括聚类、异常检测和趋势分析。

perform_advanced_analytics

基于机器学习的分析，包括聚类算法、NLP处理和异常检测。

search_field_patterns

动态字段模式搜索和从日志数据中提取。

correlate_events

交叉日志事件关联与时间同步和模式匹配。

perform_field_operations

字段提取、转换和操纵操作。

仪表板管理工具

list_dashboards

列出规范FastMCP实现中OCI支持的仪表板。

参数：

• compartmentId （可选）：OCI隔室OCID
• displayName （可选）：按显示名称筛选仪表板
• lifecycleState （可选）：按生命周期状态筛选-默认值：ACTIVE
• limit （可选）：要返回的仪表板的最大数量-默认值：50

注： 结果取决于OCI权限和目标分区中可用的仪表板内容。

get_dashboard

从OCI检索详细的仪表板元数据。

参数：

• dashboardId （必填）：要检索的仪表板的OCID
• compartmentId （可选）：OCI隔室OCID（用于验证）

get_dashboard_tiles

从特定的OCI仪表板获取图块/小部件。

参数：

• dashboardId （必填）：仪表板的OCID
• tileType （可选）：按类型过滤图块（全部、查询、可视化、度量、文本）

create_dashboard

使用规范的FastMCP实现创建仪表板。

参数：

• displayName （必填）：仪表板的显示名称
• description （可选）：仪表板说明
• compartmentId （可选）：OCI隔室OCID
• dashboardConfig （可选）：仪表板配置

注： 成功执行取决于OCI权限和目标仪表板服务配置。

update_dashboard

更新现有的OCI仪表板。

参数：

• dashboardId （必填）：要更新的仪表板的OCID
• displayName （可选）：新显示名称
• description （可选）：新描述
• addWidgets （可选）：要添加的小部件数组
• removeWidgetIds （可选）：要删除的小部件ID数组

export_dashboard

将仪表板配置导出为JSON。

参数：

• dashboardId （必填）：要导出的仪表板的OCID
• includeQueries （可选）：包含完整的查询定义-默认值：true

import_dashboard

从JSON配置导入仪表板。

参数：

• dashboardJson （必填）：包含仪表板配置的JSON字符串
• compartmentId （可选）：目标隔间OCID（如果未提供，则使用默认值）
• newDisplayName （可选）：覆盖显示名称

已保存的搜索工具

create_saved_search

创建一个真正的OCI支持的保存搜索。

参数：

• displayName （必填）：已保存搜索的显示名称
• query （必填）：Logan查询保存
• description （可选）：已保存搜索的描述
• compartmentId （可选）：OCI隔室OCID
• widgetType （可选）：首选可视化类型-默认值：搜索

list_saved_searches

列出实际OCI支持的已保存搜索。

参数：

• compartmentId （可选）：OCI隔室OCID
• displayName （可选）：按显示名称筛选
• limit （可选）：最大结果数-默认值：50

实用工具

get_logan_queries

获取预定义的Logan安全仪表板查询。

参数：

• category （可选）：查询类别（mitre攻击、安全、网络、身份验证、权限升级、全部）
• queryName （可选）：特定查询名称

validate_query

使用自动修复建议验证OCI查询语法。

参数：

• query （必填）：要验证的查询
• fix （可选）：尝试自动修复-默认值：false

get_documentation

获取OCI查询的文档和帮助。

参数：

• topic （可选）：文档主题（query_syntax、field_names、函数、时间过滤器、运算符、mitre_mapping、示例、故障排除）
• searchTerm （可选）：在文档中搜索的特定术语

check_oci_connection

测试OCI连接和身份验证。

参数：

• testQuery （可选）：运行测试查询-默认值：true

配置

环境变量

多租户配置

对于多个OCI环境，创建一个配置文件：

{
  "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"
    }
  }
}

查询语法指南

字段名称

始终用空格引用字段名称：

'Event Name' = 'UserLogin'
'User Name' contains 'admin'
'IP Address' = '192.168.1.100'

时间过滤器

使用大写的“时间”字段：

Time > dateRelative(24h)  # Last 24 hours
Time > dateRelative(7d)   # Last 7 days

常见模式

-- 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'

故障排除

常见问题

“缺少输入”错误

• 检查字段名称大小写：使用“时间”而不是“时间”
• 用空格引用字段名称
• 验证运算符语法

身份验证错误

• 验证OCI CLI配置： oci iam user get --user-id
• 检查隔间权限
• 验证密钥文件权限

无结果

• 验证时间范围是否合适
• 检查隔间是否有日志数据
• 确保日志源已配置

性能提示

1. 始终包含时间过滤器
2. 在查询早期使用特定的字段筛选器
3. 限制结果集 | head 100
4. 使用索引字段进行筛选

发展

从源头构建

npm run build    # Compile TypeScript
npm run dev      # Development mode
npm run test     # Run tests

实施状态和限制

✅ 完全实现的功能：

• 核心查询执行与真正的OCI API集成
• 40个MCP工具，涵盖查询、管理、分析、仪表板、检测和实用程序类别
• Canonical FastMCP服务器 src/mcp_logan/
• 高级分析（聚类、NLP、统计分析）
• 查询语法验证和自动修复
• MITRE ATT&CK技术映射
• IP地址行为分析
• 与UTC时区处理的时间相关性
• 无模拟数据策略-所有数据均来自OCI
• 检测目录支持的执行和搜索查询
• 规范检测内容路径的运行状况报告

⚠️ 操作注意事项：

• 仪表板和保存的搜索操作取决于OCI权限和服务可用性
• 外部检测目录路径必须存在，以便检测/狩猎功能可用
• 历史遗留实现仍保留在仓库中，可能与规范服务器合同不匹配

🔧 已知技术问题：

• 中的旧文档 docs/ 和 wiki/ 仍然包含旧的工具计数和旧的实施历史
• 中的一些传统兼容性路径 python/ 和 src/ 保持不变，不应被视为规范

Git仓库设置

存储库配置为从版本控制中排除不必要的文件：

忽略的文件：

• python/venv/ -Python虚拟环境（由setup-Python.sh创建）
• dist/ （可选）-TypeScript编译输出
• claude_desktop_config.json -本地Claude桌面配置
• 调试日志(*.log, /tmp/mcp-*.log)
• 证书(*.pem, *.key, config)
• 测试文件(test-*.js, test-*.ts)

新开发人员设置：

1. 复制 claude_desktop_config.json.template 到 claude_desktop_config.json
2. 更新配置中的路径和OCI隔间ID
3. 跑 ./setup-python.sh 创建Python虚拟环境
4. 这 python/venv/ 目录将被自动忽略

实际架构和数据流

                                 ┌─────────────────────────────────────────┐
                                 │         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                 │
                    └───────────────────────────────────────────────┘

项目结构（实际实施）

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

文档

完整的文档可在 docs/ 文件夹：

• 安装指南 -完整的安装说明
• 用户指南 -如何有效地使用MCP服务器
• 发布说明 -v1.3.0更新日志
• 关键修复 -重要的v1.3.0修复细节
• 改进 -详细更改
• 技术文档 -API覆盖范围、安全审计等。

看 docs/README.md 获取完整的文档索引。

支持

• 文档：参见 docs/ 文件夹
• 内置帮助：请Claude使用MCP工具
• 问题：GitHub问题
• 安全：私下报告安全问题

______________________________________________________________________

最近的更新

v2.0.0-使用OAuth身份验证的HTTP传输（2025年12月）

主要版本：为生产部署提供OAuth 2.0身份验证的完整HTTP传输支持！

新功能:

• HTTP传输：作为支持SSE（服务器发送事件）的web服务运行

- 端口8001上的Python FastMCP服务器（建议用于生产环境） - 端口8000上的TypeScript服务器（备选）

• OAuth 2.0身份验证:

- 具有可配置端点的令牌自检 - 范围验证（默认值： mcp:tools) - 受众验证 - 带可配置TTL的令牌缓存

• IDCS就绪：已配置OCI身份云服务集成
• 双重运输：支持stdio（克劳德桌面）和HTTP（web服务）
• 新端点:

- /health -健康检查（无需身份验证） - /.well-known/oauth-protected-resource -OAuth元数据 - /sse -MCP协议的SSE连接 - /messages/ -MCP消息端点

新建文件:

• src/auth/oauth.ts -OAuth 2.0身份验证模块（TypeScript）
• src/transport/http.ts -带有会话管理的HTTP传输（TypeScript）
• python/main.py -更新了HTTP传输和OAuth支持

已添加环境变量:

• MCP_TRANSPORT -运输类型： stdio, http, sse，或 streamable-http
• MCP_HOST, MCP_PORT -网络传输绑定配置
• MCP_HTTP_HOST, MCP_HTTP_PORT -传统HTTP绑定配置（回退）
• MCP_OAUTH_ENABLED, MCP_OAUTH_* -OAuth配置
• OTEL_TRACING_ENABLED, OCI_APM_ENDPOINT, OCI_APM_PRIVATE_DATA_KEY -可选OCI APM跟踪
• 看 HTTP传输和OAuth 供全面参考

v1.3.0-关键修复和完整文档（2025年10月）

关键修复: list_active_log_sources 现在返回完整结果！

• 关键错误修复：已修复 list_active_log_sources 返回不完整的结果
• 固定硬编码路径：删除了QueryTransformer.ts中的硬编码路径
• 工具库存已更正：该发布线的历史库存更新

v1.2.0-架构分析和文档更新（2025年8月）

• 代码分析揭示了实际与记录的特征
• 通过部分/模拟实现澄清仪表板状态
• 记录了真实数据流细节的架构

当前规范实施状态

下一步发展重点

1. ✅ ~~HTTP传输支持~~ 在v2.0.0中完成
2. ✅ ~~OAuth身份验证~~ 在v2.0.0中完成
3. 将遗留文档与规范的FastMCP实现相协调
4. 加强协调员/观察站集成的下游消费者合同
5. 围绕规范检测内容加载添加全面的合约测试
6. 继续减少遗留实施偏差 python/ 年龄较大 src/ 路径

版本: 2.0.0 最后更新：2025年12月