# OSIM MCP Server (FastMCP)

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.0+-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> 一个基于 FastMCP 的 Model Context Protocol (MCP) 服务器，提供 OSIM (Open Security Information Model) 数据标准 schema 的查询和访问能力。

## 📖 简介

OSIM MCP Server 是一个标准化的 MCP 服务器实现，旨在为 AI 应用提供结构化的安全信息模型数据标准。通过 MCP 协议，AI 助手可以轻松查询、浏览和获取各种安全相关的数据标准定义，包括告警、资产、日志、事件和设备检测等分类。

### 核心功能

- 🔍 **数据标准查询**：提供完整的 OSIM 数据标准 schema 查询能力
- 🛠️ **MCP 工具集成**：通过标准 MCP 工具接口提供数据标准服务
- 📚 **资源访问**：支持通过 MCP 资源协议访问 schema 文件
- 🏗️ **结构化数据**：涵盖 5 大分类、200+ 种数据标准定义
- ⚡ **高性能**：基于 FastMCP，支持快速启动和高效查询

## ✨ 主要特性

- **完整的 OSIM 数据标准支持**
  - 告警 (Alert)：异常行为、账户异常、数据安全、恶意软件、网络攻击等
  - 资产 (Asset)：业务资产、云资产、数据资产、网络资产、物理资产等
  - 日志 (Log)：账户操作审计、数据安全审计、主机行为审计、网络会话审计等
  - 事件 (Incident)：安全事件记录和分类
  - 设备检测 (Device Detection)：EDR、防火墙、WAF、IDS/IPS 等各类安全设备

- **标准 MCP 协议支持**
  - 工具 (Tools)：`listSchemaNames`、`describeSchemas`、`getSchema`
  - 资源 (Resources)：通过 URI 访问 schema 文件内容
  - 同步模式：支持 STDIO 通信方式

- **易于集成**
  - 基于 FastMCP，开箱即用
  - 标准 MCP 协议，兼容所有支持 MCP 的 AI 客户端
  - 清晰的 API 设计和文档

## 🚀 快速开始

### 前置要求

- Python 3.10 或更高版本
- uv 包管理器（推荐）或 pip

### 安装方式

#### 方式 1: 使用 uvx（推荐，无需安装）

如果包已发布到 PyPI，可以直接使用 `uvx` 运行：

```bash
uvx osim-mcp-server
```

#### 方式 2: 使用 uv 安装

```bash
# 从 PyPI 安装
uv pip install osim-mcp-server

# 运行
uv run osim-mcp-server
```

#### 方式 3: 从源码安装

1. **克隆仓库**

```bash
git clone https://github.com/your-org/osim-mcp-server-fastmcp.git
cd osim-mcp-server-fastmcp
```

2. **安装依赖**

使用 uv（推荐）：

```bash
uv sync
```

或使用 pip：

```bash
pip install -r requirements.txt
```

3. **运行服务器**

使用 uv（推荐）：

```bash
uv run python server.py
```

或使用启动脚本：

```bash
./run.sh
```

或使用 Python：

```bash
python server.py
```

## 📚 使用指南

### MCP 工具

服务器提供以下三个 MCP 工具：

#### 1. `listSchemaNames`

列出所有可用的数据标准 schema 名称。

**返回格式**：`{group}.{category}.{title}`

**示例**：
- `log.network_session_audit.http_audit`
- `alert.network_attack.apt_attack`
- `asset.business_asset.web_application`

#### 2. `describeSchemas`

获取指定 schema 名称列表的描述信息。

**参数**：
- `schemaNames` (List[str]): schema 名称列表

**返回**：字典，键为 schema 名称，值为描述信息

**示例**：
```json
{
  "log.network_session_audit.http_audit": "Records and monitors HTTP requests and responses...",
  "alert.network_attack.apt_attack": "Advanced Persistent Threat attack detection..."
}
```

#### 3. `getSchema`

获取指定 schema 的完整字段定义。

**参数**：
- `schemaPath` (str): schema 路径，格式为 `{group}.{category}.{title}`

**返回**：字段定义字典，包含字段名、标签、类型、要求、描述等信息

**示例**：
```json
{
  "http_method": {
    "label": "HTTP Method",
    "requirement": "RECOMMENDED",
    "description": "Identifies the request operation type...",
    "type": "string",
    "valid_type": "string_t"
  },
  ...
}
```

### MCP 资源

通过资源 URI 访问 schema 文件内容：

**URI 格式**：`data-standard://{group}/{category}/{title}`

**示例**：
- `data-standard://log/network_session_audit/http_audit`
- `data-standard://alert/network_attack/apt_attack`
- `data-standard://asset/business_asset/web_application`

**响应格式**：JSON 格式的完整 schema 文件内容

### 集成示例

#### 在 Claude Desktop 中使用

**使用 uvx（推荐）**：

```json
{
  "mcpServers": {
    "osim-mcp-server": {
      "command": "uvx",
      "args": [
        "osim-mcp-server"
      ]
    }
  }
}
```

**使用本地安装**：

```json
{
  "mcpServers": {
    "osim-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "osim-mcp-server"
      ]
    }
  }
}
```

**使用 Python 直接运行**：

```json
{
  "mcpServers": {
    "osim-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/osim-mcp-server-fastmcp/server.py"
      ]
    }
  }
}
```

#### 在 Cursor 中使用

在 Cursor 的 MCP 配置中添加服务器配置，服务器将通过 STDIO 方式与 Cursor 通信。推荐使用 `uvx` 方式配置。

## 🏗️ 项目结构

```
osim-mcp-server-fastmcp/
├── server.py                    # 主服务器文件
├── loader.py                    # 数据标准加载器
├── schemas/                     # 数据标准 schema 文件（来源于 OSIM 开源工程）
│   ├── alert/                   # 告警分类
│   ├── asset/                   # 资产分类
│   ├── device_detection/         # 设备检测分类
│   ├── incident/                # 事件分类
│   ├── log/                     # 日志分类
│   └── groups.json              # 分组元数据
├── requirements.txt             # Python 依赖
├── README.md                    # 项目文档
└── .gitignore                   # Git 忽略文件
```

## 📊 数据标准分类

> **数据标准来源**：本项目 `schemas/` 目录下的所有数据标准 schema 文件均来源于 [OSIM 开源工程](https://github.com/osim-project/osim)（Open Security Information Model）。这些 schema 文件定义了完整的安全信息模型数据标准，包括告警、资产、日志、事件和设备检测等分类。

### 告警 (Alert)
- **异常行为** (abnormal_behavior)：异常文件操作、访问异常、恶意文件创建等
- **账户异常** (account_anomaly)：账户变更异常、账户登录异常
- **数据安全** (data_security)：数据泄露、数据篡改、数据库异常操作
- **恶意软件** (malware)：僵尸网络、计算机病毒、勒索软件、木马等
- **网络攻击** (network_attack)：APT 攻击、后门利用、凭证攻击、DDoS 等
- **漏洞配置风险** (vulnerability_configuration_risk)：数据库风险、主机漏洞风险等

### 资产 (Asset)
- **业务资产** (business_asset)：应用、业务系统、小程序、公众号、Web 应用
- **云资产** (cloud_asset)：云服务器、云存储
- **数据资产** (data_asset)：账户、API、数据字段、数据表、数据库、文件
- **网络资产** (network_asset)：证书、域名、IP 地址、端口
- **物理资产** (physical_asset)：设备、服务器、终端
- **软件资产** (software_asset)：应用软件、组件、中间件、系统软件
- **虚拟资产** (virtual_asset)：容器、虚拟机

### 日志 (Log)
- **账户操作审计** (account_operation_audit)：账户登录、账户变更
- **数据安全审计** (data_security_audit)：文件通信审计、数据库操作审计
- **主机行为审计** (host_behavior_audit)：进程审计、文件审计、注册表操作等
- **网络会话审计** (network_session_audit)：HTTP、HTTPS、SSH、FTP、DNS 等协议审计
- **操作监控审计** (operation_monitoring_audit)：系统操作、状态变更、文件操作、命令操作

### 事件 (Incident)
- **安全事件** (security_incident)：安全事件记录和分类

### 设备检测 (Device Detection)
涵盖 20+ 种安全设备类型，包括：
- EDR 系统、防火墙、WAF、IDS/IPS
- 数据库审计系统、堡垒机、零信任系统
- Windows/Linux 审计增强、漏洞扫描器等

## 🧪 开发

### 运行服务器

```bash
python server.py
```

### 代码风格

项目遵循 Python PEP 8 代码风格，建议使用代码格式化工具。

## 🤝 贡献

我们欢迎所有形式的贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献指南

- 确保代码通过所有测试
- 遵循现有的代码风格
- 添加适当的注释和文档
- 更新 README.md（如需要）

## 📝 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [FastMCP](https://github.com/jlowin/fastmcp) - 提供 MCP 服务器框架
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 协议规范
- [OSIM 开源工程](https://github.com/osim-project/osim) - 提供数据标准 schema 文件资源，本项目 `schemas/` 目录下的所有 schema 文件均来源于此开源项目
- OSIM 数据标准贡献者

## 📧 联系方式

- 项目主页：[GitHub Repository](https://github.com/your-org/osim-mcp-server-fastmcp)
- 问题反馈：[GitHub Issues](https://github.com/your-org/osim-mcp-server-fastmcp/issues)
- 讨论区：[GitHub Discussions](https://github.com/your-org/osim-mcp-server-fastmcp/discussions)

## 🔗 相关链接

- [FastMCP 文档](https://github.com/jlowin/fastmcp)
- [Model Context Protocol 规范](https://modelcontextprotocol.io/)
- [OSIM 数据标准文档](https://osim.example.com/docs)

---

**⭐ 如果这个项目对你有帮助，请给我们一个 Star！**


