cumcm-rag-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cumcm-rag-mcp search for multi-objective optimization case studies"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CUMCM Optimization RAG
这是一个面向全国大学生数学建模竞赛优化与决策类问题的非官方、可审计 RAG 工程。项目提供 Python 查询核心、受 manifest 约束的入库器、命令行工具和只读 MCP 服务;不包含竞赛题面、附件、优秀论文、扫描件、压缩包或其他未获明确公开再分发许可的材料。
本项目与案例建模仓库相互独立。案例仓库可以选择通过 MCP 调用本项目,但两者不共享源码、语料、索引或虚拟环境;案例复现也不以本项目为运行前提。
协作者
yidan chen
Related MCP server: Agentic RAG Assistant
当前公开数据状态
迁移前基线 manifest 有 399 条:L0 119、L1 193、L2 87。许可审计没有发现任何具备肯定公开再分发许可的记录,因此:
data/manifest/corpus_manifest.csv:0 条公开原文记录,仅保留表头;data/manifest/sources.csv:399 条来源与权利元数据;data/manifest/exclusions.csv:399 条排除记录及理由;data/corpus/:不包含原语料;artifacts/index/:不包含生成索引。
这意味着仓库可以安装、校验、启动 CLI 和 MCP,但在添加并审核合法语料、构建本地索引之前不能执行真实检索。该状态是版权门禁的预期结果,不是数据丢失或程序故障。
其中 199 条迁移记录没有公开 URL,已明确标为 source_locator_status=local_record_no_public_url。这些记录只是本地来源台账,不能被描述为外部可独立复核的在线来源。rag_list_sources 会返回元数据总账并用 available_for_index 区分是否存在于公开 manifest;rag_get_document 仍严格只允许读取公开 manifest 登记的原文。
目录结构
.
├─ src/cumcm_rag/ # 核心、入库、CLI、MCP
├─ config/ # 相对路径配置与 Codex 示例
├─ scripts/ # manifest 迁移、校验工具
├─ tests/ # 单元与 MCP stdio 集成测试
├─ data/
│ ├─ manifest/ # 公开清单、来源元数据、排除登记
│ ├─ corpus/ # 仅放已核验可再分发文本
│ └─ incoming/ # 本地待审材料;默认忽略
├─ artifacts/index/ # 可重建索引;默认忽略
├─ docs/ # 架构、治理、接入、验证与迁移说明
└─ docker/ # 容器镜像和 Compose 配置环境与安装
要求 Python 3.11 或更高版本。推荐在项目外或项目根下自建虚拟环境;虚拟环境不会进入版本控制。
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"只运行状态、manifest 和 MCP 元数据接口不需要模型依赖。构建索引和检索时安装:
python -m pip install -e ".[runtime]"OCR/PDF 抽取工具属于本地语料准备能力,不会赋予材料再分发权:
python -m pip install -e ".[corpus]"最小可运行示例
源码模式:
$env:PYTHONPATH = "$PWD\src"
python -m cumcm_rag.cli status
python -m cumcm_rag.cli health
python scripts\verify_manifest.py可编辑安装后:
cumcm-rag status
cumcm-rag sources --all --limit 5
cumcm-rag-mcp普通安装或从仓库外运行时必须设置 CUMCM_RAG_ROOT 指向包含 config/rag.yaml 与 data/manifest 的项目/数据根目录;程序不会再把 site-packages 的父目录误判为项目根。
当前 health 会明确报告“索引缺失”,因为索引是本地生成物且公开语料白名单为空。MCP 仍可正常完成初始化、列出工具、查询状态和执行浅层健康检查。
添加合法语料与构建索引
只有同时满足以下条件的文本文件才能进入 corpus_manifest.csv:
permission_status=public_redistribution_verified;redistribution_allowed=yes;有有效 SPDX 许可证或覆盖再分发的书面授权;
来源、权利人、上游派生关系和人工复核状态完整;
文件存在且 SHA-256 与登记值一致;
文件位于
data/corpus/内,且是允许的文本格式。
完成登记后先运行:
python scripts\verify_manifest.py再构建本地索引:
cumcm-rag build-index
cumcm-rag health --deep
cumcm-rag search "MILP 不可行时如何诊断" --limit 5索引器只读取 manifest 中 index_default=yes 的文件;未登记文件会使校验失败,不会被静默收录。
MCP 与 Codex
MCP 服务暴露六个只读工具:
rag_searchrag_get_case_contextrag_get_documentrag_list_sourcesrag_get_statusrag_health
服务入口:
python -m cumcm_rag.mcp_server示例配置见 config/codex_config.example.toml,详细说明见 docs/codex-mcp.md。示例不包含个人机器绝对路径;推荐先在目标 Python 环境中安装本项目,再让 Codex 运行模块入口。
Docker
解析 Compose 配置:
docker compose -f docker\compose.yaml config构建并启动:
docker compose -f docker\compose.yaml build
docker compose -f docker\compose.yaml run --rm cumcm-rag-mcp容器只读挂载 data/corpus 和 artifacts/index。模型缓存在命名卷中;语料和索引不会写入镜像。
测试与验证
python -m compileall -q src scripts tests
python -m pytest -q --basetemp .pytest-tmp
python scripts\verify_manifest.py
docker compose -f docker\compose.yaml config完整的静态检查、MCP 验证、旧路径扫描、敏感信息扫描和环境限制见 docs/validation.md。
常见故障
索引不存在或不完整:当前仓库不分发索引。先合法添加语料、通过 manifest 校验,再执行build-index。缺少
txtai或jieba:安装.[runtime]。浅层状态和 manifest 校验不要求它们。模型无法下载:在可联网环境预先填充模型缓存,或设置
HF_HOME指向合规的本地缓存;不要提交缓存。MCP 能启动但检索失败:先调用
rag_get_status和rag_health。索引缺失是最常见原因。Windows 临时目录拒绝访问:给 pytest 指定项目内临时目录,如
--basetemp .pytest-tmp,测试后删除该目录。FAISS AVX2 警告:若随后成功回退到普通 FAISS,通常只是性能提示;仍应以真实检索结果判断功能是否正常。
许可、贡献与引用
原创代码和原创文档采用 Apache License 2.0。该许可证不覆盖语料元数据所指向的题面、论文、附件、网页、仓库或其他第三方材料。详见 DATA_LICENSE.md、NOTICE 和 THIRD_PARTY_NOTICES.md。
提交贡献前请阅读 CONTRIBUTING.md;安全问题按 SECURITY.md 私下报告;引用信息见 CITATION.cff。
已知限制
当前公开语料为 0,无法开箱执行语义检索;
旧基线中有 3 条来源记录的实际 SHA-256 与登记值不符,已保留为排除元数据,不能作为已验证证据;
未联网复核官方网页条款或取得第三方书面授权;
真实检索依赖较大的模型与 FAISS/txtai 环境,跨平台表现可能不同;
本项目只提供方法与检索支持,不能替代题面原文、用户数据、实际求解结果或人工版权判断。
Available Tools
6 toolsrag_get_case_contextC
按题号取得案例卡与通用方法卡组成的上下文。
Inputs: case_id (required), limit, query. Returns: object
rag_get_documentB
读取 manifest 已登记的文本型公开语料,拒绝未登记路径。
Inputs: source_file (required), max_chars. Returns: object
rag_get_statusA
返回语料、manifest 与本地生成索引的状态。
Inputs: no named parameters. Returns: object
rag_healthB
检查路径与索引;deep=true 时额外执行真实检索探针。
Inputs: deep. Returns: object
rag_list_sourcesC
列出 manifest 中的来源、许可、层级、题号、URL 与哈希。
Inputs: layer, limit, case_id, index_default. Returns: result
rag_searchB
检索国赛优化与决策类公开语料;可按题号、层级和文档类型过滤。
Inputs: query (required), layer, limit, case_id, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have clearly distinct roles: search, document retrieval, source listing, and case-context assembly are well separated. However, rag_get_status and rag_health overlap in purpose, both probing system/index health, which could cause occasional misselection.
All tools share the rag_ prefix and use consistent snake_case with action-oriented verbs like get, search, list, and health. The naming pattern is predictable and easy to extend.
Six tools form a tight, well-scoped surface for a RAG retrieval server: search, document access, source metadata, context assembly, and health/status checks. No tool feels redundant or unnecessary.
The retrieval side is well covered: search, document reading, source listing, case context, and health checks. Minor gaps exist around index management or ingestion, but the apparent read-only RAG purpose is largely satisfied.
Maintenance
Related MCP Connectors
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides read-only, citation-backed semantic search and retrieval-augmented generation over enterprise documents via standardized MCP tools, with local embeddings for privacy.-
- FlicenseNot gradedqualityDmaintenanceEnables querying internal documents via a FastAPI REST API and MCP server, using retrieval-augmented generation and an agentic loop that can invoke tools like document search and calculations.-

ragifix-mcpofficial
FlicenseNot gradedqualityBmaintenanceEnables chat clients to search, add, retrieve, list, and delete documents in a ragifix knowledge base via MCP, plus health checks.-- AlicenseNot gradedqualityBmaintenanceProvides read-only search and context-pack creation over a local source library, letting AI assistants retrieve relevant excerpts and audit cited quotations.20MIT