CampusIntel MCP

CampusIntel — это сервер на основе Model Context Protocol, который предоставляет ИИ-ассистентам структурированный доступ к университетским исследованиям, исследователям, академическим программам и институциональным данным. Он объединяет научный граф знаний OpenAlex и данные College Scorecard Министерства образования США, сохраняя в каждом результате ссылки на источники и ограничения.

Проект предназначен для поиска исследований и изучения университетов — а не для прогнозирования результатов поступления или составления рейтингов отдельных учебных заведений.

Что такое MCP-сервер?

MCP-сервер — это небольшой инфраструктурный компонент, который позволяет ИИ-хосту, например Claude Desktop, VS Code или MCP Inspector, вызывать надёжные инструменты вместо предположений. Его можно представить как защищённый адаптер между ИИ-ассистентом и внешними источниками данных.

CampusIntel не является чат-ботом для консультаций по колледжам и не использует LLM для выдумывания университетских фактов. Он предоставляет понятно названные функции, такие как search_research и list_academic_programs. ИИ-хост решает, когда их вызывать; 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

Например, ИИ-хост сначала вызывает search_universities, чтобы связать название университета с идентификатором OpenAlex. Затем передаёт результат в search_research или find_topic_researchers. Такая двухэтапная схема избегает неоднозначного сопоставления названий и привязывает результаты исследований к конкретному заведению.

Что CampusIntel умеет

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"]

Клиенты провайдеров включают типизированную нормализацию, ограниченные повторные попытки, таймауты и TTL-кэш в памяти. Сопоставление между источниками намеренно изолировано на уровне сервисов, поэтому исходные данные провайдеров и выявляемые зависимости не путаются.

Откуда берутся данные

CampusIntel не собирает данные со страниц преподавателей, не использует частные данные студентов и не утверждает, что может спрогнозировать результат поступления абитуриента. Он сохраняет URL источника в каждой возвращаемой записи, чтобы пользователь мог проверить первичные данные перед принятием решения.

Быстрый старт

1. Установка

Установите uv, затем клонируйте и синхронизируйте проект:

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

Активация виртуального окружения не требуется, когда команды начинаются с uv run.

2. Настройка ключей провайдеров

Скопируйте .env.example в .env, затем добавьте свои ключи:

• OPENALEX_API_KEY: рекомендуется для обычного использования; создайте бесплатный ключ в настройках OpenAlex.

• COLLEGE_SCORECARD_API_KEY: требуется для инструментов, работающих с колледжами США и академическими программами; запросите бесплатный ключ data.gov.

OpenAlex поддерживает ограниченные демонстрационные запросы без ключа. CampusIntel продолжает работать и без ключа College Scorecard, но инструменты для работы с колледжами США и программами будут возвращать понятную ошибку конфигурации, а профили будут без данных Scorecard.

Как обрабатывать ключи безопасно

Никогда не помещайте настоящий ключ в README.md, исходный код, файл .env, который попадает в коммит, скриншот или конфигурацию MCP, которую планируете распостранять. Репозиторий содержит только файл .env.example с записями, а .gitignore исключает .env.

Задайте OPENALEX_API_KEY и COLLEGE_SCORECARD_API_KEY как локальные переменные окружения или сохраните их значения только в несообщаемом коммиту файле .env, а затем запустите uv run campusintel-mcp. health_check сообщает только о том, настроен ли провайдер; он никогда не возвращает секреты.

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 задайте OPENALEX_API_KEY и COLLEGE_SCORECARD_API_KEY в локальном сеансе PowerShell или в необъявленном .env файле.

Inspector открывается в браузере. Начните с search_universities, сохраните полученный идентификатор OpenAlex и передайте его в исследовательские инструменты.

Подключение 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

Пример рабочего процесса

Чтобы исследовать исследования по безопасности ИИ в университете, MCP-клиент может:

1. Вызвать search_universities(query="Carnegie Mellon University", country_code="US").

2. Передать полученную идентификатор в search_research(topic="AI safety", institution_id="I...", from_year=2022).

3. Вызвать find_topic_researchers с той же темой и идентификатором заведения.

4. Получить федеральный идентификатор школы через search_us_colleges, затем вызвать list_academic_programs(query="computer science", credential_level=3).

5. Сохранить в итоговом ответе возвращённые ссылки на источники и примечания по методологии.

Примеры промптов для ИИ-хоста

• “Сравните недавние исследования по робототехнике в Georgia Tech и Carnegie Mellon. Укажите ссылки на исходные статьи.”

• «Найдите исследователей, работающих над безопасностью в этом университете, затем показать статьи, которые сделали каждого из них учебными соответствующими.»

• «Для этого американского вуза перечислите программы бакалавриата по направлению «Computer Science» и явно отделите данные о программе от исследовательских показателей.»

Хост должен вызывать инструменты, а не предполагать, что названия университета достаточно для идентификации одного учебного заведения. Возвращённые CampusIntel ID делают последующие вызовы точными и воспроизводимыми.

Характеристики инструментов и гарантии

• Проверка входных данных: пустые запросы, некорректные годы, повторяющиеся ID для сравнениями и недопустимые уровни квалификации отклоняются с действием сообщением об ошибке.

• Надежные запросы: вызовы к провайдерам используют таймауты, ограниченные повторные попытки после временных сбоев и недолговечный кэш в памяти, чтобы уменьшить количество повторных запросов.

• Прозрачность отсутствующих данных: отсутствующие поля остаются null; CampusIntel не заполняет их оценками или нулям.

• Обогащение данных с учётом источника: федеральные метрики США добавляют в результаты some только при разумном совпадении имени учреждения OpenAlex с записью Scorecard, почему результат снабжается соответствующей пометкой.

• Без скрытых рейтингов: двоичные индексы цитирования, hss index и исб исходных — это описательный контекст, а не рейтинг официального университета и не прогноз поступления.

Ответственность за данные

• Метрики OpenAlex отражают индексируемую научную литературу; количество цитирований сильно зависит от области науки, времени публикации и охвата.

• Поля latest College Scorecard могут относиться к разным отчётным выборкам.

• Результаты поиска «super-researchers в теме» построены по репрезентативной выборке. Они не являются исчерпывающими ежегодниками по имени специальности или показателями качества исследователя.

• Отсутствующее значение остаётся равным null; CampusIntel не производит его.

• Обогащение, основанное на сопоставлении имён OpenAlex и Scorecard, помечается и должно быть проверены перед ответственным решением.

Это же руководство можно читать в ресурсе campusintel://methodology в MCP-клиентах.

Развитие

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

Тестовый набор использует ```transport Вводный мокки для HTTP и встроенный клиент из MCP SDK. CI сообщает форматирование, линтеры, строгую проверку типов и тесты на Python 3.11 и 3.12.

Лицензия

Мощность по лицензии MIT.