内容
---
title: Creddy
emoji: 📊
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---
<p align="center">
<img src="creedymcplogo.png" alt="Creddy logo" width="160" />
</p>
# Creddy
[](https://smithery.ai/server/onatozmen44/creddy-mcp)
[](https://github.com/onatozmenn/creddy-mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://www.python.org)
**一款用于Claude和ChatGPT的信用风险分析MCP服务器。**
通过自然语言提问 → 它会编写**安全、只读的SQL**，查询超过**30,000条真实标记的信用记录**，使用可解释的模型评估**违约风险**，并从土耳其央行（TCMB）**获取实时数据** — 所有操作都基于模型上下文协议。
> ⚠️ **免责声明：** 本项目为教育/作品集项目。标记的数据是公开的UCI“信用卡客户违约”数据集（台湾，2005年）。它**不是**真正的贷款系统，不应用于实际的信用决策。
## 💬 示例问题
向您的助手提问：
- *"按教育程度划分的违约率是多少？"* → `run_query`
- *"24岁，信用额度20k，9月份延迟2个月 — 这个客户会违约吗？"* → `predict_default`
- *"风险模型的表现如何（AUC，召回率）？"* → `model_metrics`
- *"信用额度较高的客户违约率较低吗？"* → `run_query`
- *"当前的美元、欧元和黄金价格是多少？"* → `tcmb_indicators` *(实时TCMB)*
- *"查找TCMB关于信用卡消费的系列。"* → `tcmb_search` *(实时TCMB)*
- *"数据中有哪些列？"* → `describe_schema`
答案来自**真实的标记数据**和**实际训练的模型** — 而不是猜测。
## 👥 适用人群
| 角色 | 开始使用 | 原因 |
| --- | --- | --- |
| **风险分析师** | `predict_default` · `model_metrics` | 评估借款人的风险并查看决策背后的有符号驱动因素 |
| **数据科学家** | `run_query` · `describe_schema` | 使用安全的SQL探索30,000条标记记录，无写入风险 |
| **BNPL / 信用运营** | `tcmb_indicators` · `tcmb_search` | 获取实时的土耳其宏观经济背景（利率，外汇，信用卡消费）用于信用审核 |
## 🧰 工具（9）
| 工具 | 功能 |
| --- | --- |
| `list_tables` | 列出数据库表 |
| `describe_schema` | 列出列 + 类型，用于生成安全的SQL |
| `run_query` | 验证 + 执行只读`SELECT`查询，查询`credit_clients` |
| `predict_default` | 预测客户的违约概率 + 风险因素 |
| `model_metrics` | 训练模型的AUC / 精确率 / 召回率和关键驱动因素 |
| `tcmb_indicators` | **实时**土耳其经济指标（美元，欧元，黄金，利率...） — 无密钥 |
| `tcmb_search` | 在TCMB EVDS目录中搜索系列（密钥认证） |
| `tcmb_series` | 通过公共REST API获取特定的EVDS时间序列（密钥 + 当前端点） |
| `example_questions` | 建议的问题 |
## 🚀 连接（无需安装）
服务器**在线**（Hugging Face Spaces）— 大多数人无需设置。请选择您的客户端：
### ChatGPT
1. ChatGPT → **设置 → 连接器 → 高级 → 开发者模式** （启用）。
2. **添加连接器**并输入MCP URL：
```
https://onatozmenn-creddy-mcp.hf.space/mcp
```
3. 保存。现在在聊天中询问 *"按教育程度划分的违约率是多少？"* 。
> 自定义MCP工具仅在启用**开发者模式**的帐户上可见。
### Claude Desktop
添加到 `claude_desktop_config.json` （Windows：`%APPDATA%\Claude\claude_desktop_config.json` ·
macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"creddy": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://onatozmenn-creddy-mcp.hf.space/mcp"]
}
}
}
```
重启Claude Desktop；工具将出现在 🔨 菜单中。 *(需要Node.js支持`npx`.)*
### Claude.ai （网页）
在Pro / Max / Team（和Free — 一个连接器）上，您可以直接连接远程MCP：
1. **[设置 → 连接器](https://claude.ai/settings/connectors)** → **添加自定义连接器**。
2. 输入MCP URL（留空OAuth字段 — 服务器不需要身份验证）：
```
https://onatozmenn-creddy-mcp.hf.space/mcp
```
3. **添加**，然后从 **"+" → 连接器** 菜单中启用Creddy。
### Smithery （一条命令）
```
npx -y @smithery/cli install onatozmen44/creddy-mcp --client claude
```
### VS Code / Cursor
VS Code — `.vscode/mcp.json`:
```json
{ "servers": { "creddy": { "type": "http", "url": "https://onatozmenn-creddy-mcp.hf.space/mcp" } } }
```
Cursor — `.cursor/mcp.json` （注意 `mcpServers` 键）：
```json
{ "mcpServers": { "creddy": { "url": "https://onatozmenn-creddy-mcp.hf.space/mcp" } } }
```
## 架构
```mermaid
flowchart LR
User([用户]) -- "自然语言" --> Client["Claude / ChatGPT / IDE"]
Client -- "MCP（stdio或HTTP）" --> Server["Creddy MCP服务器（FastMCP）"]
Server -- "run_query" --> Guard["SQL防护（sqlglot）"]
Guard --> DB[("Postgres（只读）\n真实credit_clients")]
Server -- "predict_default / model_metrics" --> Model[["风险模型（scikit-learn）"]]
Server -- "tcmb_indicators / tcmb_search / tcmb_series" --> EVDS[["TCMB EVDS（实时）"]]
DB --> Server
Model --> Server
EVDS --> Server
Server -- "结果" --> Client --> User
```
两个独立的安全层保护数据库：**SQL防护**（`sqlglot` — 只读，单语句，行限制）**和**只读数据库会话**。模型生成的SQL绝不会被盲目信任。
## 真实数据源
| 源 | 内容 | 访问 |
| --- | --- | --- |
| **UCI信用违约** | 30,000个真实客户，真实还款历史，**真实违约标签**（~22%） | 免费，无密钥 ([UCI #350](https://archive.ics.uci.edu/dataset/350/default+of+credit+card+clients)) |
| **TCMB EVDS** | **实时**土耳其经济指标：美元/欧元，黄金，存款&贷款利率，储备，M3，通货膨胀 | 指标无需密钥；免费密钥用于目录搜索 |
## 风险模型
`creddy train-model` 在真实数据上训练一个**可解释的逻辑回归**管道（标准化数值 + 分类变量独热编码），并使用80/20的分割比例。它报告**AUC，准确率，精确率，召回率，F1，KS**，使用**Youden的J**选择决策阈值，并保存模型。每次 `predict_default` 返回概率，风险等级和**特定决策的有符号顶部因素** — 可解释，适合不利行动。
当前保持性能：**AUC ≈ 0.71**，KS ≈ 0.37。低风险评分约为~12%，高风险评分约为~58%（基准率≈ 22%）— 有意义的评分，而不是仅仅排名。
---
## 🛠️ 本地运行
先决条件：**Python 3.10+** 和 **Docker**。
```powershell
docker compose up -d # 本地Postgres
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env
creddy setup # 架构 + 真实数据 + 训练模型
creddy serve # stdio (或：creddy serve --http)
python eval/run_eval.py ; pytest # 12/12 评估，24 测试
```
### 命令行界面
```
creddy init-db | load-data [--limit N] | train-model | setup | serve [--http --host H --port P]
```
## ☁️ 自托管（免费，Hugging Face + Neon）
1. **托管Postgres:** 在 [Neon](https://neon.tech) 或 [Supabase](https://supabase.com) 上创建免费的无服务器数据库；注意主机 / 数据库 / 用户 / 密码。
2. **Hugging Face Space:** 创建一个 **Docker** Space 并推送此仓库（自带 [`Dockerfile`](Dockerfile) + [`docker-entrypoint.sh`](docker-entrypoint.sh)）。将数据库添加为Space **机密**：
```
CREDDY_DB_HOST, CREDDY_DB_PORT, CREDDY_DB_NAME, CREDDY_DB_USER, CREDDY_DB_PASSWORD
CREDDY_DB_SSLMODE=require # Neon / Supabase 需要 SSL
CREDDY_TCMB_API_KEY # 可选
```
在首次启动时，容器会初始化（架构 + 数据 + 模型）并在 `https://<用户>-<空间>.hf.space/mcp` 提供服务。
3. **保持唤醒（可选）：** 一个GitHub Actions工作流（`/.github/workflows/keepalive.yml`）每30分钟ping一次服务器 — 设置一个存储库机密 `MCP_URL` 到您的 `/mcp` URL。
## 数据模型（`credit_clients`）
货币列以 **NT$** 表示；`pay_*` 是每月的还款状态代码（`-1/0` = 正常还款，`>=1` = 延迟月份）；`defaulted` 是标签。
```
client_id, credit_limit, sex, education, marriage, age,
pay_sep..pay_apr, -- 还款状态（6个月）
bill_sep..bill_apr, -- 账单金额
pay_amt_sep..pay_amt_apr, -- 支付金额
defaulted -- TRUE = 下个月违约
```
## 项目布局
```
sql/schema.sql # Postgres DDL
src/creddy/
config.py db.py sql_guard.py
data_loader.py # 加载真实的UCI数据集（ucimlrepo）
risk_model.py # 训练 + 提供违约风险模型（scikit-learn）
tcmb.py # 实时TCMB EVDS客户端
server.py cli.py
eval/ # 黄金SQL + 评估工具
tests/ # 单元测试（无需数据库 / 无需网络）
Dockerfile, docker-entrypoint.sh # 容器镜像用于托管
```
## 设计决策
- **真实的标记数据优于合成数据** — 标签来自源，因此风险故事是真实的。
- **故意使用可解释的模型** — 特定决策的有符号因素（可解释的评分）优于略微更高的AUC。
- **在LLM信任之前进行防护** — AST检查阻止DML/DDL，语句堆叠和`COPY`/`SET`；数据库会话独立只读。
- **评估作为一等公民的产物** — `eval/` 将“SQL层是否正常工作？”转化为可衡量、CI友好的通过率。
## 安全
- 只读`SELECT`，在两个层面上强制执行（解析器 + 数据库会话）；每个查询的行限制。
- 机密（数据库密码，TCMB密钥）来自环境，绝不硬编码。
- UCI数据是公开的和匿名处理的 — 没有真实的PII。
## 关于`tcmb_series`的说明
TCMB迁移了EVDS2 → EVDS3。所有三个TCMB工具现在都针对EVDS3服务：`tcmb_indicators`（无密钥）以及密钥认证的`tcmb_search`和`tcmb_series`，它们使用EVDS3 `igmevdsms-dis` REST端点。`tcmb_series`需要有效的`CREDDY_TCMB_API_KEY`；如果端点再次更改，请覆盖`CREDDY_TCMB_BASE_URL`。
## 许可证
[MIT](LICENSE)
