风控评估 MCP Server（TypeScript 版）

本地部署的风控评估 MCP (Model Context Protocol) Server，基于 TypeScript 实现，内置 AI 推理能力（OpenAI API）和网络搜索能力（Serper API）。通过 stdio 模式运行，可直接在 Kiro、Qodo 等 AI 工具中调用。

Server 对外暴露 3 个高层 Tool，覆盖风控评估完整流程：材料提取 → 报告生成 → AI 对话优化报告。每个 Tool 内部自行完成所有 AI 调用和编排，无需外部数据库或持久化存储。

环境要求

• Node.js 18+
• npm 或 npx

快速开始

方式一：npx 一键运行（推荐）

无需手动安装，直接在 mcp.json 中配置即可。npx 会自动下载包并启动 Server。

方式二：全局安装

npm install -g @wangzhenhao123/risk-control-mcp-server

安装后可直接运行：

OPENAI_API_KEY=sk-xxx SERPER_API_KEY=xxx risk-control-mcp-server

方式三：从源码构建

git clone https://your-gitlab.com/team/risk-control-mcp-server-ts.git
cd risk-control-mcp-server-ts
npm install
npm run build
node dist/index.js

环境变量配置

| 环境变量 | 必填 | 说明 | 默认值 | |---------|------|------|--------| | OPENAI_API_KEY | ✅ | OpenAI API 密钥 | — | | SERPER_API_KEY | ✅ | Serper 网络搜索 API 密钥 | — | | AI_MODEL | ❌ | AI 模型名称 | gpt-5.3-chat-latest | | OPENAI_BASE_URL | ❌ | OpenAI API 基础 URL | http://aws-egress-gateway.t1.test.noahgrouptest.sg/openai/v1 | | SERPER_BASE_URL | ❌ | Serper API URL | https://google.serper.dev/search |

缺少必填环境变量时，Server 启动会输出错误信息并终止进程。

MCP 配置示例

Kiro 配置（npx 方式，推荐）

在项目根目录 .kiro/settings/mcp.json 中添加：

{
  "mcpServers": {
    "risk-control": {
      "command": "npx",
      "args": ["-y", "@wangzhenhao123/risk-control-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "SERPER_API_KEY": "xxx"
      }
    }
  }
}

Kiro 配置（全局安装方式）

{
  "mcpServers": {
    "risk-control": {
      "command": "risk-control-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "SERPER_API_KEY": "xxx"
      }
    }
  }
}

Kiro 配置（本地路径方式）

{
  "mcpServers": {
    "risk-control": {
      "command": "node",
      "args": ["D:/path/to/risk-control-mcp-server-ts/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "SERPER_API_KEY": "xxx"
      }
    }
  }
}

Qodo 配置（npx 方式）

{
  "mcpServers": {
    "risk-control": {
      "command": "npx",
      "args": ["-y", "@wangzhenhao123/risk-control-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "SERPER_API_KEY": "xxx"
      }
    }
  }
}

Claude Code 配置（npx 方式）

{
  "mcpServers": {
    "risk-control": {
      "command": "npx",
      "args": ["-y", "@wangzhenhao123/risk-control-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-xxx",
        "SERPER_API_KEY": "xxx"
      }
    }
  }
}

Tool 说明

1. extract_materials — 材料提取

从文件中提取并格式化内容。传入文件的本地绝对路径列表和材料提取提示词，返回格式化后的 Markdown 内容。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | file_paths | string[] | ✅ | 文件本地路径列表（最多 10 个） | | material_prompt | string | ✅ | 材料提取提示词，指导 AI 如何提取文件内容 |

2. generate_report — 报告生成

基于材料内容生成风控评估报告。内部流程：生成搜索锚点 → 网络搜索交叉验证 → 三步校验法 → 输出报告。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | materials_content | string | ✅ | extract_materials 返回的材料提取内容 | | review_prompt | string | ✅ | 评审提示词，指导文件内部一致性比对规则 | | report_output_prompt | string | ✅ | 报告输出提示词，指导报告的输出格式和结构 |

3. optimize_report — 报告优化

通过 AI 对话优化已生成的风控报告。先校验用户消息是否与报告相关，相关则进行优化处理。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | report_content | string | ✅ | 当前报告内容 | | user_message | string | ✅ | 用户的优化指令或问题 | | conversation_history | {role, content}[] | ❌ | 对话历史，格式 [{"role": "user"|"assistant", "content": "..."}] |

支持的文件格式

| 格式 | 后缀 | 解析方式 | |------|------|---------| | PDF | .pdf | mupdf 转页面图片 → OpenAI 多模态 API | | 图片 | .png .jpg .jpeg | 二进制读取 → OpenAI 视觉 API | | Word | .docx .doc | mammoth 提取文本 → OpenAI 结构化提取 | | Excel | .xlsx .xls | exceljs 提取表格 → OpenAI 结构化提取 | | PPT | .pptx | jszip + XML 解析 → OpenAI 结构化提取 |

.doc 和 .xls 为旧格式，解析可能失败，建议转换为 .docx / .xlsx 后使用。

发布到 npm

前置条件

1. 注册 npm 账号
2. 本地登录 npm：

npm login

发布步骤

# 1. 进入项目目录
cd risk-control-mcp-server-ts

# 2. 安装依赖
npm install

# 3. 构建（prepublishOnly 会自动执行，但建议先手动确认）
npm run build

# 4. 检查将要发布的文件（确认只包含 dist/ 目录）
npm pack --dry-run

# 5. 发布（scope 包首次发布必须加 --access public，package.json 中已配置也可省略）
npm publish --access public

当前包名为 scope 包 @wangzhenhao123/risk-control-mcp-server，scope 包首发时必须指定 --access public，否则会报 402 Payment Required。

更新版本

# 补丁版本 0.1.0 → 0.1.1
npm version patch

# 次版本 0.1.0 → 0.2.0
npm version minor

# 主版本 0.1.0 → 1.0.0
npm version major

# 发布新版本
npm publish

使用私有 npm registry

如果使用公司内部 registry（如 Verdaccio、GitLab npm registry），在项目根目录创建 .npmrc：

registry=https://your-registry.example.com/
//your-registry.example.com/:_authToken=${NPM_TOKEN}

然后发布：

npm publish --registry https://your-registry.example.com/

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 本地调试运行
OPENAI_API_KEY=sk-xxx SERPER_API_KEY=xxx node dist/index.js

项目结构

risk-control-mcp-server-ts/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts              # 入口（stdio transport）
│   ├── config.ts             # 环境变量配置
│   ├── server.ts             # MCP Server 注册
│   ├── clients/
│   │   ├── openai-client.ts  # OpenAI API 封装
│   │   └── serper-client.ts  # Serper 搜索 API 封装
│   ├── parsers/
│   │   └── file-parser.ts    # 文件解析器
│   ├── prompts/
│   │   └── templates.ts      # Prompt 模板常量
│   └── tools/
│       ├── extract-materials.ts  # 材料提取工具
│       ├── generate-report.ts    # 报告生成工具
│       └── optimize-report.ts    # 报告优化工具
└── dist/                     # 编译输出（发布到 npm）