CampusIntel MCP

CampusIntel 是一个模型上下文协议（Model Context Protocol，MCP）服务器，为 AI 助手提供对高校研究、研究者、研究项目和机构数据的结构化访问。它将 OpenAlex 的学术知识图谱与美国教育部（U.S. Department of Education）的 College Scorecard 相结合，并在每条结果中都保留来源链接与数据局限说明。

该项目的目标是支持科研发现和高校调研，而不是录取预测或单一评分排名。

什么是 MCP 服务器？

MCP 服务器是一小段基础配置，它让 Claude Desktop、VS Code 或 MCP Inspector 等 AI 宿主能够调用可靠的工具，而不是靠 AI 自行做一些无依据猜测。可将其视为 AI 助手与外部数据源之间的安全适配器。

CampusIntel 不是一个大学申请问答机器人，也不会用 LLM 来编造高校事实。它提供命名清晰的函数，如 search_research 和 list_academic_programs。是否需要调用这些函数由 AI 宿主来决定；CampusIntel 会校验请求、从相应的数据源获取实时数据，并返回结构化、可追溯来源的结果，宿主可以将这些结果向用户清晰解释。

Related MCP server: OpenAlex Author Disambiguation MCP Server

请求的运作方式

sequenceDiagram
    participant User
    participant Host as AI host
    participant CI as CampusIntel
    participant Data as Data provider
    User->>Host: "Find AI-safety research at a university"
    Host->>CI: Call a typed MCP tool
    CI->>CI: Validate inputs and check cache
    CI->>Data: Request live, scoped data
    Data-->>CI: Structured response
    CI-->>Host: Normalized result with source URL
    Host-->>User: Grounded answer with limitations

例如，AI 宿主先调用 search_universities，将学校名称解析为一个 OpenAlex 机构 ID，然后将该 ID 传给 search_research 或 find_topic_researchers。这种两步式模式避免了名称匹配带来的歧义，也让研究结果始终与某个特定的机构绑定。

它能做什么

CampusIntel 还提供一个 campusintel://methodology 资源，以及一个可复用的 research_university_fit 提示词。

架构

flowchart TD
    Host["AI host or MCP Inspector"] --> Server["CampusIntel MCP server"]
    Server --> Service["Validation and orchestration"]
    Service --> OA["OpenAlex client"]
    Service --> CS["College Scorecard client"]
    OA --> Research["Institutions, works, authors"]
    CS --> Federal["Programs, costs, outcomes"]

Provider 客户端包含类型化校验、有限重试、超时机制和内存 TTL 缓存。跨源匹配被刻意隔离在服务层中，因此原始 provider 数据与推断出的关联不会混为一谈。

数据来源

CampusIntel 不抓取教师个人页，不使用学生私有数据，也不声称能预测申请人的录取结果。它在每条结果中保留提供者的 URL，让用户在使用数据前可以先参照来源进行核对。

快速开始

1. 安装

先安装 uv，然后克隆并同步项目：

git clone https://github.com/acestein13/campusintel-mcp.git
cd campusintel-mcp
uv sync --all-extras --dev

当命令以 uv run 开头时，不需要激活虚拟环境。

2. 配置 Provider 密钥

将 .env.example 复制为 .env，然后填入你的密钥：

• OPENALEX_API_KEY：正常的使用建议配置；在 OpenAlex 设置页面 免费创建一个密钥。

• COLLEGE_SCORECARD_API_KEY：使用美国院校和学术项目相关工具时需要；申请一个免费的 data.gov API key。

OpenAlex 支持有限的免密钥演示请求。没有 College Scorecard 密钥时 CampusIntel 仍可运行，但美国院校和项目类工具会返回明确的配置错误，同时院校简介中会缺少 Scorecard 关联补充数据。

保护密钥

绝不真实的密钥写入 README.md、源码、已提交的 .env 文件、截图或打算共享的 MCP 配置文件中。该仓库只提供包含空白占位符的 .env.example，并且 .gitignore 已排除 .env。

将 OPENALEX_API_KEY 和 COLLEGE_SCORECARD_API_KEY 设置为本地环境变量，或者只把它们的值放在未提交的 .env 文件中，然后运行 uv run campusintel-mcp。health_check 仅报告 Provider 是否已配置，绝不会返回任何密钥值。

3. 使用 MCP Inspector 进行测试

macOS/Linux：

set -a && source .env && set +a
uv run mcp dev src/campusintel_mcp/server.py

Windows PowerShell：

uv run mcp dev src/campusintel_mcp/server.py

在运行 Windows 命令之前，请先在本地 PowerShell 会话或未提交的 .env 文件中定义 OPENALEX_API_KEY 和 COLLEGE_SCORECARD_API_KEY。

Inspector 会在浏览器中打开。先使用 search_universities，保留返回的 OpenAlex ID，并在后续研究中传入该 ID。

连接 MCP 宿主

仓库中包含了可直接修改的示例，适用于 Claude Desktop 和 VS Code。请将绝对路径替换为你的实际路径，并保证密钥不会出现在你提交或共享的文件里。

通用的 stdio 配置项为：

{
  "command": "uv",
  "args": ["--directory", "/ABSOLUTE/PATH/TO/campusintel-mcp", "run", "campusintel-mcp"]
}

Streamable HTTP 和 Docker

本地 stdio 是默认模式。若要通过 Streamable HTTP 运行相同的服务：

CAMPUSINTEL_TRANSPORT=streamable-http uv run campusintel-mcp

端点地址为 http://127.0.0.1:8000/mcp。可通过 CAMPUSINTEL_HOST 和 CAMPUSINTEL_PORT 修改主机名和端口。

docker build -t campusintel-mcp .
docker run --rm -p 8000:8000 \
  -e OPENALEX_API_KEY \
  -e COLLEGE_SCORECARD_API_KEY \
  campusintel-mcp

示例工作流

要调研某所大学的 AI 安全研究，MCP 客户端可以：

1. 调用 search_universities(query="Carnegie Mellon University", country_code="US")。

2. 将返回的 ID 传入 search_research(topic="AI safety", institution_id="I...", from_year=2022)。

3. 使用相同的主题和机构 ID 调用 find_topic_researchers。

4. 用 search_us_colleges 解析联邦院校 ID，再调用 list_academic_programs(query="computer science", credential_level=3)。

5. 最终结果或保留返回的源码 URL 和方法学注释。

面向 AI 宿主的示例提示词

• “比较 Georgia Tech 和 Carnegie Mellon 在近年的机器人研究，并关联原始论文。”

• “查找这所学校从事 AI 安全的研究者，然后展示他们相关的论文。”

• “对于这所美国高校，列出计算机科学专业的学士学位项目，并将项目数据和研究指标明确分开。”

宿主应调用工具，而不是只凭一个大学名称就假定能够唯一确认某个机构。CampusIntel 返回的 ID 让后续调用更精确、更可复现。

工具行为与保障措施

• 输入验证： 空查询、无效年份、重复的比较大 ID 和无效的学历层级都会被拒绝，并返回可操作的错误信息。

• 请求可靠性： 对 Providence 的调用会设置超时、对瞬时故障采取有限重试，并使用短时内存缓存以减少重复请求。

• 缺失数据透明： 无法获取的字段保持为 null，CampusIntel 不会用估算值或 0 填充。

• 来源可追溯的增强： 仅当 OpenAlex 机构与 Scorecard 记录能进行名称匹配时，才添加美国联邦政府指标，并在结果中明确标注。

• 没有隐藏排名： 引用量、h-index 和结果等只是描述性上下文，绝不是大学综合或被录取的可疑排行。

数据责任提示

• OpenAlex 指标反映的是一个已建立索引的学术数据源；引用数量会因领域、发表年份和覆盖范围而有较大差异。

• College Scorecard 的 latest 字段可能来自不同的报告性数据队列。

• 主题-研究者排名基于某个相关样本，不构成完整的教职人员目录，也不能代表研究者的真实水平。

• 缺少的值就是 null，CampusIntel 不会去猜测估计它。

• 基于名称的 OpenAlex 和 College Scorecard 的匹配补充会加以标注，在关键决策前应核实。

在 MCP 客户端中，也可以直接查看 campusintel://methodology 资源以获得上述说明。

开发

uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest --cov

测试套件使用模拟的 HTTP 传输层以及 MCP SDK 的内存客户端。CI 会在 Python 3.11 和 3.12 上运行格式化、lint、严格类型检查和测试。

License

基于 MIT License 许可协议发布。