CampusIntel MCP

CampusIntel은 AI 어시스턴트가 대학 연구, 연구자, 학술 프로그램 및 기관 데이터에 구조적으로 접근할 수 있게 해주는 Model Context Protocol 서버입니다. 데이터에 대한 출처 링크와 한계를 모든 결과에 보존하면서 OpenAlex 학술 지식 그래프와 미국 교육부의 College Scorecard를 결합합니다.

이 프로젝트는 입학 예측이나 단일 숫자 순위가 아니라 연구 발견과 대학 조사를 위해 설계되었습니다.

MCP 서버란 무엇인가요?

MCP 서버는 Claude Desktop, VS Code, MCP Inspector와 같은 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"]

프로바이더 클라이언트에는 타입 기반 정규화, 제한된 재시도, 타임아웃, 인메모리 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 API 키를 요청하세요.

OpenAlex는 제한된 키 없는 데모 요청을 지원합니다. CampusIntel은 College Scorecard 키 없이도 동작하지만콩실제 미국 대학/프로그램 도구는 명확한 구성 오류를 반환하고 프로필은 Scorecard 보강 정보를 생략합니다.

키 비공개 유지

실제 키를 README.md, 소스 코드, 커밋된 .env 파일, 스크린샷 또는 공유할 엔티시 설정 파일에 절대 넣지 마세요. 보고의 저장소에는 빈 보강자리만 있는 .env.example 포함되어 있고, .gitignore에서 .env가 제외됩니다.

OPENALEX_CONFIG_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 명령을 실행하기 전에 로컬 PowerShell 세션 또는 커밋되지 않은 .env 파일에서 OPENALEX_API_KEY와 COLLEGE_SCORECARD_API_KEY를 정의해야 합니다.

Inspector는 브라우저에서 엽니다. search_universities부터 시작하고, 반환된 OpenAlex 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. find_topic_researchers를 동그 주제와 기관 ID로 호출하여 연구자를 탐색합니다.

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, 유효하지 않은 학위 수준은 실행 가능한 도구 오류로 거부합니다.

• 신뢰할 수 있는 요청: 프로바이더 호출은 타임아웃, 일시적 오류에 대한 제한된 재시도, 반복 요청 줄이기 위한 단기 인메모리 캐시를 사용합니다.

• 누락 데이터 투명하기: 사용 불가능한 필드는 null로 남고, CampusIntel이 추정 값이나 0으로 채우지 않습니다.

• 출처 인식 보강: OpenAlex의 기관이 Scorecard 레코드로 합리적으로 이름 매칭된 경우에만 미국 연방 지표가 추가되어 결과에 명시됩니다.

• 숨은 순위 없음: 인용 수, h-인덱스 값, 결과는 종합 대학 점수나 입학 예측이 아닌 추가 컨텍스트입니다.

데이터 책임

• OpenAlex의 인용 수와 h-인덱스 값은 설명적 컨텍스트로, 분야와 발행 연령에 따라 크게 다를 수 있습니다.

• College Scorecard의 latest 필드는 다른 보고 중에서 오는 것일 수 있습니다.

• 주제-연구자 결과는 유사한 표본 내에서 배치됩니다. 완전한 교수 디렉토리나 연구자 질 평가 판단이 아닙니다.

• 누락된 값은 null로 남습니다. CampusIntel는 추정하지 않습니다.

• 이름 기반 OpenAlex-to-Scorecard 보강 정보는 명시적으로 나와 있으며, 영향을 미치는 결과 중요판단에 사용 전에 확인해야 합니다.

• 각 결과의 사용자 정의 문서 자체는 특정 계획 순위를 권장하지 않습니다.

MCP 클라이언트에서 동일한 가이드는 campusintel://methodology 리소스에서도 확인할 수 있습니다.

개발

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

테스트 스위트는 모의 HTTP 전송 및 MCP SDK의 인메모리 클라이언트를 사용합니다. 이 서버에서 CampusIntel는 Python 3.11 및 3.12에서 CI에 걸쳐 포맷팅, 린트, 엄격한 타입 검사, 테스트를 실행합니다.

라이선스

MIT License에 따라 배포됩니다.