Lumenore Mcp

Lumenore Analytics MCP 服务

一个 Model Context Protocol (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 助手

• URL：http://localhost:8080/mcp
• 传输方式：Streamable 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"

配置参数

参数	必填	说明	默认值
LUMENORE_CLIENT_ID	是	用于客户端凭据身份验证的客户端 ID	无
LUMENORE_SECRET	是	用于客户端凭据身份验证的客户端密钥	无
SERVER_URL	否	Lumenore 服务 URL	https://preview.lumenore.com

运行服务

启动 MCP 服务：

python main.py

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

连接 AI 助手

Claude for Desktop

1. 设置 → MCP Servers
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
})

连接详情：

• 协议：MCP 2024-11-05+
• 传输方式：Streamable 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 文件中

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

安全最佳实践

身份验证问题排查

“Authorization token missing or invalid”：

• 确认凭据已设置在 .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. 缓存常用查询以提升性能

使用示例

以下是三个真实示例，展示 AI 助手如何与 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. 性能：缓存频繁访问的数据，以缩短响应时间

Claude 提示词

连接到此 MCP 服务时，可以向 Claude 提供以下示例提示词：

用于销售分析：

“使用 Lumenore Analytics 工具分析我们的 Q4 销售业绩。我需要查看各地区的明细，找出表现最佳的产品，并了解销售趋势。”

用于客户洞察：

分析客户人口统计特征，找出任何异常的购买模式，并确定影响客户价值的因素。使用可用的分析工具提供全面的洞察。”

用于库存管理：

“预测下一季度的情况，并使用预测和趋势分析工具识别近期需求行为的任何变化。”

---

错误处理

所有工具均实现了全面的错误处理，并针对具体错误类型进行处理：

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

# Service errors
{
    "error": "<Operation> failed: <details>",
    "status": "error",
    "query": "<user_query>",
    "schema_id": <schema_id>
}

测试服务

你可以使用任何兼容 MCP 的客户端测试 MCP 服务，也可以向 SSE 端点发送 HTTP 请求：

# 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：符合《通用数据保护条例》
• CCPA：符合《加州消费者隐私法案》
• 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 允许列表
• 使用 VPN 或专用网络进行服务通信

漏洞管理

报告安全问题

我们高度重视安全问题。如果您发现漏洞：

1. 发送邮件至：[email protected]
2. 提供漏洞详情和复现步骤
3. 我们将在 24 小时内确认收到
4. 请在公开披露前与我们合作解决问题

安全更新

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

数据加密

传输中

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

静态数据

• 后端数据存储采用静态加密
• 数据库加密可保护存储的分析数据
• 密钥管理遵循行业最佳实践

访问控制

最小权限原则

• 客户端凭据应仅具备所需的最低权限
• 为不同的应用和环境使用单独的凭据
• 定期审查凭据的权限和使用情况

网络安全

• 防火墙规则仅允许访问必要的端口
• 考虑为服务器管理实施 VPN 访问
• 在生产部署中使用网络分段

---

故障排除

快速诊断步骤

1. 检查服务是否正在运行：curl -I http://localhost:8080
2. 确认令牌已加载：检查服务启动日志中是否有 "No authorization token" 警告
3. 测试后端连通性：curl -I https://preview.lumenore.com
4. 检查 MCP 协议：确保客户端使用 Streamable 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 Server 贡献！请遵循以下指南：

行为准则

请注意，本项目依据 Contributor Covenant 发布。参与本项目即表示你应遵守此准则。

如何贡献

1. Fork 此代码仓库
2. 创建 功能分支（git checkout -b feature/amazing-feature）
3. 提交 你的更改（git commit -m 'Add amazing feature'）
4. 推送 到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发环境设置

# Clone your fork
git clone <your-fork-url>
cd lumenore-mcp

# Install development dependencies
pip install -r requirements.txt

# Run tests (if available)
python -m pytest

报告 Bug

使用 问题跟踪器 报告 Bug。请提供：

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

功能请求

欢迎通过 GitHub Issues 提交功能请求。请：

• 先搜索现有问题
• 提供清晰的使用场景
• 说明所需的功能

许可证

本项目采用 MIT License 授权，详情请参见 LICENSE 文件。

支持

联系方式

如需技术支持或有任何疑问：

• 邮箱：[email protected]
• 网站：https://lumenore.com/
• 文档：Lumenore Analytics 文档

---

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