Lumenore Analytics MCP Server

Lumenore分析MCP服务器

   

模型上下文协议（MCP）服务器，为AI助手提供对Lumenore分析和自然语言查询功能的访问。使用FastMCP和Python 3.13构建，用于可扩展的数据分析集成。

快速开始

1.安装并运行

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your client credentials (LUMENORE_CLIENT_ID and LUMENORE_SECRET)
python main.py

2.连接您的AI助手

• 统一资源定位符: http://localhost:8080/mcp
• 运输：流式HTTP

3.开始分析

# Example: Get sales insights
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

📖 全部文件 | 🐛 报告问题 | 🔒 隐私政策

目录

• 概述
• 安装
• 配置
• 可用工具
• 用法示例
• 认证
• 安全与隐私
• 故障排除
• 贡献
• 支持
• 许可证

概述

此MCP服务器为AI助手提供了对Lumenore强大分析功能的访问：

• 自然语言查询：将问题转化为数据见解
• 高级分析：趋势、预测、相关性、异常值、变化、帕累托分析
• 实时处理：大型数据集的流响应
• 零数据存储：无持久日志记录的内存处理。当MCP服务器将请求转发到Lumenore后端时，Lumenore的隐私政策适用

安装

先决条件

• Python 3.13+
• Lumenore客户端凭据（客户端ID和密码）
• 访问Lumenore服务器实例

设置

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt

配置

创建 .env 使用您的凭据在项目根目录中创建文件。您可以使用 .env.example 作为模板：

cp .env.example .env

然后编辑 .env 根据您的配置：

使用客户端凭据

LUMENORE_CLIENT_ID="your_client_id_here"
LUMENORE_SECRET="your_secret_here"
SERVER_URL="https://preview.lumenore.com"

配置参数

运行服务器

启动MCP服务器：

python main.py

服务器运行在 http://0.0.0.0:8080 使用SSE传输进行实时流式传输。

连接您的AI助手

Claude桌面版

1. 设置→ MCP服务器
2. 添加服务器：

   Name: Lumenore Analytics
   URL: http://localhost:8080/mcp
   Transport: Streamable HTTP

程序化访问（Python）

from mcp.client import MCPClient

client = MCPClient("http://localhost:8080/mcp", transport="streamable_http")
tools = await client.list_tools()
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

连接详细信息:

• 协议：药品监督管理委员会2024-11-05+
• 运输：流式HTTP（SSE）
• 端口：8080（默认值）
• 认证：不需要MCP级别的身份验证

测试连接:

curl -I http://localhost:8080  # Should return HTTP/1.1 200 OK

认证

获取您的凭据

客户端凭证

1. 联系Lumenore支持以获取客户端凭据
2. 接收您的 LUMENORE_CLIENT_ID 和 LUMENORE_SECRET
3. 安全地存放在您的 .env 文件

请参阅 配置 有关详细设置说明的部分。

安全最佳实践

身份验证问题疑难解答

“授权令牌丢失或无效”:

• 验证凭据是否已在中设置 .env 文件：

- 对于客户端凭据：检查两者 LUMENORE_CLIENT_ID 和 LUMENORE_SECRET 已设定

• 确保Lumenore AI积分可用
• 检查 SERVER_URL 指向正确的Lumenore实例

可用工具

服务器提供8个强大的数据分析工具：

数据集管理

get_dataset_metadata -列出可用的数据集和架构ID

自然语言查询

nlq_to_data -将问题转化为结构化数据

{
  "userQuery": "Top 5 sales regions last month",
  "schemaId": 123
}

高级分析

get_trend_data -识别时间模式和趋势 get_prediction_data -生成预测和预报 get_outlier_data -检测异常和异常模式 get_correlation_data -分析变量关系 get_change_data -检测模式转换和转变 get_pareto_data -执行80/20影响分析

错误处理

所有工具都返回标准化的响应：

• 成功: {"data": {...}, "status": "success"}
• 验证错误: {"error": "...", "status": "validation_error"}
• 服务错误: {"error": "...", "status": "error"}

演出

• 响应时间：1-7秒
• 超时：60秒
• 并发：支持多个同时请求

最佳实践

1. 从开始 get_dataset_metadata 查找架构ID
2. 在自然语言查询中要具体
3. 始终检查 status 响应中的字段
4. 缓存频繁查询以获得更好的性能

用法示例

以下是三个真实的例子，展示了人工智能助手如何与Lumenore Analytics MCP服务器交互：

示例1：销售业绩分析

场景：一位业务分析师想了解上个季度的销售业绩。

AI助手交互:

# Step 1: Get available datasets
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Query sales data
sales_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show me total sales by region for Q4 2024, sorted by highest sales",
    "schemaId": 35403
})

# Step 3: Analyze trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the monthly sales trends for Q4 2024?",
    "schemaId": 35403
})

# Step 4: Identify top performers
pareto_analysis = await client.call_tool("get_pareto_data", {
    "userQuery": "Which products contribute to 80% of our sales?",
    "schemaId": 35403
})

预期见解:

• 区域销售明细及总计
• 显示增长/下降的月度趋势可视化
• 产品贡献分析，突出关键收入驱动因素

______________________________________________________________________

示例2：客户行为分析

场景：营销团队希望了解客户的购买模式并检测异常情况。

AI助手交互:

# Step 1: Get customer dataset information
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze customer segments
customer_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show customer demographics and average order value by age group",
    "schemaId": 35404
})

# Step 3: Detect unusual patterns
anomaly_detection = await client.call_tool("get_outlier_data", {
    "userQuery": "Find customers with unusually high order values or frequency",
    "schemaId": 35404
})

# Step 4: Understand correlations
correlation_analysis = await client.call_tool("get_correlation_data", {
    "userQuery": "What factors correlate with customer lifetime value?",
    "schemaId": 35404
})

预期见解:

• 按人口统计和支出进行客户细分
• 识别潜在欺诈或VIP客户
• 目标营销客户价值的关键驱动因素

______________________________________________________________________

示例3：库存优化

场景运营经理需要根据需求模式和预测优化库存水平。

AI助手交互:

# Step 1: Get inventory dataset
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze historical demand
demand_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show monthly demand for each product category over the past year",
    "schemaId": 35405
})

# Step 3: Identify trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the demand trends for each product category?",
    "schemaId": 35405
})

# Step 4: Generate forecasts
forecast = await client.call_tool("get_prediction_data", {
    "userQuery": "Predict demand for next 3 months by product category",
    "schemaId": 35405
})

# Step 5: Detect demand changes
change_detection = await client.call_tool("get_change_data", {
    "userQuery": "Have there been any significant changes in demand patterns recently?",
    "schemaId": 35405
})

预期见解:

• 按类别划分的历史需求模式
• 具有置信区间的未来需求预测
• 需求模式转变的预警
• 数据驱动的库存优化建议

______________________________________________________________________

好处:

• 自动数据刷新，无需人工干预
• 实时洞察运营决策
• 通过高效缓存减少后端系统的负载

______________________________________________________________________

示例中的最佳实践

1. 从元数据开始：始终使用 get_dataset_metadata 了解可用数据集
2. 组合工具：同时使用多种工具进行全面分析
3. 具体查询：在自然语言查询中要清晰具体
4. 错误处理：在处理结果之前，始终检查响应状态
5. 演出：缓存频繁访问的数据以缩短响应时间

克劳德提示

以下是连接到此MCP服务器时可以与Claude一起使用的示例提示：

用于销售分析:

“使用Lumenore Analytics工具分析我们第四季度的销售业绩。我需要查看区域细分，确定表现最佳的产品，并了解销售趋势。”

客户洞察:

分析客户的人口统计数据，找出任何不寻常的购买模式，并确定哪些因素驱动了客户价值。使用可用的分析工具提供全面的见解。"

用于库存管理:

“生成下一季度的预测，并使用预测和趋势分析工具确定需求行为的任何最新变化。”

______________________________________________________________________

错误处理

所有工具都实现了针对特定错误类型的全面错误处理：

# Validation errors
{
    "error": "Invalid request parameters: ",
    "status": "validation_error",
    "query": "",
    "schema_id": 
}

# Service errors
{
    "error": " failed: ",
    "status": "error",
    "query": "",
    "schema_id": 
}

测试服务器

您可以使用任何兼容MCP的客户端或向SSE端点发出HTTP请求来测试MCP服务器：

# Example: Testing with curl (adjust based on MCP protocol)
curl -N http://localhost:8080

安全与隐私

安全概述

Lumenore Analytics MCP服务器实现多层安全保护，以保护您的数据和API证书：

数据保护

• 内存处理：所有数据都在内存中处理，并在生成响应后立即丢弃
• 无数据存储：MCP服务器不存储或记录任何用户查询、模式ID或响应数据
• 安全通信：所有后端API请求都使用HTTPS加密
• 凭据安全：客户端凭据从不记录、存储或在响应中公开

身份验证安全

• 客户端凭据流：使用客户端ID和密钥的行业标准身份验证
• 会话管理：安全的基于cookie的会话处理，具有自动令牌刷新功能
• 无MCP级别认证：MCP连接不需要身份验证（后端身份验证由服务器端处理）
• 安全监控：记录失败的身份验证尝试以进行安全分析

凭证最佳实践

• 环境变量：将凭据存储在环境变量中或 .env 文件（从不在代码中）
• 定期轮换：每90天或根据需要轮换一次凭据
• 范围限制：使用具有最低所需权限的凭据
• 独立环境：对开发、暂存和生产使用不同的凭据

隐私政策

有关Lumenore如何处理您的数据的详细信息，请参阅我们的 隐私政策.

关键隐私原则

• 最小数据处理：仅处理用户提供的查询和模式ID
• 无对话历史记录：不存储或记录对话历史记录
• 用户控件：用户控制查询和分析哪些数据
• 合规：旨在遵守数据保护法规（GDPR、CCPA）

数据流隐私

User Query → MCP Server → Lumenore Backend → Results → User
             (No storage)   (Lumenore's privacy policy applies)

保密考虑

• MCP服务器充当AI助手和Lumenore后端之间的安全代理
• Lumenore后端API的所有隐私和数据处理政策适用于您的数据
• 服务器本身在即时请求处理之外不保留任何用户数据
• 用户有责任确保其查询符合适用的数据保护法

合规

合规

• GDPR 数据保护：符合《通用数据保护条例》
• 云室照相分析：符合《加利福尼亚州消费者隐私法》
• SOC 2：后端服务遵循SOC 2安全标准
• ISO 27001：信息安全管理最佳做法

数据驻留

• 数据处理发生在Lumenore的云基础设施中
• 应与Lumenore销售团队讨论数据驻留要求
• 企业部署可能支持私有云或内部部署选项

安全配置

环境安全

# Secure credentials management
export LUMENORE_CLIENT_ID="your_client_id"
export LUMENORE_SECRET="your_secret"

# Restrict file permissions
chmod 600 .env
chmod 700 /path/to/server/directory

# Use secure network connections only
# Avoid using public Wi-Fi for sensitive operations

生产安全

• 为生产环境使用专用客户端凭据
• 实施凭证轮换自动化
• 监控API的使用情况并设置异常活动警报
• 考虑为API访问实现IP allowlisting
• 使用VPN或专用网络进行服务器通信

漏洞管理

报告安全问题

我们认真对待安全问题。如果发现漏洞：

1. 电子邮件： askme@lumenore.com
2. 包括漏洞详细信息和复制步骤
3. 我们将在24小时内确认
4. 在公开披露之前与我们合作解决问题

安全更新

• 安全补丁被优先考虑并快速部署
• 通过我们的支持渠道订阅安全通知
• 对基础设施进行定期安全评估

数据加密

运输中

• 所有API通信都使用TLS 1.2+加密
• 对所有后端连接强制执行HTTPS
• 可以实施证书固定以增强安全性

静止

• 后端数据存储在静止时使用加密
• 数据库加密保护存储的分析数据
• 关键管理遵循行业最佳实践

访问控制

最小特权原则

• 客户端凭据应具有所需的最小权限
• 为不同的应用程序和环境提供单独的凭据
• 定期审查凭证权限和使用情况

网络安全

• 防火墙规则仅限制对必要端口的访问
• 考虑实施VPN访问以进行服务器管理
• 将网络分段用于生产部署

______________________________________________________________________

故障排除

快速诊断步骤

1. 检查服务器是否正在运行: curl -I http://localhost:8080
2. 验证令牌是否已加载：检查服务器启动日志中是否有“无授权令牌”警告
3. 测试后端连接: curl -I https://preview.lumenore.com
4. 检查MCP协议：确保客户端使用可流式HTTP传输

客户端配置示例:

{
    "server": {
        "lumenore-server": {
            "type": "streamable-http",
            "url": "http://localhost:8080/mcp",
        }
    }
}

使用Python进行手动测试:

from config import config
from core.lumenore_analytics import LumenoreAnalytics
import asyncio

async def test():
    client = LumenoreAnalytics()
    result = await client.make_request('get-domain', method='GET')
    print(result)

asyncio.run(test())

获取帮助

如果您已经尝试了上述步骤，但仍然存在问题：

1. 检查服务器日志 有关详细的错误消息
2. 验证令牌有效性 和权限
3. 直接测试后端API 隔离MCP与后端问题
4. 审查MCP客户端配置 用于传输和URL设置
5. 联系支持 带有日志和错误消息（请参见 支持 部分）

贡献

我们欢迎对Lumenore Analytics MCP服务器的贡献！请遵循以下指南：

行为准则

请注意，此项目随附 贡献者契约。通过参与，您将遵守此准则。

如何做出贡献

1. 分叉 仓库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

开发设置

# Clone your fork
git clone 
cd lumenore-mcp

# Install development dependencies
pip install -r requirements.txt

# Run tests (if available)
python -m pytest

报告Bug

使用 问题跟踪系统 报告bug。包括：

• 重现步骤
• 预期行为与实际行为
• 环境详细信息（Python版本、操作系统）

功能请求

我们欢迎通过GitHub Issues提出功能请求。拜托：

• 先搜索现有问题
• 提供清晰的用例
• 解释所需的功能

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

联系方式

如需技术支持和咨询：

• 电子邮件: askme@lumenore.com
• 网站: https://lumenore.com/
• 文档: Lumenore分析文档

______________________________________________________________________

版本: 1.0.0\ 最后更新：2026年1月\ python: 3.13+\ MCP协议：与MCP 2024-11-05规范兼容