使用说明

title：基于MCP的上下文感知NLP分类平台表情符号🧠 颜色来源：靛蓝颜色：红色 sdk:docker app_file：Dockerfile 固定：false 许可证：mit

基于MCP的上下文感知NLP分类平台

概述

此存储库实现了 上下文感知NLP分类平台 它结合了轻量级的TF-IDF（术语频率-反向文档频率）+逻辑回归基线和可选 LLM辅助上下文重新排序 通过MCP（托管上下文平台）。它支持多领域分类（财务、人力资源、法律）、结构化上下文解析、日志记录和评估。

该平台是模块化的，可以运行 在虚拟环境中本地 或在一个 拥抱脸空间中的Docker容器.

拥抱面部空间： LeonardoMdSA/基于MCP的上下文感知NLP分类平台

仓库结构

Dockerfile
LICENSE
README.md
requirements-dev.txt
requirements.txt

app/
  config.py              # Configuration and settings
  logging_config.py      # Logging configuration
  main.py                # Main entry point for API server
  api/
    routes.py            # FastAPI routes
    schemas.py           # Pydantic schemas
  classification/
    decision.py          # Classification decision & abstention logic
    llm_adapter.py       # Optional LLM integration for context
    model.py             # Abstract classifier orchestration
    preprocess.py        # Text preprocessing and tokenization
    sklearn_model.py     # TF-IDF + Logistic Regression classifier
  context/
    resolver.py          # Context resolution logic
  logging/
    context_log.py       # Context logging to JSON
    inference_log.py     # Inference (label and confidence) logging to JSON

orchestration/
  context_resolver.py    # MCP-based structured context orchestration
  mcp_client.py          # MCP server communication utilities

utils/
  validators.py          # Metadata validation utilities

data/
  samples/
    train.json           # Training samples (small dataset)
    eval.json            # Evaluation samples
    training_data.json   # Full training dataset

docs/
  TECH_DEBT.md           # Technical debt documentation

logs/                     # Runtime logs

mcp_servers/
  history_server/         # Historical label MCP server
    server.py
    data/labels.csv
  policy_server/          # Policy MCP server
    server.py
    data/rules.yaml
  taxonomy_server/        # Taxonomy MCP server
    server.py
    data/taxonomy.sqlite

models/
  trained_pipeline.joblib # Trained sklearn model pipeline

scripts/
  evaluate.py             # Offline evaluation script
  populate_taxonomy.py    # Populate taxonomy.sqlite for MCP
  seed_data.py            # Seed initial data into MCP files
  train_model.py          # Train sklearn model from JSON dataset

tests/
  conftest.py             # Pytest configuration
  test_api.py             # API endpoint tests
  test_classification.py  # Classification module tests
  test_context_resolution.py  # Context resolver tests
  test_mcp_servers.py     # MCP server tests

ui/
  static/
    script.js             # Frontend JS
    style.css             # Frontend CSS
  templates/
    index.html            # Frontend template

安装（本地）

1.克隆存储库

git clone https://github.com/LeonardoMdSACode/Context-aware-NLP-classification-platform-with-MCP.git
cd Context-aware-NLP-classification-platform-with-MCP

2.创建虚拟环境

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate     # Windows

3.安装依赖项

pip install -r requirements.txt
pip install -r requirements-dev.txt  # for testing and development

4.填充MCP分类（首次设置）

python scripts/populate_taxonomy.py

这将填充 mcp_servers/taxonomy_server/data/taxonomy.sqlite.

5.训练模型

python scripts/train_model.py

这将训练TF-IDF+逻辑回归模型并将其保存到 models/trained_pipeline.joblib.

6.评估模型

python scripts/evaluate.py

显示离线评估指标（准确性、精确度、召回率、F1分数）。

在本地运行API

1.启动服务器

uvicorn app.main:app --reload

这将在以下位置运行FastAPI服务器 http://127.0.0.1:8000.

2.运行MCP嵌入式服务器（如果使用嵌入式模式）

嵌入式MCP服务器通过以下方式自动启动 app.orchestration.mcp_client.start_embedded_mcp_servers().

3.访问UI

打开浏览器 http://127.0.0.1:8000 使用HTML/JS前端。

4.API终点

POST /classify ：发送 text 可选 metadata 根据上下文进行分类。
Swagger用户界面： http://127.0.0.1:8000/docs

测试

1.运行所有测试

pytest -v

2.烟雾测试

跑 test_backend.py 以确保核心API路由正确响应。
检查MCP服务器是否响应 /resolve 端点。

3.模块特定测试

test_classification.py → 验证 SklearnClassifier 和 LLMAdapter 预言。
test_context_resolution.py → 检查上下文解析器输出。
test_mcp_servers.py → 验证分类、策略、历史MCP服务器。

运作原理

1.分类层

基线： app/classification/sklearn_model.py → TF-IDF+逻辑回归
LLM协助： app/classification/llm_adapter.py → 可选的MCP上下文重新排序
决策逻辑： app/classification/decision.py → 应用信心、弃权、记录

2.上下文解析

嵌入式MCP模式： app/orchestration/context_resolver.py 加载JSON/SQLite本地文件
分布式MCP模式： 从分类、策略和历史MCP服务器获取上下文
记录所有上下文解析以供审计

3.日志记录

app/logging/inference_log.py → 记录每一个预测
app/logging/context_log.py → 分类中使用的日志上下文
日志以JSON格式存储在 logs/

4.MCP服务器

taxonomy_server → 提供SQLite中的类别和描述
policy_server → 从YAML提供策略规则
history_server → 从CSV提供历史标签数据
通过HTTP端点进行通信

5.脚本

train_model.py → 训练并保存sklearn管道
evaluate.py → 离线评估
populate_taxonomy.py → 填充SQLite分类
seed_data.py → 种子MCP JSON文件

6.前端用户界面

界面简洁 ui/templates/index.html
使用JS(static/script.js)拨打电话 /classify 端点
样式通过 static/style.css

技术栈

该项目实现了 生产风格、上下文感知的NLP分类平台 使用经典的机器学习、基于MCP的上下文丰富和FastAPI推理层。

核心语言和运行时

Python 3.13
- 主要实现语言
- 虚拟环境支持(venv)
- 兼容本地执行和Docker

机器学习与NLP

scikit学习
- TfidfVectorizer 用于文本特征提取
- LogisticRegression （多类，类平衡）
- 可选概率校准(CalibratedClassifierCV)
Joblib
- 模型序列化和加载(trained_pipeline.joblib)
经典机器学习（非深度学习）
- 选择可解释性、决定论和生产现实主义

文本表示法

TF-IDF（词频-逆文档频率）
- 单字和双字特征
- 稀疏向量表示
- 快速、可解释和确定性

模型推理与决策逻辑

自定义分类编排
- 基于信任的路由
- 弃权处理
- 确定性回退启发式
上下文感知决策层
- 使用MCP导出的信号调整预测
推理日志记录
- 输入、预测标签、置信度得分和上下文

上下文和MCP（模型上下文协议）

受MCP启发的架构（本地服务器）
- 在推理时动态解析上下文
独立MCP服务器
- 分类服务器 （SQLite支持的文档分类）
- 策略服务器 （基于YAML的业务规则）
- 历史服务器 （基于CSV的标签历史记录）
上下文解析器
- 聚合来自所有MCP服务器的信号
- 将结构化上下文注入分类器决策流

后端API

快速API
- 基于REST的推理服务
- 请求/响应验证
- 自动OpenAPI文档
Uvicorn
- 用于本地开发和部署的ASGI服务器
Pydantic 2
- 严格的输入/输出模式
- 验证和类型安全

前端（最小UI）

HTML/CSS/JavaScript
Jinja2模板
FastAPI静态文件
- 轻量级推理接口
- 无Streamlit或Gradio
- 拥抱面部空间–兼容

持久性和存储

SQLite
- 分类存储(taxonomy.sqlite)
基于文件系统的存储
- 训练有素的模特
- 日志
- 评估工件

测井和观测

结构化日志记录
- 推理日志
- 上下文解析日志
基于JSON的日志格式
旨在支持未来：
- 漂移检测
- 监控
- 告警

评估与实验

离线评估脚本
- 准确度、精密度、召回率、F1分数
- 详细的 classification_report
分离的列车/评估数据集
置信度分析
- 用于检查校准和过度自信

测试

pytest
- API测试
- 分类逻辑测试
- 上下文解析测试
- MCP服务器测试
冒烟测试
- 端到端推理验证
共享装置 通过 conftest.py

DevOps与打包

码头工人
- 可复制的构建
- 容器化推理服务
依赖管理
- requirements.txt
- requirements-dev.txt
CI/CD存储库结构
- GitHub操作

设计理念

经典机器学习优于深度学习（有意）
基于原始预测的上下文感知推理
可解释性优于黑盒准确性
玩具演示的生产现实主义

建议

使用一个 更大、更多样化的数据集 用于实际部署，以避免过拟合
使用 S形校准 用于真实的置信度评分
保留日志 可审计性 以及上下文可追溯性
定期运行测试 pytest -v 以确保稳定性

参考文献/文件

docs/TECH_DEBT.md → 技术债务票据及改进建议
data/samples/ → 样本培训/评估数据集
models/trained_pipeline.joblib → 预训练基线模型

联系人/作者

存储库： LeonardoMdSCode/基于MCP的上下文感知NLP分类平台