自然语言分析服务器

基于Model Context Protocol (MCP)的服务器,为AI助手提供自然语言查询和高级分析功能,支持实时数据处理和零数据存储。

  • by Lumenore-Platform
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Lumenore-Platform/lumenore-mcp

使用说明

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"

配置参数

参数 必填 说明 默认值
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桌面版

  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: <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的客户端或向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 <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许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

联系方式

如需技术支持和咨询:


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