北京
陈虎。真心想用集算器这样的工具降低程序员们的劳动强度，真心想成为高性能复杂计算、大数据计算编程难题的终结者。
17 浏览  • 
     ...

NLQ MCP 本地服务部署向导

 

1.目标

在已经部署好的NLQ 服务器（包含权限控制）上添加MCP 服务，让办公电脑上的 AI 助手 WorkBuddy 能通过 MCP 连上 NLQ 服务。需要查询的最终用户就可以在WorkBuddy 上用自然语言查数据、取结果。

如需了解NLQ 服务器的部署（包含权限控制），请参考：

WorkBuddy 自动化实施润乾 NLQ 向导 - 以保险主题为例

润乾报表> 分析教程 > 基础查询 / 分析 > 权限控制

2.MCP 的工作过程

动手操作之前先了解MCP 工作过程原理。

2.1.登录过程

MCP 工作过程中涉及两种用户，要注意区分：

名称

说明

DQL 用户

是指MCP 服务连接 DQL 服务的用户。

相当于数据库用户，DQL 服务可以控制每个用户的数据权限。

每个DQL 用户可以对应多个 MCP 用户。

MCP 用户

是指使用WorkBuddy 查询的最终用户，用于登录 MCP。

每个MCP 用户对应一个 DQL 用户。

登录过程：

1.WorkBuddy访问 MCP服务

2.MCP服务返回：未登录/ 鉴权失败

3.WorkBuddy 打开登录页面，最终用户输入、提交MCP用户名密码

4.服务器校验账号密码，确定用哪个DQL 用户，把这个DQL 用户返回给WorkBuddy

5.WorkBuddy后续查询就用这个DQL 用户连接DQL 服务，DQL 服务根据权限返回结果

其中第4 步是可编程的，可以根据实际应用的需要，编码实现用户名密码的校验、确定对应的 DQL 用户，具体编程方法在后面的实操中。

实际应用中登录校验的方式多种多样，例如：数据库用户表、LDAP/AD 域账号、统一认证平台 /SSO、短信验证码、企业微信 / 钉钉 / 微信扫码等。MCP 服务不可能把所有登录方式都写死，所以提供了这种可编程入口。

2.2.查询过程

1.WorkBuddy 收到用户的自然语言提问，例如 "查询每个客户的保单数"

2.WorkBuddy 按 nlq SKILL 的规则，把自然语言转成的 NLQ 语句，例如 查询 "客户，保单 数"

3.WorkBuddy 通过 MCP 把这段 NLQ 语句提交给服务器

4.服务器用登录时确定的 DQL 用户连库执行，把结果集返回给 WorkBuddy

5.WorkBuddy 把结果整理成表格，呈现给用户

3.实际操作

3.1.需求简述

一家保险公司，客服分三个权限组：北京客服只能查北京保单、上海客服只能查上海保单、管理员查全部保单。

服务器上已经部署了NLQ保单查询系统，现在要接上 MCP，让客服用自然语言问数，同时保证数据权限隔离。

管理员：Tom

北京客户服务：Sam、Jack

上海客户服务：Rose

为了测试简单，所有密码和用户名相同。

3.2.环境

服务器：

NLQ 应用的访问地址http://192.168.1.8:6868/demo

NLQ 数据源名称：NLQ4insurance

其中DQL 已经实现配置了三个用户（密码和用户名相同）：

"DQLroot" 管理员，查全部保单

"DQLuserBeijing" 北京客服，查北京保单

"DQLuserShanghai" 上海客服，查上海保单

办公电脑：

已经安装好WorkBuddy

3.3.服务器实操

3.3.1.配置 MCP 服务

在 C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF中找到web.xml，增加与 MCP 相关的配置：

① 服务对外基址（nlqcr.publicBaseUrl，用于拼接登录页 /authorize等 URL，写成你的服务器实际地址，不带尾部斜杠、不带 /mcp）：

<context-param>
    <param-name>nlqcr.publicBaseUrl</param-name>
    <param-value>http://192.168.1.8:6868/demo</param-value>
</context-param>

② 是否要求登录（nlqcr.requireLogin，保持 true）：

<context-param>
    <param-name>nlqcr.requireLogin</param-name>
    <param-value>true</param-value>
</context-param>

③ 注册 MCP 端点（把 /mcp路径绑定到 McpServlet，这就是 MCP 服务的入口）：

<servlet>
    <servlet-name>mcp</servlet-name>
    <servlet-class>com.raqsoft.mcp.McpServlet</servlet-class>
    <async-supported>true</async-supported>
</servlet>
<servlet-mapping>
    <servlet-name>mcp</servlet-name>
    <url-pattern>/mcp</url-pattern>
</servlet-mapping>

④ 注册认证端点（把 /authorize、/token绑定到登录程序 LoginServlet)：

<servlet>
    <servlet-name>auth</servlet-name>
    <servlet-class>LoginServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>auth</servlet-name>
    <url-pattern>/authorize</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>auth</servlet-name>
    <url-pattern>/token</url-pattern>
</servlet-mapping>

3.3.2.实现登录管理

⚫️增加文件mcp.cfg

编辑一个文本文件mcp.cfg，放到服务器 class 目录

C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes

这个文件用来存储NLQ 数据源的名称和 DQL 用户的用户名、密码：

NLQ4insurance
DQLroot,DQLroot
DQLuserBeijing,DQLuserBeijing
DQLuserShanghai,DQLuserShanghai

说明：第一行是NLQ 数据源的名称。第二行开始是 DQL 用户名和密码。

⚫️增加LoginServlet.java并编程

点击这里下载 LoginServlet.java

放 在服务器 这个位置：

C:\Program Files\raqsoft\report\web\webapps\demo\WEB-INF\classes\LoginServlet.java

修改方法 authenticate，编程实现校验MCP用户、返回DQL 用户。简单示例代码：

private String authenticate(String username, String password) {
    if ("Tom".equals(username) && "Tom".equals(password)) {
        return "DQLroot"; // 管理员，查全部保单
    } else if ("Sam".equals(username) && "Sam".equals(password)) {
        return "DQLuserBeijing"; // 北京客服，查北京保单
    } else if ("Jack".equals(username) && "Jack".equals(password)) {
        return "DQLuserBeijing"; // 北京客服，查北京保单
    } else if ("Rose".equals(username) && "Rose".equals(password)) {
        return "DQLuserShanghai"; // 上海客服，查上海保单
    }
    return null; // 账号或密码不对，登录失败
}

编译后，class 文件也放到用 classes 目录下。

在实际项目中，可以根据情况，把示例代码改成需要的用户密码校验和用户映射代码。

3.4.办公电脑实操

3.4.1.安装 nlq SKILL

从润乾 NLQ 查询演示页 http://query.raqsoft.com.cn:6999/nlq4tpch.html点击“下载 MCP SKILL”按钮，下载 SKILL 压缩包 nlqdemoskill.zip，解压后是一个 nlq目录：

文件

作用

SKILL.md

主技能文件：触发词、处理流程、MCP 调用方式

references/grammar-spec.md

NLQ/NSPL 语法规则、查询范式

references/field-dictionary.md

表/ 字段 / 维词 / 常数词 / 指标词典

scripts/nlq_login.py

OAuth 登录辅助脚本

注意：这个 zip 默认是用来连润乾公网演示服务器的，用之前要修改references/field-dictionary.md，文件内容换成保险数据集的词典信息，包括表名、字段名、维词和指标等。

词典信息从NLQ 的 IDE- 菜单 - 工具 - 词典信息中获取：

..

安装方式一：压缩包安装

把改好的 nlq目录打包成zip 文件，在 WorkBuddy 侧边栏中选择「专家·技能·连接器」→「技能」，在右上角选择「添加技能」→「上传技能」：

..

在导入技能窗口的左下角，点击「选择ZIP 文件」：

..

如果zip 文件中的 nlq 技能当前不存在，WorkBuddy 将从技能文件中识别出技能介绍，可以继续安装：

..

安装成功后，在列表中，即可看到导入的技能：

..

方式二：复制文件安装

把改好的 nlq目录复制到项目根目录 .workbuddy/skills/下（项目级，团队共用），或 ~/.workbuddy/skills/（用户全局），WorkBuddy 会自动识别。

3.4.2.配置 mcp.json

①在 WorkBuddy 侧边栏点击「专家·技能·连接器」→「连接器」：

..

②在右上角点击「自定义连接器」→「配置 MCP」：

..

③编辑 mcp.json（项目级或用户级），添加 MCP 服务配置，名称用 NLQ-MCP：

{
    "mcpServers": {
        "NLQ-MCP": {
            "url": "http://192.168.1.8:6868/demo/mcp",
            "disabled": false,
            "description": "NLQ 保单查询服务"
        }
    }
}

④保存后，在我的 MCP 中找到 NLQ-MCP，点击「信任 / 启用」，状态变为绿色即连接成功。

..

..

3.5.查询验证

①查询：查询 "客户，保单 数"。

②首次登录或者登录查实：WorkBuddy 打开浏览器:

..

③用 MCP 账号（Tom / Sam / Jack / Rose）登录，不要用 DQL 账号。

....

④重启NLQ 服务，换MCP 用户登录验证权限隔离：Sam 登录查不到上海保单，Rose 查不到北京保单，Tom 查全部。