상급 고문 MCP (Aurai Advisor)

로컬 AI가 복잡한 프로그래밍 문제에 직면했을 때 원격 거대 모델(LLM)에게 계속해서 자문을 구할 수 있게 해주는 MCP 서비스입니다.

현재 저장소는 "장기 사용 가능" 버전이며, 다음과 같은 핵심 기능이 보완되었습니다:

• 다중 턴 상담 및 진행 상황 보고

• sync_context 파일 동기화

• 코드/설정 파일 자동 텍스트 변환 및 업로드

• 세션 격리 (session_id)

• 기록 영속성, 파일 잠금, 원자적 쓰기

• 기록 자동 요약

• 컨텍스트 윈도우 트리밍

이번 업데이트 내용

이번 메인 업데이트에서는 다음 사항들에 중점을 두었습니다:

• 기록 삭제 후 재시작 시 다시 "부활"하는 문제 수정

• session_id 세션 격리 추가로 서로 다른 문제 간의 컨텍스트 혼선 방지

• AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS, AURAI_LOG_LEVEL 등 실제 사용 가능한 설정 적용

• project_info, 보충 답변 등의 컨텍스트가 상급 고문에게 제대로 전달되도록 수정

• 기록 파일 잠금 및 원자적 쓰기 추가로 동시 쓰기로 인한 기록 파일 손상 위험 감소

• 기록 자동 요약 추가로 긴 세션에서도 비대해지지 않음

• 컨텍스트 윈도우 트리밍 추가로 AURAI_CONTEXT_WINDOW가 실제로 적용됨

• sync_context가 코드/설정 등 텍스트 파일을 자동으로 전송 가능한 텍스트로 변환 지원 (수동으로 .txt로 복사할 필요 없음)

• README, 설치 가이드 및 사용자 매뉴얼 재작성, 설치 단계를 더 앞부분에 배치

이 저장소를 처음 접하신다면 다음 두 가지가 가장 중요합니다:

1. 아래의 "설치 설명"을 먼저 확인하세요.

2. 코드 파일은 이제 sync_context에 직접 전달할 수 있습니다.

용도

이 MCP는 Claude Code 또는 stdio 방식을 지원하는 다른 MCP 클라이언트에서 사용하기 적합합니다.

주요 시나리오:

• 로컬 AI가 이미 시도했지만 문제가 해결되지 않은 경우

• 에러, 코드, 문서, 설정을 모두 "상급 고문"에게 전달해야 할 때

• 복잡한 문제 해결 과정을 "질문 -> 실행 -> 보고 -> 다음 단계"의 다중 턴 프로세스로 만들고 싶을 때

기능 개요

• consult_aurai 주요 상담 도구. 질문, 코드 조각, 컨텍스트, 시도한 해결책을 제출하여 상급 고문의 분석과 다음 단계 제안을 받습니다.

• sync_context 코드 및 문서 컨텍스트 동기화. 이제 .txt/.md뿐만 아니라 .py/.js/.ts/.json/.yaml/.toml/.ini 등 텍스트 파일을 전송에 적합한 텍스트로 자동 변환합니다.

• report_progress 실행 결과를 상급 고문에게 보고하고 다음 반복 단계로 진행합니다.

• get_status 현재 세션 상태, 기록 개수, 모델 및 기록 파일 경로를 확인합니다.

설치 설명

더 자세한 설치 단계는 다음을 참조하세요:

• Claude Code 설치 가이드

• 사용자 매뉴얼

가장 일반적인 설치 절차는 다음과 같습니다.

1. 환경 준비

# 需要 Python 3.10+
python --version

# 进入仓库目录
cd G:\codex\mcp-aurai-server

2. 가상 환경 생성 및 의존성 설치

python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"

3. Claude Code에 MCP 등록

claude mcp add --scope user --transport stdio aurai-advisor ^
  --env AURAI_API_KEY="your-api-key" ^
  --env AURAI_BASE_URL="https://api.example.com/v1" ^
  --env AURAI_MODEL="gpt-4o" ^
  -- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

설명:

• AURAI_BASE_URL은 반드시 OpenAI 호환 인터페이스 주소여야 합니다.

• 현재 버전은 custom 방식만 유지하며, 이전의 AURAI_PROVIDER는 더 이상 사용하지 않습니다.

• --scope user는 모든 프로젝트에서 사용 가능하게 설정하여 편리합니다.

4. 설치 검증

claude mcp list
pytest

예상 결과:

• claude mcp list에서 aurai-advisor 확인 가능

• pytest 통과

빠른 사용법

시나리오 1: 직접 질문하기

consult_aurai(
    problem_type="runtime_error",
    error_message="启动时报 KeyError: api_key",
    code_snippet="config = load_config()\napi_key = config['api_key']",
    context={
        "file_path": "src/config.py",
        "terminal_output": "Traceback ...",
    }
)

시나리오 2: 코드 파일 업로드 후 질문하기

sync_context(
    operation="incremental",
    files=["src/main.py", "config/settings.json", "README.md"],
    project_info={
        "project_name": "My Project",
        "tech_stack": "Python + FastAPI"
    }
)

consult_aurai(
    problem_type="runtime_error",
    error_message="请结合已同步文件帮我排查启动失败"
)

주의:

• main.py를 수동으로 main.txt로 복사할 필요가 없습니다.

• 텍스트 코드 파일은 자동으로 텍스트로 변환되어 전송됩니다.

• 바이너리 파일은 건너뜁니다.

시나리오 3: 다중 문제 병렬 처리, 세션 격리 사용

consult_aurai(
    problem_type="runtime_error",
    error_message="问题 A",
    session_id="issue-a"
)

consult_aurai(
    problem_type="design_issue",
    error_message="问题 B",
    session_id="issue-b"
)

이를 통해 서로 다른 문제 간의 혼선을 방지할 수 있습니다.

sync_context 파일 업로드 규칙

직접 전송되는 파일

• .md, .markdown, .mdx

• .txt

• 각종 코드 및 설정 텍스트 파일, 예:

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

자동 변환되는 파일

• .txt/.md는 아니지만 내용이 텍스트인 파일

• 자동으로 .txt 또는 .md 전송 이름 생성

• 내용 앞에 "원본 파일 경로"와 "자동 변환된 전송 이름"이 첨부됨

건너뛰는 파일

• 이미지

• 압축 파일

• 오디오/비디오

• 실행 파일

• 명백한 바이너리 내용

파일 목록에 코드와 이미지가 섞여 있는 경우:

• 코드는 정상적으로 업로드됨

• 이미지는 skipped_files로 기록됨

• 전체 동기화는 성공으로 처리됨

환경 변수

필수 항목

일반 선택 항목

현재 버전의 핵심 동작

1. 세션 격리

• 각 session_id는 고유한 기록을 가짐

• 전달하지 않을 경우 기본값 default 사용

• 서로 다른 세션은 다른 기록 파일에 저장되어 혼선을 방지함

2. 기록 요약

• 오래된 기록은 자동으로 "기록 요약"으로 압축됨

• 최근 몇 턴과 마지막 sync_context는 원본 그대로 유지하려고 노력함

• 이를 통해 컨텍스트 점유를 줄이고 현재 문제에 대한 공간을 확보함

3. 컨텍스트 윈도우 트리밍

• 시스템 프롬프트를 우선적으로 유지

• 마지막 sync_context를 우선적으로 유지

• 최근 기록 턴을 최대한 유지

• 필요 시 현재 출력 길이를 자동으로 줄여 전체 윈도우 초과 방지

4. 기록 파일 안정성

• 기록 저장 시 잠금 파일을 사용하여 동시 쓰기 손상 방지

• 임시 파일에 쓴 후 교체하는 방식을 사용하여 JSON이 중간에 잘리는 현상 방지

테스트

pytest

현재 메인 라인에서 다루는 핵심 사항:

• 기록 삭제 및 영속화

• 세션 격리

• 자동 텍스트 변환 업로드

• 기록 잠금 및 원자적 쓰기

• 기록 요약

• 컨텍스트 윈도우 트리밍

문서

• Claude Code 설치 가이드

• 사용자 매뉴얼

• 개발 문서

자주 묻는 질문

상급 고문이 제가 업로드한 코드 파일을 받지 못하는 이유는 무엇인가요?

이전 버전에서는 수동으로 .txt로 변환해야 했습니다. 현재 버전은 텍스트 파일 자동 변환을 지원합니다.

여전히 받지 못한다면 다음을 먼저 확인하세요:

• 파일 경로가 존재하는지

• 파일이 바이너리인지

• sync_context 반환값의 uploaded_files / skipped_files 확인

서로 다른 문제가 왜 서로 영향을 주나요?

완벽하게 격리하려면 서로 다른 문제에 다른 session_id를 전달하세요.

기록 파일이 왜 짧아진 것 같나요?

기록 요약 기능이 작동 중이기 때문입니다. 오래된 기록은 요약본으로 압축된 것이며, 삭제된 것이 아니라 컨텍스트를 절약하는 "회의록"으로 대체된 것입니다.