Name: 模型上下文协议服务器
Author: insightfinder

使用说明

InsightFinder MCP服务器

该项目提供了一个模型上下文协议（MCP）服务器，允许大型语言模型（LLM）与InsightFinder平台进行交互。该服务器提供全面的事件管理、异常检测和系统监控功能。

特性

运输选项

stdio 运输：MCP客户端的标准I/O通信

`http3.其他设备测试：**

# Replace with your actual local IP
curl -k -H "X-API-Key: your-key" \
     -H "X-IF-License-Key: your-license-key" \
     -H "X-IF-User-Name: your-username" \
     https://192.168.1.100/health
```nsport**: RESTful HTTP API with authentication and security

https 运输：支持nginx反向代理的安全HTTPS

安全功能

多种身份验证方法：API密钥、承载令牌或基本身份验证
速率限制：可配置的请求限制
IP白名单：通过IP地址或CIDR块限制访问
CORS支持：web客户端的跨源资源共享
代理支持：完全兼容nginx反向代理

快速开始

先决条件

Python 3.8或更高版本
pip包管理器
（可选）用于容器化部署的Docker
（可选）用于HTTPS部署的nginx

安装

克隆存储库：

git clone <your-repo-url>
cd insightfinder-mcp-server

创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

安装依赖项：
```
pip install -e .
```

配置

环境变量

创建一个 .env 项目根目录中的文件，其中包含您的服务器配置：

# Transport Configuration
TRANSPORT_TYPE=http  # Options: stdio, http

# HTTP Server Configuration (when using http transport)
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# Authentication Configuration (for HTTP transport)
HTTP_AUTH_ENABLED=true
HTTP_AUTH_METHOD=api_key  # Options: api_key, bearer, basic
HTTP_API_KEY=your-secure-api-key-here

# Security Configuration
HTTP_RATE_LIMIT_ENABLED=true
MAX_REQUESTS_PER_MINUTE=60
HTTP_IP_WHITELIST=192.168.1.0/24  # Optional IP restrictions

# Debug Configuration
ENABLE_DEBUG_MESSAGES=false

# SSE Streaming Configuration
SSE_ENABLED=true
SSE_PING_INTERVAL=30
SSE_MAX_CONNECTIONS=100
SSE_CORS_HEADERS=Cache-Control,Content-Type
SSE_HEARTBEAT_ENABLED=true

InsightFinder凭据

重要：InsightFinder凭据现在通过每个请求上的HTTP标头提供，而不是通过环境变量提供。这允许多个客户端通过同一服务器实例使用不同的InsightFinder帐户。

所有InsightFinder操作所需的HTTP标头：

X-IF-License-Key -您的InsightFinder许可证密钥
X-IF-User-Name -您的InsightFinder用户名

可选标题：

X-IF-API-URL -API端点（默认为https://app.insightfinder.com)

HTTP标头身份验证的好处：

多租户支持：多个客户端可以通过同一服务器使用不同的InsightFinder帐户
增强安全：凭据未存储在服务器配置或环境变量中
灵活性：不同的请求可以针对不同的系统或使用不同的凭据
更好的隔离：每个请求都使用自己的凭据上下文进行操作

配置示例

将提供的示例文件用于不同的部署场景：

.env.example -全面的服务器配置模板
复制到 .env 并根据您的需求进行修改

备注：The .env 该文件仅包含服务器配置。InsightFinder凭据是通过每个请求上的HTTP标头提供的。

运行服务器

选项1:stdio传输（适用于MCP客户端）

地方发展：

# Using the provided script
./scripts/run_server.sh

# Or directly
python -m insightfinder_mcp_server.main

MCP客户端配置：

{
  "insightfinder": {
    "command": "python",
    "args": ["-m", "insightfinder_mcp_server.main"],
    "cwd": "/path/to/insightfinder-mcp-server"
  }
}

备注：使用stdio传输时，MCP客户端必须通过MCP协议的初始化或自定义标头（如果您的客户端支持）提供InsightFinder凭据。

选项2:SSE流式传输的HTTP传输

使用SSE启动HTTP服务器：

# Set transport to HTTP with SSE enabled
export TRANSPORT_TYPE=http
export SERVER_HOST=0.0.0.0
export SERVER_PORT=8000
export HTTP_AUTH_ENABLED=true
export HTTP_API_KEY=your-secure-api-key
export SSE_ENABLED=true

python -m insightfinder_mcp_server.main

测试SSE流媒体：

# Connect to SSE event stream
curl -H "X-API-Key: your-api-key" \
     -H "Accept: text/event-stream" \
     http://localhost:8000/mcp/events

# Send streaming MCP request with InsightFinder credentials
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-IF-License-Key: your-license-key" \
  -H "X-IF-User-Name: your-username" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_incidents","arguments":{"systemName":"test-system"}},"id":1}' \
  http://localhost:8000/mcp/stream

# Stream individual tool execution
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-IF-License-Key: your-license-key" \
  -H "X-IF-User-Name: your-username" \
  -H "Accept: text/event-stream" \
  -d '{"systemName":"test-system"}' \
  http://localhost:8000/tools/list_incidents/stream

选项3:HTTP传输（标准RESTful API）

启动HTTP服务器：

# Set transport to HTTP
export TRANSPORT_TYPE=http
export SERVER_HOST=0.0.0.0
export SERVER_PORT=8000
export HTTP_AUTH_ENABLED=true
export HTTP_API_KEY=your-secure-api-key

python -m insightfinder_mcp_server.main

测试HTTP API：

# Health check
curl -H "X-API-Key: your-api-key" http://localhost:8000/health

# List available tools
curl -H "X-API-Key: your-api-key" http://localhost:8000/tools

# Execute MCP request with InsightFinder credentials
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-IF-License-Key: your-license-key" \
  -H "X-IF-User-Name: your-username" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:8000/mcp

# Execute a specific tool
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-IF-License-Key: your-license-key" \
  -H "X-IF-User-Name: your-username" \
  -d '{"systemName":"your-system-name"}' \
  http://localhost:8000/tools/list_incidents

选项4:使用nginx的HTTPS（生产）

自动设置：

# For production deployment with Let's Encrypt
sudo ./scripts/setup-https.sh your-domain.com 8000

# For local testing with self-signed certificate
sudo ./scripts/setup-local-https.sh

手动设置：

# 1. Configure nginx with provided template
sudo cp config/nginx/nginx-https.conf /etc/nginx/sites-available/mcp-server
sudo ln -s /etc/nginx/sites-available/mcp-server /etc/nginx/sites-enabled/

# 2. Get SSL certificate
sudo certbot --nginx -d your-domain.com

# 3. Configure for proxy mode
export BEHIND_PROXY=true
export TRUST_PROXY_HEADERS=true
export SERVER_HOST=127.0.0.1

# 4. Start server
python -m insightfinder_mcp_server.main

测试HTTPS设置：

# Use the provided test script
./scripts/test-https.sh your-domain.com your-api-key

# Or manual testing with InsightFinder credentials
curl -H "X-API-Key: your-api-key" \
     -H "X-IF-License-Key: your-license-key" \
     -H "X-IF-User-Name: your-username" \
     https://your-domain.com/health

选项5:Docker部署

基本Docker运行（stdio传输）：

docker run -i --rm \
  -e TRANSPORT_TYPE=stdio \
  docker.io/insightfinder/insightfinder-mcp-server:latest

使用HTTP传输的Docker：

docker run -d \
  -p 8000:8000 \
  -e TRANSPORT_TYPE=http \
  -e HTTP_AUTH_ENABLED=true \
  -e HTTP_API_KEY=your-secure-api-key \
  docker.io/insightfinder/insightfinder-mcp-server:latest

Docker的MCP客户端配置：

{
  "insightfinder": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "docker.io/insightfinder/insightfinder-mcp-server:latest"
    ],
    "transport": "stdio"
  }
}

备注：使用Docker部署时，InsightFinder凭据在使用HTTP传输时通过HTTP标头提供，或在使用stdio传输时通过MCP协议提供。

api参考

HTTP端点

在HTTP模式下运行时，以下端点可用：

GET / -服务器信息和功能
GET /health -健康检查端点
GET /tools -列出具有模式的可用工具
POST /tools/{tool_name} -执行特定工具
POST /mcp -执行MCP JSON-RPC请求
POST /mcp/stream -流式处理MCP请求（已弃用，使用SSE端点）
GET /docs -交互式API文档（Swagger UI）

SSE流端点（当SSE_ENABLED=true时）：

GET /mcp/events -实时MCP事件的SSE事件流
POST /mcp/stream -通过服务器发送事件流式传输MCP请求
POST /tools/{tool_name}/stream -流式传输单个工具执行
GET /sse/connections -获取活动的SSE连接（调试端点）

InsightFinder HTTP标头

所有InsightFinder工具操作都需要以下HTTP标头：

所需标题：

X-IF-License-Key -您的InsightFinder许可证密钥
X-IF-User-Name -您的InsightFinder用户名

可选标题：

X-IF-API-URL -自定义API终结点（默认为https://app.insightfinder.com)

请求示例：

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-server-api-key" \
  -H "X-IF-License-Key: your-insightfinder-license-key" \
  -H "X-IF-User-Name: your-insightfinder-username" \
  -d '{"timeRange":"1d","status":"open"}' \
  http://localhost:8000/tools/list_incidents

身份验证方法

API密钥验证：

# Header-based (recommended)
curl -H "X-API-Key: your-key" https://api.example.com/health

# Query parameter (fallback)
curl "https://api.example.com/health?api_key=your-key"

承载令牌身份验证：

curl -H "Authorization: Bearer your-token" https://api.example.com/health

基本身份验证：

curl -u username:password https://api.example.com/health

安全配置

速率限制

HTTP_RATE_LIMIT_ENABLED=true
MAX_REQUESTS_PER_MINUTE=60

IP白名单

# Single IP
HTTP_IP_WHITELIST=192.168.1.100

# CIDR blocks (comma-separated)
HTTP_IP_WHITELIST=192.168.1.0/24,10.0.0.0/8

CORS配置

HTTP_CORS_ENABLED=true
HTTP_CORS_ORIGINS=https://your-frontend.com,https://localhost:3000

本地开发和测试

家庭网络测试

在本地网络上进行测试：

生成本地HTTPS设置：

# Creates self-signed certificates and nginx config
sudo ./scripts/setup-local-https.sh

配置本地访问：

# Update ALLOWED_HOSTS with your local IP
export ALLOWED_HOSTS=192.168.1.100,localhost,127.0.0.1

其他设备测试：

# Replace with your actual local IP
curl -k -H "X-API-Key: your-key" https://192.168.1.100/health

开发脚本

./scripts/run_server.sh -以开发模式启动服务器
./scripts/setup-https.sh -使用Let's Encrypt进行生产HTTPS设置
./scripts/setup-local-https.sh -使用自签名证书的本地HTTPS设置
./scripts/test-https.sh -测试HTTPS配置
./scripts/test-local-https.sh -测试本地HTTPS设置
./scripts/test-sse.sh -测试SSE流媒体功能（基于curl）
python tests/test_sse.py -全面的SSE测试（基于Python）

测试辅助脚本

创建测试配置脚本：

#!/bin/bash
# save as test-insightfinder.sh

# Set your credentials
export IF_LICENSE_KEY="your-license-key-here"
export IF_USERNAME="your-username-here"
export API_KEY="your-server-api-key-here"

# Helper function for API calls
call_tool() {
    local tool_name=$1
    local data=$2
    
    curl -X POST \
        -H "Content-Type: application/json" \
        -H "X-API-Key: $API_KEY" \
        -H "X-IF-License-Key: $IF_LICENSE_KEY" \
        -H "X-IF-User-Name: $IF_USERNAME" \
        -d "$data" \
        "http://localhost:8000/tools/$tool_name"
}

# Example usage:
# call_tool "list_incidents" '{"timeRange":"7d"}'
# call_tool "fetch_log_anomalies" '{"startTime":"2024-01-01","endTime":"2024-01-02"}'

Python助手示例：

import requests
import json

class InsightFinderClient:
    def __init__(self, base_url="http://localhost:8000", api_key=None, 
                 license_key=None, username=None):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "X-API-Key": api_key,
            "X-IF-License-Key": license_key,
            "X-IF-User-Name": username
        }
    
    def call_tool(self, tool_name, **kwargs):
        url = f"{self.base_url}/tools/{tool_name}"
        response = requests.post(url, headers=self.headers, json=kwargs)
        return response.json()
    
    def list_incidents(self, **kwargs):
        return self.call_tool("list_incidents", **kwargs)
    
    def fetch_log_anomalies(self, **kwargs):
        return self.call_tool("fetch_log_anomalies", **kwargs)

# Usage
client = InsightFinderClient(
    api_key="your-server-api-key",
    license_key="your-license-key", 
    username="your-username"
)

incidents = client.list_incidents(timeRange="7d")

故障排除

常见问题

1.InsightFinder凭据错误：

# Missing required headers will return HTTP 400 with error details
curl -X POST \
  -H "X-API-Key: your-api-key" \
  -d '{"systemName":"test"}' \
  http://localhost:8000/tools/list_incidents

# Response: {"error": "Missing required header: X-IF-License-Key"}

# Verify all required headers are included
curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "X-IF-License-Key: your-license-key" \
  -H "X-IF-User-Name: your-username" \
  -d '{"systemName":"test"}' \
  http://localhost:8000/tools/list_incidents

2.身份验证错误：

# Verify your server API key is set correctly
echo $HTTP_API_KEY

# Check server logs for authentication details
ENABLE_DEBUG_MESSAGES=true python -m insightfinder_mcp_server.main

3.代理/HTTPS问题：

# Ensure proxy settings are configured
export BEHIND_PROXY=true
export TRUST_PROXY_HEADERS=true

# Check nginx error logs
sudo tail -f /var/log/nginx/error.log

4.SSL证书问题：

# Test SSL certificate
echo | openssl s_client -servername your-domain.com -connect your-domain.com:443

# Renew Let's Encrypt certificate
sudo certbot renew

调试模式

启用详细日志以进行故障排除：

export ENABLE_DEBUG_MESSAGES=true
python -m insightfinder_mcp_server.main

环境变量引用

服务器配置变量

TRANSPORT_TYPE -传输方式（默认：stdio）
SERVER_HOST -HTTP服务器绑定地址（默认值：0.0.0.0）
SERVER_PORT -HTTP服务器端口（默认值：8000）
ENABLE_DEBUG_MESSAGES -启用调试日志记录（默认值：false）

InsightFinder API配置

INSIGHTFINDER_API_URL -默认API端点（默认值：https://app.insightfinder.com)

备注：个人InsightFinder凭据（许可证密钥、用户名、系统名称）现在通过每个请求上的HTTP标头提供，而不是环境变量。

HTTP传输变量

HTTP_AUTH_ENABLED -启用身份验证（默认值：true）
HTTP_AUTH_METHOD -认证方式：api_key，bearer，basic（默认：api_key）
HTTP_API_KEY -用于身份验证的API密钥
HTTP_BEARER_TOKEN -用于身份验证的承载令牌
HTTP_BASIC_USERNAME -基本身份验证用户名（默认：admin）
HTTP_BASIC_PASSWORD -基本身份验证密码
HTTP_RATE_LIMIT_ENABLED -启用速率限制（默认值：true）
MAX_REQUESTS_PER_MINUTE -速率限制阈值（默认值：60）
HTTP_IP_WHITELIST -允许的IP地址/CIDR块
HTTP_CORS_ENABLED -启用CORS（默认值：false）
HTTP_CORS_ORIGINS -允许的CORS源（默认值：*）

SSE流媒体变量

SSE_ENABLED -启用服务器发送事件流（默认值：true）
SSE_PING_INTERVAL -心跳间隔（秒）（默认值：30）
SSE_MAX_CONNECTIONS -最大并发SSE连接数（默认值：100）
SSE_CORS_HEADERS -SSE的其他CORS标头（默认值：缓存控制，内容类型）
SSE_HEARTBEAT_ENABLED -启用心跳事件（默认值：true）

代理变量

BEHIND_PROXY -服务器位于反向代理之后（默认值：false）
TRUST_PROXY_HEADERS -信任代理转发的标头（默认值：false）
ALLOWED_HOSTS -以逗号分隔的允许主机名列表

贡献

项目结构

├── src/
│   └── insightfinder_mcp_server/        # Main application code
│       ├── __init__.py
│       ├── main.py                      # Application entry point
│       ├── api_client/                  # InsightFinder API client
│       ├── config/                      # Configuration management
│       ├── security/                    # Authentication & security
│       └── server/                      # MCP server implementation
├── scripts/                             # Deployment & utility scripts
│   ├── run_server.sh                    # Development server launcher
│   ├── setup-https.sh                   # Production HTTPS setup
│   ├── setup-local-https.sh             # Local HTTPS setup  
│   ├── test-https.sh                    # HTTPS testing
│   └── test-local-https.sh              # Local HTTPS testing
├── config/
│   └── nginx/                           # Nginx configuration templates
│       └── nginx-https.conf             # HTTPS proxy configuration
├── tests/                               # Test suites
├── docs/                                # Documentation
├── .env.example                         # Environment configuration template
├── Dockerfile                           # Container configuration
├── pyproject.toml                       # Python project configuration
└── README.md                            # This file

许可证

[此处为许可证信息]