文本预检服务 MCP 工具使用文档

概述

基于Model Context Protocol (MCP)框架实现的文本预检服务工具的使用方法。

MCP服务信息

• 服务名称: mcp-server
• 服务版本: 0.0.1
• 基础URL: https://mcp.vsbclub.com
• 协议: HTTPS + MCP
• 认证方式: X-API-KEY

认证配置

API密钥获取

1. 访问开放平台注册页面
2. 完成开发者认证
3. 创建应用并获取API密钥
4. 在MCP客户端配置中添加API密钥

客户端认证配置

在MCP客户端连接时，需要在请求头中携带API密钥：

// WebFlux SSE 客户端配置
var transport = new WebFluxSseClientTransport(
    WebClient.builder()
        .defaultHeader("X-API-KEY", "your_api_key_here")
        .baseUrl("https://api.vsbclub.com")
);

文本预检工具 (precheck)

工具描述

对输入的文本进行预检，判断是否符合业务要求。检查内容包括敏感词汇、语法错误、标点符号问题等，并提供修正建议。

工具参数

参数名	类型	必填	描述	示例
text	string	是	需要检查的文本内容	创建特色社会主义道路

检查内容类型

文本预检工具主要检查以下内容：

• 领导人称谓：检查国家领导人的正确称谓
• 官员称谓：检查政府官员的规范表述
• 敏感词汇：识别政治敏感、违规内容
• 语法错误：检查常见的语法和用词错误
• 标点符号：检查标点符号使用规范
• 禁用词汇：识别明确禁止使用的词汇

MCP工具调用示例

Java客户端调用

import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import java.util.Map;

// 调用文本预检工具
CallToolResult preCheckResult = client.callTool(
    new CallToolRequest("precheck",
        Map.of("text", "创建特色社会主义道路，为深入学习贯彻党的二十精神"))
);

System.out.println("预检结果: " + preCheckResult.content().get(0));

Python客户端调用

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def call_precheck_tool():
    server_params = StdioServerParameters(
        command="java",
        args=[
            "-Dspring.ai.mcp.server.stdio=true",
            "-jar", "mcp-server.jar"
        ],
        env={"X_API_KEY": "your_api_key_here"}
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            result = await session.call_tool(
                "precheck",
                {"text": "创建特色社会主义道路，为深入学习贯彻党的二十精神"}
            )
            print(f"预检结果: {result.content}")

asyncio.run(call_precheck_tool())

返回数据格式

{
  "code": 200,
  "msg": "ok",
  "precheck": {
    "leader": [],
    "officer": [],
    "forbidden": [],
    "grammar_word": [],
    "sensitive": [
      {
        "word": "党的二十",
        "correct": ["党的二十大"],
        "misdescription": null,
        "category": "中国共产党相关表述",
        "sentence": "为深入学习贯彻党的二十精神",
        "explain": null,
        "startInSentence": 9,
        "riskLevel": "middle",
        "level": "疑似错误",
        "start": 9,
        "end": 13,
        "priority": 2,
        "typeNum": 1
      }
    ],
    "punctuation": [],
    "urlBody": null,
    "wordNum": 481
  }
}

返回字段说明

字段名	类型	描述
code	int	响应状态码，200表示成功
msg	string	响应消息
precheck	object	预检结果对象
precheck.leader	array	领导人称谓检查结果
precheck.officer	array	官员称谓检查结果
precheck.forbidden	array	禁用词检查结果
precheck.grammar_word	array	语法词检查结果
precheck.sensitive	array	敏感词检查结果
precheck.punctuation	array	标点符号检查结果
precheck.urlBody	string	URL内容（如有）
precheck.wordNum	int	文本字数统计

检查项字段说明

每个检查项（leader、officer、forbidden、grammar_word、sensitive、punctuation）包含以下字段：

字段名	类型	描述
word	string	检测到的问题词汇
correct	array	建议的正确表述
misdescription	string	错误描述
category	string	问题分类
sentence	string	包含问题词汇的句子
explain	string	详细解释
startInSentence	int	在句子中的起始位置
riskLevel	string	风险等级：low/middle/high
level	string	错误级别：疑似错误/严重错误
start	int	在全文中的起始位置
end	int	在全文中的结束位置
priority	int	优先级
typeNum	int	类型编号

MCP客户端集成

WebFlux SSE客户端

import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.McpClient;
import org.springframework.web.reactive.function.client.WebClient;

// 创建WebFlux SSE传输
var transport = new WebFluxSseClientTransport(
    WebClient.builder()
        .defaultHeader("X-API-KEY", "your_api_key_here")
        .baseUrl("https://api.vsbclub.com")
);

// 创建MCP客户端
var client = McpClient.sync(transport).build();
client.initialize();

// 列出可用工具
var tools = client.listTools();
System.out.println("可用工具: " + tools);

// 调用工具
var result = client.callTool(new CallToolRequest("precheck",
    Map.of("text", "创建特色社会主义道路，为深入学习贯彻党的二十精神")));

Cherry Studio集成

在设置中添加MCP服务器，类型选择sse，目前不支持stdio,URL配置为：https://mcp.vsbclub.com/sse 请求头需要添加：X-API-KEY: your_api_key_here 添加完成点击开启，会开始自动初始化并加载工具列表，点开工具tab可以看到可用的工具列表

随后在聊天窗口即可使用

自定义MCP客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// 创建STDIO传输
const transport = new StdioClientTransport({
  command: 'java',
  args: [
    '-Dspring.ai.mcp.server.stdio=true',
    '-Dspring.main.web-application-type=none',
    '-Dlogging.pattern.console=',
    '-jar', 'mcp-server.jar'
  ],
  env: {
    X_API_KEY: 'your_api_key_here'
  }
});

// 创建客户端
const client = new Client({
  name: "example-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

// 连接并使用
await client.connect(transport);

// 调用工具
const result = await client.callTool({
  name: "precheck",
  arguments: {
    text: "创建特色社会主义道路，为深入学习贯彻党的二十精神"
  }
});

错误处理和故障排除

常见错误码

错误码	描述	解决方案
200	请求成功	-
401	认证失败	检查X-API-KEY是否正确配置
403	权限不足	确认API密钥有相应工具调用权限
429	请求频率超限	降低请求频率
500	服务器内部错误	联系技术支持
-1	业务逻辑错误	根据msg字段提示调整参数

文本长度限制

• 预检服务单次请求文本长度不超过5000字符

数据保留期限

• 预检结果不会被服务端保存

v1.0.0 (2024-12-19)

• 发布文本预检MCP工具
• 支持WebFlux SSE传输方式
• 统一使用X-API-KEY认证方式
• 提供多种客户端集成示例

---