内容
# 🏦 贷款风险评估 — 替代信用智能平台
> **我们可以安全地向这位客户贷款吗？**
贷款风险评估是一款适用于金融科技贷款审核的生产级 **替代信用智能** 平台。它通过评估行为金融数据来做出可解释的贷款决策，而无需依赖 CIBIL 评分、工资单、所得税申报表或正式就业记录。
[](https://altcredit-apis.onrender.com/api/health)
[](https://altcredit-mcp.onrender.com/health)
[](https://modelcontextprotocol.io)
[](./LICENSE)
---
## 📋 目录
- [业务背景](#业务背景)
- [系统架构](#系统架构)
- [信用评分流程](#信用评分流程)
- [数据库模式](#数据库模式)
- [部署架构](#部署架构)
- [MCP 客户端设置](#mcp-客户端设置)
- [API 参考](#api-参考)
- [快速入门](#快速入门)
- [技术栈](#技术栈)
---
## 业务背景
业务问题
问题
数百万的自主经营者和非薪水人员，包括小商店老板、外卖员、出租车司机、自由职业者、街头小贩和小商户，由于缺乏传统的信用指标，如工资单、正式就业记录或 CIBIL 历史记录，而被拒绝贷款。
因此：
- 尽管有健康的财务习惯，但好的借款人却被拒绝。
- 贷款官员花费大量时间手动审核申请。
- 金融科技公司难以区分值得信赖的借款人和风险借款人。
- 信用决策往往不一致且难以解释。
传统的贷款审核依赖于历史信用记录，而不是实际的财务行为，这使得大量服务不足的人口无法公平地获得信贷。
## 解决方案
服务于 **自主经营和非正式收入客户** 的金融科技公司需要审核缺乏以下条件的用户：
- 传统的 CIBIL/信用评分
- 工资单或正式所得税申报表
- 长期信用记录
贷款风险评估分析 **行为金融信号**：
| 信号 | 测量内容 |
|--------|-----------------|
| 交易一致性 | 收入存款的规律性 |
| 储蓄纪律 | 存款与取款比率 |
| 现金流稳定性 | 每月流入/流出余额 |
| 交易失败率 | 支付可靠性 |
| 取款行为 | 大额/频繁取现模式 |
| 流动性缓冲 | 应急基金可用性 |
**输出：** `批准` / `审核` / `拒绝`，并附有推荐的贷款金额和易于理解的解释。
MCP 服务器通过标准化的 MCP 工具提供此智能，使 Claude Desktop、Cursor 和内部金融科技应用等 AI 助手能够执行可解释的信用分析。
## 系统架构
```mermaid
flowchart TB
subgraph USERS["终端用户/客户端"]
direction TB
U1["Claude Desktop"]
U2["Cursor IDE"]
U3["贷款官员 UI"]
U4["创始人仪表盘"]
end
subgraph CLIENT["MCP 客户端"]
direction TB
Q["自然语言请求"]
end
subgraph SERVER["替代信用智能 MCP 服务器"]
direction TB
T1["分析信用度"]
T2["分析财务行为"]
T3["生成贷款审核报告"]
end
subgraph GRAPH["LangGraph 多智能体工作流"]
direction TB
Loader["用户上下文加载器"]
Transaction["交易代理"]
Savings["储蓄代理"]
Behavior["行为代理"]
Risk["风险代理"]
Decision["信用决策代理"]
Explanation["解释代理"]
Loader --> Transaction
Loader --> Savings
Transaction --> Behavior
Savings --> Behavior
Behavior --> Risk
Risk --> Decision
Decision --> Explanation
end
subgraph API["Express 后端"]
direction TB
Controllers["控制器"]
Services["服务"]
Repositories["存储库"]
end
subgraph DATABASE["PostgreSQL"]
direction TB
Users["用户"]
Transactions["交易"]
SavingsTable["储蓄历史"]
Reports["贷款审核报告"]
Audit["审计日志"]
end
USERS --> CLIENT
CLIENT --> SERVER
SERVER --> GRAPH
GRAPH --> API
API --> DATABASE
DATABASE --> SERVER
```
## 信用评分流程
```mermaid
flowchart LR
IN(["用户 ID"]) --> UA["assertUserExists()"]
UA -->|found| TA["交易服务\n最近 6 个月数据"]
UA -->|not found| ERR(["isError: true\n用户未找到"])
TA --> TX["交易摘要\n总交易笔数\n失败交易笔数\n每月流入/流出\n收入一致性评分"]
IN --> SA["储蓄服务\n所有历史记录"]
SA --> SV["储蓄摘要\n总存款/取款\n当前余额\n存款次数"]
TX --> S1["交易一致性评分\n× 0.35"]
SV --> S2["储蓄纪律评分\n× 0.40"]
TX --> S3["现金流稳定性评分\n× 0.25"]
S1 --> WA["加权总评分\n0 至 100"]
S2 --> WA
S3 --> WA
WA --> CS["信用评分\n加/减调整\n用于奖励/惩罚"]
CS --> RISK["风险等级\n70+ = 低风险\n40-69 = 中风险\n低于 40 = 高风险"]
RISK --> DEC["决策\n低风险 + 60 = 批准\n中风险 + 40 = 审核\n否则 = 拒绝"]
DEC --> AMT["推荐金额\n低风险 × 0.7\n中风险 × 0.5\n高风险 × 0.2"]
DEC --> OUT(["贷款审核报告\n保存到数据库"])
RISK --> OUT
AMT --> OUT
```
### 评分公式
```
信用评分 = (交易一致性 × 0.35)
+ (储蓄纪律 × 0.40)
+ (现金流稳定性 × 0.25)
```
### 风险和决策表
| 评分 | 风险等级 | 决策 | 最大贷款金额 |
|-------|-----------|----------|----------|
| ≥ 70 | 低风险 | **批准** | 最高 ₹2,00,000 |
| 40–69 | 中风险 | **审核** | 最高 ₹75,000 |
| < 40 | 高风险 | **拒绝** | 不适用 |
## 数据库模式
```mermaid
erDiagram
users {
UUID id PK
VARCHAR 名称
VARCHAR 电话 UK
VARCHAR 职业
VARCHAR 雇主名称
DECIMAL 月收入
TIMESTAMP 创建时间
TIMESTAMP 更新时间
}
transactions {
UUID id PK
UUID user_id FK
DECIMAL 金额
VARCHAR 类型
VARCHAR 状态
VARCHAR 类别
TEXT 描述
TIMESTAMP 时间戳
}
savings_history {
UUID id PK
UUID user_id FK
DECIMAL 存款金额
DECIMAL 取款金额
DECIMAL 余额
TIMESTAMP 创建时间
}
underwriting_reports {
UUID id PK
UUID user_id FK
INTEGER 信用评分
VARCHAR 风险等级
DECIMAL 推荐金额
VARCHAR 推荐
TEXT 解释
JSONB 详情
TIMESTAMP 创建时间
}
audit_logs {
UUID id PK
UUID user_id FK
VARCHAR 操作
VARCHAR 资源
JSONB 详情
VARCHAR IP 地址
TIMESTAMP 创建时间
}
users ||--o{ transactions : "拥有"
users ||--o{ savings_history : "拥有"
users ||--o{ underwriting_reports : "拥有"
users ||--o{ audit_logs : "拥有"
```
## 部署架构
```mermaid
graph TB
subgraph DEV["本地开发"]
CODE["源代码"]
CSV["CSV 数据集\n用户 · 交易 · 储蓄"]
SEED["npm run seed"]
end
subgraph GH["GitHub"]
REPO["Ppp111ppp111/LoanRiskLens_MCP\n分支：main"]
end
subgraph RENDER["Render.com"]
SVC1["altcredit-apis\nNode.js · 端口 3000\nnpm run dev"]
SVC2["altcredit-mcp\nNode.js · 端口 3001\nnpm run dev:mcp"]
end
subgraph SUPABASE["Supabase"]
PG["PostgreSQL\naws-ap-southeast-1\n连接池"]
end
CODE -- "git push" --> REPO
REPO -- "自动部署" --> SVC1
REPO -- "自动部署" --> SVC2
SVC1 -- "DATABASE_URL" --> PG
SVC2 -- "DATABASE_URL" --> PG
CSV --> SEED
SEED -- "插入" --> PG
```
## MCP 客户端设置
将以下内容添加到您的 MCP 客户端配置中 - 适用于 **Claude Desktop**、**Cursor** 和任何 MCP 兼容的客户端：
```json
{
"mcpServers": {
"LoanRiskLens": {
"url": "https://altcredit-mcp.onrender.com/mcp"
}
}
}
```
| 客户端 | 配置文件 (macOS) |
|--------|---------------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |
### 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `analyze_creditworthiness` | 信用评分、风险等级、贷款金额、决策 |
| `analyze_financial_behavior` | 行为概况、储蓄评分、现金流、取款模式 |
| `generate_underwriting_report` | 完整报告 - 以上所有内容 + 评分明细，保存到数据库 |
### Claude 示例提示
```
分析用户 550e8400-e29b-41d4-a716-446655440001 的信用度
为用户 ID 550e8400-e29b-41d4-a716-446655440001 生成完整的贷款审核报告
检查用户 85919b78-ec7d-4d17-8e67-6a02ebfca84a 的财务行为概况
```
> **注意：** Render 免费层可能在不活动后 30-60 秒内首次请求时出现冷启动。
## API 参考
### 信用端点
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/api/credit/analyze/:userId` | 运行信用度分析 |
| `GET` | `/api/credit/behavior/:userId` | 获取财务行为概况 |
| `POST` | `/api/credit/report/:userId` | 生成并保存贷款审核报告 |
### 其他端点
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/api/health` | API 健康检查 |
| `GET` | `/api/users/:id` | 获取用户信息 |
| `GET` | `/api/transactions/:userId` | 列出用户交易记录 |
| `GET` | `/api/savings/:userId` | 列出储蓄历史记录 |
## 快速入门
```bash
# 1. 克隆并安装
git clone https://github.com/Ppp111ppp111/LoanRiskLens_MCP.git
cd LoanRiskLens_MCP
npm install
# 2. 配置环境
cp .env.example .env
# 编辑 .env - 设置 DB_HOST, DB_NAME, DB_USER, DB_PASSWORD
# 3. 初始化模式并导入演示数据
npm run seed
# 4. 启动 API 服务器（端口 3000）
npm run dev
# 5. 启动 MCP 服务器（端口 3001，独立终端）
npm run dev:mcp
# 6. 运行测试
npm test
```
### 项目结构
```
LoanRiskLens_MCP/
├── apps/
│ └── api/ # Express REST API (端口 3000)
│ ├── src/controllers/ # 路由处理程序
│ ├── src/services/ # 业务逻辑（creditService 等）
│ ├── src/repositories/ # 数据库访问层
│ └── src/middleware/ # 认证、安全、错误处理
├── packages/
│ └── mcp-server/ # HTTP JSON-RPC MCP 服务器（端口 3001）
│ ├── src/server/ # mcpServer.js - JSON-RPC 路由器
│ └── src/tools/ # creditTools.js - 工具定义
├── credit-engine/ # 纯评分和逻辑分析
│ ├── src/scoring/ # 评分计算器
│ └── src/analysis/ # 风险分类器、概况分析器
├── langgraph-workflows/ # 6 智能体顺序工作流
│ ├── src/agents/ # 单个智能体类
│ └── src/workflows/ # CreditIntelligenceWorkflow
├── shared/ # 公共模块
│ ├── src/config/ # 应用程序配置
│ ├── src/database/ # pg Pool + 模式初始化
│ └── src/utils/ # 帮助程序、日志记录器、验证器
├── scripts/
│ └── seed-datasets.js # CSV → PostgreSQL 导入脚本
└── docs/ # 文档
```
## 技术栈
| 层 | 技术 |
|-------|-----------|
| 运行时 | Node.js 18+ |
| API 框架 | Express.js |
| 协议 | MCP（模型上下文协议）- HTTP JSON-RPC 2.0 |
| 智能体工作流 | LangGraph 风格的 6 智能体流水线 |
| 数据库 | PostgreSQL（Supabase 主机）|
| 认证 | JWT + RBAC |
| 验证 | Joi |
| 日志记录 | Winston |
| 测试 | Jest |
| 部署 | Render.com（从 GitHub 自动部署） |
## 文档
| 文档 | 描述 |
|-----|-------------|
| [智能体上下文指南](docs/AGENT_CONTEXT.md) | 业务背景、演示问题、预期结果 |
| [设置指南](docs/SETUP.md) | 本地开发设置 |
| [架构](docs/ARCHITECTURE.md) | 详细技术架构 |
| [LangGraph 工作流](docs/LANGGRAPH.md) | 智能体流水线详情 |
| [MCP 集成](docs/MCP_INTEGRATION.md) | MCP 服务器集成指南 |
| [API 文档](docs/API.md) | 完整 API 参考 |
