ARES MCP

로컬 Model Context Protocol 서버로, 학술 문헌 검색 및 작성을 지원합니다. OpenAlex, arXiv, Crossref 등 공개 카탈로그와 통신하고, 오픈 액세스 PDF(PDF 파일만)를 다운로드하며, 요청에 따라 IMRaD 섹션을 추출하고 BibTeX를 추가합니다. — Cursor 옆에서 실행되도록 설계되었습니다.

라이선스: MIT. 기여: CONTRIBUTING.md.

ARES는 발행사 페이월을 우회하지 않습니다. OA PDF가 없으면 HTML을 스크래핑하는 대신 no_open_pdf를 반환합니다.

이 저장소는 문헌 보조 도구이며, PRISMA 스크리닝/감사 워크벤치가 아닙니다.

도구

일반적인 에이전트 흐름: (sort=cited_by로 유명한 논문) 검색 → OA PDF 다운로드 → 초록/방법 추출 → get_bibtex.

Related MCP server: Scholar MCP Server

요구 사항

• Python 3.11+

• uv는 uvx 사용 시 권장

.env 파일은 필요하지 않습니다. ARES는 다음 순서로 OpenAlex / Unpaywall polite pool에 사용할 연락처 이메일을 선택합니다.

1. ares-mcp --mailto you@university.edu

2. 프로세스 환경의 ARES_MAILTO (Cursor의 mcp.json env 블록)

3. 선택적인 현재 작업 디렉터리의 .env (ARES_MAILTO=...) — 로컬 체크아웃 전용

4. git config user.email

5. 기본 값 ares-mcp@localhost (서버는 계속 시장됨니)

PyPI에서 설치 (Cursor)

배포 후:

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp"]
    }
  }
}

선택적 식별 정보 (여전히 .env 없이):

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp", "--mailto", "you@university.edu"]
    }
  }
}

설치 (개발)

git clone <this-repo>
cd AREsMCP
uv sync

테스트 실하면:

uv run pytest
uv run ruff check src tests

라이브 API 점검 (선택):

uv run pytest -m integration

Cursor 구성 (로컬 체크아웃)

.cursor.mcp.json을 복사하고 --project 경로를 클론에 맞게 바꾼셔. 이메일은 선택 사항; 설저하지 않으면 git user.email을 사용합니다.

권장 — uv run:

{
  "mcpServers": {
    "ares": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:/Users/vitor/Documents/Projetos/AREsMCP",
        "ares-mcp"
      ]
    }
  }
}

venv Python:

{
  "mcpServers": {
    "ares": {
      "command": "C:/Users/vitor/Documents/Projetos/AREsMCP/.venv/Scripts/python.exe",
      "args": ["-m", "ares_mcp.server"]
    }
  }
}

uvx를 로컬 체크아웃에서 사용 (PyPI 배표 불요):

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["--from", "C:/Users/vitor/Documents/Projetos/AREsMCP", "ares-mcp"]
    }
  }
}

Cursor에서 MCP 서버를 재로드한 후 이렇게 물어보세요: “2022년 이후 그래프 신경망 관련 오픈 액세스 논문을 검색해 줘.”

Inspector (Cursor 외부):

uv run fastmcp dev src/ares_mcp/server.py

환경

쓰기 작업은 서버의 현재 작업 디렉토리 (Cursor가 연 프로젝트)로 제한됩니다. 경로 순회(travel)는 거부됩니다.

API 참고

• OpenAlex: search + filter와 함께 GET /works를 사용합니다. 초록은 역색인 형태로 저장되며 로컬에서 재구성됩니다. 다운로드 시 pdf_url이 있는 모든 locations을 사용하며, arXiv/DMC ID가 있으면 함께 사용합니다.

• **Unpaywall:**인터프린트, 수용 manuscript, 저장소 등 합법적인 OA 사본을 위해 GET /v2/{doi}를 사용합니다. 이 방식 덕분에 많은 IEEE/Elsevier논문Ꞙ 페이월 HTML을 건드리지 않고도 다운로드할 수 있습니다.

• arXiv: export.arxiv.org의 Atom API를 사용합니다. 모든 검색 결과는 OA입니다.

• Crossref: DOI 콘텐츠 협상으로 Accept: application/x-bibtex.

• 가능할 때 프로세스를 --mailto 또는 ARES_MAILTO로 식별하세요. API를 과도하게 호출하지 마세요. 각 도구 호출은 몇 개의 요청일 뿐이며 429/5xx 응답 시 한 번 재시도합니다.

모든 OA 후보자가 403을 반환하거나 HTML을 반환하면 도구는 download_ 또는 no_open_pdf를 보합니다. 사전프린트가 존재한다는 것을 알면 arXiv ID를 전달하세요. ARTS는 발행사 HTML을 스크레핑하지 않습니다.

대체 license

MIT는 프로젝트의 라이선스입니다. 추후 특허 권리(patent grant)가 필요하면 Apache-2.0을 고려할 수 있씃니다. 다시 라이선스를 변경하기 전에 이슈에서 늘에 대해 논의하세요.

상태

MVP 0.1.0. uv build와 uv publish (또는 GitHub Actions의 Trusted Publisher)로 배표하세요. 그 후이후 Cursor가 .env 없이 uvx ares-mc를 실항할 수 있씃니다.